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.

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 6-phase pipeline:

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

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. 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:

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:

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/ma