* feat(#1945): tracer-first planning default + executor feedback gate Make "thin end-to-end slice first, verify, then expand" the default planning + execution discipline instead of the opt-in --mvp mode. - gsd-planner: first-class `type="tracer"` task; every plan LEADS with one production-quality end-to-end tracer slice by default; --no-tracer restores horizontal layers; --mvp/--tdd compose on top. - gsd-executor + execute-plan: post-tracer feedback gate — autonomous runs halt-on-fail before expansion, interactive runs emit checkpoint:human-verify after the tracer. - --no-tracer flag wired through plan-phase workflow/command/help/skill. - CONTEXT.md glossary defines tracer bullet vs prototype; docs + references reconciled. - tests/tracer-bullet.test.cjs: prose-contract + behavioral (verify plan-structure accepts tracer) coverage. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#1945): backfill changeset PR number to 2294 --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -152,11 +152,17 @@ For each task:
|
||||
- Commit (see task_commit_protocol)
|
||||
- Track completion + commit hash for Summary
|
||||
|
||||
2. **If `type="checkpoint:*"`:**
|
||||
2. **If `type="tracer"`:** (the leading thin end-to-end slice — production-quality, never a throwaway)
|
||||
- Execute and commit exactly like `type="auto"` (real implementation, real `<verify>`, atomic commit).
|
||||
- **Then run the tracer feedback gate BEFORE any expansion task** — an early integration checkpoint on the proven slice:
|
||||
- **Autonomous run (auto mode active — `AUTO_CHAIN` or `AUTO_CFG` is `"true"`, per `<auto_mode_detection>`):** re-run the tracer's `<verify>` end-to-end. If it **fails**, HALT and surface it (deviation Rule 1) — do NOT proceed to expansion tasks. Pouring more layers onto a broken foundation is exactly the failure this gate prevents. If it passes, log `⚡ Tracer verified end-to-end — expanding` and continue.
|
||||
- **Interactive run (auto mode not active):** immediately after committing the tracer, STOP and return a `checkpoint:human-verify` for the tracer's `<verify>` (the working slice) using checkpoint_return_format, before any expansion task.
|
||||
|
||||
3. **If `type="checkpoint:*"`:**
|
||||
- STOP immediately — return structured checkpoint message
|
||||
- A fresh agent will be spawned to continue
|
||||
|
||||
3. After all tasks: run overall verification, confirm success criteria, document deviations
|
||||
4. After all tasks: run overall verification, confirm success criteria, document deviations
|
||||
</step>
|
||||
|
||||
</execution_flow>
|
||||
@@ -310,6 +316,8 @@ For full automation-first patterns, server lifecycle, CLI handling:
|
||||
|
||||
**Quick reference:** Users NEVER run CLI commands. Users ONLY visit URLs, click UI, evaluate visuals, provide secrets. Claude does all automation.
|
||||
|
||||
**Tracer feedback gate:** a `type="tracer"` task is followed by an early integration checkpoint on the proven slice (see `<execution_flow>` → `execute_tasks`) — in autonomous runs a failing tracer `<verify>` HALTS before any expansion task; in interactive runs the executor emits a `checkpoint:human-verify` for the tracer immediately after committing it.
|
||||
|
||||
---
|
||||
|
||||
**Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
|
||||
|
||||
@@ -250,34 +250,33 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config
|
||||
|
||||
`workflow.human_verify_mode=end-of-phase`: no `checkpoint:human-verify`; use `<verify><human-check>`.
|
||||
|
||||
## MVP Mode Detection
|
||||
## Tracer-First Decomposition (default)
|
||||
|
||||
**When `MVP_MODE` is enabled (passed by the plan-phase orchestrator):** Decompose tasks as **vertical feature slices**, not horizontal layers. Required reading: Read `~/.claude/gsd-core/references/planner-mvp-mode.md` for the vertical-slice rules (lazy — only on MVP runs).
|
||||
**Every phase plan LEADS with one `type="tracer"` task** — the thinnest path that touches every layer the phase will modify, wired end-to-end, carrying a real runnable `<verify>`. The remaining `<tasks>` are horizontal *expansion* tasks that build out from the proven slice. This is the default for **every** phase; it is not gated behind a flag. Required reading for the full vertical-slice rules and anti-patterns: Read `~/.claude/gsd-core/references/planner-mvp-mode.md`.
|
||||
|
||||
**Core rule:** After each task completes, a real user can do something they could not do after the previous task. If a task only "lays foundation," it is horizontal disguised as vertical — restructure.
|
||||
**Why tracer-first:** proving the architecture end-to-end on the agent's best early-context tokens catches an architectural dead-end after one commit instead of after ten already-committed layers.
|
||||
|
||||
**Plan structure under MVP_MODE:**
|
||||
**A tracer is production-quality, not a prototype.** It carries the same `<verify>` and validation as any `auto` task and becomes part of the skeleton of the final system — you write it for keeps. Stubs are allowed ONLY where they can later be filled without an architectural change: functionality gaps are acceptable, architectural gaps are not. (Glossary: `tracer bullet` vs `prototype` in `CONTEXT.md` — GSD ships tracers, never prototypes.)
|
||||
|
||||
1. Frame the phase goal as a user story at the top of `PLAN.md`. The user story is sourced from the `**Goal:**` line in ROADMAP.md (set by `mvp-phase`). Emit it with bolded keywords:
|
||||
**Tracer task shape:**
|
||||
|
||||
```
|
||||
## Phase Goal
|
||||
```xml
|
||||
<task type="tracer">
|
||||
<name>End-to-end "[capability]" — one path only</name>
|
||||
<files>[one file per layer the phase touches]</files>
|
||||
<action>Wire ONE entry point through every layer to the far end of the stack. No other call sites, no batching. Real error handling on the single path.</action>
|
||||
<verify>[a real, runnable END-TO-END check of the one path — not a per-layer unit test]</verify>
|
||||
<done>The single happy path works end-to-end and is committed.</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
**As a** [user role], **I want to** [capability], **so that** [outcome].
|
||||
```
|
||||
**Core rule (expansion tasks):** after each task a real user can do something they could not before. A task that only "lays foundation" is horizontal disguised as vertical — restructure.
|
||||
|
||||
Format rules (Read `~/.claude/gsd-core/references/user-story-template.md`):
|
||||
- All three slots required. If the ROADMAP `**Goal:**` line is not in user-story format, surface the discrepancy and ask the user to run `/gsd mvp-phase ${PHASE}` first — do not invent a story.
|
||||
- Bold the three keywords (`**As a**`, `**I want to**`, `**so that**`) when emitting to PLAN.md. The ROADMAP form does not use bolded keywords; the PLAN form does.
|
||||
2. First task: failing end-to-end test for the happy path.
|
||||
3. Second task: thinnest UI → API → DB slice that makes the test pass (stubs allowed for non-critical branches).
|
||||
4. Third+ tasks: replace stubs with real implementations, add validation, error states, polish.
|
||||
**`--no-tracer` (`TRACER_MODE=false`):** opt out of tracer-first and decompose into horizontal layers (the legacy default). Use only when the architecture is already proven and a thin slice would add no information. Do not mix a tracer-first plan with horizontal-layer tasks — one shape per phase.
|
||||
|
||||
**Mode is all-or-nothing per phase** (PRD decision Q1). Do not produce a plan that mixes vertical-slice tasks with horizontal layer tasks within the same phase.
|
||||
**MVP enrichment (`MVP_MODE=true`):** layered on top of the tracer-first ordering above (MVP no longer *turns on* vertical slices — that is now the default). It adds: (1) frame the phase goal as a user story at the top of `PLAN.md`, sourced from the ROADMAP `**Goal:**` line, bolding `**As a**` / `**I want to**` / `**so that**` (Read `~/.claude/gsd-core/references/user-story-template.md`; if the Goal line is not in user-story format, surface it and ask the user to run `/gsd mvp-phase ${PHASE}` first — do not invent a story); and (2) **Walking Skeleton mode** (`WALKING_SKELETON=true`, Phase 1 of a new project) — emit `SKELETON.md` from `~/.claude/gsd-core/references/skeleton-template.md` alongside `PLAN.md`. The Walking Skeleton is the Phase-1 special case of the tracer, recording architectural decisions (framework, DB, auth, deployment, layout) later phases build on.
|
||||
|
||||
**Walking Skeleton mode** (`WALKING_SKELETON=true`, set by orchestrator for Phase 1 + new project under `--mvp`): The first deliverable is a Walking Skeleton — the thinnest possible end-to-end stack. In addition to `PLAN.md`, produce `SKELETON.md` using the template at `~/.claude/gsd-core/references/skeleton-template.md` (Read it now). `SKELETON.md` records architectural decisions (framework, DB, auth, deployment, directory layout) that subsequent phases will build on without renegotiating.
|
||||
|
||||
**Compatibility with TDD detection:** When both `MVP_MODE=true` and `workflow.tdd_mode=true`, every behavior-adding task uses `tdd="true"` and a `<behavior>` block, AND the task ordering follows the vertical-slice structure above. The first task is always a failing end-to-end test.
|
||||
**TDD composition (`workflow.tdd_mode=true`):** the leading tracer task is `type="tracer"` and starts red — its first move is a failing end-to-end test for the happy path — and every behavior-adding expansion task uses `tdd="true"` with a `<behavior>` block.
|
||||
|
||||
See @~/.claude/gsd-core/references/planner-guidance.md for User Setup Detection protocol (external service indicators, env vars, dashboard config).
|
||||
|
||||
@@ -768,6 +767,8 @@ At decision points during plan creation, apply structured reasoning:
|
||||
|
||||
Decompose phase into tasks. **Think dependencies first, not sequence.**
|
||||
|
||||
**Lead with the tracer.** Unless `TRACER_MODE=false` (`--no-tracer`), the FIRST task is a `type="tracer"` slice (see **Tracer-First Decomposition**) wiring one path through every layer the phase touches, end-to-end, with a real `<verify>`; the remaining tasks expand out from that proven slice.
|
||||
|
||||
For each task:
|
||||
1. What does it NEED? (files, types, APIs that must exist)
|
||||
2. What does it CREATE? (files, types, APIs others might need)
|
||||
|
||||
Reference in New Issue
Block a user