A cross-platform AI agent skill that turns "rewrite this in Rust" or "migrate to microservices" into a disciplined, document-driven workflow — analyze, decompose, track, execute. One SKILL.md, no framework, no runtime. Works with Claude Code, Codex, Cursor, or any agent that reads Markdown.
# Add to your Claude Code skills
git clone https://github.com/zhu1090093659/spec_driven_developEnglish | 中文
A structured methodology for AI coding agents. Pure Markdown. Any platform. Architecture-first.
Spec-Driven Develop is a platform-agnostic AI agent plugin that ships two complementary skills:
No comments yet. Be the first to share your thoughts!
No SDK. No runtime. No dependencies. Just Markdown files that any AI coding agent can read and execute.
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 7-phase preparation 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
|
Phase 4 Progress Tracking Generate MASTER.md + per-phase detail files
| for cross-conversation continuity
|
Phase 5 Sub-SKILL Generation Create a project-level SKILL with inlined
| S.U.P.E.R principles and code review checklist
|
Phase 6 Handoff Present all artifacts, confirm readiness
|
... Development Phases Iterative implementation with progress tracking
|
Phase 7 Archive Preserve all artifacts for traceability
A master progress file (docs/progress/MASTER.md) serves as the agent's memory anchor across conversations. No matter how many sessions a task spans, the agent always knows where things stand.
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.
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.
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.
| Principle | Meaning | How It's Enforced | |:----------|:--------|:------------------| | Single Purpose | One module, one job | Analysis phase rates each module's single-responsibility compliance. Tasks that span multiple concerns get decomposed further. | | Unidirectional Flow | Data flows one way | Architecture health check flags circular dependencies. Dependencies must point inward — outer layers depend on inner, never the reverse. | | Ports over Implementation | Contracts before code | Module inventory evaluates whether I/O is schema-defined. Task breakdown requires interface contracts before implementation tasks. | | Environment-Agnostic | Runs anywhere | Risk assessment catches hardcoded config and platform-specific assumptions. Config must come from environment variables or config files. | | Replaceable Parts | Swap without ripple | Each module is rated by replacement cost. If swapping a component causes cascading changes, the architecture is broken. |
S.U.P.E.R isn't just a reference document the agent might read — it's woven into the workflow at every level:
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.
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.
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.
Phase 5 — Sub-SKILL: The full S.U.P.E.R principles are inlined verbatim into the generated sub-SKILL (not just referenced), along with a mandatory 10-point code review checklist that the agent must pass after every task:
| Check | Principle | |:------|:----------| | Every new module/file has exactly one responsibility | S | | No function does more than one conceptual thing | S | | Data flows input → processing → output, no reverse deps | U | | No circular imports introduced | U | | Cross-module interfaces are schema-defined | P | | Module I/O is serializable | P | | No hardcoded paths, URLs, keys, or config values | E | | All new dependencies explicitly declared | E | | New modules can be replaced without changes to others | R | | All tests pass after the change | — |
All pass = proceed. 1-2 fail = fix before marking complete. 3+ fail = stop and refactor.
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.
Tested platforms with install scripts:
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.
/plugin marketplace add zhu1090093659/spec_driven_develop
/plugin install spec-driven-develop@spec-driven-develop
After installation, run /reload-plugins to activate.
Use 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)
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
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 h