@alenfitz/spec-copilot

Spec-Driven Development Framework — One package, six AI coding tools. Turn AI coding from "black-box YOLO" into "white-box step-by-step."

中文文档

Supported Tools

Quick Start

# Install — specify your tool
npx @alenfitz/spec-copilot install --tool cursor
npx @alenfitz/spec-copilot install --tool claude-code
npx @alenfitz/spec-copilot install --tool windsurf
# ... any of: opencode, claude-code, cursor, windsurf, copilot, cline

# Verify
npx @alenfitz/spec-copilot doctor

The framework auto-detects your tool on subsequent commands (update, doctor, etc.).

How It Works

1. Spec First (No Spec, No Code) — AI evaluates complexity, asks questions, generates spec in segments. No confirmed spec, no code written.
2. Task Rhythm — AI completes one atomic task, shows proof, commits immediately, then waits for you to say "continue."
3. Knowledge Flywheel — Pitfalls are logged and archived into a tag-indexed knowledge base. Next requirement reads past experience.

Commands

CLI Commands

npx @alenfitz/spec-copilot install --tool <name>    # Install framework
npx @alenfitz/spec-copilot update [--force]          # Upgrade framework
npx @alenfitz/spec-copilot sync [--tool <name>]      # Re-sync adapter files
npx @alenfitz/spec-copilot gate <name> <phase>       # Phase gate check
npx @alenfitz/spec-copilot lint <name>               # Spec completeness check
npx @alenfitz/spec-copilot agents list               # List built-in agent profiles
npx @alenfitz/spec-copilot scorecard <msg-file>      # Validate task commit self-scorecard
npx @alenfitz/spec-copilot guard status              # View guardrail status
npx @alenfitz/spec-copilot ci setup                  # Generate CI/CD config
npx @alenfitz/spec-copilot doctor                    # Health check
npx @alenfitz/spec-copilot uninstall --confirm       # Remove framework

What Gets Installed

your-project/
├── <tool-specific prompt file>        ← AI reads this
├── <tool-specific commands/>          ← Native commands (if supported)
├── README.md                          ← Auto-generated project docs
├── docs/                              ← API, architecture, deploy docs
│
└── spec_copilot/
    ├── commands/                      ← 12 command definitions
    ├── rules/
    │   ├── coding-style.md            ← Universal coding standards
    │   ├── security.md                ← Security red lines
    │   ├── project-context.md         ← Your project's tech context
    │   └── domain-rules.md            ← Business rules (you fill this)
    ├── stack-adapters/
    │   ├── _template.md               ← Template for new tech stacks
    │   └── spring-boot-vue3.md        ← Built-in adapter (example)
    ├── knowledge/index.md             ← Tag-indexed knowledge base
    ├── changes/templates/             ← spec.md / tasks.md / log.md
    ├── archives/                      ← Completed requirements
    └── scripts/                       ← Lint, gate, hook scripts

Gate System (Automated Quality Checks)

The CLI gate system blocks phase transitions until objective criteria are met:

npx @alenfitz/spec-copilot gate <name> smoke

E2E Browser Smoke

Playwright-based end-to-end verification — catches "compiles but doesn't work" issues:

• Auto-detects tech stack (Spring Boot + Vue3, Vite, etc.) and starts dev servers
• Spec-driven route extraction from spec.md + project router files
• Acceptance-driven ACxx coverage summary from the spec acceptance matrix
• Checks per page: white screen, uncaught JS errors, API failures, framework error overlays
• Zero config for common stacks, optional flags: --headed, --base-url, --no-e2e

Uses system-installed Chrome — no extra installation needed. Just have Chrome on your machine.

Contract Gate

Available in current 3.2.x releases.

The framework now blocks a frequent low-score failure mode: frontend/backend contract drift.

• Checks whether frontend request fields match backend required fields
• Flags non-snake_case request/response field names when your spec requires snake_case
• Detects hardcoded current-user / operator identity in frontend code

