Spec Driven Develop

Spec-Driven Develop

You are executing the Spec-Driven Development workflow — a standardized pipeline for large-scale complex tasks. Your job is to complete preparation phases (analysis, planning, progress setup), then execute the plan — all within a single session.

Configuration

Templates for all generated documents are in references/templates/. Behavioral rules are in references/behavioral-rules.md. The parallel execution protocol is in references/parallel-protocol.md. The GitHub integration protocol is in references/github-integration.md. The adaptive control protocol is in references/adaptive-control.md.

Task Tracking Modes

The workflow supports three task tracking modes, auto-detected via a pre-flight check in Phase 1:

See references/github-integration.md for the full protocol, gh command reference, and Issue body template.

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 — shared project instructions for Codex, Cursor, and other Markdown-aware agents
• CLAUDE.md — Claude Code-specific instructions
• Platform-specific rule files that already exist (for example .cursor/rules/, .windsurf/, .clinerules*, .codex/, or equivalent)
• The active coding agent's native project memory surface, if available
• 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 in the project.

• If it exists: Read it immediately. You are resuming an in-progress task. Identify the tracking mode (GITHUB_FULL, GITHUB_STANDARD, or LOCAL_ONLY) from the Mode field, which phase you are in, what has been completed, and continue from the exact point where the previous conversation left off. Do NOT restart from Phase 0.
  • If mode is GITHUB_FULL or GITHUB_STANDARD: Also query GitHub for the latest task status, since Issues may have been closed (via merged PRs) since the last session. Use the commands in references/github-integration.md § "Reading Progress from GitHub". Update MASTER.md if the 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. For each task, set content to the task description, status to "in-progress" for the currently active task and "todo" for the rest, and priority mapped as P0=high, P1=medium, P2=low. This gives the user real-time visual progress in their IDE. 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, without deep clarification.

Actions:

1. Extract the big-picture direction from the user's message:

   • The type of transformation (language migration, framework change, architecture overhaul, new feature development, etc.)
   • The rough target state (e.g., "rewrite in Rust", "migrate to microservices")
   • Any constraints or preferences the user explicitly mentioned

2. Summarize the direction back to the user in 1-2 sentences. Do NOT ask deep clarifying questions at this stage — the analysis in Phase 1 will reveal the project reality needed for informed questions. Simply confirm: "I understand you want to [direction]. Let me first analyze the current project so I can ask you the right questions."

3. If the user's intent is completely unclear (e.g., they said something vague like "improve this project"), ask ONE high-level question to determine the transformation type. Keep it brief.

Output: A preliminary direction statement that guides Phase 1's analysis focus. This is NOT the final task definition — that comes in Phase 2 after analysis.

---

Phase 1: Deep Project Analysis

Goal: Build a comprehensive understanding of the current codebase, informed by the preliminary direction from Phase 0.

Actions:

1. Launch project-analyzer sub-agents in parallel to analyze the codebase concurrently. Split the work by focus area:

   • Agent 1 — Architecture & Stack: Project structure, directory layout, technology stack, entry points, build/run commands
   • Agent 2 — Module Inventory: Each module's responsibility, public API surface, size, internal/external dependencies. Must evaluate each module against all five S.U.P.E.R principles (Single Purpose, Unidirectional Flow, Ports over Implementation, Environment-Agnostic, Replaceable Parts) and assign a per-principle compliance rating.
   • Agent 3 — Risks, Tests & Governance: Transformation risks, complexity hotspots, platform-specific code, coding conventions, test coverage, and project-level instruction/memory surfaces. Must produce a S.U.P.E.R Architecture Health Summary evaluating the overall codebase against each principle, identifying violation hotspots that become priority targets in the transformation plan.

   Provide each agent with the preliminary direction from Phase 0 AND references/super-philosophy.md so they can assess findings against S.U.P.E.R principles in context of the intended transformation.

   If sub-agents are not available on the current platform, perform the analysis sequentially yourself — the scope is the same either way.

