Skip to content
Back to search

spec-driven-develop

MarketplaceWorks with Claude CodeGitHub

Spec-driven development workflow for AI coding agents: architecture-first planning, task decomposition, GitHub Issue/PR tracking, Deep Discuss, and adaptive control for Claude Code, Codex, Cursor, and other Markdown-capable agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhu1090093659--spec-driven-develop/badge.svg)](/listings/zhu1090093659--spec-driven-develop)

HTML

<a href="/listings/zhu1090093659--spec-driven-develop"><img src="/api/listings/zhu1090093659--spec-driven-develop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Claude Code

/plugin marketplace add zhu1090093659/spec_driven_develop
/plugin install spec-driven-develop@spec-driven-develop

After installation, run `/reload-plugins` to activate.

Codex CLI

This repository includes Codex plugin metadata at `.agents/plugins/marketplace.json` and `plugins/spec-driven-develop/.codex-plugin/plugin.json`.

Install the Codex plugin marketplace from GitHub:

codex plugin marketplace add zhu1090093659/spec_driven_develop --ref main

Then enable `Spec-Driven Develop` from the Codex plugin UI. If your Codex client does not expose the plugin UI yet, add this to `~/.codex/config.toml`:

[plugins."spec-driven-develop@spec-driven-develop"]
enabled = true

Alternative: install only the core skill with the built-in skill installer inside a Codex session:

$skill-installer install https://github.com/zhu1090093659/spec_driven_develop/tree/main/plugins/spec-driven-develop/skills/spec-driven-develop

Or install via shell:

bash <(curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/scripts/install-codex.sh)

opencode / OpenCode

This repository includes an opencode plugin entrypoint at `plugins/spec-driven-develop/opencode-plugin.js`. The installer copies the plugin bundle under `~/.config/opencode/vendor/` and creates an auto-loaded plugin file in `~/.config/opencode/plugins/`.

Install globally:

bash <(curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/scripts/install-opencode.sh)

Or install from a local clone:

git clone https://github.com/zhu1090093659/spec_driven_develop.git
bash spec_driven_develop/scripts/install-opencode.sh

For project-local installation, add the plugin file directly in `opencode.json`:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "file:///absolute/path/to/spec_driven_develop/plugins/spec-driven-develop/opencode-plugin.js"
  ]
}

Quit and restart opencode after installation or config changes. opencode loads plugins only at startup.

Cursor

bash <(curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/scripts/install-cursor.sh)

Or clone the repo and run locally:

git clone https://github.com/zhu1090093659/spec_driven_develop.git
bash spec_driven_develop/scripts/install-cursor.sh

Other Agents (Generic)

For any other coding agent, grab the SKILL file and place it where your agent reads instructions:

# Download the SKILL.md
curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/plugins/spec-driven-develop/skills/spec-driven-develop/SKILL.md -o SKILL.md

Where to place it depends on your agent:

| Agent | Location | |---|---| | Windsurf | `.windsurf/skills/` or project rules | | Cline | `.cline/skills/` or custom instructions | | Aider | Reference via `.aider.conf.yml` or paste into chat | | Continue | `.continue/` config or system prompt | | Others | Wherever your agent reads custom instructions or system prompts |

If your agent doesn't have a formal "skills" directory, you can paste the content of `SKILL.md` into its system prompt or custom instructions field — the effect is the same.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 36 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "spec-driven-develop",
  3. "owner": {
  4. "name": "zhu1090093659"
  5. },
  6. "metadata": {
  7. "description": "Automates project analysis, task decomposition, project governance, progress tracking, and execution for large-scale complex tasks"
  8. },
  9. "plugins": [
  10. {
  11. "name": "spec-driven-develop",
  12. "source": "./plugins/spec-driven-develop",
  13. "description": "Three complementary AI agent skills: (1) Spec-Driven Develop — automates full development workflow for large-scale complex tasks: project analysis, task decomposition, project governance, progress tracking, and execution; (2) Deep Discuss — structured deep discussion for problem analysis, brainstorming, and solution design; (3) Review SPD — findings-first code review for uncommitted changes, date-range commits, and branch/PR diffs.",
  14. "version": "1.15.0",
  15. "author": {
  16. "name": "zhu1090093659"
  17. },
  18. "homepage": "https://github.com/zhu1090093659/spec_driven_develop",
  19. "repository": "https://github.com/zhu1090093659/spec_driven_develop",
  20. "license": "MIT",
  21. "keywords": [
  22. "spec-driven",
  23. "workflow",
  24. "planning",
  25. "task-decomposition",
  26. "project-analysis",
  27. "deep-discuss",
  28. "brainstorming",
  29. "problem-analysis",
  30. "code-review",
  31. "review-spd",
  32. "bug-risk"
  33. ]
  34. }
  35. ]
  36. }
