DOCSEARCHbyAlgolia
Submit Docs

cc-sdd Documentation

repository·main·Indexed 25 days ago

https://github.com/gotalab/cc-sdd

A spec-driven implementation framework for AI coding agents that transforms technical specifications into autonomous implementation workflows. It utilizes a structured SDLC (discovery, requirements, design, tasks, and implementation) and provides Agent Skills for Claude Code, Codex, Cursor, Copilot, Windsurf, OpenCode, Gemini CLI, and Antigravity. Features include the /kiro-impl command for TDD-based autonomous execution and the spec-quick macro for rapid specification generation.

Tokens
25K
Snippets
48
Records
130
Agent score
86%

What's inside cc-sdd

  1. Understand the cc-sdd project structure

    main

    After installation, cc-sdd organizes your project using specific directories for different AI agents and shared specification state. The structure depends on whether you use Skills mode (recommended) or the Legacy command mode (deprecated).

    Skills Mode (Recommended)

    One of the following directories will be installed depending on your chosen agent:

    • .claude/skills/ (Claude Code Skills)
    • .agents/skills/ (Codex Skills)
    • .cursor/skills/ (Cursor Skills)
    • .github/skills/ (GitHub Copilot Skills)
    • .windsurf/skills/ (Windsurf Skills)
    • .opencode/skills/ (OpenCode Skills)
    • .gemini/skills/ (Gemini CLI Skills)
    • .agent/skills/ (Antigravity Skills)

    Legacy Command Mode (Deprecated)

    • .claude/commands/kiro/ (11 slash commands, use --claude)
    • .github/prompts/ (11 prompt commands, use --copilot)
    • .windsurf/workflows/ (11 workflow files, use --windsurf)

    Shared Project Memory and Spec State

    These directories are used across agents to maintain specification and steering:

    • .kiro/settings/templates/: Common templates (expands {{KIRO_DIR}})
    • .kiro/settings/rules/: Common rules for non-skills agents
    • .kiro/specs/: Feature specifications
    • .kiro/steering/: AI steering documents
    • CLAUDE.md / AGENTS.md: Project settings specific to each agent

  2. Determine when to use cc-sdd

    main

    Use cc-sdd when your development workflow meets these criteria:

    • Work decomposes into multiple medium-grained specs rather than a single monolith or tiny line changes.
    • Multiple humans or agents are working on the codebase simultaneously and require explicit coordination.
    • You aim to ship in small vertical slices to learn incrementally.
    • You require an audit trail linking agent-generated code back to an approved contract.

    Do not use cc-sdd for:

    • Solo work that fits within a single agent session.
    • Prototypes or throwaway code where formal boundaries are overkill.
    • Scenarios where "vibe coding" is demonstrably faster than defining a contract.

    Note: The /kiro-discovery command may explicitly suggest "no spec needed, implement directly" if the change does not warrant a formal contract.

  3. Use /kiro-impl for autonomous implementation

    main

    The /kiro-impl command triggers a long-running autonomous implementation process. For each task in the spec, it spawns:

    • A fresh implementer running TDD (RED → GREEN) behind a feature flag.
    • An independent reviewer.
    • An auto-debug pass that investigates root causes in a clean context if the implementer is blocked or the reviewer rejects twice.

    Learnings from previous tasks are propagated via ## Implementation Notes in tasks.md.

    /kiro-impl photo-albums

  5. Pilot operation for custom templates

    main

    When introducing new customizations, follow this pilot workflow:

    1. Test with a small feature using the spec commands.
    2. Conduct a team review to check output quality, identify missing information, and adjust templates.
    3. Start production operation by notifying the team and updating onboarding materials.
    # 1. Try with a small feature
/kiro:spec-init Small feature for testing custom templates
/kiro:spec-requirements test-feature
/kiro:spec-design test-feature
/kiro:spec-tasks test-feature

  6. Customize output format via templates

    main

    To change how design documents are generated, edit the template file located at {{KIRO_DIR}}/settings/templates/specs/design.md.

    Important Structure Rule:

    • You must ensure the file exists.
    • You are free to change heading names, the order of sections, and the formatting styles. The system only requires that the file itself is present.

  7. Create domain-specific steering rules

    main

    Use the /kiro:steering-custom command to create domain-specific steering documents. These documents unify rules like API standards, authentication methods, or error handling across a project, training the AI to automatically reflect these rules in all future spec generation.

    Workflow:

    1. Run /kiro:steering-custom.
    2. Provide a prompt describing the domain (e.g., Create domain-specific steering for REST API standards).
    3. The document is saved to {{KIRO_DIR}}/steering/{{domain-name}}.md.

    Impact on AI behavior:

    • All spec generation commands will automatically reference these rules.
    • /kiro:spec-design applies the standard format during API design.
    • /kiro:spec-requirements includes the defined error handling requirements.
    • /kiro:spec-tasks generates authentication and testing tasks according to the steering standards.

  8. Understand the Spec-Driven Development (SDD) lifecycle

    main

    The SDD lifecycle follows a structured progression from discovery to validation. Most phases pause for human review to ensure quality control.

    1. Discovery: /kiro-discovery (Skills mode) is the recommended entry point. It determines if you should extend a spec, implement directly, create a new spec, or decompose work into multiple specs. It generates brief.md and roadmap.md.
    2. Steering: /kiro:steering and /kiro:steering-custom capture architecture and domain knowledge into steering docs.
    3. Spec Initiation: /kiro:spec-init <feature> creates the workspace at .kiro/specs/<feature>/.
    4. Requirements: /kiro:spec-requirements <feature> produces requirements.md.
    5. Design: /kiro:spec-design <feature> produces research.md (if needed) and design.md. In v3.0, design.md includes a File Structure Plan.
    6. Task Planning: /kiro:spec-tasks <feature> creates tasks.md with priority labels (P0, P1, etc.).
    7. Implementation: /kiro:spec-impl <feature> <task-ids> (Legacy) or /kiro-impl (Skills mode) drives execution.
    8. Quality Gates: Optional /kiro:validate-gap and /kiro:validate-design compare specs against existing code.
    9. Validation: /kiro:validate-impl verifies implementation quality.
    10. Status Tracking: /kiro:spec-status <feature> summarizes progress.

    Quick Pass: Use /kiro:spec-quick <feature> to orchestrate steps 2–5 automatically, pausing for approval after each phase.

  9. Customize output formats via templates/

    main

    You can define the structure and format of AI-generated documents by editing files in {{KIRO_DIR}}/settings/templates/specs/. Sections and fields added to these templates will be automatically populated by the AI.

    Files to edit:

    • requirements.md: Controls the structure of the requirements document.
    • design.md: Controls the structure of the design document.
    • tasks.md: Controls the structure of the task breakdown document.

    Common use cases:

    • Adding PRD-style sections (e.g., Product Overview, Success Metrics).
    • Adding approval checklists or JIRA fields.
    ls -la {{KIRO_DIR}}/settings/templates/specs/

  10. Migrate from cc-sdd 2.x to 3.0 (Skills Mode)

    main

    Version 3.0 introduces Skills Mode, which is the required installation target for all supported platforms. Legacy command-based flags (e.g., --claude-code, --cursor) are deprecated and will be removed.

    1. Reinstall using Skills flags

    Use the specific --*-skills flag for your platform to install the correct skill set:

    npx cc-sdd@latest --claude-skills     # Claude Code (default)
