╔═══════════════════════════════════════════════════════════════════╗
║                                                                   ║
║   ███████╗ █████╗ ██╗     ████████╗██╗ ██████╗                  ║
║   ██╔════╝██╔══██╗██║     ╚══██╔══╝██║██╔════╝                  ║
║   ███████╗███████║██║        ██║   ██║██║                       ║
║   ╚════██║██╔══██║██║        ██║   ██║██║                       ║
║   ███████║██║  ██║███████╗   ██║   ██║╚██████╗                  ║
║   ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝ ╚═════╝                  ║
║                                                                   ║
║           Spec-Driven Development Framework                      ║
║           Constitutional Software Development                    ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝

Saltic Spec-Driven Development (SDD) Framework

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

# 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

# Angular with Auto Research (experimental research tools)
npx create-saltic@latest create --kit claude/angular-genresearch --release experiment

# 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

📦 Angular with Auto Research (Experiment) - Angular 20+ with Advanced Research Tools

• Version: 0.0.1 (Experiment)
• Framework: Angular 20+ with Auto Research
• AI Model: Claude Code
• Architecture: Clean Architecture + Research Tools
• Features: Auto Search functionality, Advanced Research Tools, Figma Integration, Task Orchestration
• Agents: 6 specialized agents including component-generator, test-generator, figma-extractor, and task-orchestrator
• Skills: task-orchestrator for complex workflow management
• Commands: Markdown-based (.md format) with /research command for AI-assisted requirement generation
• Templates: Complete set including agent-file-template.md, execution-plan-template.md, feature-spec-template.md, and feature-implementation-input-template.md
• Directory: .claude/
• Install: Interactive selection → Choose "🤖 Claude" → "🔧 Show experiment versions" → "Angular with Auto Research (experiment)"
• Quick Start: After installation, use /research command to generate requirements with AI assistance

✨ 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

# 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

# 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

# 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:

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:

/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:

/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:

/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:

/execute T001           # Execute single task
/execute T001-T005      # Execute task range
/execute T001,T003,T007 # Execute specific tasks

Execute by phase:

/execute phase-0        # Execute Phase 0 tasks
/execute phase-1        # Execute Phase 1 tasks
/execute all-phases     # Execute all phases sequentially

List available phases:

/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

# 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

# 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

# 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

# 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:

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