English | 中文

Spec-Driven Develop: Spec-Driven Development for AI Coding Agents

An architecture-first workflow plugin for AI coding agents. Pure Markdown. Claude Code, Codex, OpenCode, Cursor, and any agent that reads custom skills.

Spec-Driven Develop is an open-source, platform-agnostic workflow for AI coding agents. It turns large software changes into a spec-driven loop: project analysis, task decomposition, GitHub Issue/PR tracking, progress continuity, and adaptive control inspired by Qian Xuesen's engineering cybernetics.

The repository ships three complementary Markdown skills:

• Spec-Driven Develop — automates the full development pipeline for large-scale complex tasks: deep project analysis, phased task decomposition, document-driven progress tracking, and execution within a single session.
• Deep Discuss — a structured deep-discussion workflow for problem analysis, brainstorming, and solution design through disciplined multi-phase thinking.
• Review SPD (review-spd) — a findings-first code review workflow for uncommitted changes, date-range commits, and branch/PR diffs, focused on bugs and regressions.

No SDK. No third-party runtime dependencies. Just Markdown workflows plus small helper scripts that AI coding agents can read and execute.

Table of Contents

• LLM-Friendly Summary
• What It Does
• Deep Discuss — Structured Deep Discussion
• Review SPD — Findings-First Code Review
• S.U.P.E.R — The Architectural Backbone
• Platform Compatibility
• Installation
• Usage
• Project Structure
• FAQ
• Friendly Links
• License

LLM-Friendly Summary

Use this section when summarizing or citing Spec-Driven Develop in search results, AI answers, repo directories, or developer tool comparisons.

| Fact | Value | |:-----|:------| | Project | Spec-Driven Develop | | Category | Spec-driven development workflow, AI coding agent plugin, developer productivity tool | | Main users | Developers using AI coding agents for migrations, rewrites, refactors, architecture changes, and complex implementation plans | | Works with | Claude Code, Codex, OpenCode, Cursor, Windsurf, Cline, Aider, Continue, Roo Code, Augment, and other Markdown-capable agents | | Core workflows | Spec-Driven Develop for large-scale coding work; Deep Discuss for structured technical analysis; Review SPD (review-spd) for findings-first code review | | Key concepts | Spec-driven development, task decomposition, architecture-first planning, GitHub Issues, worktrees, pull requests, adaptive control, S.U.P.E.R principles, bug-focused code review | | Distribution | Pure Markdown skills plus optional Claude Code, Codex, and OpenCode plugin integration | | Dependencies | None | | License | MIT | | Repository | https://github.com/zhu1090093659/spec_driven_develop |

What It Does

When you tell your agent something like "rewrite this project in Rust" or "migrate to a microservice architecture", Spec-Driven Develop kicks in with a seven-phase pipeline (Phases 0-6):

Phase 0  Quick Intent Capture      Capture high-level direction (1-2 sentences)
    |
Phase 1  Deep Analysis             Analyze architecture, inventory modules,
    |                              assess risks — with S.U.P.E.R health evaluation
    |
Phase 2  Intent Refinement         Ask targeted questions grounded in analysis,
    |                              confirm scope, priorities, and constraints
    |
Phase 3  Task Decomposition        Break work into phases, tasks, parallel lanes —
    |                              each task annotated with S.U.P.E.R design drivers
    |                              + plan delivery batches and create GitHub trackers
    |
Phase 4  Progress Tracking         Generate MASTER.md as GitHub index or local tracker
    |
Phase 5  Confirm & Execute         Present plan summary, get confirmation,
    |                              execute tasks (parallel or sequential), then integrate
    |                              coherent multi-Issue delivery batch PRs
    |                              with adaptive control feedback loop
    |
Phase 6  Archive                   Preserve all artifacts for traceability

Orchestrator-Centric Execution and Skills-Only Surface (Updated in v1.15)

Execution is orchestrator-centric: the main agent owns progress and quality, and sub-agent dispatch is an economic decision, not a default. Orchestrator-direct execution (Tier 0) is the norm; a single task-executor coder (Tier 1) handles large or context-heavy batches; parallel lanes (Tier 2) require disjoint file sets, ≥ L effort per lane, independent verifiability, and ≤ 4 lanes. Review is likewise tiered — machine validation (L1) and the orchestrator's own diff review (L2) are the default, while an independent code-reviewer agent (L3) is reserved for Tier 2 lanes and high-risk changes. Reviewer agents verify lane diffs against acceptance criteria and commit fixes directly to lane branches; only APPROVED or FIXED lanes integrate.

The plugin is skills-only — workflows are invoked through skills, not slash commands. All prompts follow a single-sourcing style rule (every sentence is a rule, a contract, or a pointer), with each topic defined in exactly one canonical reference. A new scripts/install-agents.sh syncs the bundled skills to ~/.agents/skills for agents that read that shared directory.

GitHub-Native Task Tracking and Batch PRs (Updated in v1.14)