npx cc-sdd@latest --codex-skills      # Codex
npx cc-sdd@latest --cursor-skills     # Cursor IDE
npx cc-sdd@latest --copilot-skills    # GitHub Copilot
npx cc-sdd@latest --windsurf-skills   # Windsurf IDE
npx cc-sdd@latest --opencode-skills   # OpenCode
npx cc-sdd@latest --gemini-skills     # Gemini CLI
npx cc-sdd@latest --antigravity       # Antigravity

    2. Update Commands and Workflows

    • Replace Implementation Commands: Update any scripts using kiro-spec-impl to use the new unified /kiro-impl skill, which includes native subagent dispatch (implementer, reviewer, and debugger).
    • Adopt Discovery Entry Point: Instead of starting with /kiro:spec-init, start new features with /kiro-discovery. This command writes brief.md and roadmap.md, which provide session persistence and feed downstream skills.
    • Use Batch Processing: For multi-feature work, use /kiro-spec-batch to create multiple specs in parallel with cross-spec review.
    • Session Continuity: Leverage brief.md to persist feature context across different sessions.
    npx cc-sdd@latest --claude-skills

  11. Complete Brownfield Workflow (Existing Projects)

    main

    When adding features to an existing codebase, use gap analysis to ensure compatibility:

    1. Context: /kiro:steering (and /kiro:steering-custom for domain patterns)
    2. Initialize: /kiro:spec-init <description>
    3. Requirements: /kiro:spec-requirements <feature-name>
    4. Gap Analysis: /kiro:validate-gap <feature-name>
    5. Design: /kiro:spec-design <feature-name>
    6. Design Validation: /kiro:validate-design <feature-name>
    7. Tasks: /kiro:spec-tasks <feature-name>
    8. Implement & Validate: /kiro:spec-impl <feature-name> <task-ids> followed by /kiro:validate-impl <feature-name>
    # 1. Establish project context
/kiro:steering
/kiro:steering-custom  # Add domain-specific patterns

# 2. Initialize enhancement
/kiro:spec-init Add OAuth to existing auth system

# 3. Generate requirements
/kiro:spec-requirements oauth-enhancement

# 4. Analyze integration gaps
/kiro:validate-gap oauth-enhancement

# 5. Create design (informed by gap analysis)
/kiro:spec-design oauth-enhancement

# 6. Validate design against existing system
/kiro:validate-design oauth-enhancement

# 7. Break into tasks
/kiro:spec-tasks oauth-enhancement

# 8. Implement and validate
/kiro:spec-impl oauth-enhancement 1.1,1.2
/kiro:validate-impl oauth-enhancement

  12. Implement the Spec-Driven Development workflow

    main

    Follow these steps to develop a new feature using the /kiro command suite. The process relies on a sequence of requirements, design, and task generation, with human review required at each stage.

    Workflow for New Features

    1. (Optional) Project Steering: Run /kiro:steering to establish project-wide knowledge (architecture, tech stack, etc.).
    2. Initialize Specification: Run /kiro:spec-init "<detailed description>" to create the feature structure.
    3. Define Requirements: Run /kiro:spec-requirements <feature-name>. Review and edit the generated .kiro/specs/<feature-name>/requirements.md.
    4. Technical Design: Run /kiro:spec-design <feature-name>. Confirm review of requirements when prompted, then review and edit .kiro/specs/<feature-name>/design.md.
    5. Generate Tasks: Run /kiro:spec-tasks <feature-name>. Confirm review of requirements and design, then review and edit .kiro/specs/<feature-name>/tasks.md.
    6. Implementation: Begin coding based on the approved tasks.
    # Example workflow
/kiro:steering
/kiro:spec-init "I want to create a feature where users can upload PDFs..."
/kiro:spec-requirements pdf-diagram-extractor
/kiro:spec-design pdf-diagram-extractor
/kiro:spec-tasks pdf-diagram-extractor