Home

Spec-Driven Develop Wiki

Spec-Driven Develop is a pure-Markdown workflow system for AI coding agents. It helps Claude Code, Codex, Cursor, and other Markdown-capable agents handle large software changes through project analysis, task decomposition, progress tracking, GitHub Issue/PR execution, project governance, and adaptive control.

Use this wiki when you need a practical overview of the project, installation options, workflow phases, architecture principles, GitHub integration, and the Deep Discuss companion skill.

Quick Facts

Fact	Value
Project	Spec-Driven Develop
Repository	https://github.com/zhu1090093659/spec_driven_develop
Category	Spec-driven development workflow, AI coding agent plugin, developer productivity tool
Core format	Pure Markdown skills and references
Runtime dependency	None for the core workflow
Main platforms	Claude Code, Codex, Cursor, and other agents that can read Markdown instructions
Main workflows	Spec-Driven Develop and Deep Discuss
Current version	1.11.1
License	MIT

What Problem Does Spec-Driven Develop Solve?

AI coding agents are effective at local implementation tasks, but large changes often fail because the work starts before the system is understood. Typical failure modes include vague scope, duplicated planning, stale context between sessions, hidden architectural coupling, missing tests, and work that drifts away from the original goal.

Spec-Driven Develop turns those projects into a structured workflow:

1. Capture the high-level intent.
2. Analyze the current project.
3. Refine scope with evidence from the codebase.
4. Decompose the work into phases, tasks, dependencies, and parallel lanes.
5. Track progress in GitHub or local Markdown.
6. Execute tasks with validation and governance updates.
7. Archive the artifacts for future sessions.

When Should You Use It?

Use Spec-Driven Develop for large, multi-step implementation work:

• Rewrite a project in another language.
• Migrate a codebase to a new framework.
• Refactor an entire project or subsystem.
• Split a monolith into services.
• Introduce architecture boundaries, schemas, or durable project governance.
• Plan and execute work that needs Issues, PRs, milestones, and cross-session continuity.

Use Deep Discuss instead when the problem is still unclear and you need structured analysis before deciding what to build.

Core Concepts

Concept	Short Explanation
Spec-driven development	The agent writes and follows explicit analysis, planning, and progress artifacts before and during implementation.
S.U.P.E.R architecture	A five-principle architecture model: Single Purpose, Unidirectional Flow, Ports over Implementation, Environment-Agnostic, Replaceable Parts.
Adaptive control	A closed-loop execution model that measures plan-vs-reality drift and triggers annotation, replanning, or rescoping.
GitHub-native tracking	Tasks can become GitHub Issues, grouped by Milestones and implemented through worktrees and PRs.
Native memory first	Durable project decisions should use the active coding agent's native memory surface when available; repo-local fallback memory is explicit, not automatic.
Deep Discuss	A companion workflow for structured problem analysis, brainstorming, trade-off review, and solution design.

Wiki Guide

• Installation — install on Claude Code, Codex, Cursor, or any Markdown-capable coding agent.
• Spec-Driven-Develop-Workflow — understand the full 6-phase development pipeline.
• Deep-Discuss — use the structured discussion workflow for analysis and decisions.
• SUPER-Architecture-Principles — learn the architecture principles enforced by the workflow.
• GitHub-Issues-Projects-and-PRs — use Issues, Milestones, Projects, worktrees, and PRs.
• Adaptive-Control-and-Drift-Score — understand drift measurement and automatic correction.
• Project-Governance-and-Memory — resolve AGENTS.md, CLAUDE.md, platform rules, and native memory.
• LLM-and-AI-Search-Summary — concise facts for search engines, AI assistants, and repository directories.
• FAQ — answers to common questions.
• Chinese-Overview — 中文介绍与关键词入口。

Source of Truth

The wiki is an explanatory layer. For exact behavior, use these source files in the repository:

• README.md and README.zh-CN.md for public-facing project description.
• plugins/spec-driven-develop/skills/spec-driven-develop/SKILL.md for the core workflow.
• plugins/spec-driven-develop/skills/deep-discuss/SKILL.md for the discussion workflow.
• plugins/spec-driven-develop/skills/spec-driven-develop/references/ for GitHub integration, adaptive control, S.U.P.E.R principles, behavioral rules, and templates.

Repository

Main repository: https://github.com/zhu1090093659/spec_driven_develop