README.md · README · 488 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. **English** | [中文](./README.zh-CN.md)
  2. [![GitHub stars](https://img.shields.io/github/stars/zhu1090093659/spec_driven_develop?style=social)](https://github.com/zhu1090093659/spec_driven_develop/stargazers)
  3. [![Forks](https://img.shields.io/github/forks/zhu1090093659/spec_driven_develop?style=social)](https://github.com/zhu1090093659/spec_driven_develop/fork)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  5. [![Platform](https://img.shields.io/badge/Platform-Claude%20Code%20%7C%20Codex%20%7C%20OpenCode%20%7C%20Cursor-FF6B6B.svg)](https://github.com)
  6. # Spec-Driven Develop: Spec-Driven Development for AI Coding Agents
  7. **An architecture-first workflow plugin for AI coding agents. Pure Markdown. Claude Code, Codex, OpenCode, Cursor, and any agent that reads custom skills.**
  8. 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.
  9. The repository ships three complementary Markdown skills:
  10. - **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.
  11. - **Deep Discuss** — a structured deep-discussion workflow for problem analysis, brainstorming, and solution design through disciplined multi-phase thinking.
  12. - **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.
  13. No SDK. No third-party runtime dependencies. Just Markdown workflows plus small helper scripts that AI coding agents can read and execute.
  14. ## Table of Contents
  15. - [LLM-Friendly Summary](#llm-friendly-summary)
  16. - [What It Does](#what-it-does)
  17. - [Deep Discuss — Structured Deep Discussion](#deep-discuss--structured-deep-discussion)
  18. - [Review SPD — Findings-First Code Review](#review-spd--findings-first-code-review)
  19. - [S.U.P.E.R — The Architectural Backbone](#super--the-architectural-backbone)
  20. - [Platform Compatibility](#platform-compatibility)
  21. - [Installation](#installation)
  22. - [Usage](#usage)
  23. - [Project Structure](#project-structure)
  24. - [FAQ](#faq)
  25. - [Friendly Links](#friendly-links)
  26. - [License](#license)
  27. ## LLM-Friendly Summary
  28. Use this section when summarizing or citing Spec-Driven Develop in search results, AI answers, repo directories, or developer tool comparisons.
  29. | Fact | Value |
  30. |:-----|:------|
  31. | Project | Spec-Driven Develop |
  32. | Category | Spec-driven development workflow, AI coding agent plugin, developer productivity tool |
  33. | Main users | Developers using AI coding agents for migrations, rewrites, refactors, architecture changes, and complex implementation plans |
  34. | Works with | Claude Code, Codex, OpenCode, Cursor, Windsurf, Cline, Aider, Continue, Roo Code, Augment, and other Markdown-capable agents |
  35. | 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 |
  36. | 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 |
  37. | Distribution | Pure Markdown skills plus optional Claude Code, Codex, and OpenCode plugin integration |
  38. | Dependencies | None |
  39. | License | MIT |
  40. | Repository | <https://github.com/zhu1090093659/spec_driven_develop> |
  41. ## What It Does
  42. 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):
  43. ```
  44. Phase 0 Quick Intent Capture Capture high-level direction (1-2 sentences)
  45. |
  46. Phase 1 Deep Analysis Analyze architecture, inventory modules,
  47. | assess risks — with S.U.P.E.R health evaluation
  48. |
  49. Phase 2 Intent Refinement Ask targeted questions grounded in analysis,
  50. | confirm scope, priorities, and constraints
  51. |
  52. Phase 3 Task Decomposition Break work into phases, tasks, parallel lanes —
  53. | each task annotated with S.U.P.E.R design drivers
  54. | + plan delivery batches and create GitHub trackers
  55. |
  56. Phase 4 Progress Tracking Generate MASTER.md as GitHub index or local tracker
  57. |
  58. Phase 5 Confirm & Execute Present plan summary, get confirmation,
  59. | execute tasks (parallel or sequential), then integrate
  60. | coherent multi-Issue delivery batch PRs
  61. | with adaptive control feedback loop
  62. |
  63. Phase 6 Archive Preserve all artifacts for traceability
  64. ```
  65. ### Orchestrator-Centric Execution and Skills-Only Surface (Updated in v1.15)
  66. 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.
  67. 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.
  68. ### GitHub-Native Task Tracking and Batch PRs (Updated in v1.14)
  69. 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.
  70. 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.
  71. Three modes are auto-detected based on environment:
  72. | Mode | What You Get |
  73. |:-----|:-------------|
  74. | **GITHUB_FULL** | Issues + Milestones + Labels + Project board + worktrees + batch PRs |
  75. | **GITHUB_STANDARD** | Issues + Milestones + Labels + worktrees + batch PRs (no board) |
  76. | **LOCAL_ONLY** | Original Markdown-based workflow (no GitHub dependency) |
  77. The workflow gracefully degrades — if `gh` CLI is unavailable or the repo isn't on GitHub, it falls back to local-only mode automatically.
  78. ### Adaptive Control (New in v1.10)
  79. 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:
  80. ```
  81. Set Point (Phase 2 spec)
  82. │
  83. ▼
  84. ┌────────────┐ drift_score + telemetry
  85. │ Controller │◄────────────────────────────┐
  86. │ (SKILL) │ │
  87. └─────┬──────┘ │
  88. │ task instructions │ observe
  89. ▼ │
  90. ┌────────────┐ │
  91. │ Executor │──── actual effort/SUPER/deps ┘
  92. │ (Agent) │
  93. └─────┬──────┘
  94. │ code changes
  95. ▼
  96. ┌────────────┐
  97. │ Codebase │
  98. └────────────┘
  99. ```
  100. 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:
  101. | Drift Level | Threshold | Automatic Response |
  102. |:------------|:----------|:-------------------|
  103. | Mild | ≥ 20% of phase tasks | Annotate next task with warning |
  104. | Significant | ≥ 40% | Halt and re-decompose remaining tasks |
  105. | Severe | ≥ 60% | Return to Phase 2 for scope re-evaluation |
  106. This ensures the workflow **self-corrects** instead of blindly executing a plan that no longer matches reality.
  107. ## Deep Discuss — Structured Deep Discussion
  108. 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:
  109. ```
  110. Phase 1 Receive Information Listen, restate, confirm understanding
  111. |
  112. Phase 2 Problem Audit Validate the problem, check info sufficiency,
  113. | surface hidden issues (Critical Thinking)
  114. |
  115. Phase 3 Deep Analysis Multi-angle root cause analysis
  116. | with explicit confidence levels
  117. |
  118. Phase 4 Solution Design 2-3 options with trade-offs and recommendations
  119. |
  120. Phase 5 Self-Review Proactive first review of proposed solutions
  121. |
  122. Phase 6 Final Review Completeness check, risk mitigation, verification plan
  123. |
  124. Phase 7 Execution (optional) Only when user explicitly says "go"
  125. ```
  126. 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.
  127. ## Review SPD — Findings-First Code Review
  128. 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.
  129. It supports three review targets:
  130. - **Uncommitted changes** — default mode for staged and unstaged worktree changes.
  131. - **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.
  132. - **Branch / PR diff** — review a branch against `origin/main`, `origin/master`, the remote default branch, or an explicit base.
  133. The packaged helper script produces Markdown context for the agent. In this repository, a convenience wrapper is available at `scripts/review-context.py`:
  134. ```bash
  135. python scripts/review-context.py
  136. python scripts/review-context.py --since "3 days ago"
  137. python scripts/review-context.py --since 2026-06-28 --until 2026-07-01
  138. python scripts/review-context.py --branch feature/foo --base origin/main
  139. ```
  140. The Review SPD skill asks the main agent to use platform-native sub-agents when available, with focused reviewers for correctness, regression compatibility, tests, security/data safety, and performance/concurrency. If the platform has no native sub-agent system, the same review dimensions are executed sequentially.
  141. ## S.U.P.E.R — The Architectural Backbone
  142. S.U.P.E.R is not a footnote — it is the design philosophy that drives every phase of the workflow and every line of code the agent produces.
  143. > Write code like building with LEGO — each brick has a single job, a standard interface, a clear direction, runs anywhere, and can be swapped at will.
  144. | Principle | Meaning | How It's Enforced |
  145. |:----------|:--------|:------------------|
  146. | **S**ingle Purpose | One module, one job | Analysis phase rates each module's single-responsibility compliance. Tasks that span multiple concerns get decomposed further. |
  147. | **U**nidirectional Flow | Data flows one way | Architecture health check flags circular dependencies. Dependencies must point inward — outer layers depend on inner, never the reverse. |
  148. | **P**orts over Implementation | Contracts before code | Module inventory evaluates whether I/O is schema-defined. Task breakdown requires interface contracts before implementation tasks. |
  149. | **E**nvironment-Agnostic | Runs anywhere | Risk assessment catches hardcoded config and platform-specific assumptions. Config must come from environment variables or config files. |
  150. | **R**eplaceable Parts | Swap without ripple | Each module is rated by replacement cost. If swapping a component causes cascading changes, the architecture is broken. |
  151. ### Where S.U.P.E.R Shows Up
  152. S.U.P.E.R isn't just a reference document the agent might read — it's woven into the workflow at every level:
  153. - **Phase 1 — Analysis**: Every module gets a per-principle compliance score (`S🟢 U🟡 P🔴 E🟢 R🟡`). The risk assessment includes a S.U.P.E.R Architecture Health Summary with violation hotspots.
  154. - **Phase 2 — Intent Refinement**: Analysis findings are presented to the user so they can make informed decisions about scope and S.U.P.E.R priorities before task decomposition begins.
  155. - **Phase 3 — Planning**: Each task is annotated with its S.U.P.E.R design drivers (which principles matter most for that task). Early phases prioritize fixing violation hotspots before building new features.
  156. - **Phase 5 — Execution**: The S.U.P.E.R Code Review Checklist is run after every task before marking it complete. The adaptive control loop collects S.U.P.E.R compliance scores as part of execution telemetry:
  157. | Check | Principle |
  158. |:------|:----------|
  159. | Every new module/file has exactly one responsibility | S |
  160. | No function does more than one conceptual thing | S |
  161. | Data flows input → processing → output, no reverse deps | U |
  162. | No circular imports introduced | U |
  163. | Cross-module interfaces are schema-defined | P |
  164. | Module I/O is serializable | P |
  165. | No hardcoded paths, URLs, keys, or config values | E |
  166. | All new dependencies explicitly declared | E |
  167. | New modules can be replaced without changes to others | R |
  168. | All tests pass after the change | — |
  169. **All pass = proceed. 1-2 fail = fix before marking complete. 3+ fail = stop and refactor.**
  170. ## Platform Compatibility
  171. The SKILL prompt is written in a generic, platform-neutral way. It gracefully degrades on platforms without certain capabilities — for example, if sub-agents aren't available, it falls back to sequential execution automatically.
  172. **Tested platforms with install scripts:**
  173. - **Claude Code** — installed as a plugin (with enhanced sub-agent support)
  174. - **Codex (OpenAI)** — installed as a Codex plugin or directly as a skill
  175. - **opencode / OpenCode** — installed as an auto-loaded plugin with bundled skills and sub-agents
  176. - **Cursor** — installed as a global or project-level skill
  177. **Any other agent** — copy `SKILL.md` (plus the `references/` directory if you want full template and protocol support) to wherever your agent reads instructions. The files have no external dependencies and no platform-specific logic. Works with Windsurf, Cline, Aider, Continue, Roo Code, Augment, or any other coding agent that reads Markdown-based skills or system prompts.
  178. ## Installation
  179. ### Claude Code
  180. ```
  181. /plugin marketplace add zhu1090093659/spec_driven_develop
  182. /plugin install spec-driven-develop@spec-driven-develop
  183. ```
  184. After installation, run `/reload-plugins` to activate.
  185. ### Codex CLI
  186. This repository includes Codex plugin metadata at `.agents/plugins/marketplace.json` and `plugins/spec-driven-develop/.codex-plugin/plugin.json`.
  187. Install the Codex plugin marketplace from GitHub:
  188. ```bash
  189. codex plugin marketplace add zhu1090093659/spec_driven_develop --ref main
  190. ```
  191. Then enable `Spec-Driven Develop` from the Codex plugin UI. If your Codex client does not expose the plugin UI yet, add this to `~/.codex/config.toml`:
  192. ```toml
  193. [plugins."spec-driven-develop@spec-driven-develop"]
  194. enabled = true
  195. ```
  196. Alternative: install only the core skill with the built-in skill installer inside a Codex session:
  197. ```text
  198. $skill-installer install https://github.com/zhu1090093659/spec_driven_develop/tree/main/plugins/spec-driven-develop/skills/spec-driven-develop
  199. ```
  200. Or install via shell:
  201. ```bash
  202. bash <(curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/scripts/install-codex.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 271 on GitHub
  203. ```
  204. ### opencode / OpenCode
  205. This repository includes an opencode plugin entrypoint at `plugins/spec-driven-develop/opencode-plugin.js`. The installer copies the plugin bundle under `~/.config/opencode/vendor/` and creates an auto-loaded plugin file in `~/.config/opencode/plugins/`.
  206. Install globally:
  207. ```bash
  208. bash <(curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/scripts/install-opencode.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 281 on GitHub
  209. ```
  210. Or install from a local clone:
  211. ```bash
  212. git clone https://github.com/zhu1090093659/spec_driven_develop.git
  213. bash spec_driven_develop/scripts/install-opencode.sh
  214. ```
  215. For project-local installation, add the plugin file directly in `opencode.json`:
  216. ```json
  217. {
  218. "$schema": "https://opencode.ai/config.json",
  219. "plugin": [
  220. "file:///absolute/path/to/spec_driven_develop/plugins/spec-driven-develop/opencode-plugin.js"
  221. ]
  222. }
  223. ```
  224. Quit and restart opencode after installation or config changes. opencode loads plugins only at startup.
  225. ### Cursor
  226. ```bash
  227. bash <(curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/scripts/install-cursor.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 307 on GitHub
  228. ```
  229. Or clone the repo and run locally:
  230. ```bash
  231. git clone https://github.com/zhu1090093659/spec_driven_develop.git
  232. bash spec_driven_develop/scripts/install-cursor.sh
  233. ```
  234. ### Other Agents (Generic)
  235. For any other coding agent, grab the SKILL file and place it where your agent reads instructions:
  236. ```bash
  237. # Download the SKILL.md
  238. curl -sL https://raw.githubusercontent.com/zhu1090093659/spec_driven_develop/main/plugins/spec-driven-develop/skills/spec-driven-develop/SKILL.md -o SKILL.md
  239. ```
  240. Where to place it depends on your agent:
  241. | Agent | Location |
  242. |---|---|
  243. | Windsurf | `.windsurf/skills/` or project rules |
  244. | Cline | `.cline/skills/` or custom instructions |
  245. | Aider | Reference via `.aider.conf.yml` or paste into chat |
  246. | Continue | `.continue/` config or system prompt |
  247. | Others | Wherever your agent reads custom instructions or system prompts |
  248. If your agent doesn't have a formal "skills" directory, you can paste the content of `SKILL.md` into its system prompt or custom instructions field — the effect is the same.
  249. ## Usage
  250. ### Automatic Trigger
  251. Simply describe your task to the agent. Each skill triggers on different keywords:
  252. **Spec-Driven Develop** — large-scale transformation tasks:
  253. - English: "rewrite", "migrate", "overhaul", "refactor entire project", "transform", "rebuild in [language]"
  254. - Chinese: "改造", "重写", "迁移", "重构", "大规模"
  255. **Deep Discuss** — problem analysis and brainstorming:
  256. - English: "let's discuss", "help me analyze", "I have a problem", "what do you think", "I'm torn between"
  257. - Chinese: "讨论一下", "帮我分析", "我遇到一个问题", "你觉得怎么样", "帮我想想", "我在纠结"
  258. **Review SPD** — findings-first code review:
  259. - English: "review-spd", "use review-spd", "review-spd uncommitted changes", "review-spd recent commits", "review-spd this branch", "review-spd PR"
  260. - Chinese: "review-spd", "用 review-spd 评审", "review-spd 审查未提交修改", "review-spd 审查最近提交", "review-spd PR"
  261. ### Manual Trigger (Claude Code)
  262. ```
  263. /spec-dev rewrite this Python project in Rust
  264. /dp Our API response times have been spiking recently
  265. ```
  266. ### Cross-Conversation Continuity
  267. If a session is interrupted before completion, the agent can resume by reading `docs/progress/MASTER.md` at the start of a new session to restore context and continue from where it left off. In GitHub modes, it also queries GitHub for the latest Issue states — PRs may have been merged since the last session.
  268. ### Native Task Tracking
  269. When the agent starts a work session, it automatically loads the current phase's pending tasks into the platform's native task tracking tool (e.g. TodoWrite in Claude Code). You get real-time visual progress in your IDE sidebar — no need to open Markdown files manually. In GitHub modes, progress is also visible on the GitHub Milestone and Project board. MASTER.md remains the persistent local index across conversations.
  270. ### Project Governance and Memory
  271. For new projects, the workflow now creates or updates project-level agent instructions and resolves the durable memory surface alongside progress tracking:
  272. - `AGENTS.md` — shared constraints for Codex, OpenCode, Cursor, and other Markdown-aware coding agents
  273. - `CLAUDE.md` — Claude Code-specific instructions, kept aligned with `AGENTS.md`
  274. - Native project memory surface when available — durable project facts, recurring gotchas, and engineering rules that should survive across sessions
  275. - Optional repo-local fallback memory file only when explicitly selected or already declared by the project
  276. Feature and behavior tasks are planned with tests by default. If a task cannot add automated tests, the plan must state why and name the closest validation command to run.
  277. ### Progress Export
  278. An optional script exports your progress data to structured JSON, making it easy to import into external project management tools (Linear, Jira, Notion, etc.):
  279. ```bash
  280. python scripts/export-progress.py docs/progress/
  281. ```
  282. ### Archive
  283. When all tasks are marked complete, the agent archives all workflow artifacts (analysis, plan, progress, and governance snapshots) into `docs/archives/<project-name>/` and updates an index at `docs/archives/README.md`. Active root-level governance files stay in place; archived copies preserve traceability.
  284. ## Project Structure
  285. ```
  286. spec_driven_develop/
  287. ├── AGENTS.md # Shared project instructions for coding agents
  288. ├── CLAUDE.md # Claude Code-specific project instructions
  289. ├── .agents/plugins/marketplace.json # Codex repo-local plugin marketplace
  290. ├── docs/
  291. │ └── archives/ # Completed workflow archives
  292. ├── plugins/spec-driven-develop/ # Self-contained Claude Code, Codex, and OpenCode plugin
  293. │ ├── .claude-plugin/
  294. │ │ └── plugin.json # Claude Code plugin manifest
  295. │ ├── .codex-plugin/
  296. │ │ └── plugin.json # Codex plugin manifest
  297. │ ├── opencode-plugin.js # OpenCode plugin entrypoint
  298. │ ├── skills/
  299. │ │ ├── spec-driven-develop/
  300. │ │ │ ├── SKILL.md # Core workflow — works on ANY platform
  301. │ │ │ └── references/
  302. │ │ │ ├── super-philosophy.md # S.U.P.E.R architecture principles
  303. │ │ │ ├── parallel-protocol.md # Parallel execution protocol
  304. │ │ │ ├── behavioral-rules.md # Non-negotiable workflow rules
  305. │ │ │ ├── github-integration.md # GitHub Issues/Projects/PR protocol
  306. │ │ │ ├── adaptive-control.md # Closed-loop adaptive control protocol
  307. │ │ │ └── templates/ # Document templates (one per concern)
  308. │ │ │ ├── analysis.md # Phase 1: with S.U.P.E.R health assessment
  309. │ │ │ ├── plan.md # Phase 3: with S.U.P.E.R design constraints
  310. │ │ │ ├── progress.md # Phase 4: cross-conversation tracking
  311. │ │ │ ├── governance.md # Phase 4: instruction/native memory surface templates
  312. │ │ │ └── archive.md # Phase 6: artifact preservation
  313. │ │ ├── deep-discuss/
  314. │ │ │ └── SKILL.md # Structured deep discussion workflow
  315. │ │ └── review-spd/
  316. │ │ ├── SKILL.md # Findings-first code review workflow with non-conflicting skill name
  317. │ │ ├── references/
  318. │ │ │ ├── reviewer-template.md # Generic focused sub-agent template
  319. │ │ │ └── output-format.md # Findings-first review output contract
  320. │ │ └── scripts/
  321. │ │ └── review-context.py # Packaged git context collector
  322. │ ├── agents/ # Claude Code sub-agents (optional)
  323. │ │ ├── project-analyzer.md
  324. │ │ ├── task-architect.md
  325. │ │ ├── task-executor.md
  326. │ │ └── code-reviewer.md
  327. ├── scripts/ # Installation & utility scripts
  328. │ ├── install-cursor.sh
  329. │ ├── install-codex.sh
  330. │ ├── install-opencode.sh
  331. │ ├── install-agents.sh # Sync bundled skills to ~/.agents/skills
  332. │ ├── install-all.sh
  333. │ ├── export-progress.py # Export progress to JSON
  334. │ └── review-context.py # Repo convenience wrapper for Review SPD
  335. └── LICENSE
  336. ```
  337. The essential files for cross-platform use are the `SKILL.md` files, their `references/` directories, and packaged helper scripts. Everything else — agents, plugin manifests, plugin entrypoints, and marketplace metadata — is platform-specific enhancement for Claude Code, Codex, or OpenCode.
  338. ## FAQ
  339. ### What is Spec-Driven Develop?
  340. Spec-Driven Develop is a pure-Markdown spec-driven development workflow for AI coding agents. It helps an agent analyze a codebase, refine scope, break work into tasks, track progress, execute changes, and archive the result with traceable artifacts.
  341. ### How is it different from a prompt template?
  342. It is a repeatable workflow system rather than a single prompt. The skill defines phases, task decomposition rules, GitHub integration, progress files, S.U.P.E.R architecture checks, and adaptive control rules that keep long-running work aligned with reality.
  343. ### Which AI coding agents can use it?
  344. It includes plugin metadata or plugin entrypoints for Claude Code, Codex, and OpenCode, installation scripts for Codex, OpenCode, and Cursor, and generic Markdown instructions for other agents. Any agent that can read custom skills, project rules, or system prompts can use the core workflow.
  345. ### When should I use Deep Discuss instead of Spec-Driven Develop?
  346. Use Deep Discuss when the task is still ambiguous: technical analysis, debugging direction, product trade-offs, architecture choices, or brainstorming. Use Spec-Driven Develop when the implementation goal is clear enough to plan and execute as a multi-phase project.
  347. ### Does it require a runtime, API key, or SDK?
  348. No. The core workflow is Markdown-only and has no runtime dependency. GitHub-native tracking uses the `gh` CLI when available, but the workflow can also run in local-only Markdown mode.
  349. ## Star History
  350. <p align="center">
  351. <a href="https://www.star-history.com/#zhu1090093659/spec_driven_develop&Date" target="_blank">
  352. <img src="https://api.star-history.com/svg?repos=zhu1090093659/spec_driven_develop&type=Date" alt="Star History" width="600">
  353. </a>
  354. </p>
  355. ## Friendly Links
  356. - [linux.do](https://linux.do)
  357. - [zhu1090093659/deepseek-pp](https://github.com/zhu1090093659/deepseek-pp)
  358. ## License
  359. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.