diff --git a/.changeset/lazy-mvp-bodies-progressive-disclosure.md b/.changeset/lazy-mvp-bodies-progressive-disclosure.md new file mode 100644 index 000000000..2dad6c698 --- /dev/null +++ b/.changeset/lazy-mvp-bodies-progressive-disclosure.md @@ -0,0 +1,5 @@ +--- +type: Changed +pr: 746 +--- +**`/gsd:plan-phase` and `/gsd:execute-phase` no longer eagerly load MVP-only guidance on non-MVP runs** — the MVP planner rules, user-story template, Walking-Skeleton template, and MVP+TDD halt-report reference are now Read lazily by the planner/executor only when MVP / Walking-Skeleton / MVP+TDD mode is active, in both the workflow files and the `gsd-planner`/`gsd-executor` agent definitions, instead of being `@`-imported into every run. Behaviour is unchanged; non-MVP planning/execution simply carries less context. (#720) diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index 1deac8ca3..2a70dbea5 100644 --- a/agents/gsd-executor.md +++ b/agents/gsd-executor.md @@ -385,7 +385,7 @@ If RED or GREEN gate commits are missing, add a warning to SUMMARY.md under a `# ## MVP+TDD Gate -**When the orchestrator passes both `MVP_MODE=true` and `TDD_MODE=true`:** Before running the implementation step of any task with `tdd="true"`, run the runtime gate from `@~/.claude/gsd-core/references/execute-mvp-tdd.md`. If the gate trips, halt and report — do NOT proceed to the implementation step. +**When the orchestrator passes both `MVP_MODE=true` and `TDD_MODE=true`:** Before running the implementation step of any task with `tdd="true"`, run the runtime gate from `~/.claude/gsd-core/references/execute-mvp-tdd.md` (Read it). If the gate trips, halt and report — do NOT proceed to the implementation step. **Halt-and-report protocol:** diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index 2a6a9aaac..6eeabea88 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -309,7 +309,7 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config ## MVP Mode Detection -**When `MVP_MODE` is enabled (passed by the plan-phase orchestrator):** Decompose tasks as **vertical feature slices**, not horizontal layers. Required reading: `@~/.claude/gsd-core/references/planner-mvp-mode.md` (loaded conditionally by the orchestrator). +**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). **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. @@ -323,7 +323,7 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config **As a** [user role], **I want to** [capability], **so that** [outcome]. ``` - Format rules from `@~/.claude/gsd-core/references/user-story-template.md`: + 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. @@ -332,7 +332,7 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config **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. -**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`. `SKELETON.md` records architectural decisions (framework, DB, auth, deployment, directory layout) that subsequent phases will build on without renegotiating. +**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 `` block, AND the task ordering follows the vertical-slice structure above. The first task is always a failing end-to-end test. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0443991e5..48380d3b2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -193,6 +193,16 @@ parent dispatches, modes/ holds per-flag behavior (`power.md`, `all.md`, checkpoint.json schemas that are read only when the corresponding output file is being written. +`workflows/plan-phase.md`, `workflows/execute-phase.md`, and the +`gsd-planner` / `gsd-executor` agent definitions apply the same discipline +to their MVP-only reference bodies — `planner-mvp-mode.md`, +`user-story-template.md`, `skeleton-template.md`, and `execute-mvp-tdd.md` +are referenced for the planner/executor to Read only on MVP, +Walking-Skeleton, or MVP+TDD paths, rather than eagerly `@`-imported, so +non-MVP runs do not pay their context cost (guards against the "`@`-import +behind a conditional still loads eagerly" leak; see #720). The dedicated +`mvp-phase` workflow keeps its eager imports, since it is always MVP. + ### Agents (`agents/*.md`) Specialized agent definitions with frontmatter specifying: diff --git a/gsd-core/workflows/execute-phase.md b/gsd-core/workflows/execute-phase.md index 96ca1d190..b1af74812 100644 --- a/gsd-core/workflows/execute-phase.md +++ b/gsd-core/workflows/execute-phase.md @@ -188,7 +188,7 @@ if [ "$MVP_MODE" = "true" ] && [ "$TDD_MODE" = "true" ]; then fi fi ``` -Pure doc-only / config-only / test-only tasks return `is_behavior_adding=false` and are exempt. See `execute-mvp-tdd.md` for the halt report format. +Pure doc-only / config-only / test-only tasks return `is_behavior_adding=false` and are exempt. When the gate trips, Read `~/.claude/gsd-core/references/execute-mvp-tdd.md` for the exact halt report format. diff --git a/gsd-core/workflows/plan-phase.md b/gsd-core/workflows/plan-phase.md index cc93aa5ce..f578042e8 100644 --- a/gsd-core/workflows/plan-phase.md +++ b/gsd-core/workflows/plan-phase.md @@ -143,7 +143,7 @@ fi ``` When `WALKING_SKELETON=true`: -- Planner is instructed to produce `SKELETON.md` in the phase directory alongside `PLAN.md`. The template lives at `@~/.claude/gsd-core/references/skeleton-template.md`. +- Planner is instructed to produce `SKELETON.md` in the phase directory alongside `PLAN.md`. The template lives at `~/.claude/gsd-core/references/skeleton-template.md` — the planner reads it when producing SKELETON.md (lazy; not loaded on non-skeleton runs). - The plan must scaffold project + routing + one real DB read/write + one real UI interaction + dev deployment — the thinnest possible end-to-end working slice. **Interaction with `--prd `.** `--mvp` and `--prd` compose. The PRD express path (Step 3.5) creates `CONTEXT.md` from the PRD file and continues to research; the Walking Skeleton gate fires independently from the conditions above. When both are active on Phase 1 of a new project, the planner receives `WALKING_SKELETON=true` and PRD-derived context simultaneously — the PRD informs *what the skeleton should prove*. No precedence is needed; the two signals are orthogonal. See [`references/mvp-concepts.md`](../references/mvp-concepts.md) for the broader interaction map. @@ -933,12 +933,12 @@ Each TDD plan gets one feature with RED/GREEN/REFACTOR gate sequence. ` : ''} -**MVP_MODE:** ${MVP_MODE} (when true, follow vertical-slice rules from `@~/.claude/gsd-core/references/planner-mvp-mode.md`; when false, ignore MVP guidance entirely.) -**WALKING_SKELETON:** ${WALKING_SKELETON} (when true, the first deliverable must be a Walking Skeleton — produce SKELETON.md alongside PLAN.md.) +**MVP_MODE:** ${MVP_MODE} (when true, follow vertical-slice rules from `~/.claude/gsd-core/references/planner-mvp-mode.md`; when false, ignore MVP guidance entirely.) +**WALKING_SKELETON:** ${WALKING_SKELETON} (when true, the first deliverable must be a Walking Skeleton — Read the template at `~/.claude/gsd-core/references/skeleton-template.md` and produce SKELETON.md alongside PLAN.md.) ${MVP_MODE === 'true' ? ` -**MVP Mode is ENABLED.** Follow vertical-slice planning rules from @~/.claude/gsd-core/references/planner-mvp-mode.md. Each plan must deliver a complete vertical slice — thin end-to-end functionality rather than horizontal layers. +**MVP Mode is ENABLED.** Read `~/.claude/gsd-core/references/planner-mvp-mode.md` now and follow its vertical-slice planning rules. Each plan must deliver a complete vertical slice — thin end-to-end functionality rather than horizontal layers. ` : ''} diff --git a/tests/workflow-size-budget.test.cjs b/tests/workflow-size-budget.test.cjs index 65da82e37..18673661f 100644 --- a/tests/workflow-size-budget.test.cjs +++ b/tests/workflow-size-budget.test.cjs @@ -402,3 +402,150 @@ describe('SIZE: discuss-phase progressive disclosure (issue #2551)', () => { ); }); }); + +const AGENTS_DIR = path.join(__dirname, '..', 'agents'); + +describe('workflow progressive disclosure — MVP bodies lazy-loaded (#720)', () => { + // MVP-only reference bodies (planner-mvp-mode.md, skeleton-template.md, + // execute-mvp-tdd.md) must NOT be eagerly @-imported at the top level of the + // always-loaded workflow files or agent definitions. An @-prefixed path is + // expanded into context the moment the file loads — regardless of whether + // MVP_MODE is true — inflating every session's token cost. Use a plain + // backtick path or a conditional "Read ..." instruction instead. See issue #720. + + test('plan-phase.md does not eagerly @-import planner-mvp-mode.md', () => { + const planPhaseContent = fs.readFileSync(path.join(WORKFLOWS_DIR, 'plan-phase.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*planner-mvp-mode\.md/.test(planPhaseContent), + 'plan-phase.md contains an eager @-import of planner-mvp-mode.md — ' + + 'this loads the MVP body into context for every session, even when MVP_MODE is false. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('plan-phase.md does not eagerly @-import skeleton-template.md', () => { + const planPhaseContent = fs.readFileSync(path.join(WORKFLOWS_DIR, 'plan-phase.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*skeleton-template\.md/.test(planPhaseContent), + 'plan-phase.md contains an eager @-import of skeleton-template.md — ' + + 'this loads the template into context on every plan-phase invocation. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('plan-phase.md still references both MVP bodies (lazy reference preserved)', () => { + const planPhaseContent = fs.readFileSync(path.join(WORKFLOWS_DIR, 'plan-phase.md'), 'utf-8'); + assert.ok( + /planner-mvp-mode\.md/.test(planPhaseContent) && /skeleton-template\.md/.test(planPhaseContent), + 'plan-phase.md must still reference planner-mvp-mode.md and skeleton-template.md ' + + '(as lazy backtick paths or Read instructions) so agents know where to find them. ' + + 'Do not delete the references — only remove the leading @ sigil. See #720.' + ); + }); + + test('plan-phase.md does not list MVP bodies in ', () => { + const planPhaseContent = fs.readFileSync(path.join(WORKFLOWS_DIR, 'plan-phase.md'), 'utf-8'); + const requiredReadingMatch = planPhaseContent.match(/([\s\S]*?)<\/required_reading>/); + if (requiredReadingMatch) { + const block = requiredReadingMatch[1]; + assert.ok( + !/planner-mvp-mode\.md/.test(block), + 'planner-mvp-mode.md must NOT appear in plan-phase.md — ' + + 'that block is always loaded regardless of MVP_MODE. See #720.' + ); + assert.ok( + !/skeleton-template\.md/.test(block), + 'skeleton-template.md must NOT appear in plan-phase.md — ' + + 'that block is always loaded regardless of MVP_MODE. See #720.' + ); + } + }); + + test('execute-phase.md does not eagerly @-import execute-mvp-tdd.md', () => { + const executePhaseContent = fs.readFileSync(path.join(WORKFLOWS_DIR, 'execute-phase.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*execute-mvp-tdd\.md/.test(executePhaseContent), + 'execute-phase.md contains an eager @-import of execute-mvp-tdd.md — ' + + 'this loads the MVP TDD body into context for every session. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('execute-phase.md still references execute-mvp-tdd.md (lazy reference preserved)', () => { + const executePhaseContent = fs.readFileSync(path.join(WORKFLOWS_DIR, 'execute-phase.md'), 'utf-8'); + assert.ok( + /execute-mvp-tdd\.md/.test(executePhaseContent), + 'execute-phase.md must still reference execute-mvp-tdd.md (as a lazy backtick path ' + + 'or Read instruction) so agents know where to find it. ' + + 'Do not delete the reference — only ensure there is no leading @ sigil. See #720.' + ); + }); + + test('gsd-planner.md does not eagerly @-import planner-mvp-mode.md', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-planner.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*planner-mvp-mode\.md/.test(content), + 'gsd-planner.md contains an eager @-import of planner-mvp-mode.md — ' + + 'this loads the MVP body into context for every session, even when MVP_MODE is false. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('gsd-planner.md does not eagerly @-import skeleton-template.md', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-planner.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*skeleton-template\.md/.test(content), + 'gsd-planner.md contains an eager @-import of skeleton-template.md — ' + + 'this loads the template into context on every planner invocation. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('gsd-planner.md does not eagerly @-import user-story-template.md', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-planner.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*user-story-template\.md/.test(content), + 'gsd-planner.md contains an eager @-import of user-story-template.md — ' + + 'this loads the template into context on every planner invocation. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('gsd-planner.md still references the three MVP bodies', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-planner.md'), 'utf-8'); + assert.ok( + /planner-mvp-mode\.md/.test(content), + 'gsd-planner.md must still reference planner-mvp-mode.md (as a lazy path or Read instruction). ' + + 'Do not delete the reference — only remove the leading @ sigil. See #720.' + ); + assert.ok( + /skeleton-template\.md/.test(content), + 'gsd-planner.md must still reference skeleton-template.md (as a lazy path or Read instruction). ' + + 'Do not delete the reference — only remove the leading @ sigil. See #720.' + ); + assert.ok( + /user-story-template\.md/.test(content), + 'gsd-planner.md must still reference user-story-template.md (as a lazy path or Read instruction). ' + + 'Do not delete the reference — only remove the leading @ sigil. See #720.' + ); + }); + + test('gsd-executor.md does not eagerly @-import execute-mvp-tdd.md', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-executor.md'), 'utf-8'); + assert.ok( + !/@[~./\w-]*execute-mvp-tdd\.md/.test(content), + 'gsd-executor.md contains an eager @-import of execute-mvp-tdd.md — ' + + 'this loads the MVP TDD body into context for every session. ' + + 'Replace with a conditional Read instruction or a plain backtick path. See #720.' + ); + }); + + test('gsd-executor.md still references execute-mvp-tdd.md', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-executor.md'), 'utf-8'); + assert.ok( + /execute-mvp-tdd\.md/.test(content), + 'gsd-executor.md must still reference execute-mvp-tdd.md (as a lazy path or Read instruction). ' + + 'Do not delete the reference — only remove the leading @ sigil. See #720.' + ); + }); +});