This turns “the UI looks complete but the API cannot actually be called” into a gate failure instead of a review surprise.

Acceptance Coverage Gate

smoke now consumes the ACxx acceptance matrix in spec.md and reports how many scenarios are fully covered, partially covered, or still missing evidence.

• happy scenarios without end-to-end closure are treated as gate failures
• rule/error scenarios show where validation or error-feedback evidence is still missing
• multi-step scenarios are now checked step by step instead of only by coarse keyword coverage
• detail-open, modal/drawer lifecycle, and list-to-detail return paths are now included in frontend interaction checks
• The goal is to turn "spec has acceptance cases" into "gate can prove whether they were exercised"

Fxx to ACxx Trace Gate

review now checks the traceability chain in both directions:

• every Fxx feature point must point to at least one real ACxx
• every ACxx must point back to at least one Fxx or Vxx
• broken trace links are treated as requirement-matching risk, not just documentation drift

Vxx Rule Coverage Gate

review now also checks whether Vxx business rules are actually grounded in implementation evidence:

• frontend / backend rule landing points must exist when the rule says they should
• trigger points and error/result evidence must be searchable
• verification can no longer be a vague placeholder like "handled in code"

Precision Mapping

review now prefers explicit spec matrices before falling back to fuzzy grep:

• API coverage checks use 前端调用方 and 后端实现入口 from the spec matrix when available
• this reduces false positives on frontend/backend matching

Rule-Check DSL

The spec template now supports a small RULE-CHECK YAML block for Vxx rules.

• it is a lightweight execution-oriented template, not a full test framework yet
• review validates whether the block is structurally complete and aligned with the referenced Vxx
• field-based rules now also need to line up with the API field checklist, so the DSL is no longer detached from the contract
• field-based rules can now bind api: APIxx, allowing the gate to check whether those fields really land in the mapped frontend caller and backend entrypoint
• smoke/e2e now also tries to collect runtime evidence for RULE-CHECK; when an AC scenario really hits the bound API but the request fields or error message drift from the spec, the gate will surface it directly
• state_transition and idempotent now also have first-pass runtime evidence support; prefer declaring field/from/to and key/repeat explicitly
• for idempotent, if the AC scenario explicitly describes repeat submission, smoke can now better distinguish frontend anti-double-submit behavior from actual duplicate requests reaching the backend
• for real business validation, prefer adding final_state, second_request, duplicate_status, and duplicate_message so the gate output is closer to business acceptance language

Guard System (v2.6.0) — Code-Enforced Guardrails

AI tools ignore prompt-based rules. Guard uses hash verification at gate time — AI can modify files, but modified files fail the gate:

npx @alenfitz/spec-copilot guard install    # Initialize protection (record hashes)
npx @alenfitz/spec-copilot guard status     # View protection & integrity status
npx @alenfitz/spec-copilot guard lock       # Lock files (record hash, auto by phase)
npx @alenfitz/spec-copilot guard unlock     # Human unlock (clear hash record)

Gate blocks when protected files are tampered:

• ❌ Modifying spec.md after approval (auto-locked when gate passes)
• ❌ Modifying domain-rules.md / project-context.md (permanently protected)
• ❌ Committing skeleton .vue components (optional git hook)

Zero dependencies: no git, no chmod, no special permissions. Works on all platforms. Works with all AI tools: Claude Code, Cursor, Windsurf, Copilot, Cline, opencode. Human unlock: spec-copilot guard unlock <file>.

Complexity Tiers

Upgrade Safety

• Overwritten: coding-style.md, security.md, templates, scripts, commands, built-in adapters
• Skipped by default: prompt file (use --force)
• Never touched: project-context.md, domain-rules.md, knowledge/, changes/, archives/, custom adapters

Related Packages

• @alenfitz/opencode-copilot — opencode-only version
• @alenfitz/spec-driven-dev — Claude Code-only version (legacy)

License

MIT