--- name: Spec-Driven Develop slug: spec-driven-develop category: Automation description: Spec-Driven Develop automates the pre-development workflow for large-scale transformations, including analysis, task decomposition, planning, and progress tracking before implementation. Use it for rewrites, migrations, refactors, or other project-wide changes that need structure first. github: "https://github.com/zhu1090093659/spec_driven_develop/tree/main/plugins/spec-driven-develop/skills/spec-driven-develop" language: Shell stars: 969 forks: 99 install: "npx degit https://github.com/zhu1090093659/spec_driven_develop/tree/main/plugins/spec-driven-develop/skills/spec-driven-develop ~/.claude/skills/spec-driven-develop" installs_to: ~/.claude/skills/spec-driven-develop source_path: plugins/spec-driven-develop/skills/spec-driven-develop/SKILL.md collection_size: 3 category_size: 1523 collection_url: "https://dirskills.com/collections/zhu1090093659/spec_driven_develop" added: 2026-08-21T05:15:07.837Z last_synced: 2026-08-21T05:15:07.837Z canonical_url: "https://dirskills.com/skills/spec-driven-develop" --- # Spec-Driven Develop Spec-Driven Develop automates the pre-development workflow for large-scale transformations, including analysis, task decomposition, planning, and progress tracking before implementation. Use it for rewrites, migrations, refactors, or other project-wide changes that need structure first. **Install:** ```bash npx degit https://github.com/zhu1090093659/spec_driven_develop/tree/main/plugins/spec-driven-develop/skills/spec-driven-develop ~/.claude/skills/spec-driven-develop ``` ## README # Spec-Driven Develop You are executing the **Spec-Driven Development** workflow — a seven-phase pipeline (Phases 0-6) for large-scale complex tasks. Complete preparation phases (analysis, planning, progress setup), then execute the plan — all within a single session. **Behavioral rules**: `references/behavioral-rules.md` — read and follow them in every phase; they are non-negotiable. ## Configuration | Path | Default Value | Purpose | |:-----|:--------------|:--------| | Analysis output | `docs/analysis/` | Phase 1 analysis documents | | Plan output | `docs/plan/` | Phase 3 planning documents | | Progress output | `docs/progress/` | Phase 4 tracking documents (incl. MASTER.md) | | Instruction surfaces | Resolved per project | Project-level constraints for agents (see Phase 4) | | Memory surface | Native first | Durable facts via the agent's native memory when available; repo fallback only when explicitly selected | | Archive output | `docs/archives//` | Phase 6 archived artifacts | | Task tracking mode | Auto-detect | `GITHUB_FULL`, `GITHUB_STANDARD`, or `LOCAL_ONLY` | | Delivery batching | Phase-first | Issues track tasks; PRs integrate coherent task batches | | Adaptive control | Enabled | Drift thresholds: annotate=20%, replan=40%, rescope=60% of phase tasks | **Canonical references** (each topic has exactly one home — cite it, never re-explain it): | Reference | Owns | |:----------|:-----| | `references/behavioral-rules.md` | All behavioral rules (1-19) | | `references/github-integration.md` | Tracking modes, pre-flight check, all `gh` commands and Issue/PR body templates | | `references/adaptive-control.md` | Telemetry collection, drift calculation, response actions, state storage, controller activation | | `references/parallel-protocol.md` | Dispatch/review admission (tiers), lane/worktree protocol, review loop, merge risk, post-integration checks | | `references/super-philosophy.md` | S.U.P.E.R principles + the 10-check review checklist | | `references/templates/` | Schemas for every generated document (analysis, plan, progress, governance, archive) | **Task tracking modes** (capabilities differ; detection and upgrade instructions live in `references/github-integration.md` § "Pre-flight Check"): - **GITHUB_FULL**: Issues + Milestones + Labels + Project board + worktrees + batch PRs - **GITHUB_STANDARD**: same minus the Project board - **LOCAL_ONLY**: original local-file workflow, no GitHub dependency ## Before You Begin: Cross-Conversation Continuity Check **CRITICAL**: Before starting any phase, inventory and read any existing project-level instruction and memory surfaces (`AGENTS.md`, `CLAUDE.md`, existing platform rule files, the active agent's native project memory, any repo-local fallback memory file already declared by the project or by an existing `docs/progress/MASTER.md`). Then check if `docs/progress/MASTER.md` already exists: - If it **exists**: Read it immediately. You are resuming an in-progress task. Identify the tracking mode, current phase, and completed work; continue from the exact point where the previous conversation left off. Do NOT restart from Phase 0. - **In GitHub modes**: Also query GitHub for the latest task status — see `references/github-integration.md` § "Reading Progress from GitHub". Update MASTER.md if GitHub state is ahead of the local index. - If it **does not exist**: This is a fresh start. Proceed to Phase 0. After loading your current state, populate the platform's native task tracking tool (e.g. TodoWrite) with the active phase's pending tasks: content = task description, status = in-progress for the active task, priority mapped P0=high, P1=medium, P2=low. If no native task tool is available, skip this step — MASTER.md alone is sufficient. --- ## Phase 0: Quick Intent Capture **Goal**: Capture the user's high-level transformation direction in 1-2 sentences — just enough to give Phase 1 analysis a focus. **Actions**: 1. Extract from the user's message: the transformation type, the rough target state, and any explicitly stated constraints. 2. Summarize the direction back in 1-2 sentences. Do NOT ask deep clarifying questions here — Phase 1 analysis will reveal what to ask. Confirm: "I understand you want to [direction]. Let me first analyze the current project so I can ask you the right questions." 3. If intent is completely unclear, ask ONE high-level question to determine the transformation type. **Output**: A preliminary direction statement guiding Phase 1. NOT the final task definition — that comes in Phase 2. --- ## Phase 1: Deep Project Analysis **Goal**: Build a comprehensive understanding of the current codebase, informed by the Phase 0 direction. **Actions**: 1. Launch `project-analyzer` sub-agents **in parallel**, split by focus area: - **Architecture & Stack**: structure, directory layout, tech stack, entry points, build/run commands - **Module Inventory**: each module's responsibility, public API surface, size, dependencies — evaluated against all five S.U.P.E.R principles with a per-principle compliance rating - **Risks, Tests & Governance**: transformation risks, complexity hotspots, coding conventions, test coverage, instruction/memory surfaces — plus a S.U.P.E.R Architecture Health Summary with violation hotspots (priority targets for the plan) Give each agent the Phase 0 direction AND `references/super-philosophy.md`. If sub-agents are unavailable, perform the same analysis sequentially yourself. 2. Consolidate outputs, resolve contradictions, and write `docs/analysis/` documents from `references/templates/analysis.md`: - `project-overview.md`, `module-inventory.md` (with per-module S.U.P.E.R scores), `risk-assessment.md` (with the S.U.P.E.R health summary) 3. **GitHub Pre-flight Check**: detect the tracking mode per `references/github-integration.md` § "Pre-flight Check". Report the detected mode; if it differs from user expectation, explain how to upgrade (e.g., `gh auth refresh -s project`). **Output**: Complete `docs/analysis/` (three documents) + detected tracking mode. The S.U.P.E.R assessment is the architectural baseline for all subsequent phases. --- ## Phase 2: Intent Refinement & Confirmation **Goal**: With the project analyzed, finalize the task definition through a grounded discussion. **Actions**: 1. Present key Phase 1 findings: brief architecture summary, notable S.U.P.E.R health issues, and coupling/complexity highlights relevant to the transformation. 2. Ask **targeted questions grounded in the analysis** — specific and informed, not generic (e.g., about circular dependencies found, hardcoded environment assumptions, missing interface contracts). At minimum confirm: - **Scope** — which modules from the inventory are in scope - **Target** — target technology/architecture/state - **Constraints** — timeline, backward compatibility, libraries, deployment targets - **Priorities** — performance, maintainability, feature parity (use the risk assessment) - **S.U.P.E.R priorities** — which violations to fix now vs. defer - **Testing policy** — which test layers protect changes; whether to establish a minimal test harness if none exists - **Project governance** — canonical instruction surfaces; native memory surface or explicitly named repo fallback 3. Summarize the refined understanding and get explicit confirmation. **Output**: The authoritative, confirmed task definition guiding Phases 3-6. --- ## Phase 3: Task Decomposition **Goal**: Break the transformation into manageable, trackable tasks organized in phases, with parallel lanes and coherent delivery batches. **Actions**: 1. Launch `task-architect` sub-agents with the full Phase 1 analysis AND the confirmed Phase 2 definition. If multiple strategies are plausible, launch 2 agents exploring different approaches (e.g., bottom-up vs. strangler fig) and pick the better result. If sub-agents are unavailable, decompose yourself. 2. The decomposition must produce: - **Phases** ordered by dependency; early phases prioritize fixing S.U.P.E.R violation hotspots before new features. - **Tasks**, each with: description, priority (P0/P1/P2), effort (S/M/L/XL), dependencies, S.U.P.E.R design drivers, acceptance criteria, test expectation, and memory/governance impact. Every task's acceptance criteria implicitly include passing the S.U.P.E.R Quick Check for its listed principles. - **Testing is default**: tasks changing user-visible features, behavior, API contracts, schemas, migrations, parsing, routing, permissions, caching, or persistence MUST add or update automated tests; documentation/config tasks may mark tests N/A with an explicit reason. - **Governance is default**: tasks introducing a stable rule, gotcha, or convention must include updating the resolved memory surface (and instruction surfaces if the rule affects future agents). - **Parallel execution lanes** per phase: group mutually independent tasks; assess merge risk (file overlap). - **Delivery batches**: after reviewing the complete phase task set (dependencies, file overlap, shared validation, rollout risk, rollback boundary), assign every task to exactly one batch. Default to one coherent PR batch per phase; split only for documented reviewability, release/rollback, ownership, risk-isolation, or policy reasons; a single-Issue batch needs explicit justification. Record per batch: ID, goal, task IDs, execution waves, lanes, integration branch, combined validation, dependency order, split rationale. - **Dependency graph** as a Mermaid diagram (subgraphs for batch boundaries and lanes) and **milestones** at phase boundaries. 3. Write `docs/plan/` documents from `references/templates/plan.md`: `task-breakdown.md`, `dependency-graph.md`, `milestones.md`. 4. **GitHub Resource Synchronization** (skip in LOCAL_ONLY): create Labels → Milestones → Issues → [GITHUB_FULL only] Project board, in that order, using the exact commands and the Issue body template in `references/github-integration.md`. Add a 1-second delay between Issue creations. Record all URLs and the Task → Issue → Delivery Batch mapping for Phase 4. Issue creation does not imply PR creation. 5. **Initialize Adaptive Control State**: for each Milestone, compute percentage-based drift thresholds and append the adaptive YAML block per `references/adaptive-control.md` § "Adaptive State Storage". In LOCAL_ONLY mode, the state goes to MASTER.md in Phase 4 instead. **Output**: Complete `docs/plan/` (three documents); in GitHub modes, all tasks exist as labeled, milestoned Issues with adaptive state initialized. --- ## Phase 4: Progress Tracking Documentation **Goal**: Create a progress tracking and governance system that survives across conversations. **Actions**: Use `references/templates/progress.md` for progress documents and `references/templates/governance.md` for governance records. ### Project Governance Surface (all modes) 1. **Inventory existing surfaces**: shared instruction files (`AGENTS.md` or equivalent), `CLAUDE.md`, existing platform rule files, the agent's native project memory, and repo-local fallback memory files only if they already exist or the user explicitly selects one. 2. **Update instruction surfaces without overwriting**: shared cross-agent rules → `AGENTS.md`; Claude Code-specific → `CLAUDE.md`; platform rule files only when they already exist or are requested. Preserve user-written sections, local commands, and security constraints. If an existing rule conflicts with the plan, do not silently replace it — record the conflict in MASTER.md and ask the user at the next checkpoint. 3. **Resolve the memory surface**: prefer native project memory; never silently create a Markdown memory file; use a repo-local fallback only on user confirmation or existing project declaration. Record the resolution in MASTER.md "Governance Status". Do not create competing truth sources. ### In GITHUB_FULL or GITHUB_STANDARD mode: 1. Create `docs/progress/MASTER.md` as a **lightweight GitHub index**: task name/description, tracking mode, repository, Project URL (GITHUB_FULL), links to analysis/plan documents, milestone table, Issue mapping table (Task → Issue → Batch → PR → status), delivery batch table, "Quick Status Commands", "Current Status", "Next Steps". Do NOT duplicate task details — those live in GitHub Issues. 2. Add an "Execution Telemetry" reference noting where telemetry and drift state live per `references/adaptive-control.md` § "Adaptive State Storage" (Issue comments + Milestone descriptions). 3. Per-phase detail files are optional and lightweight (Issue references only). ### In LOCAL_ONLY mode: 1. Create `docs/progress/MASTER.md`: task name/description, `LOCAL_ONLY` mode, links to analysis/plan documents, phase summary table, links to phase files, "Current Status", "Next Steps". 2. Create one `docs/progress/phase-N-.md` per phase: checkbox tasks with inline acceptance criteria plus a "Notes" section. 3. Add the "Adaptive Control State" section and a "Task Telemetry Log" table to MASTER.md per `references/adaptive-control.md` § "Adaptive State Storage". ### Common to all modes: - Phases use `- [ ] Phase N: (0/X tasks)` linking to the phase file (LOCAL_ONLY) or milestone URL (GitHub modes); `- [x] Phase N: (X/X tasks)` when done. - "Current Status" is updated at the start and end of each work session. **Output**: Complete `docs/progress/` with MASTER.md (plus phase files in LOCAL_ONLY). --- ## Phase 5: Confirm & Execute **Goal**: Present preparation artifacts, get confirmation, then execute the plan. **Actions**: ### 5a. Summary & Confirmation 1. Present: task definition (Phase 2), key findings (Phase 1), phased plan with task counts (Phase 3), delivery batch overview with PR count and split rationales (Phase 3), tracking mode and its implications, progress system description (Phase 4), and the execution model (tiered dispatch: orchestrator-direct by default; `task-executor`/`code-reviewer` sub-agents dispatched per `references/parallel-protocol.md` § "Dispatch Admission (Tiered Execution)"). 2. List all generated artifacts (analysis, plan, and progress documents; resolved instruction and memory surfaces; GitHub Project URL, Milestone URLs, Issue numbers, batch mapping in GitHub modes). 3. Ask the user: "All preparation is complete. Ready to begin execution?" ### 5b. Execution 1. **Process each phase sequentially.** Before editing, read every open Issue in the phase and revalidate the planned batches against current dependencies, affected files, review scope, and repository rules. If the mapping must change, update `task-breakdown.md`, MASTER.md, and the `Delivery Batch` field in every affected Issue body; comment the regrouping reason so all execution surfaces agree. 2. **Choose the execution tier for each delivery batch** per the admission criteria in `references/parallel-protocol.md` § "Dispatch Admission (Tiered Execution)": - **Tier 0 — orchestrator-direct (default)**: S/M effort, ≤ 3 files, context already held, or machine-verifiable acceptance. Execute directly on the batch integration branch. No sub-agents, no worktrees. - **Tier 1 — single coder**: L/XL bundles or context-heavy exploration. Delegate the complete batch to one `task-executor`. - **Tier 2 — parallel lanes**: only when ALL hold — disjoint lane file sets, ≥ L effort per lane, independent verifiability, ≤ 4 lanes. Launch one `task-executor` per dependency-ready lane in isolated worktrees, in waves, each with the full batch context plus its task/Issue subset. Lane agents never create PRs. - Branch convention: repository's own; otherwise `batch/{batch_id}-{slug}` (integration) and `work/{batch_id}-{lane_id}-{slug}` (Tier 2 lanes only). 3. **Review before integrating** per `references/parallel-protocol.md` § "Review Admission (Tiered Review)": - **L1 — machine validation (always)**: every task's targeted checks plus the batch's combined validation. - **L2 — orchestrator diff review (default)**: personally read the diff against every Issue's acceptance criteria. - **L3 — independent reviewer (reserved)**: one `code-reviewer` per lane, mandatory for Tier 2 lanes and high-risk work (contract/port formats, logic code, cross-surface semantic invariants). Verdict APPROVED | FIXED | ESCALATE; integrate only APPROVED or FIXED lanes; resolve ESCALATE yourself, with the user when needed. - Writer model: reviewers never write GitHub state, MASTER.md, drift state, or instruction/memory surfaces. You remain the acceptance-verification authority and single writer for all shared state. 4. **After each task completion** — follow `references/adaptive-control.md` § "Controller Activation": collect telemetry, update cumulative `drift_score`, write telemetry to the Issue (GitHub modes) or MASTER.md (LOCAL_ONLY), and execute automatic threshold responses. For parallel lanes, lane agents return per-task telemetry and you record it once during batch integration. 5. **Integrate and validate each delivery batch** per `references/github-integration.md` § "Delivery Batch Execution Workflow": - Consolidate reviewed lane branches onto the batch integration branch; reconcile overlaps. - Run per-task checks plus combined validation and post-integration architecture checks. - Verify every included Issue's acceptance criteria yourself (L2). Keep incomplete Issues out of closing keywords. - Create exactly one batch PR with one `Closes #N` per completed Issue. Immediately write the PR number and `in review` state to the batch row and every completed Issue row in MASTER.md; keep partial Issues open with explicit partial status. - A single-Issue PR is allowed only for a documented exception or a one-Issue phase. 6. **Progress updates**: - **GitHub modes**: merged batch PRs auto-close their Issues; update MASTER.md "Current Status", "Issue Mapping", "Delivery Batches". - **LOCAL_ONLY**: check off tasks in phase files; update MASTER.md counts. - **All modes**: durable knowledge → resolved memory surface; agent-behavior changes → resolved instruction surfaces. 7. **When all tasks are complete** (all Issues closed or all checkboxes checked): proceed to Phase 6. **Output**: All planned tasks implemented and verified. --- ## Phase 6: Archive **Trigger**: All tasks complete — all Issues closed (GitHub modes) or all checkboxes `[x]` (LOCAL_ONLY). **Goal**: Archive all workflow artifacts for traceability, then clean up working directories. **Actions**: 1. Announce completion to the user. 2. Determine the archive directory name from the Phase 2 task name (lowercase, hyphens, no special characters): `docs/archives//`. Target structure and index template: `references/templates/archive.md`. 3. Move `docs/analysis/`, `docs/plan/`, and `docs/progress/` into the archive; copy snapshots or export references for the resolved instruction and memory surfaces into `docs/archives//governance/`; move any other temporary workflow files. 4. **[GitHub modes]** Close each phase's Milestone (if not already closed); optionally close the Project board. These remain on GitHub as a permanent record. 5. Create or update `docs/archives/README.md` with an entry: project name, one-line description, date range, link to archived MASTER.md, and (GitHub modes) the Project URL. 6. Remove the now-empty `docs/analysis/`, `docs/plan/`, `docs/progress/` directories. Keep active instruction and memory surfaces in place; only their snapshots live under the archive. 7. Suggest the user commit the archive to version control. **Output**: All artifacts under `docs/archives//` with an updated `docs/archives/README.md` index.