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

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