spec-driven-dev（规范驱动的开发）

Spec-Driven Development

You are operating in spec-driven development mode. This project uses a 6-phase pipeline with human approval gates between each phase.

Pipeline

Explore → [APPROVE] → Requirements → [APPROVE] → Design → [APPROVE] → Task Plan → [APPROVE] → Implementation → [APPROVE] → Review → [APPROVE] → Done

Each phase has a dedicated prompt template. Read the template for the current phase before generating any output.

Quick Reference

Hard rules: check status first · never skip phases · never auto-approve · save artifacts to .spec/features/<feature>/ · max 3 revisions then ask user

Config: .spec/config.yaml → context (all phases), rules.<phase> (per phase), test_skill, test_reference, docs_dir, auto_branch, branch_prefix

Phase flow: read template → generate artifact → save → artifact → present → wait for "approve" → approve

Phases

State Machine

The pipeline state is managed via a shell script. Use these commands:

# Check current phase and progress
sh ./scripts/pipeline.sh status

# Start a new feature pipeline
sh ./scripts/pipeline.sh init <feature-name>

# Start with auto-branch (creates git branch <prefix><name>)
sh ./scripts/pipeline.sh init --branch <feature-name>

# Start with worktree (creates isolated worktree in <worktree_dir>/<name>)
sh ./scripts/pipeline.sh init --worktree <feature-name>

# Register the artifact you generated for the current phase
sh ./scripts/pipeline.sh artifact [path]

# Advance to the next phase (only after user says "approve")
sh ./scripts/pipeline.sh approve

# View revision history for current or specified phase
sh ./scripts/pipeline.sh revisions [phase]

# View all features and their status
sh ./scripts/pipeline.sh history

# Check project documentation status
sh ./scripts/pipeline.sh docs-check

# Mark an implementation task as completed (enables resume)
sh ./scripts/pipeline.sh task <T-N>

# Validate config file keys and types
sh ./scripts/pipeline.sh config-check

# Inject a pre-written artifact and skip to that phase
sh ./scripts/pipeline.sh inject <phase> <path>

# Finalize branch after pipeline completes (merge, push PR, keep, or discard)
sh ./scripts/pipeline.sh finish <merge|pr|keep|discard>

Parallel Pipelines

When multiple features are active simultaneously, add --feature <name> before the command:

sh ./scripts/pipeline.sh --feature auth-flow status
sh ./scripts/pipeline.sh --feature payment approve

Without the flag, the pipeline auto-detects the active feature. If more than one is active, it will error and prompt you to use --feature.

Project Configuration

If the file .spec/config.yaml exists in the project root, read it before starting any phase. See .spec/config.yaml.example for a template with all supported keys.

Format limitation: the pipeline parser reads flat key: value pairs only. Nested YAML structures, multi-line values, and quoted strings are not supported.

Phase-specific rule keys: rules.explore, rules.requirements, rules.design, rules.task-plan, rules.implementation, rules.review, rules.docs.

Injection order: context → phase rules → template instructions.

If the file does not exist, skip this step.

Pre-flight Checklist

Before starting any pipeline work, follow these steps in order:

1. Check pipeline state: run pipeline.sh status.

- If exactly one active pipeline exists → resume from the current phase. Do NOT run init again. - If no active pipeline → proceed to step 2. - If multiple active pipelines → ask the user which feature to work on, then use --feature <name> with all subsequent commands.

1. Read project config: check if .spec/config.yaml exists.

- If yes → read it, apply context to all phases, note rules.* for each phase. - If no → proceed without config (defaults apply).

1. Check documentation (MUST — do not skip this step): run pipeline.sh docs-check.

- Docs directory missing → suggest: *"Project documentation (<docs_dir>/) not found. I can generate it to better understand your codebase. Say 'generate docs' or 'skip'."* Wait for the user's response before proceeding. This is a soft gate — the pipeline works without documentation, but the user must explicitly acknowledge (say 'generate docs' or 'skip'). - Docs exist, stale files found → suggest: *"Some docs are outdated (: days old). Regenerate before starting? Say 'update docs' or 'skip'."* Wait for the user's response. If user agrees, read ./templates/docs-maintenance.md for the Stale doc regeneration workflow. - Docs exist, all fresh → use as supplementary context for ALL phases. Read <docs_dir>/README.md for the documentation map. - If user says "generate docs" or "update docs": read ./templates/docs-maintenance.md, follow the workflow. Generated documentation files go to <docs_dir>/ (default: .spec/), NOT to .spec/features/<feature>/. - Do NOT proceed to step 4 until the user responds to the documentation suggestion.

1. Start pipeline: run pipeline.sh init <feature-name>.

For documentation generation, staleness checks, and regeneration workflows, read ./templates/docs-maintenance.md.

When to Use This Pipeline

Use the pipeline for:

• New features ("add user authentication", "implement search")
• Significant changes to existing features (new behavior, API changes, schema migrations)
• Bug fixes that require investigation and design (root cause unknown, multiple components affected)

Do NOT use the pipeline for:

• Trivial changes: typo fixes, config tweaks, single-field additions, comment updates
• Dependency updates with no code changes
• Pure refactors with no behavioral change (unless they are large and risky)

For trivial changes, just make the change directly — no pipeline needed. The skill is designed for work that benefits from structured thinking before coding.

Fast-track mode

For bug fixes with a known reproduction or other small, well-understood changes:

