spex

cc-spex

Extend Spec-Kit with composable traits and additional workflow commands for Claude Code.

[!IMPORTANT] Starting with v4.0.0, cc-spex requires Spec-Kit 0.5.0 or later. For older Spec-Kit versions, use a 3.0.x release.

[!NOTE] This project was previously named cc-sdd. It has been renamed to cc-spex in v3.0.0 to avoid confusion with the unrelated gotalab/cc-sdd project. If you were using cc-sdd, see Migrating from sdd below.

Why cc-spex?

Spec-Kit is a great foundation for specification-driven development. cc-spex is a Claude Code plugin that stays as close to upstream Spec-Kit as possible while adding orthogonal features through traits, a composable overlay mechanism similar to aspect-oriented programming for Claude Code plugins.

Each trait injects cross-cutting behavior into Spec-Kit's existing commands without modifying them. Quality gates, git worktree isolation, parallel agent execution: these concerns live outside the core workflow. Traits let you opt into them selectively, and Spec-Kit's commands remain the same underneath.

cc-spex also adds its own commands for things Spec-Kit doesn't cover, like interactive brainstorming, spec/code drift detection, and review workflows. For hands-on work, you call each step yourself in the order that fits your situation. For full automation, /spex:ship chains the entire workflow from brainstorm to verification with configurable oversight.

Workflow

The recommended workflow has two phases, each producing a pull request:

Phase 1: Specification

Start with an idea, refine it through brainstorming, then create a formal spec and implementation plan. The output is a PR containing spec.md, plan.md, tasks.md, and a REVIEWERS.md that guides reviewers through what to look for during spec review.

/spex:brainstorm          # Refine the idea through dialogue
/speckit-specify           # Create formal spec
/spex:review-spec          # Validate spec quality
/speckit-plan              # Generate implementation plan + tasks
/spex:review-plan          # Validate plan, generate REVIEWERS.md

Open a PR with these artifacts. Reviewers use REVIEWERS.md as a starting point to understand the spec's scope, key decisions, and areas that need scrutiny.

Phase 2: Implementation

After the spec PR is reviewed and merged, implementation can proceed in one or more PRs (one per logical phase is ideal). Each implementation PR updates REVIEWERS.md with code-specific review hints, compliance notes, and areas where the reviewer should focus.

/speckit-implement         # Build following the plan
/spex:review-code          # Spec compliance + deep review
/spex:stamp                # Final gate

If spec/code drift is detected during implementation, use /spex:evolve to reconcile: either update the spec or fix the code, then continue.

One-Shot: /spex:ship

For smaller features or solo projects, /spex:ship chains the entire workflow from brainstorm through verification in a single session, without intermediate PRs. It runs all nine stages autonomously with configurable oversight levels (--ask always|smart|never) and can optionally create a PR at the end with --create-pr. See Ship Command below for details.

flowchart TD
    Start([Idea]) --> HasClarity{Clear<br>requirements?}

    HasClarity -->|Not yet| Brainstorm["/spex:brainstorm<br>Refine idea"]
    HasClarity -->|Yes| Specify["/speckit-specify<br>Create spec"]

    Brainstorm --> Specify
    Brainstorm -->|Full auto| Ship["/spex:ship<br>Autonomous pipeline"]

    Specify --> ReviewSpec["/spex:review-spec<br>Validate spec"]
    ReviewSpec --> Plan["/speckit-plan<br>Generate plan + tasks"]
    Plan --> ReviewPlan["/spex:review-plan<br>Create REVIEWERS.md"]

    ReviewPlan -->|PR #1: Spec| SpecPR([Spec Review & Merge])

    SpecPR --> Implement["/speckit-implement<br>Build with TDD"]
    Implement --> ReviewCode["/spex:review-code<br>Spec compliance +<br>deep review"]

    ReviewCode --> Verify{Tests pass?<br>Spec compliant?}

    Verify -->|Yes| ImplPR([PR #2+: Implementation])
    Verify -->|Drift detected| Evolve["/spex:evolve<br>Reconcile"]

    Evolve -->|Update spec| ReviewSpec
    Evolve -->|Fix code| Implement

    Ship -->|Chains all stages| ImplPR

Quick Start