@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
• 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.

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