@ai-is-gonna/get-tasks-done 0.2.0

package/get-tasks-done/references/model-profiles.md

@@ -0,0 +1,245 @@
+# Model Profiles
+
+Model profiles control which Claude model each GTD agent uses. This allows balancing quality vs token spend, or inheriting the currently selected session model.
+
+## Profile Definitions
+
+| Agent | `quality` | `balanced` | `budget` | `adaptive` | `inherit` |
+|-------|-----------|------------|----------|------------|-----------|
+| gtd-planner | opus | opus | sonnet | opus | inherit |
+| gtd-roadmapper | opus | sonnet | sonnet | sonnet | inherit |
+| gtd-task-executor | opus | sonnet | sonnet | sonnet | inherit |
+| gtd-phase-researcher | opus | sonnet | haiku | sonnet | inherit |
+| gtd-project-researcher | opus | sonnet | haiku | sonnet | inherit |
+| gtd-research-synthesizer | sonnet | sonnet | haiku | haiku | inherit |
+| gtd-debugger | opus | sonnet | sonnet | opus | inherit |
+| gtd-codebase-mapper | sonnet | haiku | haiku | haiku | inherit |
+| gtd-verifier | sonnet | sonnet | haiku | sonnet | inherit |
+| gtd-plan-checker | sonnet | sonnet | haiku | haiku | inherit |
+| gtd-integration-checker | sonnet | sonnet | haiku | haiku | inherit |
+| gtd-nyquist-auditor | sonnet | sonnet | haiku | haiku | inherit |
+
+## Per-Phase-Type Model Map (#3023)
+
+`.planning/config.json` accepts a coarse per-**phase-type** map under the `models` key. Use this when you want tuning at the phase level ("Opus for planning and execution, Sonnet for the rest") without learning the agent taxonomy.
+
+```json
+{
+  "model_profile": "balanced",
+  "models": {
+    "planning": "opus",
+    "discuss": "opus",
+    "research": "sonnet",
+    "execution": "opus",
+    "verification": "sonnet",
+    "completion": "sonnet"
+  },
+  "model_overrides": {
+    "gtd-codebase-mapper": "haiku"
+  }
+}
+```
+
+### Phase-type → agent mapping
+
+| Phase type | Agents |
+|---|---|
+| `planning` | gtd-planner, gtd-roadmapper, gtd-pattern-mapper |
+| `discuss` | (reserved — no subagent today) |
+| `research` | gtd-phase-researcher, gtd-project-researcher, gtd-research-synthesizer, gtd-codebase-mapper, gtd-ui-researcher |
+| `execution` | gtd-task-executor, gtd-task-executor, gtd-debugger, gtd-doc-writer |
+| `verification` | gtd-verifier, gtd-plan-checker, gtd-integration-checker, gtd-nyquist-auditor, gtd-ui-checker, gtd-ui-auditor, gtd-doc-verifier |
+| `completion` | (reserved — no subagent today) |
+
+### Resolution precedence (highest to lowest)
+
+1. **Per-agent `model_overrides[agent]`** — full IDs accepted; targeted exceptions
+2. **Phase-type `models[phase_type]`** — tier alias only (`opus` / `sonnet` / `haiku` / `inherit`)
+3. **Profile table** — the per-agent column from the active `model_profile`
+4. **Runtime default** — when nothing else applies
+
+### Why two layers above the profile?
+
+- **Profile** is a global tier strategy (everyone runs balanced).
+- **`models`** is coarse phase-level tuning without learning agent names.
+- **`model_overrides`** is per-agent precision (e.g. force `haiku` on `gtd-codebase-mapper` for a fan-out).
+
+The three layers compose: `models` defaults a phase, `model_overrides` carves an exception out of it.
+
+## Profile Philosophy
+
+**quality** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- Use when: quota available, critical architecture work
+
+**balanced** (default) - Smart allocation
+- Opus only for planning (where architecture decisions happen)
+- Sonnet for execution and research (follows explicit instructions)
+- Sonnet for verification (needs reasoning, not just pattern matching)
+- Use when: normal development, good balance of quality and cost
+
+**budget** - Minimal Opus usage
+- Sonnet for anything that writes code
+- Haiku for research and verification
+- Use when: conserving quota, high-volume work, less critical phases
+
+**adaptive** — Role-based cost optimization
+- Opus for planning and debugging (where reasoning quality has highest impact)
+- Sonnet for execution, research, and verification (follows explicit instructions)
+- Haiku for mapping, checking, and auditing (high volume, structured output)
+- Use when: optimizing cost without sacrificing plan quality, solo development on paid API tiers
+
+**inherit** - Follow the current session model
+- All agents resolve to `inherit`
+- Best when you switch models interactively (for example OpenCode or Kilo `/model`)
+- **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise GTD may call Anthropic models directly, incurring unexpected costs
+- Use when: you want GTD to follow your currently selected runtime model
+
+## Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
+
+When installed for a non-Claude runtime, the GTD installer sets `resolve_model_ids: "omit"` in `~/.gtd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
+
+To assign different models to different agents, add `model_overrides` with model IDs your runtime recognizes:
+
+```json
+{
+  "resolve_model_ids": "omit",
+  "model_overrides": {
+    "gtd-planner": "o3",
+    "gtd-task-executor": "o4-mini",
+    "gtd-debugger": "o3",
+    "gtd-codebase-mapper": "o4-mini"
+  }
+}
+```
+
+The same tiering logic applies: stronger models for planning and debugging, cheaper models for execution and mapping.
+
+## Using Claude Code with Non-Anthropic Providers (OpenRouter, Local)
+
+If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic provider, set the `inherit` profile to prevent GTD from calling Anthropic models for subagents:
+
+```bash
+# Via settings command
+/gtd:settings
+# → Select "Inherit" for model profile
+
+# Or manually in .planning/config.json
+{
+  "model_profile": "inherit"
+}
+```
+
+Without `inherit`, GTD's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider.
+
+## Dynamic Routing with Failure-Tier Escalation (#3024)
+
+When `dynamic_routing.enabled = true` in `.planning/config.json`, the resolver picks a model from a tier-mapped table based on the agent's *default tier* (light / standard / heavy) and escalates to the next tier up on orchestrator-detected soft failure.
+
+```json
+{
+  "dynamic_routing": {
+    "enabled": true,
+    "tier_models": {
+      "light":    "haiku",
+      "standard": "sonnet",
+      "heavy":    "opus"
+    },
+    "escalate_on_failure": true,
+    "max_escalations": 1
+  }
+}
+```
+
+**Agent default tiers** (each agent in `MODEL_PROFILES` declares one):
+
+| Tier | Agents | Use case |
+|---|---|---|
+| `light` | gtd-task-executor, gtd-codebase-mapper, gtd-pattern-mapper, gtd-research-synthesizer, gtd-plan-checker, gtd-integration-checker, gtd-nyquist-auditor, gtd-ui-checker, gtd-ui-auditor, gtd-doc-verifier | Cheap/fast — pre-scoped task execution, pure mappers, scanners, low-stakes audits |
+| `standard` | gtd-task-executor, gtd-phase-researcher, gtd-project-researcher, gtd-verifier, gtd-doc-writer, gtd-ui-researcher | Default workhorse — research, writing, primary verification |
+| `heavy` | gtd-planner, gtd-roadmapper, gtd-debugger | Deep reasoning — already at top, can't escalate further |
+
+**Escalation flow** (orchestrator-driven):
+
+1. Orchestrator spawns agent with `attempt: 0` → resolver returns `tier_models[default_tier]`
+2. If orchestrator marks the result a soft failure, it re-spawns with `attempt: 1` → resolver returns `tier_models[next_tier_up]`
+3. `max_escalations` caps total retries (default 1). Beyond the cap the resolver returns the cap-tier model so the orchestrator can log without burning further budget.
+4. Hard failures (exceptions) bypass escalation and surface immediately.
+
+**Precedence with other tier sources** (highest → lowest):
+
+1. `model_overrides[<agent>]` — full ID, always wins
+2. `dynamic_routing.tier_models[escalated_tier]` — when `enabled: true`
+3. `models[<phase_type>]` — coarse phase-level (#3023)
+4. `model_profile` — global tier strategy
+
+When `dynamic_routing.enabled = false` (default), behavior is identical to today.
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning. The full precedence ladder
+is (highest → lowest):
+
+```text
+1. Read .planning/config.json
+2. Check model_overrides[<agent>] (full IDs accepted; targeted exceptions)
+3. If dynamic_routing.enabled, return tier_models[escalated_tier]
+   (see §Dynamic Routing — escalation steps tier up per attempt counter)
+4. If no dynamic_routing match, check models[phase_type] for a phase-type tier
+   (see §Per-Phase-Type Model Map for the agent → phase-type mapping)
+5. If no phase-type slot, look up agent in profile table
+6. Pass model parameter to Task call
+```
+
+The same precedence applies to `reasoning_effort` resolution on runtimes
+that support it (Codex), so `model` and `reasoning_effort` always derive
+from the same tier source — a `models[phase_type]` or
+`dynamic_routing` override flips both.
+
+## Per-Agent Overrides
+
+Override specific agents without changing the entire profile:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "gtd-task-executor": "opus",
+    "gtd-planner": "haiku"
+  }
+}
+```
+
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
+
+## Switching Profiles
+
+Runtime: `/gtd-set-profile <profile>`
+
+Per-project default: Set in `.planning/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## Design Rationale
+
+**Why Opus for gtd-planner?**
+Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+
+**Why Sonnet for gtd-task-executor?**
+Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
+
+**Why Sonnet (not Haiku) for verifiers in balanced?**
+Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+
+**Why Haiku for gtd-codebase-mapper?**
+Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
+
+**Why `inherit` instead of passing `opus` directly?**
+Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. GTD returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.
+
+**Why `inherit` profile?**
+Some runtimes (including OpenCode) let users switch models at runtime (`/model`). The `inherit` profile keeps all GTD subagents aligned to that live selection.

package/get-tasks-done/references/mvp-concepts.md

@@ -0,0 +1,49 @@
+# MVP Concepts — index
+
+Cross-reference for the six MVP-related reference files. Each file has a single, narrow purpose. This index exists so future readers (and agents resolving `@`-refs) can find the right file without grepping the directory.
+
+Canonical domain terms for the concepts named below live in [CONTEXT.md](../../CONTEXT.md) under "Domain terms" — start there if you need a precise definition.
+
+## File map
+
+| File | Purpose | Loaded by |
+|---|---|---|
+| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gtd-planner` agent when `MVP_MODE=true` |
+| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gtd-planner` agent when the Walking Skeleton gate fires |
+| `references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gtd-mvp-phase` workflow during interactive prompting; `gtd-planner` when emitting the `## Phase Goal` header |
+| `references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gtd-mvp-phase` workflow when the user story exceeds size threshold |
+| `references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gtd-task-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
+| `references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gtd-verifier` agent when the phase under verification has `mode: mvp` |
+
+## Concept-to-file map
+
+If you're looking for the canonical statement of a concept, this is where to find it:
+
+- **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `work-task-issue.md` and `verify-work.md`.
+- **`**Mode:** mvp` parser** — `get-tasks-done/bin/lib/roadmap.cjs` (`searchPhaseInContent` + `cmdRoadmapAnalyze`). Workflows compare against the parser output, never re-parse.
+- **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `gtd-verifier` (the user-story-format guard) and `gtd-mvp-phase` (interactive validation).
+- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gtd-task-executor`.
+- **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
+- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
+- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
+- **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
+- **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
+
+## Interactions worth knowing
+
+- **`--mvp` and `--prd <file>` together on Phase 1.** Both paths converge at the planner spawn. The PRD express path creates `CONTEXT.md` from the PRD file and continues to the research step; the Walking Skeleton gate fires independently when Phase 1 + new project + `--mvp`. The planner therefore receives both `WALKING_SKELETON=true` and PRD-derived context. This is intentional: the PRD informs what the skeleton should prove.
+- **`MVP_MODE` is all-or-nothing per phase, not per task.** A phase is either MVP-mode or standard. Mixed-mode phases are not supported (PRD #2826 Q1).
+- **`TDD_MODE` is independent of `MVP_MODE`.** TDD can be on without MVP, MVP can be on without TDD. Only the *intersection* (both true) activates the MVP+TDD Gate.
+- **The `gtd-roadmapper` agent makes the MVP/standard decision once at project init** based on `PROJECT_MODE`. Per-phase opt-in/out happens later via `/gtd:mvp-phase` or `/gtd-edit-phase`.
+
+## Tests
+
+Structural contract tests for each integration site live under `tests/`:
+
+- `plan-phase-mvp-flag.test.cjs` — plan-phase MVP_MODE resolution chain
+- `planner-mvp-mode.test.cjs` — gtd-planner agent MVP section
+- `mvp-phase-command.test.cjs`, `mvp-phase-integration.test.cjs`, `mvp-phase-spidr.test.cjs` — `/gtd:mvp-phase`
+- `execute-mvp-tdd-gate.test.cjs`, `executor-mvp-tdd-section.test.cjs` — MVP+TDD Gate
+- `verifier-mvp-section.test.cjs`, `verify-mvp-uat.test.cjs` — verifier UAT framing
+- `new-project-mvp-prompt.test.cjs` — mode prompt at init
+- `progress-mvp-display.test.cjs`, `stats-mvp-display.test.cjs`, `graphify-mvp-viz.test.cjs` — discovery surfaces

package/get-tasks-done/references/phase-argument-parsing.md

@@ -0,0 +1,61 @@
+# Phase Argument Parsing
+
+Parse and normalize phase arguments for commands that operate on phases.
+
+## Extraction
+
+From `$ARGUMENTS`:
+- Extract phase number (first numeric argument)
+- Extract flags (prefixed with `--`)
+- Remaining text is description (for insert/add commands)
+
+## Using gtd-tools
+
+The `find-phase` command handles normalization and validation in one step:
+
+```bash
+PHASE_INFO=$(gtd-sdk query find-phase "${PHASE}")
+```
+
+Returns JSON with:
+- `found`: true/false
+- `directory`: Full path to phase directory
+- `phase_number`: Normalized number (e.g., "06", "06.1")
+- `phase_name`: Name portion (e.g., "foundation")
+- `plans`: Array of PLAN.md files
+- `summaries`: Array of SUMMARY.md files
+
+## Manual Normalization (Legacy)
+
+Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
+
+```bash
+# Normalize phase number
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # Integer: 8 → 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # Decimal: 2.1 → 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## Validation
+
+Use `roadmap get-phase` to validate phase exists:
+
+```bash
+PHASE_CHECK=$(gtd-sdk query roadmap.get-phase "${PHASE}" --pick found)
+if [ "$PHASE_CHECK" = "false" ]; then
+  echo "ERROR: Phase ${PHASE} not found in roadmap"
+  exit 1
+fi
+```
+
+## Directory Lookup
+
+Use `find-phase` for directory lookup:
+
+```bash
+PHASE_DIR=$(gtd-sdk query find-phase "${PHASE}" --raw)
+```

package/get-tasks-done/references/plan-checker-task-atomicity.md

@@ -0,0 +1,73 @@
+# Plan Checker Task Atomicity
+
+Use this reference when Dimension 13 requires manual judgment beyond the deterministic `verify.plan-structure` output.
+
+## Scope
+
+Task-level atomicity asks whether one executor in a fresh context window can complete the task without interpretation, degradation, hallucination, or scope creep.
+
+## Checks
+
+### 13a. Per-Task File Count
+
+Count file paths in `<files>`.
+
+| Files | Status | Severity |
+|-------|--------|----------|
+| 1-3 | OK | none |
+| 4-5 | Borderline | WARNING |
+| 6+ | Over-scoped | BLOCKER |
+
+### 13b. Single Concern
+
+Analyze `<action>` for unrelated operations:
+- Distinct action verbs targeting different subsystems
+- "and" or "also" connecting operations on different file groups
+- Three or more imperative verbs across different domains
+
+| Pattern | Severity |
+|---------|----------|
+| 1 concern | OK |
+| 2 concerns, same subsystem | WARNING |
+| 2+ concerns, different subsystems | BLOCKER |
+
+### 13c. Boundaries Present
+
+Every `auto` and `tdd` task must have non-empty `<boundaries>`.
+
+| Status | Severity |
+|--------|----------|
+| Structured with Allowed/Forbidden/Out of scope or DO NOT modify clause | OK |
+| Present but prose-only | WARNING |
+| Placeholder (`No boundaries`, `none`, `N/A`) | BLOCKER |
+| Empty or absent | BLOCKER |
+
+### 13d. Independent Verifiability
+
+`<verify>` must be executable without later tasks in the same plan:
+- References file created by later task: BLOCKER
+- References endpoint or route created by later task: BLOCKER
+- Runs full test suite with no filter: WARNING
+
+Dependencies on earlier tasks are acceptable because tasks execute sequentially.
+
+### 13e. Atomic Done Criteria
+
+`<done>` should be verifiable with one assertion:
+- "and" joining distinct outcomes: BLOCKER
+- Vague language such as "works correctly" or "complete": WARNING
+- Multi-step verification: WARNING
+
+### 13f. Per-Task Context Budget
+
+Estimate context load:
+- Each `<files>` path: about 3-5%
+- Each `<read_first>` path: about 2-3%
+- `<action>` longer than 500 characters suggests complexity
+- New subsystem setup adds about 10%
+
+| Estimated context | Severity |
+|-------------------|----------|
+| <25% | OK |
+| 25-35% | WARNING |
+| >35% | BLOCKER |

package/get-tasks-done/references/planner-antipatterns.md

@@ -0,0 +1,89 @@
+# Planner Anti-Patterns and Specificity Examples
+
+> Reference file for gtd-planner agent. Loaded on-demand via `@` reference.
+> For sub-200K context windows, this content is stripped from the agent prompt and available here for on-demand loading.
+
+## Checkpoint Anti-Patterns
+
+### Bad — Asking human to automate
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com, import repo, click deploy...</instructions>
+</task>
+```
+
+**Why bad:** Vercel has a CLI. Claude should run `vercel --yes`. Never ask the user to do what Claude can automate via CLI/API.
+
+### Bad — Too many checkpoints
+
+```xml
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+```
+
+**Why bad:** Verification fatigue. Users should not be asked to verify every small step. Combine into one checkpoint at the end of meaningful work.
+
+### Good — Single verification checkpoint
+
+```xml
+<task type="auto">Create schema</task>
+<task type="auto">Create API</task>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+</task>
+```
+
+### Bad — Mixing checkpoints with implementation
+
+A plan should not interleave multiple checkpoint types with implementation tasks. Checkpoints belong at natural verification boundaries, not scattered throughout.
+
+## Specificity Examples
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "Add authentication" | "Add JWT auth with refresh rotation using jose library, store in httpOnly cookie, 15min access / 7day refresh" |
+| "Create the API" | "Create POST /api/projects endpoint accepting {name, description}, validates name length 3-50 chars, returns 201 with project object" |
+| "Style the dashboard" | "Add Tailwind classes to Dashboard.tsx: grid layout (3 cols on lg, 1 on mobile), card shadows, hover states on action buttons" |
+| "Handle errors" | "Wrap API calls in try/catch, return {error: string} on 4xx/5xx, show toast via sonner on client" |
+| "Set up the database" | "Add User and Project models to schema.prisma with UUID ids, email unique constraint, createdAt/updatedAt timestamps, run prisma db push" |
+
+**Specificity test:** Could a different Claude instance execute the task without asking clarifying questions? If not, add more detail.
+
+## Context Section Anti-Patterns
+
+### Bad — Reflexive SUMMARY chaining
+
+```markdown
+<context>
+@.planning/phases/01-foundation/01-01-SUMMARY.md
+@.planning/phases/01-foundation/01-02-SUMMARY.md  <!-- Does Plan 02 actually need Plan 01's output? -->
+@.planning/phases/01-foundation/01-03-SUMMARY.md  <!-- Chain grows, context bloats -->
+</context>
+```
+
+**Why bad:** Plans are often independent. Reflexive chaining (02 refs 01, 03 refs 02...) wastes context. Only reference prior SUMMARY files when the plan genuinely uses types/exports from that prior plan or a decision from it affects the current plan.
+
+### Good — Selective context
+
+```markdown
+<context>
+@.planning/PROJECT.md
+@.planning/STATE.md
+@.planning/phases/01-foundation/01-01-SUMMARY.md  <!-- Uses User type defined in Plan 01 -->
+</context>
+```
+
+## Scope Reduction Anti-Patterns
+
+**Prohibited language in task actions:**
+- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
+- "future enhancement", "placeholder", "basic version", "minimal implementation"
+- "will be wired later", "dynamic in future phase", "skip for now"
+
+If a decision from CONTEXT.md says "display cost calculated from billing table in impulses", the plan must deliver exactly that. Not "static label /min" as a "v1". If the phase is too complex, recommend a phase split instead of silently reducing scope.

package/get-tasks-done/references/planner-chunked.md

@@ -0,0 +1,49 @@
+# Chunked Mode Return Formats
+
+Used when `plan-phase` spawns `gtd-planner` with `CHUNKED_MODE=true` (triggered by `--chunked`
+flag or `workflow.plan_chunked: true` config). Splits the single long-lived planner Task into
+shorter-lived Tasks to bound the blast radius of Windows stdio hangs.
+
+## Modes
+
+### outline-only
+
+Write **only** `{PHASE_DIR}/{PADDED_PHASE}-PLAN-OUTLINE.md`. Do not write any PLAN.md files.
+Return:
+
+```markdown
+## OUTLINE COMPLETE
+
+**Phase:** {phase-name}
+**Plans:** {N} plan(s) in {M} wave(s)
+
+| Plan ID | Objective | Wave | Depends On | Requirements |
+|---------|-----------|------|-----------|-------------|
+| {padded_phase}-01 | [brief objective] | 1 | none | REQ-001, REQ-002 |
+| {padded_phase}-02 | [brief objective] | 1 | none | REQ-003 |
+```
+
+The orchestrator reads this table, then spawns one single-plan Task per row.
+
+### single-plan
+
+Write **exactly one** `{PHASE_DIR}/{plan_id}-PLAN.md`. Do not write any other plan files.
+Return:
+
+```markdown
+## PLAN COMPLETE
+
+**Plan:** {plan-id}
+**Objective:** {brief}
+**File:** {PHASE_DIR}/{plan-id}-PLAN.md
+**Tasks:** {N}
+```
+
+The orchestrator verifies the file exists on disk after each return, commits it, then moves
+to the next plan entry from the outline.
+
+## Resume Behaviour
+
+If the orchestrator detects that `PLAN-OUTLINE.md` already exists (from a prior interrupted
+run), it skips the outline-only Task and goes directly to single-plan Tasks, skipping any
+`{plan_id}-PLAN.md` files that already exist on disk.

package/get-tasks-done/references/planner-execution-flow.md

@@ -0,0 +1,85 @@
+# Planner Execution Flow
+
+This reference holds the operational runbook for `agents/gtd-planner.md`.
+Load it after mode-specific context and before writing plans.
+
+## Load Project State
+
+Run `gtd-sdk query init.plan-phase "${PHASE}"` and resolve `@file:` output if
+present. Extract `planner_model`, `researcher_model`, `checker_model`,
+`commit_docs`, `research_enabled`, `phase_dir`, `phase_number`,
+`has_research`, and `has_context`.
+
+Also run `gtd-sdk query state.load`. If `STATE.md` is missing but `.planning/`
+exists, offer to reconstruct or continue without it.
+
+## Load Context
+
+Read the active mode reference first:
+
+- Gap closure: `get-tasks-done/references/planner-gap-closure.md`
+- Revision: `get-tasks-done/references/planner-revision.md`
+- Reviews: `get-tasks-done/references/planner-reviews.md`
+
+Then gather planning context:
+
+- `.planning/ROADMAP.md` and `.planning/phases/`
+- Existing `PLAN.md` or `DISCOVERY.md` in the phase directory
+- `$phase_dir/*-CONTEXT.md`, `$phase_dir/*-RESEARCH.md`, and `$phase_dir/*-DISCOVERY.md`
+- Relevant `.planning/codebase/*.md` files by phase type
+- `gtd-sdk query history-digest`, then full SUMMARY files for the top 2-4 relevant prior phases
+- `.planning/RETROSPECTIVE.md` tail when present
+- `gtd-sdk query learnings.query --tag <tag> --limit 5` when global learnings are enabled
+
+If `.planning/graphs/graph.json` exists, use `gtd-tools.cjs graphify status`
+and `graphify query "<phase-goal-keyword>" --budget 2000`; graphify is not
+exposed through `gtd-sdk query` yet.
+
+If `RESEARCH.md` has an `## Architectural Responsibility Map`, cross-reference
+each task against it and correct tier misassignments before finalizing.
+
+## Build Plans
+
+Apply mandatory discovery rules, then decompose dependencies before sequence.
+For each candidate task, record what it needs, what it creates, and whether it
+requires a checkpoint. Apply TDD detection, user setup detection, file ownership
+constraints, and vertical-slice preference.
+
+Assign waves from explicit dependencies and file overlap. Same-wave plans must
+have zero `files_modified` overlap. Group tasks into plans using these rules:
+
+- Same-wave tasks with no file conflicts can be parallel plans.
+- Shared files either stay in the same plan or force a later wave.
+- Checkpoint tasks make the plan `autonomous: false`.
+- Each plan has 2-3 tasks, one concern, and a roughly 50% context target.
+
+Derive `must_haves` goal-backward: observable truths, required artifacts, and
+critical links. Reachability-check each must-have before writing.
+
+## Write And Validate
+
+Create PLAN files with the exact name `{padded_phase}-{NN}-PLAN.md` under
+`.planning/phases/{padded_phase}-{slug}/`. Include all required frontmatter.
+
+Validate every file:
+
+- `gtd-sdk query frontmatter.validate "$PLAN_PATH" --schema plan`
+- `gtd-sdk query verify.plan-structure "$PLAN_PATH"`
+
+Fix missing frontmatter, task contract errors, atomicity blockers, and
+checkpoint/autonomous mismatches before returning.
+
+Update `.planning/ROADMAP.md`: derive the phase goal only if it is still a
+placeholder, update `**Plans:** {N} plans`, and replace the plan list with the
+new PLAN filenames and brief objectives.
+
+When `commit_docs` is enabled, commit plan docs with `gtd-sdk query commit`.
+
+## Return
+
+Return the compact structured result described in `agents/gtd-planner.md`.
+Next steps must route planned implementation through task issues:
+
+- Export: `/gtd:export-phase-issues {phase} --repo owner/name`
+- Work: `/gtd:work-task-issue ...` or `/gtd:orchestrate-tasks ...`
+- Finish: `/gtd:work-task-issue --complete-phase {phase} --execute`