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

| 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 Codex/Cursor-compatible agents, Claude Code, and existing platform rule files |
| Memory surface     | Native first                 | Durable project facts and cross-session decisions using the active coding 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` (see below) |
| Adaptive control   | Enabled                      | Drift thresholds: annotate=20%, replan=40%, rescope=60% of phase tasks |

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:

| Mode | Requirements | Capabilities |
|:-----|:------------|:-------------|
| **GITHUB_FULL** (default) | `gh` CLI + auth + `project` scope | Issues + Milestones + Labels + Project board + worktree + PR |
| **GITHUB_STANDARD** (auto-fallback) | `gh` CLI + auth + `repo` scope | Issues + Milestones + Labels + worktree + PR (no board) |
| **LOCAL_ONLY** (fallback) | None | Original local-file workflow |

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 & S