2. Consolidate agent outputs and resolve any contradictions or gaps. Write analysis documents to docs/analysis/ using the templates in references/templates/analysis.md:

   • project-overview.md — Architecture, tech stack, entry points, build system
   • module-inventory.md — Every module with: responsibility, dependencies, size, complexity rating, S.U.P.E.R compliance score per module
   • risk-assessment.md — Technical risks, compatibility risks, complexity hotspots, testing gaps, project governance gaps, S.U.P.E.R Architecture Health Summary with violation hotspots

3. GitHub Pre-flight Check: Run the pre-flight detection from references/github-integration.md § "Pre-flight Check" to determine the task tracking mode (GITHUB_FULL, GITHUB_STANDARD, or LOCAL_ONLY). Report the detected mode to the user. If the mode is not what they expect, explain what's missing and how to upgrade (e.g., gh auth refresh -s project).

Output: Complete docs/analysis/ directory with three documents. The S.U.P.E.R assessment serves as the architectural baseline for all subsequent phases. The detected GitHub integration mode is communicated to the user.

---

Phase 2: Intent Refinement & Confirmation

Goal: With the project fully analyzed, engage the user in a grounded, high-quality discussion to finalize the task definition. The analysis from Phase 1 enables asking precise, informed questions that would have been impossible before understanding the codebase.

Actions:

1. Present key findings from Phase 1 as context for the discussion:

   • Brief architecture summary (how the project is structured today)
   • Notable S.U.P.E.R health issues (violation hotspots, architectural risks)
   • Module coupling and complexity highlights relevant to the intended transformation

2. Ask the user targeted clarifying questions grounded in the analysis. These should be specific and informed, not generic. Examples of the quality expected:

   • "Module A and Module B are tightly coupled with circular dependencies. Do you want to decouple them as part of this migration, or preserve the current structure?"
   • "The risk assessment shows 3 modules with hardcoded environment assumptions. Should we fix these (aligning with S.U.P.E.R E principle) or defer that to a separate task?"
   • "The current codebase has no interface contracts between modules. Do you want to introduce schema-defined boundaries (S.U.P.E.R P principle) during this transformation?"

   At minimum, confirm:

   • Scope: Which parts of the project are in scope? Reference specific modules from the inventory.
   • Target: Confirm the target technology/architecture/state, now informed by current architecture reality.
   • Constraints: Hard constraints (timeline, backward compatibility, specific libraries, deployment targets)?
   • Priorities: What matters most — performance, maintainability, feature parity, or something else? Reference the risk assessment to help the user prioritize.
   • S.U.P.E.R priorities: Which architectural violations should be fixed during this transformation vs. deferred?
   • Testing policy: Which test layers must protect new features or behavior changes? If the project lacks tests, should the first phase establish a minimal test harness?
   • Project governance: Which instruction surfaces are canonical for shared rules and platform-specific rules? Which native memory surface should receive durable project facts? If no native memory surface is available, should the workflow use an explicitly named repo-local fallback memory file?

3. Summarize the refined understanding back to the user and get explicit confirmation before proceeding.

Output: A clear, confirmed task definition grounded in project reality. This is the authoritative task definition that guides all subsequent phases (Phase 3-7).

---

Phase 3: Task Decomposition

Goal: Break down the transformation into manageable, trackable tasks organized in phases, with explicit parallel execution lanes.

Actions:

1. Launch task-architect sub-agents with the full analysis output from Phase 1 AND the confirmed task definition from Phase 2 — including the S.U.P.E.R health assessment from risk-assessment.md. If the project is large enough to warrant multiple strategies, launch 2 agents exploring different decomposition approaches (e.g., bottom-up vs. strangler fig) and pick the better result.

   If sub-agents are not available, perform the decomposition yourself.

