create-saltic

<div align="center"> ``` ╔═══════════════════════════════════════════════════════════════════╗ ║ ║ ║ ███████╗ █████╗ ██╗ ████████╗██╗ ██████╗ ║ ║ ██╔════╝██╔══██╗██║ ╚══██╔══╝██║██╔════╝ ║ ║ ███████╗███████║██║ ██║ ██║██║ ║ ║ ╚════██║██╔══██║██║ ██║ ██║██║ ║ ║ ███████║██║ ██║███████╗ ██║ ██║╚██████╗ ║ ║ ╚══════╝╚═╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ║ ║ ║ ║ Spec-Driven Development Framework ║ ║ Constitutional Software Development ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════╝ ``` ### **Saltic Spec-Driven Development (SDD) Framework** </div> --- A structured approach to software development through specifications, plans, and tasks. This framework provides tools and templates for following a constitutional development methodology. **🎯 Choose your framework:** Angular, React, or more to come! ## Installation ### Prerequisites - Node.js (v16 or higher) - npm (comes with Node.js) - Git - **AI Model Choice:** - **Claude Code** with MCP tools enabled (Figma Dev Mode MCP, Context7) - **Gemini** with TOML-based command system - **Qwen** with TOML-based command system ### Setup with npx ```bash # Install Saltic with interactive AI model and framework selection npx create-saltic@latest # Quick framework installation (recommended) npx create-saltic@latest angular # Angular (stable version) - Claude npx create-saltic@latest angular --experiment # Angular (experiment version) - Claude npx create-saltic@latest react # React (stable version) - Claude # List all available kits (both Claude and Gemini) npx create-saltic@latest --list-kits # Interactive mode with directory npx create-saltic@latest my-project ``` ## Available Kits ### Version-Based Kit Organization Saltic provides kits in two versions to match your project needs: #### 🟢 **Stable Version** (Production-Ready) Kits that are mature, well-tested, and suitable for production environments. #### 🟡 **Experiment Version** (Cutting-Edge) Kits with latest features and experimental capabilities for innovative projects. ### AI Model-Based Kit Organization Saltic provides kits for different AI models with unique approaches: #### 🤖 **Claude Code Kits** (Framework-Specific) **📦 Angular (Stable)** - Angular 20+ with Clean Architecture - **Version:** 0.0.3 (Stable) - **Framework:** Angular 20+ - **AI Model:** Claude Code - **Architecture:** Clean Architecture + Atomic Design - **Features:** TDD with Jest, Context7 Integration, Figma Integration - **Agents:** 6 specialized agents for Angular development - **Commands:** Markdown-based (`.md` format) - **Directory:** `.claude/` - **Install:** `npx create-saltic@latest angular` (stable), `npx create-saltic@latest angular --experiment` (experiment) **📦 React (Stable)** - React 18+ with Clean Architecture - **Version:** 0.0.3 (Stable) - **Framework:** React 18+ - **AI Model:** Claude Code - **Architecture:** Clean Architecture - **Features:** TDD with Jest, Context7 Integration, Figma Integration - **Agents:** Framework-specific agents - **Commands:** Markdown-based (`.md` format) - **Directory:** `.claude/` - **Install:** `npx create-saltic@latest react` **📦 Angular (Experiment)** - Angular 20+ Experimental Features - **Version:** 0.0.4 (Experiment) - **Framework:** Angular 20+ - **AI Model:** Claude Code - **Architecture:** Clean Architecture + Constitutional Development - **Features:** Enhanced constitution, experimental memory files, custom architecture - **Agents:** 6 specialized agents including angular-new-component-generator and angular-testing-expert - **Commands:** Markdown-based (`.md` format) - **Directory:** `.claude/` - **Install:** `npx create-saltic@latest angular --experiment` #### ✨ **Gemini Kits** (Framework-Agnostic) **📦 Gemini (Stable)** - Agnostic Spec-Driven Development - **Version:** 0.0.1 (Stable) - **Framework:** Agnostic (Multi-framework) - **AI Model:** Gemini - **Architecture:** Constitutional-Driven Development - **Features:** TOML-based command system, framework-agnostic approach - **Agents:** No agents (direct execution) - **Commands:** TOML-based (`.toml` format) - **Directory:** `.gemini/` - **Install:** Interactive selection → Choose "✨ Gemini" **📦 Gemini (Experiment)** - Experimental Gemini Features - **Version:** 0.0.1-experiment - **Framework:** Agnostic (Multi-framework) - **AI Model:** Gemini - **Architecture:** Constitutional-Driven Development - **Features:** Experimental TOML commands, enhanced constitutional features - **Agents:** No agents (direct execution) - **Commands:** TOML-based (`.toml` format) - **Directory:** `.gemini/` - **Install:** Interactive selection → Choose "✨ Gemini" → Experiment version #### 🟢 **Qwen Kits** (Framework-Agnostic) **📦 Qwen (Stable)** - Agnostic Spec-Driven Development - **Version:** 0.0.1 (Stable) - **Framework:** Agnostic (Multi-framework) - **AI Model:** Qwen - **Architecture:** Constitutional-Driven Development - **Features:** TOML-based command system, framework-agnostic approach - **Agents:** No agents (direct execution) - **Commands:** TOML-based (`.toml` format) - **Directory:** `.qwen/` - **Install:** Interactive selection → Choose "🟢 Qwen" **📦 Qwen (Experiment)** - Experimental Qwen Features - **Version:** 0.0.1-experiment - **Framework:** Agnostic (Multi-framework) - **AI Model:** Qwen - **Architecture:** Constitutional-Driven Development - **Features:** Experimental TOML commands, enhanced constitutional features - **Agents:** No agents (direct execution) - **Commands:** TOML-based (`.toml` format) - **Directory:** `.qwen/` - **Install:** Interactive selection → Choose "🟢 Qwen" → Experiment version ## Quick Start ### **Claude Code Quick Start** ```bash # 1. Install Saltic with Claude (quick and simple) npx create-saltic@latest angular # 2. Check framework status npx create-saltic@latest status # 3. Switch to kit-specific constitution (optional) npx create-saltic@latest use-kit-constitution # 4. Start using Claude Code commands # After injection, check CLAUDE.md for usage guidance ``` ### **Gemini Quick Start** ```bash # 1. Install Saltic with interactive selection npx create-saltic@latest # Choose "✨ Gemini" when prompted for AI model # 2. Check framework status npx create-saltic@latest status # 3. Start using Gemini commands # Commands are in TOML format in .gemini/commands/ ``` ### **Qwen Quick Start** ```bash # 1. Install Saltic with interactive selection npx create-saltic@latest # Choose "🟢 Qwen" when prompted for AI model # 2. Check framework status npx create-saltic@latest status # 3. Start using Qwen commands # Commands are in TOML format in .qwen/commands/ ``` ## How to Use Saltic SDD Framework ### Step-by-Step Workflow After installing Saltic into your project, follow this structured workflow to build features using Spec-Driven Development: --- #### **Step 1: Prepare Feature Documentation** 📝 Create a feature folder in `docs/features/` with your feature name: ```bash docs/features/your-feature-name/ ├── acceptance-criteria.md # Gherkin scenarios and test cases ├── feature-flow.md # User flow and interaction steps ├── raw-spec.md # Core functionality checklist and requirements ├── ui-contract.md # [Optional] Design references, wireframes, and UI specs └── api-contract.md # [Optional] API specifications and data models ``` **What each file contains:** - **`acceptance-criteria.md`**: Gherkin-style acceptance criteria with scenarios - User stories in "As a [role], I want [feature], So that [benefit]" format - Background setup and preconditions - Scenario-based test cases with Given-When-Then structure - Edge cases and error handling scenarios - **`feature-flow.md`**: Step-by-step feature flow documentation - Main user interaction flow - Success and failure paths - Exit/quit conditions - State transitions and navigation - **`raw-spec.md`**: Raw specification and requirements checklist - Core functionality requirements (must maintain) - New enhancements and features - Form validation rules - Interactive elements behavior - Feature flag implementation notes - **`ui-contract.md`** *(Optional - for features with UI/design requirements)*: UI design contract and references - Figma design URLs with node IDs - Design screenshots and references - Wireframes (ASCII art format) - Component hierarchy - Responsive breakpoints - Design system integration notes - **`api-contract.md`** *(Optional - for features requiring backend integration)*: API contract and integration specifications - Base URL and authentication requirements - Endpoint definitions (method, path, headers) - Request/response body schemas - Field specifications with validation rules - Data models and TypeScript interfaces - Error handling and status codes - Used for generating API connection to backend services --- #### **Step 2: Generate Specification** 🔍 Use the `/spec` command to create a technical specification from your feature documentation: ```bash /spec Build a CSV upload feature that allows users to import data with validation. Reference the feature docs in docs/features/csv-upload-feature/ ``` **What happens:** - AI model analyzes your feature documentation - Generates implementation-ready technical specification - Creates spec file: - **Claude**: `.claude/specs/[feature-name]/spec.md` - **Gemini**: `.gemini/specs/[feature-name]/spec.md` - Includes data models, contracts, and architecture decisions --- #### **Step 3: Create Implementation Plan** 📋 Use the `/plan` command to generate an execution plan from your spec document: ```bash /plan Generate execution plan from csv-upload-feature spec ``` **What happens:** - Reads spec file from model-specific specs directory: - **Claude**: `.claude/specs/[spec-name]/spec.md` - **Gemini**: `.gemini/specs/[spec-name]/spec.md` - Loads contracts from model-specific contracts folder - Extracts technical requirements, constraints, and architecture decisions - Generates detailed implementation task breakdown with: - Phase-based structure (Phase 0, 1, 2, etc.) - Numbered tasks in format: `[ID] [P?] Description` - Parallel `[P]` vs serial execution requirements - Dependency mapping and proper task ordering - Constitutional compliance requirements - Creates execution plan in model-specific directory --- #### **Step 4: Analyze and Validate** 🔍 Use the `/analyze` command to review your specifications and plans before implementation: ```bash /analyze Review csv-upload-feature spec and plan for completeness ``` **What happens:** - Validates specification completeness and identifies missing requirements - Checks plan feasibility and execution dependencies - Identifies constitutional compliance issues - Catches potential implementation risks early - Ensures you're ready to start coding with confidence --- #### **Step 5: Execute Tasks** ⚡ Use the `/execute` command to run tasks from your execution plan: **Execute specific tasks:** ```bash /execute T001 # Execute single task /execute T001-T005 # Execute task range /execute T001,T003,T007 # Execute specific tasks ``` **Execute by phase:** ```bash /execute phase-0 # Execute Phase 0 tasks /execute phase-1 # Execute Phase 1 tasks /execute all-phases # Execute all phases sequentially ``` **List available phases:** ```bash /execute list-phases # Show all phases and their tasks ``` **What happens:** - Tasks are executed following constitutional principles - Tests are written first (TDD) as defined in constitution - Code is generated based on AI model approach: - **Claude**: Kit-specific agents - **Gemini**: Direct execution without agents - Progress is tracked in execution plan - Constitutional gates are validated --- ### Complete Workflow Example #### **Claude Code Workflow** ```bash # 1. Install Saltic with Angular (quick command) npx create-saltic@latest angular # 2. Prepare feature documentation mkdir -p docs/features/photo-album-manager # Create acceptance-criteria.md, feature-flow.md, raw-spec.md, ui-contract.md # 3. Generate specification /spec Build a photo album manager that allows users to organize photos by date. Reference docs in docs/features/photo-album-manager/ # 4. Create implementation plan /plan Generate execution plan from photo-album-manager spec # 5. Analyze and validate /analyze Review photo-album-manager spec and plan for completeness # 6. Review phases /execute list-phases # 7. Execute tasks /execute phase-0 # Research and setup /execute phase-1 # Core implementation /execute T015-T020 # Execute specific task range /execute all-phases # Or execute everything ``` #### **Gemini Workflow** ```bash # 1. Install Saltic with Gemini (interactive) npx create-saltic@latest # Choose "✨ Gemini" when prompted # 2. Prepare feature documentation mkdir -p docs/features/photo-album-manager # Create acceptance-criteria.md, feature-flow.md, raw-spec.md, ui-contract.md # 3. Generate specification (using TOML commands) # Commands are in .gemini/commands/spec.toml # 4. Create implementation plan # Commands are in .gemini/commands/plan.toml # 5. Analyze and validate # Commands are in .gemini/commands/analyze.toml # 6. Execute tasks # Commands are in .gemini/commands/execute.toml ``` --- ### Available Commands | Command | Description | |---------|-------------| | `/spec` | Transform your feature documentation into comprehensive technical specifications with architecture decisions, data models, and implementation requirements | | `/plan` | Convert your specifications into actionable task breakdowns with phase-based structure, dependency mapping, and parallel execution planning | | `/analyze` | Perform comprehensive gap analysis between your specifications and plans to identify missing requirements, constitutional compliance issues, and implementation risks | | `/execute` | Run specific tasks or entire phases from your execution plan with automatic progress tracking and constitutional validation | #### Command Usage Examples ```bash # Create specification from feature documentation /spec Build a CSV upload feature that allows users to import data with validation. Reference the feature docs in docs/features/csv-upload-feature/ # Generate detailed implementation plan /plan Generate execution plan from csv-upload-feature spec # Analyze gaps and identify potential issues /analyze Review csv-upload-feature spec and plan for completeness # Execute tasks from your plan /execute T001-T005 # Execute specific task range /execute phase-1 # Execute entire phase /execute all-phases # Execute everything sequentially ``` ## Development Workflow The framework follows a strict Spec-Driven Development lifecycle with model-specific approaches: ### **Shared Workflow** 1. **Specify** (`/spec`): Transform your feature documentation into implementation-ready technical specifications 2. **Plan** (`/plan`): Break down your specifications into actionable tasks with clear phases, dependencies, and execution order 3. **Analyze** (`/analyze`): Review your specifications and plans to catch gaps, validate completeness, and identify potential issues before you start coding 4. **Execute** (`/execute`): Build your feature following the plan, with automatic progress tracking and constitutional validation 5. **Validate**: Run tests and verify that your implementation meets all acceptance criteria ### **Model-Specific Implementation** - **Claude Code**: Commands in Markdown format (`.md`) with AI agents - **Gemini**: Commands in TOML format (`.toml`) with direct execution - **Qwen**: Commands in TOML format (`.toml`) with direct execution ### **Directory Structures** **Claude Installation:** ``` .claude/ ├── agents/ # AI agents ├── commands/ # .md command files ├── specs/ # Feature specifications ├── execution-plans/ # Execution plans └── templates/ # Code templates ``` **Gemini Installation:** ``` .gemini/ ├── commands/ # .toml command files ├── specs/ # Feature specifications ├── execution-plans/ # Execution plans └── templates/ # Code templates ``` **Qwen Installation:** ``` .qwen/ ├── commands/ # .toml command files ├── specs/ # Feature specifications ├── execution-plans/ # Execution plans └── templates/ # Code templates ``` ## Key Commands ### Framework Management ```bash # Quick framework installation (recommended) npx create-saltic@latest angular # Angular (stable) npx create-saltic@latest angular --experiment # Angular (experiment) npx create-saltic@latest react # React (stable) # Interactive framework selection npx create-saltic@latest # List all available kits npx create-saltic@latest --list-kits # Check framework status npx create-saltic@latest status # Switch to kit-specific constitution npx create-saltic@latest use-kit-constitution # Remove framework from project npx create-saltic@latest remove ``` ### Feature Management - **Claude**: Check CLAUDE.md for usage guidance after installing - **Gemini**: Check .gemini/commands/ for TOML-based command definitions ## File Structure After Installation ### **Claude Installation Structure** ``` your-project/ ├── .claude/ # Framework configuration and commands │ ├── agents/ # Kit-specific AI agents │ ├── commands/ # Command definitions in .md format │ ├── templates/ # Kit-specific code templates │ ├── specs/ # Feature specifications │ │ └── [feature-name]/ # Feature-specific files │ ├── execution-plans/ # Task execution plans │ └── kit.json # Kit metadata ├── .saltic/ # Framework core │ └── memory/ # Constitution and governance documents │ ├── constitution.md # Active constitution │ ├── constitution_update_checklist.md │ └── [kit]-constitution.md # Kit-specific constitution ├── docs/ # Documentation files └── CLAUDE.md # Framework usage guide ``` ### **Gemini Installation Structure** ``` your-project/ ├── .gemini/ # Framework configuration and commands │ ├── commands/ # Command definitions in .toml format │ ├── templates/ # Kit-specific code templates │ ├── specs/ # Feature specifications │ │ └── [feature-name]/ # Feature-specific files │ ├── execution-plans/ # Task execution plans │ └── kit.json # Kit metadata ├── .saltic/ # Framework core │ └── memory/ # Constitution and governance documents │ └── constitution.md # Main constitution ├── docs/ # Documentation files └── GEMINI.md # Framework usage guide (generated) ``` ### **Qwen Installation Structure** ``` your-project/ ├── .qwen/ # Framework configuration and commands │ ├── commands/ # Command definitions in .toml format │ ├── templates/ # Kit-specific code templates │ ├── specs/ # Feature specifications │ │ └── [feature-name]/ # Feature-specific files │ ├── execution-plans/ # Task execution plans │ └── kit.json # Kit metadata ├── .saltic/ # Framework core │ └── memory/ # Constitution and governance documents │ └── constitution.md # Main constitution ├── docs/ # Documentation files └── QWEN.md # Framework usage guide (generated) ``` ### **Key Differences** - **Claude**: Uses AI agents and `.md` command format - **Gemini**: Framework-agnostic with `.toml` command format - **Qwen**: Framework-agnostic with `.toml` command format - **Constitution**: All models use same constitutional principles - **Workflow**: Identical SDD process regardless of AI model ## Development Principles ### Constitutional Development All features must comply with the constitution (`memory/constitution.md`): - **Library-First**: Every feature starts as a standalone library - **CLI Interface**: All libraries expose functionality via CLI - **Test-First**: TDD is mandatory - tests must fail before implementation - **Integration Testing**: Required for new libraries, contract changes, and shared schemas - **Observability**: Structured logging and error context required - **Versioning**: MAJOR.MINOR.BUILD format with breaking change handling - **Context7 Documentation Integration**: Always use context7 tools for external library documentation ### Branch Naming Convention Feature branches must follow the pattern: `<git:branchname>-<git:name>-<featurename>` (e.g., `WEC0101-BUDI-authentication`) ## Framework Features ### What the CLI Does When you run `npx create-saltic@latest`, the CLI: 1. **Presents AI Model Selection**: Choose between Claude Code, Gemini, or Qwen 2. **Presents Kit Selection**: Choose from available kits based on AI model - **Claude**: Angular, React, etc. - **Gemini**: Agnostic framework option - **Qwen**: Agnostic framework option 3. **Creates Directory Structure**: Sets up model-specific directories - **Claude**: `.claude/` and `.saltic/` directories - **Gemini**: `.gemini/` and `.saltic/` directories - **Qwen**: `.qwen/` and `.saltic/` directories 4. **Copies Kit Files**: - **Claude**: Agents → `.claude/agents/`, Templates → `.claude/templates/`, Commands → `.claude/commands/` - **Gemini**: Templates → `.gemini/templates/`, Commands → `.gemini/commands/` (TOML format) - **Qwen**: Templates → `.qwen/templates/`, Commands → `.qwen/commands/` (TOML format) - Constitution → `.saltic/memory/` (all models) 5. **Creates Working Directories**: `docs/` and model-specific `specs/` for your project 6. **Saves Metadata**: Kit information to model-specific `kit.json` 7. **Adds Documentation**: Model-specific usage guidelines 8. **Command Format Conversion**: Automatically converts commands to appropriate format during installation ### Available Commands #### Framework Installation - `npx create-saltic@latest angular`: Install Angular (stable version) - Claude - `npx create-saltic@latest angular --experiment`: Install Angular (experiment version) - Claude - `npx create-saltic@latest react`: Install React (stable version) - Claude - `npx create-saltic@latest`: Interactive AI model and framework selection #### Framework Management - `--list-kits`: List all available kits - `status`: Check framework installation status - `use-kit-constitution`: Switch to kit-specific constitution - `remove`: Remove framework from current project #### Legacy Support (backward compatibility) - `create --kit <id> --release <version>`: Install specific kit (legacy format) ### Version Selection **Stable vs Experiment:** - **stable**: Production-ready kits with proven stability (default) - **experiment**: Cutting-edge kits with latest features and experimental capabilities **Example Usage:** ```bash npx create-saltic@latest angular # Angular stable npx create-saltic@latest angular --experiment # Angular experiment npx create-saltic@latest react # React stable ``` ### After Installation Once installed, use the framework through: - **Claude Code**: Use CLAUDE.md for AI-assisted development - **Gemini**: Use .gemini/commands/ for TOML-based command definitions - **Qwen**: Use .qwen/commands/ for TOML-based command definitions - **Custom Commands**: `/spec`, `/plan`, `/execute`, `/analyze` (format varies by model) - **Code Generation**: - **Claude**: Kit-specific AI agents - **Gemini**: Direct execution without agents - **Qwen**: Direct execution without agents ## Framework Configuration ### Version Management Saltic uses a modular version system: - **CLI Version**: Defined in `package.json` (currently 0.0.7) - **Kit Versions**: Individual kit versions tracked in manifest files - **Installation Metadata**: Both versions recorded in `.claude/kit.json` ### Git Commit Guidelines The framework includes standardized commit message format: #### Standard Commits ``` [type]: [author] [ticket-id] description ``` **Commit Types:** - `feat:` New feature or enhancement - `fix:` Bug fix or correction - `docs:` Documentation changes - `style:` Code formatting, style changes - `refactor:` Code refactoring without functional changes - `test:` Adding or updating tests - `chore:` Maintenance tasks, dependencies, build changes **JIRA Configuration:** - JIRA ticket prefix is configured in `package.json` under `jira.ticketPrefix` - Current prefix: `VIBE` (configured in package.json) - Format: `[PREFIX]-[NUMBER]` (e.g., `VIBE-13000`) **Examples:** - `feat: [ricko] [VIBE-13000] add api-contract.md support and registration-form example` - `fix: [budisantoso] [VIBE-13001] resolve package version conflict` #### Branch Naming Pattern: `<ticket-id>-<author>-<feature-name>` - Example: `VIBE-13000-ricko-api-contract-support`