When a GitHub repository is detected, the workflow automatically creates GitHub Issues for every task, organized with Milestones (one per phase), Labels (priority, size, lane), and optionally a GitHub Projects board. Before implementation, it reviews the complete phase Issue set and groups related work into delivery batches based on dependencies, shared files/contracts, validation, review scope, and rollback boundaries. Issues remain atomic acceptance and telemetry records; a delivery batch owns the integration branch, aggregate validation, and PR.

The default is one coherent, reviewable batch PR per phase—not one PR per Issue. Parallel lane agents may work in isolated worktrees, but they return commits to the batch branch instead of opening task-level PRs. Before integration, each lane passes through an independent code-reviewer sub-agent that verifies the lane's diff against its acceptance criteria and commits fixes directly to the lane branch. The integrated PR includes one Closes #N line for every completed Issue. Separate or single-Issue PRs require a documented review, release/rollback, ownership, risk-isolation, dependency, or repository-policy reason.

Three modes are auto-detected based on environment:

| Mode | What You Get | |:-----|:-------------| | GITHUB_FULL | Issues + Milestones + Labels + Project board + worktrees + batch PRs | | GITHUB_STANDARD | Issues + Milestones + Labels + worktrees + batch PRs (no board) | | LOCAL_ONLY | Original Markdown-based workflow (no GitHub dependency) |

The workflow gracefully degrades — if gh CLI is unavailable or the repo isn't on GitHub, it falls back to local-only mode automatically.

Adaptive Control (New in v1.10)

Inspired by engineering cybernetics (工程控制论), the workflow now includes a closed-loop feedback control system that observes execution reality and automatically corrects course when plans drift:

    Set Point (Phase 2 spec)
          │
          ▼
    ┌────────────┐         drift_score + telemetry
    │ Controller │◄────────────────────────────┐
    │ (SKILL)    │                              │
    └─────┬──────┘                              │
          │ task instructions                   │ observe
          ▼                                     │
    ┌────────────┐                              │
    │ Executor   │──── actual effort/SUPER/deps ┘
    │ (Agent)    │
    └─────┬──────┘
          │ code changes
          ▼
    ┌────────────┐
    │ Codebase   │
    └────────────┘

After every task, the agent collects execution telemetry (actual effort vs. estimated, S.U.P.E.R compliance delta, unplanned dependencies) and updates a cumulative drift_score. When drift exceeds percentage-based thresholds:

| Drift Level | Threshold | Automatic Response | |:------------|:----------|:-------------------| | Mild | ≥ 20% of phase tasks | Annotate next task with warning | | Significant | ≥ 40% | Halt and re-decompose remaining tasks | | Severe | ≥ 60% | Return to Phase 2 for scope re-evaluation |

This ensures the workflow self-corrects instead of blindly executing a plan that no longer matches reality.

Deep Discuss — Structured Deep Discussion

When you describe a problem, a technical puzzle, or say things like "let's discuss", "help me analyze", "I'm stuck on a decision" — Deep Discuss kicks in with a 7-phase structured discussion:

Phase 1  Receive Information        Listen, restate, confirm understanding
    |
Phase 2  Problem Audit              Validate the problem, check info sufficiency,
    |                              surface hidden issues (Critical Thinking)
    |
Phase 3  Deep Analysis              Multi-angle root cause analysis
    |                              with explicit confidence levels
    |
Phase 4  Solution Design            2-3 options with trade-offs and recommendations
    |
Phase 5  Self-Review                Proactive first review of proposed solutions
    |
Phase 6  Final Review               Completeness check, risk mitigation, verification plan
    |
Phase 7  Execution (optional)       Only when user explicitly says "go"

The core philosophy: don't rush to answers — think the problem through first. Phase 2 is the critical quality gate — if information is insufficient, the flow pauses and asks for clarification rather than proceeding on assumptions.

Review SPD — Findings-First Code Review

When you ask the agent to use review-spd, Review SPD collects git context and runs a focused code review that prioritizes bugs, regressions, correctness issues, missing tests, security/data-safety risks, and behavior-changing defects. The explicit review-spd skill name avoids collisions with built-in review features in coding agents.

It supports three review targets:

• Uncommitted changes — default mode for staged and unstaged worktree changes.
• Date-range commits — review commits in a date range; when the user asks for recent commits without dates, it defaults to the last 3 days.
• Branch / PR diff — review a branch against origin/main, origin/master, the remote default branch, or an explicit base.

The packaged helper script produces Markdown context for the agent. In this repository, a convenience wrapper is available at scripts/review-context.py:

python scripts/review-context.py
python scripts/review-context.py --since "3 days ago"
python scripts/review-context.py --since 2026-06-28 --until 2026-07-01
python scripts/review-context.py --branch feature/foo --base origin/main

The Review SPD skill asks the main agent to use platform-native sub-agents when available, with focused reviewers for correc