Spec Driven Develop

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

Canonical references (each topic has exactly one home — cite it, never re-explain it):

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.