2. The decomposition must produce:

   • Phased approach with natural phase boundaries, ordered by dependency. Early phases should prioritize fixing S.U.P.E.R violation hotspots identified in Phase 1, establishing clean architecture foundations before building new features.
   • Concrete tasks for each phase, each with: description, priority (P0/P1/P2), effort (S/M/L/XL), dependencies, S.U.P.E.R design drivers (which principles are most relevant), acceptance criteria, test expectation, and memory/governance impact. Every task's acceptance criteria implicitly includes passing the S.U.P.E.R Quick Check for its listed principles.
   • Testing is default: Every task that adds or changes user-visible features, business behavior, API contracts, schemas, migrations, parsing, routing, permissions, caching, or persistence MUST add or update relevant automated tests. Pure documentation/config tasks may mark tests as not applicable, but the reason must be explicit in the task's acceptance criteria.
   • Governance is default: If a task introduces a stable engineering rule, gotcha, command, invariant, or project-specific convention, its acceptance criteria must include updating the resolved native memory surface or the explicitly selected repo fallback. If the rule affects future agents' behavior, update the resolved instruction surfaces such as AGENTS.md, CLAUDE.md, or existing platform rule files.
   • Parallel execution lanes: For each phase, group tasks that have no mutual dependencies into lanes that can run simultaneously. Assess merge risk (file overlap) between lanes.
   • Dependency graph as a Mermaid diagram — use subgraphs to visualize parallel lanes
   • Milestones at natural phase boundaries

3. Write planning documents to docs/plan/ using the templates in references/templates/plan.md:

   • task-breakdown.md — All phases and tasks with full detail, including parallel lane assignments and S.U.P.E.R design constraints
   • dependency-graph.md — Mermaid diagram showing task/phase dependencies and parallel lanes
   • milestones.md — Milestone definitions with target criteria

4. GitHub Resource Synchronization (skip if LOCAL_ONLY mode):

   After writing the local plan documents, create the corresponding GitHub resources. Follow the commands and templates in references/github-integration.md. Execute in this order:

   a. Create Labels — priority, size, phase, lane, and spec-driven labels (idempotent with --force) b. Create Milestones — one per Phase, via gh api REST call c. Create Issues — one per task, using the Issue body template from references/github-integration.md. Assign labels and milestone. Add a 1-second delay between creations to avoid rate limits. d. [GITHUB_FULL only] Create Project board — create the Project, link it to the repo, create custom fields (Priority, Size, Phase), and add all Issues to the board. If custom field value assignment fails, log a warning and continue — the Labels already carry the same information.

   After creation, record all GitHub resource URLs (Project URL, Milestone URLs, Issue number mapping) — these are needed for MASTER.md in Phase 4.

5. Initialize Adaptive Control State (see references/adaptive-control.md § 4):

   For each Milestone created, compute the percentage-based drift thresholds from the task count in that phase and append the adaptive control YAML block to the Milestone description:

   ---
   adaptive:
     drift_score: 0
     strategy: "<decomposition-strategy>"
     thresholds:
       annotate: <ceil(total_tasks * 0.20)>
       replan: <ceil(total_tasks * 0.40)>
       rescope: <ceil(total_tasks * 0.60)>
     total_tasks: <count>
     completed_tasks: 0
     last_updated: "<ISO-8601>"

   In LOCAL_ONLY mode, add the "Adaptive Control State" section to MASTER.md instead (see Phase 4).

Output: Complete docs/plan/ directory with three documents. Every task is annotated with its S.U.P.E.R design drivers. In GitHub modes, all tasks also exist as GitHub Issues with Labels and Milestones. Adaptive control state is initialized for each phase.

---

Phase 4: Progress Tracking Documentation

Goal: Create a progress tracking and project governance system that survives across conversations. The format depends on the detected tracking mode.

Actions:

Use the templates in references/templates/progress.md for progress documents and references/templates/governance.md for project-level instruction and memory surface records.