Spec-Driven Develop: A Markdown Workflow Layer for AI Coding Agents

The problem: agents start coding before the plan exists

The repository targets a specific failure pattern. A developer tells an agent to rewrite a project in Rust or migrate to a microservice architecture, and the agent begins editing files. The README frames the project as a response to exactly this: it turns large software changes into a spec-driven loop covering project analysis, task decomposition, GitHub Issue and PR tracking, progress continuity, and adaptive control. The stated audience is developers using AI coding agents for migrations, rewrites, refactors, architecture changes, and complex implementation plans. That list matters. Spec-Driven Develop is not positioned as a general coding assistant enhancement. It is scoped to work where the cost of a wrong architectural assumption is measured in days, not keystrokes. If your task is renaming a function or adding a test, the seven-phase pipeline is overhead with no matching benefit. The project's own phase list starts with a one-to-two sentence intent capture and then moves into deep analysis before any code is written, which tells you the intended unit of work is a project-scale change.

The seven-phase pipeline and what each phase produces

The README gives the pipeline explicitly as Phases 0 through 6. Phase 0 is Quick Intent Capture, one or two sentences of high-level direction. Phase 1 is Deep Analysis: architecture analysis, module inventory, and risk assessment, with what the README calls a S.U.P.E.R health evaluation. Phase 2 is Intent Refinement, which asks targeted questions grounded in that analysis and confirms scope, priorities, and constraints. Phase 3 is Task Decomposition, breaking work into phases, tasks, and parallel lanes, with each task annotated with S.U.P.E.R design drivers, plus planning of delivery batches and creation of GitHub trackers. Phase 4 is Progress Tracking, generating a MASTER.md file as either a GitHub index or a local tracker. Phase 5 is Confirm and Execute: present the plan summary, get confirmation, execute tasks in parallel or sequentially, integrate coherent multi-Issue delivery batch PRs, and run an adaptive control feedback loop. Phase 6 is Archive, preserving artifacts for traceability. Note the ordering. Confirmation comes after planning and before execution, and the plan is written to a file rather than held in context. That is the mechanism that separates this from simply prompting an agent to think step by step.

Orchestrator-centric execution and the tier system added in v1.15.0

Version 1.15.0 changed the execution model, and the release notes describe it as orchestrator-centric. The main agent owns progress and quality, and sub-agent dispatch is treated as an economic decision rather than a default. Orchestrator-direct execution, called Tier 0, is the norm. A single task-executor coder, Tier 1, handles large or context-heavy batches. Tier 2 parallel lanes carry four stated preconditions: disjoint file sets, at least L effort per lane, independent verifiability, and a maximum of four lanes. Review is tiered along the same lines. Machine validation is L1 and the orchestrator's own diff review is L2, and those are the default. An independent code-reviewer agent, L3, is reserved for Tier 2 lanes and high-risk changes. The README states that reviewer agents verify lane diffs against acceptance criteria and commit fixes directly to lane branches, and that only APPROVED or FIXED lanes integrate. This is the most concrete part of the design. The four-lane cap and the disjoint-file requirement are constraints a reader can check against their own repository before adopting, which is more than most prompt collections offer.

GitHub-native tracking and why batches replace per-Issue PRs

When a GitHub repository is detected, the workflow creates an Issue for every task, organized with Milestones, one per phase, Labels for priority, size, and lane, and optionally a GitHub Projects board. Version 1.14.0 added delivery batches. Before implementation, the workflow reviews the complete phase Issue set and groups related work by dependencies, shared files or contracts, validation, review scope, and rollback boundaries. Issues stay atomic as acceptance and telemetry records, while the delivery batch owns the integration branch, aggregate validation, and the PR. The README states the default is one coherent, reviewable batch PR per phase rather than one PR per Issue. This is a defensible position and also a debatable one. A batch PR is easier to review as a unit and easier to roll back, but it concentrates risk: if one Issue in the batch is wrong, the whole phase integration is suspect. The workflow's answer is the rollback-boundary grouping criterion, which at least names the problem. Whether it solves it depends on how honestly the grouping is done, and that is a judgement the agent makes, not a rule the code enforces.

Installation is a file copy, and that is the whole dependency story

The README states there is no SDK and no third-party runtime dependencies, and the repository is described as pure Markdown skills plus small helper scripts. Version 1.15.0 added a script named scripts/install-agents.sh which syncs the bundled skills to the ~/.agents/skills directory for agents that read that shared location. The README also refers to optional Claude Code, Codex, and OpenCode plugin integration. Beyond that, the supplied material does not give a full install command sequence, so anyone adopting this should read the repository's Installation section directly rather than rely on a summary. One structural change is worth flagging: the plugin is now skills-only, meaning workflows are invoked through skills rather than slash commands. If you have notes or scripts from an earlier version that call slash commands, those invocations will not match the current surface. The three skills are Spec-Driven Develop for the full pipeline, Deep Discuss for structured problem analysis and solution design, and Review SPD, invoked as review-spd, for findings-first review of uncommitted changes, date-range commits, and branch or PR diffs.

The single-sourcing rule and what it costs to maintain

Version 1.15.0 introduced a style rule the README calls single-sourcing: every sentence in a prompt is a rule, a contract, or a pointer, and each topic is defined in exactly one canonical reference. This is a maintenance decision as much as a writing one. It means the prompts are meant to be edited like code, with one authoritative location per concept, and it implies that contributors who duplicate an explanation across skills are creating a defect. The practical consequence for adopters is that updating the workflow means editing Markdown, reviewing the change for duplication, and re-syncing with scripts/install-agents.sh. There is no compiled artifact and no version pinning mechanism described in the material, so a team that copies these skills into a repository inherits the maintenance burden of keeping its copy current as releases land. The release cadence visible here is roughly two to three weeks between v1.13.1, v1.14.0, and v1.15.0, and v1.15.0 changed both the execution model and the invocation surface. Budget for re-reading the changelog before each upgrade.

Where this is the wrong tool, and what to use instead

The clearest limitation is that nothing here enforces itself. The phases, the tier preconditions, the four-lane cap, and the batch grouping criteria are text that an agent reads and follows. An agent that skips Phase 2 or declares four overlapping lanes still produces output, and the workflow has no gate that stops it. The README's own framing supports this reading: the adaptive control feedback loop is a described behaviour, not a described enforcement mechanism. The second limitation is scope. For a single-file change, running Phase 0 through Phase 6 and writing a MASTER.md costs more than the change itself. Compare this with a conventional specification toolchain such as OpenAPI plus a code generator for API work, or a task runner like Make for build orchestration. Those tools fail loudly when the spec and the artifact disagree, because a machine parses both sides. Spec-Driven Develop has no parser. Its guarantee is that a well-behaved agent will follow a written process, which is a weaker guarantee than a build failure but applies to a much wider class of work, including the architectural changes that no schema can describe. Pick the tool that matches whether your correctness condition is mechanical or editorial.

Editorial conclusion

Spec-Driven Develop fits teams already running Claude Code, Codex, OpenCode, or Cursor who want a repeatable planning and tracking structure for migrations, rewrites, and other multi-week changes, and who accept that the enforcement is textual rather than mechanical. It is the wrong choice for small, single-file edits, and for anyone who wants the tool to gate execution on its own. Before adopting, verify the skills-only invocation path in v1.15.0, read the single-sourcing rule that governs how prompts are maintained, and confirm which of the three skills you actually need rather than installing all of them.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zhu1090093659/spec_driven_develop on GitHub