From 325713903b062e6ac48b51cf8b91be24d8b5b20f Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Sat, 31 Jan 2026 14:49:10 -0600 Subject: [PATCH] fix(plan-phase): pass CONTEXT.md to all downstream agents CONTEXT.md from /gsd:discuss-phase now flows through entire pipeline: - Loaded early in step 4, stored for all agent spawns - Researcher: constrains research scope (locked decisions vs discretion) - Planner: explicit guidance to honor locked decisions - Checker: new Context Compliance dimension to verify plans respect user vision - Revision: reminder to maintain context compliance during fixes Adds Dimension 7 (Context Compliance) to gsd-plan-checker: - Verifies locked decisions have implementing tasks - Flags if tasks contradict locked decisions - Flags if deferred ideas included in plans Co-Authored-By: Claude Opus 4.5 --- agents/gsd-plan-checker.md | 69 +++++++++++++++++++++++++++++++++- commands/gsd/plan-phase.md | 77 +++++++++++++++++++++++++++++--------- 2 files changed, 128 insertions(+), 18 deletions(-) diff --git a/agents/gsd-plan-checker.md b/agents/gsd-plan-checker.md index 860597d4e..8de800fc2 100644 --- a/agents/gsd-plan-checker.md +++ b/agents/gsd-plan-checker.md @@ -21,10 +21,26 @@ Your job: Goal-backward verification of PLANS before execution. Start from what - Dependencies are broken or circular - Artifacts are planned but wiring between them isn't - Scope exceeds context budget (quality will degrade) +- **Plans contradict user decisions from CONTEXT.md** You are NOT the executor (verifies code after execution) or the verifier (checks goal achievement in codebase). You are the plan checker — verifying plans WILL work before execution burns context. + +**CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase` + +| Section | How You Use It | +|---------|----------------| +| `## Decisions` | LOCKED — plans MUST implement these exactly. Flag if contradicted. | +| `## Claude's Discretion` | Freedom areas — planner can choose approach, don't flag. | +| `## Deferred Ideas` | Out of scope — plans must NOT include these. Flag if present. | + +If CONTEXT.md exists, add a verification dimension: **Context Compliance** +- Do plans honor locked decisions? +- Are deferred ideas excluded? +- Are discretion areas handled appropriately? + + **Plan completeness =/= Goal achievement** @@ -235,6 +251,49 @@ issue: fix_hint: "Reframe as user-observable: 'User can log in', 'Session persists'" ``` +## Dimension 7: Context Compliance (if CONTEXT.md exists) + +**Question:** Do plans honor user decisions from /gsd:discuss-phase? + +**Only check this dimension if CONTEXT.md was provided in the verification context.** + +**Process:** +1. Parse CONTEXT.md sections: Decisions, Claude's Discretion, Deferred Ideas +2. For each locked Decision, find task(s) that implement it +3. Verify no tasks implement Deferred Ideas (scope creep) +4. Verify Discretion areas are handled (planner's choice is valid) + +**Red flags:** +- Locked decision has no implementing task +- Task contradicts a locked decision (e.g., user said "cards layout", plan says "table layout") +- Task implements something from Deferred Ideas +- Plan ignores user's stated preference + +**Example issue:** +```yaml +issue: + dimension: context_compliance + severity: blocker + description: "Plan contradicts locked decision: user specified 'card layout' but Task 2 implements 'table layout'" + plan: "01" + task: 2 + user_decision: "Layout: Cards (from Decisions section)" + plan_action: "Create DataTable component with rows..." + fix_hint: "Change Task 2 to implement card-based layout per user decision" +``` + +**Example issue - scope creep:** +```yaml +issue: + dimension: context_compliance + severity: blocker + description: "Plan includes deferred idea: 'search functionality' was explicitly deferred" + plan: "02" + task: 1 + deferred_idea: "Search/filtering (Deferred Ideas section)" + fix_hint: "Remove search task - belongs in future phase per user decision" +``` + @@ -243,6 +302,8 @@ issue: Gather verification context from the phase directory and project state. +**Note:** The orchestrator provides CONTEXT.md content in the verification prompt. If provided, parse it for locked decisions, discretion areas, and deferred ideas. + ```bash # Normalize phase and find directory PADDED_PHASE=$(printf "%02d" $PHASE_ARG 2>/dev/null || echo "$PHASE_ARG") @@ -261,7 +322,9 @@ ls "$PHASE_DIR"/*-BRIEF.md 2>/dev/null **Extract:** - Phase goal (from ROADMAP.md) - Requirements (decompose goal into what must be true) -- Phase context (from BRIEF.md if exists) +- Phase context (from CONTEXT.md if provided by orchestrator) +- Locked decisions (from CONTEXT.md Decisions section) +- Deferred ideas (from CONTEXT.md Deferred Ideas section) ## Step 2: Load All Plans @@ -738,6 +801,10 @@ Plan verification complete when: - [ ] Key links checked (wiring planned, not just artifacts) - [ ] Scope assessed (within context budget) - [ ] must_haves derivation verified (user-observable truths) +- [ ] Context compliance checked (if CONTEXT.md provided): + - [ ] Locked decisions have implementing tasks + - [ ] No tasks contradict locked decisions + - [ ] Deferred ideas not included in plans - [ ] Overall status determined (passed | issues_found) - [ ] Structured issues returned (if any found) - [ ] Result returned to orchestrator diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 4055c4b4b..15c7a1d4c 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -106,7 +106,7 @@ grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null **If not found:** Error with available phases. **If found:** Extract phase number, name, description. -## 4. Ensure Phase Directory Exists +## 4. Ensure Phase Directory Exists and Load CONTEXT.md ```bash # PHASE is already normalized (08, 02.1, etc.) from step 2 @@ -117,8 +117,19 @@ if [ -z "$PHASE_DIR" ]; then mkdir -p ".planning/phases/${PHASE}-${PHASE_NAME}" PHASE_DIR=".planning/phases/${PHASE}-${PHASE_NAME}" fi + +# Load CONTEXT.md immediately - this informs ALL downstream agents +CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null) ``` +**CRITICAL:** Store `CONTEXT_CONTENT` now. It must be passed to: +- **Researcher** — constrains what to research (locked decisions vs Claude's discretion) +- **Planner** — locked decisions must be honored, not revisited +- **Checker** — verifies plans respect user's stated vision +- **Revision** — context for targeted fixes + +If CONTEXT.md exists, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md` + ## 5. Handle Research **If `--gaps` flag:** Skip research (gap closure uses VERIFICATION.md instead). @@ -160,7 +171,7 @@ Proceed to spawn researcher ### Spawn gsd-phase-researcher -Gather context for research prompt: +Gather additional context for research prompt: ```bash # Get phase description from roadmap @@ -172,8 +183,7 @@ REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requir # Get prior decisions from STATE.md DECISIONS=$(grep -A20 "### Decisions Made" .planning/STATE.md 2>/dev/null) -# Get phase context if exists -PHASE_CONTEXT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null) +# CONTEXT_CONTENT already loaded in step 4 ``` Fill research prompt and spawn: @@ -185,19 +195,26 @@ Research how to implement Phase {phase_number}: {phase_name} Answer: "What do I need to know to PLAN this phase well?" - + +**IMPORTANT:** If CONTEXT.md exists below, it contains user decisions from /gsd:discuss-phase. + +- **Decisions section** = Locked choices — research THESE deeply, don't explore alternatives +- **Claude's Discretion section** = Your freedom areas — research options, make recommendations +- **Deferred Ideas section** = Out of scope — ignore completely + +{context_content} + + + **Phase description:** {phase_description} **Requirements (if any):** {requirements} -**Prior decisions:** +**Prior decisions from STATE.md:** {decisions} - -**Phase context (if any):** -{phase_context} - + Write research findings to: {phase_dir}/{phase}-RESEARCH.md @@ -243,7 +260,7 @@ ROADMAP_CONTENT=$(cat .planning/ROADMAP.md) # Read optional files (empty string if missing) REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null) -CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null) +# CONTEXT_CONTENT already loaded in step 4 RESEARCH_CONTENT=$(cat "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null) # Gap closure files (only if --gaps mode) @@ -280,6 +297,12 @@ Fill prompt with inlined content and spawn: {requirements_content} **Phase Context (if exists):** + +IMPORTANT: If phase context exists below, it contains USER DECISIONS from /gsd:discuss-phase. +- **Decisions** = LOCKED — honor these exactly, do not revisit or suggest alternatives +- **Claude's Discretion** = Your freedom — make implementation choices here +- **Deferred Ideas** = Out of scope — do NOT include in this phase + {context_content} **Research (if exists):** @@ -352,14 +375,14 @@ Display: ◆ Spawning plan checker... ``` -Read plans and requirements for the checker: +Read plans for the checker: ```bash # Read all plans in phase directory PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null) -# Read requirements (reuse from step 7 if available) -REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null) +# CONTEXT_CONTENT already loaded in step 4 +# REQUIREMENTS_CONTENT already loaded in step 7 ``` Fill checker prompt with inlined content and spawn: @@ -376,6 +399,17 @@ Fill checker prompt with inlined content and spawn: **Requirements (if exists):** {requirements_content} +**Phase Context (if exists):** + +IMPORTANT: If phase context exists below, it contains USER DECISIONS from /gsd:discuss-phase. +Plans MUST honor these decisions. Flag as issue if plans contradict user's stated vision. + +- **Decisions** = LOCKED — plans must implement these exactly +- **Claude's Discretion** = Freedom areas — plans can choose approach +- **Deferred Ideas** = Out of scope — plans must NOT include these + +{context_content} + @@ -418,6 +452,7 @@ Read current plans for revision context: ```bash PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null) +# CONTEXT_CONTENT already loaded in step 4 ``` Spawn gsd-planner with revision prompt: @@ -434,11 +469,18 @@ Spawn gsd-planner with revision prompt: **Checker issues:** {structured_issues_from_checker} +**Phase Context (if exists):** + +IMPORTANT: If phase context exists, revisions MUST still honor user decisions. + +{context_content} + Make targeted updates to address checker issues. Do NOT replan from scratch unless issues are fundamental. +Revisions must still honor all locked decisions from Phase Context. Return what changed. ``` @@ -513,12 +555,13 @@ Verification: {Passed | Passed with override | Skipped} - [ ] .planning/ directory validated - [ ] Phase validated against roadmap - [ ] Phase directory created if needed +- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents - [ ] Research completed (unless --skip-research or --gaps or exists) -- [ ] gsd-phase-researcher spawned if research needed +- [ ] gsd-phase-researcher spawned with CONTEXT.md (constrains research scope) - [ ] Existing plans checked -- [ ] gsd-planner spawned with context (including RESEARCH.md if available) +- [ ] gsd-planner spawned with context (CONTEXT.md + RESEARCH.md) - [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled) -- [ ] gsd-plan-checker spawned (unless --skip-verify) +- [ ] gsd-plan-checker spawned with CONTEXT.md (verifies context compliance) - [ ] Verification passed OR user override OR max iterations with user decision - [ ] User sees status between agent spawns - [ ] User knows next steps (execute or review)