cc-spex

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

Important

Starting with v5.0.0, cc-spex uses spec-kit's native extension system. The old traits/overlay system has been removed. See Migrating from v4.x below.

Why cc-spex?

Spec-Kit is a great foundation for specification-driven development. cc-spex is a Claude Code plugin that extends Spec-Kit through extensions, self-contained bundles that provide additional commands and lifecycle hooks.

Six bundled extensions add quality gates, git worktree isolation, parallel agent execution, multi-perspective code review, and collaborative PR workflows. Each extension registers hooks that fire automatically at spec-kit lifecycle boundaries. You enable or disable them independently via specify extension enable/disable.

cc-spex also adds commands for things Spec-Kit doesn't cover: interactive brainstorming, spec/code drift detection, and autonomous pipelines. For hands-on work, you call each step yourself. For full automation, /speckit-spex-ship chains the entire workflow from brainstorm to verification with configurable oversight.

Workflow

Specification-driven development works well as a solo practice: you write the spec, you implement it, you review your own code. The feedback loop is tight and the overhead is low. In a team setting, though, the approach hits friction. The spec, plan, and implementation together can produce thousands of lines of structured artifacts and code. A single PR containing all of that is difficult to review meaningfully. Reviewers either rubber-stamp it or spend hours trying to understand decisions that were made early in the process.

cc-spex addresses this with a two-phase workflow that separates specification from implementation. The key insight: catch design problems during spec review, before any code exists, so that implementation review can focus on whether the code matches an already-agreed specification.

The two phases can live in separate PRs (spec PR first, implementation PR second) or on the same PR (spec committed first, implementation added after approval). Labels track which phase the PR is in. The spex-collab extension must be enabled for the collaborative workflow features described below (specify extension enable spex-collab).

Phase 1: Specification

Start with an idea, refine it through brainstorming, then create a formal spec and implementation plan.

/speckit-spex-brainstorm   # Refine the idea into a structured brainstorm document
/speckit-specify           # Create formal spec from brainstorm
/speckit-plan              # Generate implementation plan
/speckit-tasks             # Generate task breakdown

Quality gates fire automatically via spex-gates hooks: review-spec runs after specify, review-plan runs after tasks. With spex-collab enabled, REVIEWERS.md is generated automatically after task generation as the single reviewer-facing artifact. The reviewers command offers to create a [Spec] PR automatically after generating REVIEWERS.md.

The REVIEWERS.md Guide

Reviewing a 500-line specification document from scratch is daunting. REVIEWERS.md is generated by spex to make even medium to large PRs reviewable within 30 minutes. It follows a question-driven structure: Why (the problem), What (outcome-level summary), How (implementation approach from plan.md), When (applicability and scope), then the design decisions that need human judgment and areas of concern.

All PRs created by spex include a link to the Review Guide at the top of the PR description, using full GitHub URLs that work across forks.

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

PR Title Conventions

spex uses structured PR titles to communicate the content at a glance:

Stage	Title format	Example
Spec only	Feature Name [Spec]	Structured events [Spec]
Spec + implementation	Feature Name [Spec + Impl]	Structured events [Spec + Impl]
Multi-phase	Feature Name [Spec + Impl (N/T)]	Structured events [Spec + Impl (1/3)]

PR Labels

Labels track the current phase of a PR, especially useful when spec and implementation live on the same PR. They are applied automatically by collab commands and updated as the PR progresses:

Label	Applied when	Meaning
spex/spec	Spec PR created	Spec is under review, not yet approved
spex/spec-approved	Spec approved, implementation starting	Replaces spex/spec after review approval
spex/implement	Implementation added	Code is being implemented against the approved spec

Labels are configurable in .specify/extensions/spex-collab/collab-config.yml and can be disabled entirely for repos that don't have them.

Spec Revision Loop

When a [Spec] PR receives review comments, the revision workflow handles the feedback without manual artifact juggling:

/speckit-spex-collab-revise --pr 42     # Read PR comments, update spec, cascade