• All 6 phases still apply — do not skip phases.
• Each phase produces a minimal artifact: 1-paragraph exploration, 1–2 requirements, focused design (CPs only for the bug scenario), 4–5 tasks (RED→GREEN→CODE→VERIFY→GATE), brief implementation report, short review.
• Each template contains a "Fast-track mode" section with phase-specific minimums. Follow those rules when fast-track applies.

When to activate: The agent activates fast-track when the user describes a bug with a known reproduction step, or a small, scoped change where investigation is unnecessary. At the start, announce: *"Using fast-track mode — all 6 phases, minimal artifacts."* If the user says "full pipeline", switch to the standard (non-abbreviated) flow.

Scope: This pipeline is designed for a single project or monorepo. It is not intended for features that span multiple independent repositories. Within a monorepo, use one .spec/ directory at the repository root.

Rules

1. MUST check status first. Run pipeline.sh status before doing anything. Never generate phase output without checking status. If multiple active pipelines exist, use --feature <name> with all commands.
2. Never skip phases. Follow the order: explore → requirements → design → task-plan → implementation → review.
3. Never auto-approve. Wait for the user to explicitly say "approve" or equivalent.
4. Read the template. Before generating output for a phase, read the corresponding template file.
5. Save artifacts. Save phase artifacts (explore, requirements, design, task-plan, implementation, review) to .spec/features/<feature>/ and register them with pipeline.sh artifact. Project documentation (README.md, ARCHITECTURE.md, DOMAIN.md, etc.) goes to <docs_dir>/ (default: .spec/), NOT to .spec/features/<feature>/ — these are separate directories with separate purposes.
6. Each phase produces one artifact that becomes input for the next phase.
7. Artifacts are cumulative. Each phase reads all prior artifacts.
8. Revision limit. If the user rejects the same artifact 3 times in a row, stop generating and ask: "We've gone through 3 revisions — could you clarify what's missing or what direction you'd prefer?" Do not continue revising without explicit guidance. The review phase's internal fix cycle has a separate limit: maximum 3 fix cycles (see templates/review.md Iteration Workflow). After 3 fix cycles without PASS, escalate to user.
9. Surface uncertainty. If you are unsure about intent, scope, or technical approach — say so explicitly. State the assumption you would make and ask the user to confirm or correct it. Never silently assume.
10. Write in the user's language. Detect the user's language from their first message and use it for ALL pipeline artifacts and conversational replies. What stays in English: Everything else — prose, section headers, descriptions, interview questions, explanations — is written in the user's language.

- Formal grammar keywords: WHEN, SHALL, the system - Requirement IDs: REQ-X.Y - Task IDs: T-N - Instruction keywords: CRITICAL, IMPORTANT, NOTE, DO NOT, GOAL - Correctness Property format: Property N, Category, For all, Validates - Code identifiers, file paths, shell commands, Mermaid node labels - Documentation in <docs_dir>/ (.spec/) — always English (see templates/docs/README.md)

Error Recovery

• Revising an artifact: Overwrite the file, re-register with pipeline.sh artifact, and present the updated version to the user. The previous version is automatically saved as a revision in the feature’s revisions/ directory. Use pipeline.sh revisions to view past revisions.

Documentation Maintenance

After the pipeline reaches phase=done, read ./templates/docs-maintenance.md § Documentation Maintenance to check if project documentation needs updating.

Branch Finishing

After documentation maintenance is complete (or skipped), finalize the feature branch.

1. Auto-detect git state: run git branch --show-current and compare with the default branch (main/master).
2. If on a feature branch (non-default branch):

- Present 4 options to the user (in the user's language): 1. Merge locally — merge the feature branch into the base branch 2. Create PR — push branch to origin for pull request 3. Keep branch — leave as-is for manual handling 4. Discard — delete the branch and all unmerged commits - Wait for the user's choice. - Run pipeline.sh finish <merge|pr|keep|discard>.

1. If on the default branch (main/master) or git is unavailable:

- Run pipeline.sh finish keep and skip this step.

1. This is a soft suggestion, not a blocker. If the user ignores it, the pipeline is still complete.

Quick Start (for the agent)

When the user says something like "I want to add feature X":

1. Follow the Pre-flight Checklist (status → config → docs-check → init)
2. Read ./templates/explore.md — investigate the problem space (use .spec/ docs as context if available)
3. Generate the exploration document → save to .spec/features/<feature>/explore.md
4. Run pipeline.sh artifact
5. Present to user → wait for "approve"
6. Run pipeline.sh approve → phase advances to requirements
7. Read ./templates/requirements.md → follow its interview process
8. Generate the requirements document → save, register artifact, present, wait for approve
9. Repeat for design phase
10. Read ./templates/task-plan.md → generate TDD implementation plan (no code yet)
11. Save, register artifact, present, wait for approve
12. Read ./templates/implementation.md → execute the task plan (write tests, write code, mark tasks done)
13. Save implementation report, register artifact, present, wait for approve
14. Read ./templates/review.md → review the written code against all prior artifacts
15. If findings exist → agent fixes code using TDD fix plan (exploration test → fix → re-test) → re-reviews → repeats until verdict is PASS (max 3 fix cycles; escalates to user if not resolved)
16. Present final review document (verdict PASS) → wait for approve
17. After review is approved → pipeline.sh approve → pipeline complete
18. Check if documentation needs updating (see Documentation Maintenance)
19. Check if the feature branch needs finalizing (see Branch Finishing) → present options → pipeline.sh finish