/spec-driven-develop

name: spec-driven-develop
description: >-
  Automates pre-development workflow for large-scale complex tasks. Use when the user
  mentions "rewrite", "migrate", "overhaul", "refactor entire project", "transform",
  "rebuild in [language]", "spec-driven", or describes any large-scale project transformation
  that requires planning before coding. Also triggers on Chinese keywords: "改造", "重写",
  "迁移", "重构", "大规模", "规范驱动". Performs full project analysis, task decomposition,
  documentation generation, project-level instruction and native memory surface resolution,
  progress tracking setup, and then executes the plan within the same session. Keeps Issues as
  task-tracking units while batching related implementation into coherent reviewable PRs.
metadata:
  version: 1.15.0

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/<project>/` | 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 cove