This updates spec.md based on the feedback, re-runs /speckit-clarify and quality gates (review-spec, review-plan), regenerates plan.md and tasks.md, appends a revision history entry to REVIEWERS.md, commits, pushes, and posts a summary comment on the PR.

If implementation was already started in parallel (before the spec PR was approved), the revised tasks may conflict with existing code:

/speckit-spex-collab-reconcile          # Scan code against revised tasks
/speckit-implement                      # Pick up only the delta

The reconcile command classifies each task as DONE (existing code satisfies it), REWORK (code exists but needs changes per revised spec), or NEW (added by revision). It marks DONE tasks as [X] and annotates REWORK tasks with hints, so /speckit-implement picks up only the remaining work.

Phase 2: Implementation

After the spec is approved, implementation can proceed. Two patterns are supported:

Same PR (recommended for smaller scopes): Keep spec and implementation on the same PR. After spec approval, the spex/spec label is replaced with spex/spec-approved, then spex/implement is added when implementation begins. The PR title updates from [Spec] to [Spec + Impl]. Reviewers can see the full history in one place.

Separate PRs (for larger scopes): Merge the spec PR first, then create one or more implementation PRs. Each implementation PR references the approved spec via REVIEWERS.md.

With spex-collab enabled, a phase split proposal is presented before implementation begins (via the before_implement hook). You confirm or adjust how tasks.md phases map to PRs, then implementation pauses after each phase. At each pause, the phase-manager command runs code review, updates REVIEWERS.md with code-specific review hints, and offers to create a PR via gh.

/speckit-implement                        # Starts with phase split proposal
/speckit-spex-collab-phase-manager        # After each phase: review, PR, pause

Without spex-collab, implementation runs straight through and code review fires automatically via spex-gates hooks after completion.

Because the spec is already reviewed and agreed, reviewers already understand the design. They can focus on whether the code correctly implements the spec rather than questioning the approach itself.

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

Context Management

Start each spec-kit/spex session in a fresh Claude Code session. The SDD workflow orchestration requires a non-fatigued context to be followed rigorously. Reusing a session that already has significant conversation history leads to the model taking shortcuts, skipping quality gates, or collapsing workflow steps. Open a new terminal or run claude fresh before starting a spec-kit workflow.

Similarly, do not accept shortcuts that Claude offers during the workflow. If the model suggests skipping a phase, combining steps, or bypassing a quality gate, decline. The phases exist for a reason: each one produces artifacts that downstream steps depend on.

Between phases (and between planning and implementation within a phase), running /clear gives each stage a fresh context window. This prevents context accumulation from degrading output quality and ensures reviewers evaluate code independently of implementation history.

When you run /clear, review commands automatically resolve the spec from the current git branch name, so no manual spec selection is needed. The spex-gates extension displays context clear recommendations at transition points.

In the /speckit-spex-ship pipeline, all review stages and the implementation stage run as isolated subagents automatically, so the orchestrator stays lightweight without manual /clear calls.

One-Shot: /speckit-spex-ship

For smaller features or solo work where intermediate review is not needed, /speckit-spex-ship chains the entire workflow from brainstorm through verification in a single session. 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["/speckit-spex-brainstorm<br>Refine idea"]
    HasClarity -->|Yes| Specify["/speckit-specify<br>Create spec"]

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

    Specify --> ReviewSpec["review-spec<br>(auto via hook)"]
    ReviewSpec --> Plan["/speckit-plan<br>Generate plan + tasks"]
    Plan --> ReviewPlan["review-plan<br>(auto via hook)"]

    ReviewPlan -->|"PR #1: [Spec]"| SpecPR([Spec Review via REVIEWERS.md])

    SpecPR -->|Feedback| Revise["/speckit-spex-collab-revise<br>Update spec + cascade"]
    Revise --> ReviewSpec
    SpecPR -->|Approved| PhaseSplit["phase-split<br>(auto via hook, spex-collab)"]
    PhaseSplit --> Implement["/speckit-implement<br>Build phase N"]
    Implement --> ReviewCode["review-code<br>(auto via hook)"]

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

    Verify -->|Yes| PhaseManager["phase-manager<br>Update REVIEWERS.md, create PR"]
    PhaseManager -->|"More phases"| Implement
    PhaseManager -->|"All done"| ImplPR([PR #2+: Implementation])
    Verify -->|Drift detected| Evolve["/speckit-spex-evolve<br>Reconcile"]

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

    Ship -->|Chains all stages| ImplPR

Loading

Quick Start

Prerequisites:

1. Claude Code installed
2. Spec-Kit installed (uv tool install specify-cli --from git+https://github.com/github/spec-kit.git or see their docs)

Install via Marketplace (recommended):

# Add the marketplace (once)
/plugin marketplace add rhuss/cc-rhuss-marketplace

# Install the plugin
/plugin install spex@cc-rhuss-marketplace

Install from source:

git clone https://github.com/rhuss/cc-spex.git
cd cc-spex
make install

Initialize your project:

/spex:init

This runs Spec-Kit's specify init, installs all six bundled extensions, and asks about permissions. After initialization, extension hooks fire automatically at spec-kit lifecycle boundaries.

The Extensions System

cc-spex uses spec-kit's native extension system. Each extension lives in spex/extensions/<ext-id>/ with an extension.yml manifest, commands, and optional config files.

Bundled Extensions

spex (core, always active): Brainstorming, ship pipeline, help, evolve, spec refactoring, flow state tracking, and lifecycle hooks (smoke test prompt via before_finish, flow state cleanup via after_finish).

spex-gates: Quality gates that fire automatically via lifecycle hooks:

• after_specify: runs spec review
• after_tasks: runs plan review
• after_implement: runs code review and verification

spex-deep-review (requires spex-gates): Multi-perspective code review with five specialized agents (correctness, architecture, security, production readiness, test quality). Critical and Important findings trigger an autonomous fix loop (up to 3 rounds). Integrates with CodeRabbit CLI when available.

spex-teams (experimental, requires spex-gates): Parallel implementation via Claude Code Agent Teams. When combined with spex-deep-review, review agents run in parallel.

spex-worktrees: Git worktree isolation for feature development. After /speckit-specify, optionally creates a sibling worktree and copies .claude/ and .specify/ config to it.

spex-collab (requires spex-gates): Collaborative PR workflows for team-based spec-driven development. Generates REVIEWERS.md review guides that help PR reviewers complete reviews within 30 minutes, and manages implementation phases with pause points between them.

• after_tasks: generates REVIEWERS.md with spec PR review guidance, offers to create a [Spec] PR
• before_implement: presents phase split proposal for implementation PRs
• phase-manager: coordinates PR creation, code review updates, and phase boundaries. After spec PR creation, suggests triage with a /loop command and delay notice. After spec triage completes, runs a gate check comparing review comment count against triage.split_threshold (default 100) to recommend continuing on the same PR or splitting into separate implementation PR(s). After implementation push, suggests triage (with deep-review first if that extension is enabled).
• revise: handles spec revision from PR review feedback, cascades to plan/tasks, runs quality gates, documents changes in revision history
• reconcile: after spec revision, scans existing implementation against revised tasks, classifies each as DONE/REWORK/NEW, and produces a delta for re-implementation
• triage: autonomously handles bot review comments (assess, apply fixes, reject with justification, reply), then interactively presents human comments for approval. Supports loop mode for continuous triage and spec-aware assessment. The triage lifecycle is integrated into the flow state with triage-spec and triage-impl phases, visible in the status line as a T badge.

Managing Extensions

specify extension list                    # Show installed extensions and status
specify extension disable spex-teams      # Disable an extension
specify extension enable spex-teams       # Re-enable an extension

Extension state is tracked in .specify/extensions/.registry.

Commands Reference

Workflow Commands

These are the commands you'll use day-to-day. The /speckit-* commands come from Spec-Kit. Extension commands use the /speckit-spex-* prefix and are registered after /spex:init.

Command	Purpose
/speckit-specify	Define requirements and create a formal spec
/speckit-plan	Generate an implementation plan from a spec
/speckit-tasks	Create actionable tasks from a plan
/speckit-implement	Build features following the plan and tasks
/speckit-constitution	Define project-wide governance principles
/speckit-clarify	Clarify underspecified areas of a spec
/speckit-analyze	Check consistency across spec artifacts
/speckit-checklist	Generate a quality validation checklist
/speckit-taskstoissues	Convert tasks to GitHub issues

Spex Extension Commands

These commands are provided by spex extensions and available after /spex:init.

Command	Extension	Purpose
/spex:init	(plugin)	Initialize Spec-Kit, install extensions, configure permissions
/speckit-spex-brainstorm	spex	Refine a rough idea into a structured brainstorm document as input for /speckit-specify
/speckit-spex-ship	spex	Run the full workflow autonomously
/speckit-spex-evolve	spex	Reconcile spec/code drift with guided resolution
/speckit-spex-clear	spex	Clear stuck state, dismiss status line
/speckit-spex-help	spex	Show a quick reference for all commands
/speckit-spex-gates-review-spec	spex-gates	Validate spec (fires automatically via hook)
/speckit-spex-gates-review-plan	spex-gates	Review plan (fires automatically via hook)
/speckit-spex-gates-review-code	spex-gates	Review code compliance (fires automatically via hook)
/speckit-spex-smoke-test	spex	Two-phase acceptance scenario walkthrough: subagent executes with fresh context, human reviews evidence interactively. Writes SMOKE-TEST.md report. Always interactive, even in ship pipeline
/speckit-spex-finish	spex	Verify + merge/PR/keep (all-in-one feature completion). Runs before_finish hooks (e.g., smoke test prompt) before verification and after_finish hooks after completion. --watch: monitor CI after PR creation, auto-fix failures
/speckit-spex-gates-stamp	spex-gates	Verification only (use finish for full flow)
/speckit-spex-deep-review-review	spex-deep-review	Multi-perspective code review with 5 agents
/speckit-spex-worktrees-manage	spex-worktrees	List, create, or clean up git worktrees
/speckit-spex-collab-reviewers	spex-collab	Generate REVIEWERS.md review guide, offer [Spec] PR (fires automatically via hook)
/speckit-spex-collab-phase-split	spex-collab	Present phase split proposal before implementation
/speckit-spex-collab-phase-manager	spex-collab	Manage phase boundaries, PR creation, and REVIEWERS.md updates
/speckit-spex-collab-revise	spex-collab	Revise spec from PR review feedback, cascade to plan/tasks, update REVIEWERS.md
/speckit-spex-collab-reconcile	spex-collab	Reconcile revised tasks against existing implementation, produce delta
/speckit-spex-collab-triage	spex-collab	Triage PR review comments: handle bot suggestions autonomously, review human comments interactively

Ship Command

/speckit-spex-ship is the autonomous full-cycle workflow that chains all stages from specification through verification. It requires both the spex-gates and spex-deep-review extensions to be enabled.

/speckit-spex-ship [brainstorm-file] [--ask always|smart|never] [--resume] [--start-from <stage>] [--create-pr] [--no-external] [--[no-]coderabbit] [--[no-]copilot]

The pipeline runs nine stages in strict order:

#	Stage	What happens
0	specify	Generate spec from brainstorm document
1	clarify	Resolve spec ambiguities (up to 5 questions)
2	review-spec	Validate spec quality and structure
3	plan	Generate implementation plan with research
4	tasks	Generate dependency-ordered task breakdown
5	review-plan	Validate plan feasibility, create REVIEWERS.md
6	implement	Execute implementation following task plan (with per-task test checkpoints)
7	review-code	Spec compliance + deep-review agents + auto-fix loop
8	smoke-test	Two-phase acceptance walkthrough: fresh-context subagent collects evidence, then human reviews interactively. Writes SMOKE-TEST.md. Pipeline announces readiness and asks for opt-in. Stops here; run /speckit-spex-finish manually

Oversight levels control how findings are handled:

Level	Unambiguous fixes	Ambiguous fixes	Blockers
always	Pause for approval	Pause	Pause
smart (default)	Auto-fix	Pause	Pause
never	Auto-fix	Auto-fix	Pause

Pipeline state is persisted to .specify/.spex-state, so interrupted runs can be resumed with --resume. Use --start-from <stage> to begin at a specific stage when artifacts from earlier stages already exist.

Backpressure loops

The ship pipeline includes two automated feedback mechanisms that catch problems early:

Per-task test checkpoints (Stage 6): After completing each task during implementation, the test suite runs automatically. If tests fail, the agent attempts to fix the regression before moving to the next task (max 2 attempts). This prevents compounding breakage where tasks 3-5 build on a broken foundation from task 2. Disable with implement.test_between_tasks: false in .specify/extensions/spex/spex-config.yml.

Mid-implementation review checkpoints (Stage 6): When spex-deep-review is enabled and a feature has 3 or more tasks, fresh-context correctness review agents are spawned at the 1/3 and 2/3 task completion marks. Each checkpoint reviews all code so far against the spec, focusing only on correctness (not architecture, security, or test quality). Findings are fixed before implementation continues, preventing drift from compounding across the remaining tasks. Checkpoint results are recorded in the state file so the final deep review can show a layer comparison of what each review layer caught. Disable with implement.review_checkpoints: false in .specify/extensions/spex/spex-config.yml.

Post-PR watch mode (Stage 8): When --create-pr is set, the finish stage automatically enters watch mode after PR creation. It polls CI status, reads failure logs, and attempts fixes within the PR's changed file set (max 2 attempts). If spex-collab is enabled, watch mode also triages new review comments via /speckit-spex-collab-triage. Watch mode exits on CI success, timeout (default 30 minutes), or when the PR is closed/merged externally. Configure timeouts and intervals in .specify/extensions/spex/spex-config.yml under watch.timeout_minutes and watch.poll_interval_seconds.

Worktree integration

When the spex-worktrees extension is enabled, the ship pipeline automatically creates a sibling worktree during Stage 0 (specify) and continues the pipeline there. Your main workspace stays on main, free for other work while ship runs in the worktree.

After the pipeline completes, you choose what to do:

• Merge to main: delegates to /speckit-spex-worktrees-manage finish (merges, removes worktree, deletes branch)
• Create PR: pushes the branch and creates a PR
• Test first: leaves everything as-is for manual testing

If worktrees are not enabled, the pipeline works in-place on the feature branch (existing behavior).

Deep Review

The deep-review process is a two-stage code review pipeline that runs automatically when the spex-deep-review extension is enabled (via the after_implement hook).

Stage 1: Spec Compliance. The code is checked against functional and non-functional requirements from the spec. If the compliance score is below 95%, the pipeline stops and reports gaps before proceeding.

Stage 2: Multi-Perspective Review. Five specialized agents analyze the codebase, each focused on a distinct concern:

Agent	Focus
Correctness	Mutation safety, shared references, logic errors, resource cleanup, null safety
Architecture & Idioms	Dead code, unnecessary complexity, duplication, misleading naming, YAGNI violations
Security	Input validation, injection risks, secret handling, authentication, RBAC scope
Production Readiness	Goroutine leaks, unbounded channels, memory patterns, observability gaps, graceful shutdown
Test Quality	Coverage gaps, weak assertions, wrong-reason passes, missing edge cases, test isolation

When the spex-teams extension is also enabled, all five agents run in parallel via Claude Code Agent Teams. Otherwise they run sequentially.

Autonomous Fix Loop. After all agents report their findings, Critical and Important issues are collected and fixed automatically (up to 3 rounds). Each round applies fixes and re-reviews only the modified files. The loop ends when no Critical or Important findings remain, or when the maximum rounds are reached.

Agent Leaderboard. After every deep review run, a per-agent statistics summary is displayed showing findings found, fixed, and remaining for each agent, plus a total row. The agent with the most findings is highlighted as MVP. In ship mode with checkpoints enabled, a layer comparison table shows what each review layer (checkpoint 1/3, checkpoint 2/3, final review) caught, including unique findings per layer.

Output. The process produces two artifacts:

• review-findings.md with detailed findings including severity, confidence, file/line, and resolution status
• An appended section in REVIEWERS.md summarizing what was found, what was fixed automatically, and what still needs human attention

Multi-Agent Support

spex supports multiple AI coding agents beyond Claude Code. The enforcement model adapts to each agent's hook API and available tools.

Supported Agents

Agent	Tool Gating	Prompt Interception	Interactive Prompts	Parallel Dispatch
Claude Code	PreToolUse hooks	UserPromptSubmit hooks	AskUserQuestion	Agent tool (teams)
Codex CLI	PreToolUse hooks	UserPromptSubmit hooks	Inline numbered list	Subagents
OpenCode	TypeScript plugin	Skill preambles	question tool	Task tool

Architecture

Enforcement logic is extracted into shared POSIX shell functions (spex/scripts/hooks/shared/). Per-agent adapters (spex/scripts/adapters/{agent}/) call the shared functions and format responses for each agent's hook API. This keeps enforcement behavior identical across agents while adapting to different hook contracts.

Agent detection follows this priority: (1) agent-specific environment variables, (2) agent directory presence (.claude/, .codex/, .opencode/), (3) --ai value from .specify/init-options.json.

Graceful Degradation

Extensions degrade gracefully on agents with fewer capabilities:

Extension	Claude Code	Codex / OpenCode
spex-gates	Full enforcement	Full enforcement
spex-collab	Full functionality	Full functionality
spex-teams	Parallel via Agent Teams	Sequential fallback
spex-worktrees	EnterWorktree tool	Manual git worktree commands
spex-deep-review	Parallel 5-agent review	Sequential single-session review

Migrating from v4.x

If you were using the traits-based v4.x, follow these steps:

1. Update the plugin:

cd cc-spex
git pull
make install

2. Migrate project config:

Run /spex:init in each project. Extensions are installed automatically. If .specify/spex-traits.json exists, a warning is printed (the old config is no longer used).

3. Update command references:

Before (v4.x)	After (v5.x)
/spex:brainstorm	/speckit-spex-brainstorm
/spex:ship	/speckit-spex-ship
/spex:review-spec	/speckit-spex-gates-review-spec (or automatic via hook)
/spex:review-code	/speckit-spex-gates-review-code (or automatic via hook)
/spex:review-plan	/speckit-spex-gates-review-plan (or automatic via hook)
/spex:evolve	/speckit-spex-evolve
/spex:stamp	/speckit-spex-gates-stamp
/spex:worktree	/speckit-spex-worktrees-manage
/spex:traits enable X	specify extension enable X
/spex:traits disable X	specify extension disable X
.specify/spex-traits.json	.specify/extensions/.registry

All /speckit-* commands remain unchanged.

Migrating from sdd (v2.x)

If you were using the previous sdd plugin, follow these steps:

1. Update the plugin:

cd cc-spex       # (formerly cc-sdd)
git pull
make install     # automatically removes old sdd plugin and marketplace

2. Migrate project config:

Run /spex:init in each project. This automatically renames .specify/sdd-traits.json to spex-traits.json and .specify/.sdd-phase to .spex-phase.

3. Update references:

Before (v2.x)	After (v3.x)
/sdd:brainstorm	/spex:brainstorm
/sdd:review-spec	/spex:review-spec
/sdd:evolve	/spex:evolve
/sdd:init	/spex:init
/sdd:traits	/spex:traits
.specify/sdd-traits.json	.specify/spex-traits.json

All /speckit-* commands remain unchanged.

Development

make validate          # Validate plugin and marketplace schemas
make test-install      # Integration test: install from local marketplace
make test-install-remote  # Integration test: install from GitHub marketplace
make release           # Pre-release checks (validate + test-install), then prints the release command

The release process:

1. Update the version in .claude-plugin/marketplace.json
2. Run make release to validate and run the full integration test
3. If all checks pass, run the printed gh release create command
4. Update the version in cc-rhuss-marketplace to match

Acknowledgements

cc-spex builds on two projects:

• Superpowers by Jesse Vincent, which provides quality gates and verification workflows for Claude Code.
• Spec-Kit by GitHub, which provides specification-driven development templates and the specify CLI.

License

Apache License 2.0. See LICENSE for details.