From 3dcd3f06099d531e98c06445d3ea990cfc774b6b Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 19 Feb 2026 12:40:45 -0600 Subject: [PATCH] refactor: complete context-proxy orchestration flow --- agents/gsd-codebase-mapper.md | 3 + agents/gsd-debugger.md | 3 + agents/gsd-executor.md | 3 + agents/gsd-integration-checker.md | 3 + agents/gsd-phase-researcher.md | 3 + agents/gsd-plan-checker.md | 3 + agents/gsd-planner.md | 3 + agents/gsd-project-researcher.md | 3 + agents/gsd-research-synthesizer.md | 3 + agents/gsd-roadmapper.md | 3 + agents/gsd-verifier.md | 3 + commands/gsd/add-phase.md | 8 +- commands/gsd/add-todo.md | 7 +- commands/gsd/audit-milestone.md | 8 +- commands/gsd/check-todos.md | 8 +- commands/gsd/debug.md | 4 +- commands/gsd/discuss-phase.md | 6 +- commands/gsd/execute-phase.md | 3 +- commands/gsd/insert-phase.md | 3 +- commands/gsd/list-phase-assumptions.md | 6 +- commands/gsd/new-milestone.md | 9 +- commands/gsd/pause-work.md | 5 +- commands/gsd/plan-milestone-gaps.md | 8 +- commands/gsd/quick.md | 3 +- commands/gsd/remove-phase.md | 3 +- commands/gsd/research-phase.md | 32 ++--- commands/gsd/verify-work.md | 3 +- get-shit-done/bin/gsd-tools.cjs | 143 ++++++++++----------- get-shit-done/bin/gsd-tools.test.cjs | 134 +++++++------------ get-shit-done/workflows/diagnose-issues.md | 2 +- get-shit-done/workflows/execute-phase.md | 12 +- get-shit-done/workflows/execute-plan.md | 14 +- get-shit-done/workflows/new-milestone.md | 23 +++- get-shit-done/workflows/new-project.md | 56 ++++---- get-shit-done/workflows/plan-phase.md | 121 +++++++---------- get-shit-done/workflows/progress.md | 40 ++---- get-shit-done/workflows/quick.md | 40 +++--- get-shit-done/workflows/research-phase.md | 21 ++- get-shit-done/workflows/verify-work.md | 23 ++-- 39 files changed, 351 insertions(+), 427 deletions(-) diff --git a/agents/gsd-codebase-mapper.md b/agents/gsd-codebase-mapper.md index c47ef2a19..9762f1577 100644 --- a/agents/gsd-codebase-mapper.md +++ b/agents/gsd-codebase-mapper.md @@ -15,6 +15,9 @@ You are spawned by `/gsd:map-codebase` with one of four focus areas: - **concerns**: Identify technical debt and issues → write CONCERNS.md Your job: Explore thoroughly, then write document(s) directly. Return confirmation only. + +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. diff --git a/agents/gsd-debugger.md b/agents/gsd-debugger.md index 4413c99eb..f2ca1bc55 100644 --- a/agents/gsd-debugger.md +++ b/agents/gsd-debugger.md @@ -15,6 +15,9 @@ You are spawned by: Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode). +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Core responsibilities:** - Investigate autonomously (user reports symptoms, you find cause) - Maintain persistent debug file state (survives context resets) diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index e00bed6d2..7d95f2623 100644 --- a/agents/gsd-executor.md +++ b/agents/gsd-executor.md @@ -11,6 +11,9 @@ You are a GSD plan executor. You execute PLAN.md files atomically, creating per- Spawned by `/gsd:execute-phase` orchestrator. Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md. + +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. diff --git a/agents/gsd-integration-checker.md b/agents/gsd-integration-checker.md index 280563bd8..14e1a8c7c 100644 --- a/agents/gsd-integration-checker.md +++ b/agents/gsd-integration-checker.md @@ -10,6 +10,9 @@ You are an integration checker. You verify that phases work together as a system Your job: Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Critical mindset:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence. diff --git a/agents/gsd-phase-researcher.md b/agents/gsd-phase-researcher.md index b04e197fe..12a18ee8a 100644 --- a/agents/gsd-phase-researcher.md +++ b/agents/gsd-phase-researcher.md @@ -10,6 +10,9 @@ You are a GSD phase researcher. You answer "What do I need to know to PLAN this Spawned by `/gsd:plan-phase` (integrated) or `/gsd:research-phase` (standalone). +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Core responsibilities:** - Investigate the phase's technical domain - Identify standard stack, patterns, and pitfalls diff --git a/agents/gsd-plan-checker.md b/agents/gsd-plan-checker.md index beddf647c..fa3878d92 100644 --- a/agents/gsd-plan-checker.md +++ b/agents/gsd-plan-checker.md @@ -12,6 +12,9 @@ Spawned by `/gsd:plan-phase` orchestrator (after planner creates PLAN.md) or re- Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify plans address it. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Critical mindset:** Plans describe intent. You verify they deliver. A plan can have all tasks filled in but still miss the goal if: - Key requirements have no tasks - Tasks exist but don't actually achieve the requirement diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index ae23ac493..126e33f9e 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -15,6 +15,9 @@ Spawned by: Your job: Produce PLAN.md files that Claude executors can implement without interpretation. Plans are prompts, not documents that become prompts. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Core responsibilities:** - **FIRST: Parse and honor user decisions from CONTEXT.md** (locked decisions are NON-NEGOTIABLE) - Decompose phases into parallel-optimized plans with 2-3 tasks each diff --git a/agents/gsd-project-researcher.md b/agents/gsd-project-researcher.md index e4b9f46ed..cbf5554bc 100644 --- a/agents/gsd-project-researcher.md +++ b/agents/gsd-project-researcher.md @@ -10,6 +10,9 @@ You are a GSD project researcher spawned by `/gsd:new-project` or `/gsd:new-mile Answer "What does this domain ecosystem look like?" Write research files in `.planning/research/` that inform roadmap creation. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + Your files feed the roadmap: | File | How Roadmap Uses It | diff --git a/agents/gsd-research-synthesizer.md b/agents/gsd-research-synthesizer.md index 87c48b280..b016557ad 100644 --- a/agents/gsd-research-synthesizer.md +++ b/agents/gsd-research-synthesizer.md @@ -14,6 +14,9 @@ You are spawned by: Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Core responsibilities:** - Read all 4 research files (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md) - Synthesize findings into executive summary diff --git a/agents/gsd-roadmapper.md b/agents/gsd-roadmapper.md index 60f0b8f1b..97b5cd22f 100644 --- a/agents/gsd-roadmapper.md +++ b/agents/gsd-roadmapper.md @@ -14,6 +14,9 @@ You are spawned by: Your job: Transform requirements into a phase structure that delivers the project. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Core responsibilities:** - Derive phases from requirements (not impose arbitrary structure) - Validate 100% requirement coverage (no orphans) diff --git a/agents/gsd-verifier.md b/agents/gsd-verifier.md index 812a7f257..6c325fc43 100644 --- a/agents/gsd-verifier.md +++ b/agents/gsd-verifier.md @@ -10,6 +10,9 @@ You are a GSD phase verifier. You verify that a phase achieved its GOAL, not jus Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase. +**CRITICAL: Mandatory Initial Read** +If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. + **Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ. diff --git a/commands/gsd/add-phase.md b/commands/gsd/add-phase.md index b04d89885..e3caa5fb2 100644 --- a/commands/gsd/add-phase.md +++ b/commands/gsd/add-phase.md @@ -19,11 +19,15 @@ Routes to the add-phase workflow which handles: -@.planning/ROADMAP.md -@.planning/STATE.md @~/.claude/get-shit-done/workflows/add-phase.md + +Arguments: $ARGUMENTS (phase description) + +Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls. + + **Follow the add-phase workflow** from `@~/.claude/get-shit-done/workflows/add-phase.md`. diff --git a/commands/gsd/add-todo.md b/commands/gsd/add-todo.md index c38d3f9cf..138abdcec 100644 --- a/commands/gsd/add-todo.md +++ b/commands/gsd/add-todo.md @@ -23,10 +23,15 @@ Routes to the add-todo workflow which handles: -@.planning/STATE.md @~/.claude/get-shit-done/workflows/add-todo.md + +Arguments: $ARGUMENTS (optional todo description) + +State is resolved in-workflow via `init todos` and targeted reads. + + **Follow the add-todo workflow** from `@~/.claude/get-shit-done/workflows/add-todo.md`. diff --git a/commands/gsd/audit-milestone.md b/commands/gsd/audit-milestone.md index 525419a6b..ba40548b2 100644 --- a/commands/gsd/audit-milestone.md +++ b/commands/gsd/audit-milestone.md @@ -23,13 +23,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c Version: $ARGUMENTS (optional — defaults to current milestone) -**Original Intent:** -@.planning/PROJECT.md -@.planning/REQUIREMENTS.md - -**Planned Work:** -@.planning/ROADMAP.md -@.planning/config.json (if exists) +Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed. **Completed Work:** Glob: .planning/phases/*/*-SUMMARY.md diff --git a/commands/gsd/check-todos.md b/commands/gsd/check-todos.md index 5ecc3c689..4955d25e3 100644 --- a/commands/gsd/check-todos.md +++ b/commands/gsd/check-todos.md @@ -21,11 +21,15 @@ Routes to the check-todos workflow which handles: -@.planning/STATE.md -@.planning/ROADMAP.md @~/.claude/get-shit-done/workflows/check-todos.md + +Arguments: $ARGUMENTS (optional area filter) + +Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads. + + **Follow the check-todos workflow** from `@~/.claude/get-shit-done/workflows/check-todos.md`. diff --git a/commands/gsd/debug.md b/commands/gsd/debug.md index d0014bb76..3ce14a1d1 100644 --- a/commands/gsd/debug.md +++ b/commands/gsd/debug.md @@ -129,7 +129,9 @@ Continue debugging {slug}. Evidence is in the debug file. -Debug file: @.planning/debug/{slug}.md + +- .planning/debug/{slug}.md (Debug session state) + diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md index 270aeba34..dbeb2a417 100644 --- a/commands/gsd/discuss-phase.md +++ b/commands/gsd/discuss-phase.md @@ -32,11 +32,7 @@ Extract implementation decisions that downstream agents need — researcher and Phase number: $ARGUMENTS (required) -**Load project state:** -@.planning/STATE.md - -**Load roadmap:** -@.planning/ROADMAP.md +Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls. diff --git a/commands/gsd/execute-phase.md b/commands/gsd/execute-phase.md index 2493c5502..1a798471f 100644 --- a/commands/gsd/execute-phase.md +++ b/commands/gsd/execute-phase.md @@ -32,8 +32,7 @@ Phase: $ARGUMENTS **Flags:** - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans. -@.planning/ROADMAP.md -@.planning/STATE.md +Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `` blocks. diff --git a/commands/gsd/insert-phase.md b/commands/gsd/insert-phase.md index dd593142f..e7c06a3f9 100644 --- a/commands/gsd/insert-phase.md +++ b/commands/gsd/insert-phase.md @@ -23,8 +23,7 @@ Purpose: Handle urgent work discovered during execution without renumbering enti Arguments: $ARGUMENTS (format: ) -@.planning/ROADMAP.md -@.planning/STATE.md +Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls. diff --git a/commands/gsd/list-phase-assumptions.md b/commands/gsd/list-phase-assumptions.md index 4f7a0a996..79083bc6e 100644 --- a/commands/gsd/list-phase-assumptions.md +++ b/commands/gsd/list-phase-assumptions.md @@ -23,11 +23,7 @@ Output: Conversational output only (no file creation) - ends with "What do you t Phase number: $ARGUMENTS (required) -**Load project state first:** -@.planning/STATE.md - -**Load roadmap:** -@.planning/ROADMAP.md +Project state and roadmap are loaded in-workflow using targeted reads. diff --git a/commands/gsd/new-milestone.md b/commands/gsd/new-milestone.md index a8611d806..1c28df6c7 100644 --- a/commands/gsd/new-milestone.md +++ b/commands/gsd/new-milestone.md @@ -35,14 +35,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga Milestone name: $ARGUMENTS (optional - will prompt if not provided) -**Load project context:** -@.planning/PROJECT.md -@.planning/STATE.md -@.planning/MILESTONES.md -@.planning/config.json - -**Load milestone context (if exists, from /gsd:discuss-milestone):** -@.planning/MILESTONE-CONTEXT.md +Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `` blocks where subagents are used. diff --git a/commands/gsd/pause-work.md b/commands/gsd/pause-work.md index 005cae725..9c25da536 100644 --- a/commands/gsd/pause-work.md +++ b/commands/gsd/pause-work.md @@ -19,10 +19,13 @@ Routes to the pause-work workflow which handles: -@.planning/STATE.md @~/.claude/get-shit-done/workflows/pause-work.md + +State and phase progress are gathered in-workflow with targeted reads. + + **Follow the pause-work workflow** from `@~/.claude/get-shit-done/workflows/pause-work.md`. diff --git a/commands/gsd/plan-milestone-gaps.md b/commands/gsd/plan-milestone-gaps.md index 1f438cc23..a9b684523 100644 --- a/commands/gsd/plan-milestone-gaps.md +++ b/commands/gsd/plan-milestone-gaps.md @@ -25,13 +25,7 @@ One command creates all fix phases — no manual `/gsd:add-phase` per gap. **Audit results:** Glob: .planning/v*-MILESTONE-AUDIT.md (use most recent) -**Original intent (for prioritization):** -@.planning/PROJECT.md -@.planning/REQUIREMENTS.md - -**Current state:** -@.planning/ROADMAP.md -@.planning/STATE.md +Original intent and current planning state are loaded on demand inside the workflow. diff --git a/commands/gsd/quick.md b/commands/gsd/quick.md index 06fe80e30..a8f8a75cd 100644 --- a/commands/gsd/quick.md +++ b/commands/gsd/quick.md @@ -30,8 +30,9 @@ Quick mode is the same system with a shorter path: -@.planning/STATE.md $ARGUMENTS + +Context files are resolved inside the workflow (`init quick`) and delegated via `` blocks. diff --git a/commands/gsd/remove-phase.md b/commands/gsd/remove-phase.md index 3bdb9a16d..6595738d1 100644 --- a/commands/gsd/remove-phase.md +++ b/commands/gsd/remove-phase.md @@ -22,8 +22,7 @@ Output: Phase deleted, all subsequent phases renumbered, git commit as historica Phase: $ARGUMENTS -@.planning/ROADMAP.md -@.planning/STATE.md +Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads. diff --git a/commands/gsd/research-phase.md b/commands/gsd/research-phase.md index b589cf317..ad022bf00 100644 --- a/commands/gsd/research-phase.md +++ b/commands/gsd/research-phase.md @@ -37,7 +37,7 @@ Normalize phase input in step 1 before any directory lookups. INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init phase-op "$ARGUMENTS") ``` -Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`. +Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`. Resolve researcher model: ```bash @@ -64,15 +64,12 @@ ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null ## 3. Gather Phase Context -```bash -# Phase section already loaded in PHASE_INFO -echo "$PHASE_INFO" | jq -r '.section' -cat .planning/REQUIREMENTS.md 2>/dev/null -cat .planning/phases/${PHASE}-*/*-CONTEXT.md 2>/dev/null -grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null -``` +Use paths from INIT (do not inline file contents in orchestrator context): +- `requirements_path` +- `context_path` +- `state_path` -Present summary with phase description, requirements, prior decisions. +Present summary with phase description and what files the researcher will load. ## 4. Spawn gsd-phase-researcher Agent @@ -101,12 +98,15 @@ Research implementation approach for Phase {phase_number}: {phase_name} Mode: ecosystem - + +- {requirements_path} (Requirements) +- {context_path} (Phase context from discuss-phase, if exists) +- {state_path} (Prior project decisions and blockers) + + + **Phase description:** {phase_description} -**Requirements:** {requirements_list} -**Prior decisions:** {decisions_if_any} -**Phase context:** {context_md_content} - + Your RESEARCH.md will be loaded by `/gsd:plan-phase` which uses specific sections: @@ -158,7 +158,9 @@ Continue research for Phase {phase_number}: {phase_name} -Research file: @.planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md + +- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research) + diff --git a/commands/gsd/verify-work.md b/commands/gsd/verify-work.md index 14ab175e3..089dcb8e0 100644 --- a/commands/gsd/verify-work.md +++ b/commands/gsd/verify-work.md @@ -29,8 +29,7 @@ Phase: $ARGUMENTS (optional) - If provided: Test specific phase (e.g., "4") - If not provided: Check for active sessions or prompt for phase -@.planning/STATE.md -@.planning/ROADMAP.md +Context files are resolved inside the workflow (`init verify-work`) and delegated via `` blocks. diff --git a/get-shit-done/bin/gsd-tools.cjs b/get-shit-done/bin/gsd-tools.cjs index 1f5f6646e..62d750edf 100755 --- a/get-shit-done/bin/gsd-tools.cjs +++ b/get-shit-done/bin/gsd-tools.cjs @@ -145,14 +145,6 @@ const MODEL_PROFILES = { // ─── Helpers ────────────────────────────────────────────────────────────────── -function parseIncludeFlag(args) { - const includeIndex = args.indexOf('--include'); - if (includeIndex === -1) return new Set(); - const includeValue = args[includeIndex + 1]; - if (!includeValue) return new Set(); - return new Set(includeValue.split(',').map(s => s.trim())); -} - function safeReadFile(filePath) { try { return fs.readFileSync(filePath, 'utf-8'); @@ -4244,7 +4236,7 @@ function getMilestoneInfo(cwd) { } } -function cmdInitExecutePhase(cwd, phase, includes, raw) { +function cmdInitExecutePhase(cwd, phase, raw) { if (!phase) { error('phase required for init execute-phase'); } @@ -4300,23 +4292,16 @@ function cmdInitExecutePhase(cwd, phase, includes, raw) { state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), config_exists: pathExistsInternal(cwd, '.planning/config.json'), + // File paths + state_path: '.planning/STATE.md', + roadmap_path: '.planning/ROADMAP.md', + config_path: '.planning/config.json', }; - // Include file contents if requested via --include - if (includes.has('state')) { - result.state_content = safeReadFile(path.join(cwd, '.planning', 'STATE.md')); - } - if (includes.has('config')) { - result.config_content = safeReadFile(path.join(cwd, '.planning', 'config.json')); - } - if (includes.has('roadmap')) { - result.roadmap_content = safeReadFile(path.join(cwd, '.planning', 'ROADMAP.md')); - } - output(result, raw); } -function cmdInitPlanPhase(cwd, phase, includes, raw) { +function cmdInitPlanPhase(cwd, phase, raw) { if (!phase) { error('phase required for init plan-phase'); } @@ -4352,59 +4337,33 @@ function cmdInitPlanPhase(cwd, phase, includes, raw) { // Environment planning_exists: pathExistsInternal(cwd, '.planning'), roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), + + // File paths + state_path: '.planning/STATE.md', + roadmap_path: '.planning/ROADMAP.md', + requirements_path: '.planning/REQUIREMENTS.md', }; - // Include file contents if requested via --include - if (includes.has('state')) { - result.state_content = safeReadFile(path.join(cwd, '.planning', 'STATE.md')); - } - if (includes.has('roadmap')) { - result.roadmap_content = safeReadFile(path.join(cwd, '.planning', 'ROADMAP.md')); - } - if (includes.has('requirements')) { - result.requirements_content = safeReadFile(path.join(cwd, '.planning', 'REQUIREMENTS.md')); - } - if (includes.has('context') && phaseInfo?.directory) { + if (phaseInfo?.directory) { // Find *-CONTEXT.md in phase directory const phaseDirFull = path.join(cwd, phaseInfo.directory); try { const files = fs.readdirSync(phaseDirFull); const contextFile = files.find(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'); if (contextFile) { - result.context_content = safeReadFile(path.join(phaseDirFull, contextFile)); + result.context_path = path.join(phaseInfo.directory, contextFile); } - } catch {} - } - if (includes.has('research') && phaseInfo?.directory) { - // Find *-RESEARCH.md in phase directory - const phaseDirFull = path.join(cwd, phaseInfo.directory); - try { - const files = fs.readdirSync(phaseDirFull); const researchFile = files.find(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'); if (researchFile) { - result.research_content = safeReadFile(path.join(phaseDirFull, researchFile)); + result.research_path = path.join(phaseInfo.directory, researchFile); } - } catch {} - } - if (includes.has('verification') && phaseInfo?.directory) { - // Find *-VERIFICATION.md in phase directory - const phaseDirFull = path.join(cwd, phaseInfo.directory); - try { - const files = fs.readdirSync(phaseDirFull); const verificationFile = files.find(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'); if (verificationFile) { - result.verification_content = safeReadFile(path.join(phaseDirFull, verificationFile)); + result.verification_path = path.join(phaseInfo.directory, verificationFile); } - } catch {} - } - if (includes.has('uat') && phaseInfo?.directory) { - // Find *-UAT.md in phase directory - const phaseDirFull = path.join(cwd, phaseInfo.directory); - try { - const files = fs.readdirSync(phaseDirFull); const uatFile = files.find(f => f.endsWith('-UAT.md') || f === 'UAT.md'); if (uatFile) { - result.uat_content = safeReadFile(path.join(phaseDirFull, uatFile)); + result.uat_path = path.join(phaseInfo.directory, uatFile); } } catch {} } @@ -4463,6 +4422,9 @@ function cmdInitNewProject(cwd, raw) { // Enhanced search brave_search_available: hasBraveSearch, + + // File paths + project_path: '.planning/PROJECT.md', }; output(result, raw); @@ -4490,6 +4452,11 @@ function cmdInitNewMilestone(cwd, raw) { project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), + + // File paths + project_path: '.planning/PROJECT.md', + roadmap_path: '.planning/ROADMAP.md', + state_path: '.planning/STATE.md', }; output(result, raw); @@ -4539,6 +4506,7 @@ function cmdInitQuick(cwd, description, raw) { // File existence roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), planning_exists: pathExistsInternal(cwd, '.planning'), + }; output(result, raw); @@ -4560,6 +4528,11 @@ function cmdInitResume(cwd, raw) { project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), planning_exists: pathExistsInternal(cwd, '.planning'), + // File paths + state_path: '.planning/STATE.md', + roadmap_path: '.planning/ROADMAP.md', + project_path: '.planning/PROJECT.md', + // Agent state has_interrupted_agent: !!interruptedAgentId, interrupted_agent_id: interruptedAgentId, @@ -4648,8 +4621,36 @@ function cmdInitPhaseOp(cwd, phase, raw) { // File existence roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), planning_exists: pathExistsInternal(cwd, '.planning'), + + // File paths + state_path: '.planning/STATE.md', + roadmap_path: '.planning/ROADMAP.md', + requirements_path: '.planning/REQUIREMENTS.md', }; + if (phaseInfo?.directory) { + const phaseDirFull = path.join(cwd, phaseInfo.directory); + try { + const files = fs.readdirSync(phaseDirFull); + const contextFile = files.find(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'); + if (contextFile) { + result.context_path = path.join(phaseInfo.directory, contextFile); + } + const researchFile = files.find(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'); + if (researchFile) { + result.research_path = path.join(phaseInfo.directory, researchFile); + } + const verificationFile = files.find(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'); + if (verificationFile) { + result.verification_path = path.join(phaseInfo.directory, verificationFile); + } + const uatFile = files.find(f => f.endsWith('-UAT.md') || f === 'UAT.md'); + if (uatFile) { + result.uat_path = path.join(phaseInfo.directory, uatFile); + } + } catch {} + } + output(result, raw); } @@ -4807,7 +4808,7 @@ function cmdInitMapCodebase(cwd, raw) { output(result, raw); } -function cmdInitProgress(cwd, includes, raw) { +function cmdInitProgress(cwd, raw) { const config = loadConfig(cwd); const milestone = getMilestoneInfo(cwd); @@ -4895,22 +4896,13 @@ function cmdInitProgress(cwd, includes, raw) { project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), + // File paths + state_path: '.planning/STATE.md', + roadmap_path: '.planning/ROADMAP.md', + project_path: '.planning/PROJECT.md', + config_path: '.planning/config.json', }; - // Include file contents if requested via --include - if (includes.has('state')) { - result.state_content = safeReadFile(path.join(cwd, '.planning', 'STATE.md')); - } - if (includes.has('roadmap')) { - result.roadmap_content = safeReadFile(path.join(cwd, '.planning', 'ROADMAP.md')); - } - if (includes.has('project')) { - result.project_content = safeReadFile(path.join(cwd, '.planning', 'PROJECT.md')); - } - if (includes.has('config')) { - result.config_content = safeReadFile(path.join(cwd, '.planning', 'config.json')); - } - output(result, raw); } @@ -5252,13 +5244,12 @@ async function main() { case 'init': { const workflow = args[1]; - const includes = parseIncludeFlag(args); switch (workflow) { case 'execute-phase': - cmdInitExecutePhase(cwd, args[2], includes, raw); + cmdInitExecutePhase(cwd, args[2], raw); break; case 'plan-phase': - cmdInitPlanPhase(cwd, args[2], includes, raw); + cmdInitPlanPhase(cwd, args[2], raw); break; case 'new-project': cmdInitNewProject(cwd, raw); @@ -5288,7 +5279,7 @@ async function main() { cmdInitMapCodebase(cwd, raw); break; case 'progress': - cmdInitProgress(cwd, includes, raw); + cmdInitProgress(cwd, raw); break; default: error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, phase-op, todos, milestone-op, map-codebase, progress`); diff --git a/get-shit-done/bin/gsd-tools.test.cjs b/get-shit-done/bin/gsd-tools.test.cjs index 9fe423934..2136e0369 100644 --- a/get-shit-done/bin/gsd-tools.test.cjs +++ b/get-shit-done/bin/gsd-tools.test.cjs @@ -1098,10 +1098,10 @@ key-decisions: }); // ───────────────────────────────────────────────────────────────────────────── -// init --include flag tests +// init commands tests // ───────────────────────────────────────────────────────────────────────────── -describe('init commands with --include flag', () => { +describe('init commands', () => { let tmpDir; beforeEach(() => { @@ -1112,127 +1112,83 @@ describe('init commands with --include flag', () => { cleanup(tmpDir); }); - test('init execute-phase includes state and config content', () => { + test('init execute-phase returns file paths', () => { const phaseDir = path.join(tmpDir, '.planning', 'phases', '03-api'); fs.mkdirSync(phaseDir, { recursive: true }); fs.writeFileSync(path.join(phaseDir, '03-01-PLAN.md'), '# Plan'); - fs.writeFileSync( - path.join(tmpDir, '.planning', 'STATE.md'), - '# State\n\n**Current Phase:** 03\n**Status:** In progress' - ); - fs.writeFileSync( - path.join(tmpDir, '.planning', 'config.json'), - JSON.stringify({ model_profile: 'balanced' }) - ); - - const result = runGsdTools('init execute-phase 03 --include state,config', tmpDir); - assert.ok(result.success, `Command failed: ${result.error}`); - - const output = JSON.parse(result.output); - assert.ok(output.state_content, 'state_content should be included'); - assert.ok(output.state_content.includes('Current Phase'), 'state content correct'); - assert.ok(output.config_content, 'config_content should be included'); - assert.ok(output.config_content.includes('model_profile'), 'config content correct'); - }); - - test('init execute-phase without --include omits content', () => { - const phaseDir = path.join(tmpDir, '.planning', 'phases', '03-api'); - fs.mkdirSync(phaseDir, { recursive: true }); - fs.writeFileSync(path.join(phaseDir, '03-01-PLAN.md'), '# Plan'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# State'); const result = runGsdTools('init execute-phase 03', tmpDir); assert.ok(result.success, `Command failed: ${result.error}`); const output = JSON.parse(result.output); - assert.strictEqual(output.state_content, undefined, 'state_content should be omitted'); - assert.strictEqual(output.config_content, undefined, 'config_content should be omitted'); + assert.strictEqual(output.state_path, '.planning/STATE.md'); + assert.strictEqual(output.roadmap_path, '.planning/ROADMAP.md'); + assert.strictEqual(output.config_path, '.planning/config.json'); }); - test('init plan-phase includes multiple file contents', () => { + test('init plan-phase returns file paths', () => { const phaseDir = path.join(tmpDir, '.planning', 'phases', '03-api'); fs.mkdirSync(phaseDir, { recursive: true }); - fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# Project State'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'ROADMAP.md'), '# Roadmap v1.0'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'REQUIREMENTS.md'), '# Requirements'); fs.writeFileSync(path.join(phaseDir, '03-CONTEXT.md'), '# Phase Context'); fs.writeFileSync(path.join(phaseDir, '03-RESEARCH.md'), '# Research Findings'); + fs.writeFileSync(path.join(phaseDir, '03-VERIFICATION.md'), '# Verification'); + fs.writeFileSync(path.join(phaseDir, '03-UAT.md'), '# UAT'); - const result = runGsdTools('init plan-phase 03 --include state,roadmap,requirements,context,research', tmpDir); + const result = runGsdTools('init plan-phase 03', tmpDir); assert.ok(result.success, `Command failed: ${result.error}`); const output = JSON.parse(result.output); - assert.ok(output.state_content, 'state_content included'); - assert.ok(output.state_content.includes('Project State'), 'state content correct'); - assert.ok(output.roadmap_content, 'roadmap_content included'); - assert.ok(output.roadmap_content.includes('Roadmap v1.0'), 'roadmap content correct'); - assert.ok(output.requirements_content, 'requirements_content included'); - assert.ok(output.context_content, 'context_content included'); - assert.ok(output.research_content, 'research_content included'); + assert.strictEqual(output.state_path, '.planning/STATE.md'); + assert.strictEqual(output.roadmap_path, '.planning/ROADMAP.md'); + assert.strictEqual(output.requirements_path, '.planning/REQUIREMENTS.md'); + assert.strictEqual(output.context_path, '.planning/phases/03-api/03-CONTEXT.md'); + assert.strictEqual(output.research_path, '.planning/phases/03-api/03-RESEARCH.md'); + assert.strictEqual(output.verification_path, '.planning/phases/03-api/03-VERIFICATION.md'); + assert.strictEqual(output.uat_path, '.planning/phases/03-api/03-UAT.md'); }); - test('init plan-phase includes verification and uat content', () => { + test('init progress returns file paths', () => { + const result = runGsdTools('init progress', tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const output = JSON.parse(result.output); + assert.strictEqual(output.state_path, '.planning/STATE.md'); + assert.strictEqual(output.roadmap_path, '.planning/ROADMAP.md'); + assert.strictEqual(output.project_path, '.planning/PROJECT.md'); + assert.strictEqual(output.config_path, '.planning/config.json'); + }); + + test('init phase-op returns core and optional phase file paths', () => { const phaseDir = path.join(tmpDir, '.planning', 'phases', '03-api'); fs.mkdirSync(phaseDir, { recursive: true }); - fs.writeFileSync(path.join(phaseDir, '03-VERIFICATION.md'), '# Verification Results'); - fs.writeFileSync(path.join(phaseDir, '03-UAT.md'), '# UAT Findings'); + fs.writeFileSync(path.join(phaseDir, '03-CONTEXT.md'), '# Phase Context'); + fs.writeFileSync(path.join(phaseDir, '03-RESEARCH.md'), '# Research'); + fs.writeFileSync(path.join(phaseDir, '03-VERIFICATION.md'), '# Verification'); + fs.writeFileSync(path.join(phaseDir, '03-UAT.md'), '# UAT'); - const result = runGsdTools('init plan-phase 03 --include verification,uat', tmpDir); + const result = runGsdTools('init phase-op 03', tmpDir); assert.ok(result.success, `Command failed: ${result.error}`); const output = JSON.parse(result.output); - assert.ok(output.verification_content, 'verification_content included'); - assert.ok(output.verification_content.includes('Verification Results'), 'verification content correct'); - assert.ok(output.uat_content, 'uat_content included'); - assert.ok(output.uat_content.includes('UAT Findings'), 'uat content correct'); + assert.strictEqual(output.state_path, '.planning/STATE.md'); + assert.strictEqual(output.roadmap_path, '.planning/ROADMAP.md'); + assert.strictEqual(output.requirements_path, '.planning/REQUIREMENTS.md'); + assert.strictEqual(output.context_path, '.planning/phases/03-api/03-CONTEXT.md'); + assert.strictEqual(output.research_path, '.planning/phases/03-api/03-RESEARCH.md'); + assert.strictEqual(output.verification_path, '.planning/phases/03-api/03-VERIFICATION.md'); + assert.strictEqual(output.uat_path, '.planning/phases/03-api/03-UAT.md'); }); - test('init progress includes state, roadmap, project, config', () => { - fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# State'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'ROADMAP.md'), '# Roadmap'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'PROJECT.md'), '# Project'); - fs.writeFileSync( - path.join(tmpDir, '.planning', 'config.json'), - JSON.stringify({ model_profile: 'quality' }) - ); - - const result = runGsdTools('init progress --include state,roadmap,project,config', tmpDir); - assert.ok(result.success, `Command failed: ${result.error}`); - - const output = JSON.parse(result.output); - assert.ok(output.state_content, 'state_content included'); - assert.ok(output.roadmap_content, 'roadmap_content included'); - assert.ok(output.project_content, 'project_content included'); - assert.ok(output.config_content, 'config_content included'); - }); - - test('missing files return null in content fields', () => { + test('init plan-phase omits optional paths if files missing', () => { const phaseDir = path.join(tmpDir, '.planning', 'phases', '03-api'); fs.mkdirSync(phaseDir, { recursive: true }); - fs.writeFileSync(path.join(phaseDir, '03-01-PLAN.md'), '# Plan'); - const result = runGsdTools('init execute-phase 03 --include state,config', tmpDir); + const result = runGsdTools('init plan-phase 03', tmpDir); assert.ok(result.success, `Command failed: ${result.error}`); const output = JSON.parse(result.output); - assert.strictEqual(output.state_content, null, 'missing state returns null'); - assert.strictEqual(output.config_content, null, 'missing config returns null'); - }); - - test('partial includes work correctly', () => { - const phaseDir = path.join(tmpDir, '.planning', 'phases', '03-api'); - fs.mkdirSync(phaseDir, { recursive: true }); - fs.writeFileSync(path.join(phaseDir, '03-01-PLAN.md'), '# Plan'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# State'); - fs.writeFileSync(path.join(tmpDir, '.planning', 'ROADMAP.md'), '# Roadmap'); - - // Only request state, not roadmap - const result = runGsdTools('init execute-phase 03 --include state', tmpDir); - assert.ok(result.success, `Command failed: ${result.error}`); - - const output = JSON.parse(result.output); - assert.ok(output.state_content, 'state_content included'); - assert.strictEqual(output.roadmap_content, undefined, 'roadmap_content not requested, should be undefined'); + assert.strictEqual(output.context_path, undefined); + assert.strictEqual(output.research_path, undefined); }); }); diff --git a/get-shit-done/workflows/diagnose-issues.md b/get-shit-done/workflows/diagnose-issues.md index b30245865..27e40a5b7 100644 --- a/get-shit-done/workflows/diagnose-issues.md +++ b/get-shit-done/workflows/diagnose-issues.md @@ -79,7 +79,7 @@ For each gap, fill the debug-subagent-prompt template and spawn: ``` Task( - prompt=filled_debug_subagent_prompt, + prompt=filled_debug_subagent_prompt + "\n\n\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n", subagent_type="general-purpose", description="Debug: {truth_short}" ) diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index dc6258567..5e3397574 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -118,11 +118,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true` Read these files at execution start using the Read tool: - - Plan: {phase_dir}/{plan_file} - - State: .planning/STATE.md - - Config: .planning/config.json (if exists) - - Project instructions: ./CLAUDE.md (if exists — follow project-specific guidelines and coding conventions) - - Project skills: .agents/skills/ (if exists — list skills, read SKILL.md for each, follow relevant rules during implementation) + - {phase_dir}/{plan_file} (Plan) + - .planning/STATE.md (State) + - .planning/config.json (Config, if exists) + - ./CLAUDE.md (Project instructions, if exists — follow project-specific guidelines and coding conventions) + - .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation) @@ -375,7 +375,7 @@ The CLI handles: Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`. ```bash -node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/{phase_dir}/*-VERIFICATION.md +node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md ``` diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index 4b51d7c40..0c2edb802 100644 --- a/get-shit-done/workflows/execute-plan.md +++ b/get-shit-done/workflows/execute-plan.md @@ -12,19 +12,13 @@ Read config.json for planning behavior settings. -Load execution context (uses `init execute-phase` for full context, including file contents): +Load execution context (paths only to minimize orchestrator context): ```bash -INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init execute-phase "${PHASE}" --include state,config) +INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init execute-phase "${PHASE}") ``` -Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`. - -**File contents (from --include):** `state_content`, `config_content`. Access with: -```bash -STATE_CONTENT=$(echo "$INIT" | jq -r '.state_content // empty') -CONFIG_CONTENT=$(echo "$INIT" | jq -r '.config_content // empty') -``` +Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`, `state_path`, `config_path`. If `.planning/` missing: error. @@ -40,7 +34,7 @@ Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix ```bash PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+') -# config_content already loaded via --include config in init_context +# config settings can be fetched via gsd-tools config-get if needed ``` diff --git a/get-shit-done/workflows/new-milestone.md b/get-shit-done/workflows/new-milestone.md index e8324b865..3b4c11bd1 100644 --- a/get-shit-done/workflows/new-milestone.md +++ b/get-shit-done/workflows/new-milestone.md @@ -128,7 +128,9 @@ Focus ONLY on what's needed for the NEW features. {QUESTION} -[PROJECT.md summary] + +- .planning/PROJECT.md (Project context) + {CONSUMER} @@ -157,7 +159,12 @@ After all 4 complete, spawn synthesizer: Task(prompt=" Synthesize research outputs into SUMMARY.md. -Read: .planning/research/STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md + +- .planning/research/STACK.md +- .planning/research/FEATURES.md +- .planning/research/ARCHITECTURE.md +- .planning/research/PITFALLS.md + Write to: .planning/research/SUMMARY.md Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md @@ -264,11 +271,13 @@ node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs: define milestone v[ ``` Task(prompt=" -@.planning/PROJECT.md -@.planning/REQUIREMENTS.md -@.planning/research/SUMMARY.md (if exists) -@.planning/config.json -@.planning/MILESTONES.md + +- .planning/PROJECT.md +- .planning/REQUIREMENTS.md +- .planning/research/SUMMARY.md (if exists) +- .planning/config.json +- .planning/MILESTONES.md + diff --git a/get-shit-done/workflows/new-project.md b/get-shit-done/workflows/new-project.md index 5ace0589f..b925dbbdc 100644 --- a/get-shit-done/workflows/new-project.md +++ b/get-shit-done/workflows/new-project.md @@ -49,7 +49,7 @@ The document should describe what you want to build. INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init new-project) ``` -Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`. +Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`. **If `project_exists` is true:** Error — project already initialized. Use `/gsd:progress`. @@ -541,7 +541,7 @@ Display spawning indicator: → Pitfalls research ``` -Spawn 4 parallel gsd-project-researcher agents with rich context: +Spawn 4 parallel gsd-project-researcher agents with path references: ``` Task(prompt="First, read ~/.claude/agents/gsd-project-researcher.md for your role and instructions. @@ -561,9 +561,9 @@ Subsequent: Research what's needed to add [target features] to an existing [doma What's the standard 2025 stack for [domain]? - -[PROJECT.md summary - core value, constraints, what they're building] - + +- {project_path} (Project context and goals) + Your STACK.md feeds into roadmap creation. Be prescriptive: @@ -601,9 +601,9 @@ Subsequent: How do [target features] typically work? What's expected behavior? What features do [domain] products have? What's table stakes vs differentiating? - -[PROJECT.md summary] - + +- {project_path} (Project context) + Your FEATURES.md feeds into requirements definition. Categorize clearly: @@ -641,9 +641,9 @@ Subsequent: How do [target features] integrate with existing [domain] architectu How are [domain] systems typically structured? What are major components? - -[PROJECT.md summary] - + +- {project_path} (Project context) + Your ARCHITECTURE.md informs phase structure in roadmap. Include: @@ -681,9 +681,9 @@ Subsequent: What are common mistakes when adding [target features] to [domain]? What do [domain] projects commonly get wrong? Critical mistakes? - -[PROJECT.md summary] - + +- {project_path} (Project context) + Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall: @@ -713,13 +713,12 @@ Task(prompt=" Synthesize research outputs into SUMMARY.md. - -Read these files: + - .planning/research/STACK.md - .planning/research/FEATURES.md - .planning/research/ARCHITECTURE.md - .planning/research/PITFALLS.md - + Write to: .planning/research/SUMMARY.md @@ -902,23 +901,18 @@ Display stage banner: ◆ Spawning roadmapper... ``` -Spawn gsd-roadmapper agent with context: +Spawn gsd-roadmapper agent with path references: ``` Task(prompt=" -**Project:** -@.planning/PROJECT.md - -**Requirements:** -@.planning/REQUIREMENTS.md - -**Research (if exists):** -@.planning/research/SUMMARY.md - -**Config:** -@.planning/config.json + +- .planning/PROJECT.md (Project context) +- .planning/REQUIREMENTS.md (v1 Requirements) +- .planning/research/SUMMARY.md (Research findings - if exists) +- .planning/config.json (Depth and mode settings) + @@ -1006,7 +1000,9 @@ Use AskUserQuestion: User feedback on roadmap: [user's notes] - Current ROADMAP.md: @.planning/ROADMAP.md + + - .planning/ROADMAP.md (Current roadmap to revise) + Update the roadmap based on feedback. Edit files in place. Return ROADMAP REVISED with changes made. diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index efe7bd158..de05d11ea 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -12,23 +12,15 @@ Read all files referenced by the invoking prompt's execution_context before star ## 1. Initialize -Load all context in one call (include file contents to avoid redundant reads): +Load all context in one call (paths only to minimize orchestrator context): ```bash -INIT_RAW=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init plan-phase "$PHASE" --include state,roadmap,requirements,context,research,verification,uat) -# Large payloads are written to a tmpfile — output starts with @file:/path -if [[ "$INIT_RAW" == @file:* ]]; then - INIT_FILE="${INIT_RAW#@file:}" - INIT=$(cat "$INIT_FILE") - rm -f "$INIT_FILE" -else - INIT="$INIT_RAW" -fi +INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init plan-phase "$PHASE") ``` Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`. -**File contents (from --include):** `state_content`, `roadmap_content`, `requirements_content`, `context_content`, `research_content`, `verification_content`, `uat_content`. These are null if files don't exist. +**File paths (for blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist. **If `planning_exists` is false:** Error — run `/gsd:new-project` first. @@ -55,13 +47,11 @@ PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$ ## 4. Load CONTEXT.md -Use `context_content` from init JSON (already loaded via `--include context`). +Check `context_path` from init JSON. -**CRITICAL:** Use `context_content` from INIT — pass to researcher, planner, checker, and revision agents. +If `context_path` is not null, display: `Using phase context from: ${context_path}` -If `context_content` is not null, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md` - -**If `context_content` is null (no CONTEXT.md exists):** +**If `context_path` is null (no CONTEXT.md exists):** Use AskUserQuestion: - header: "No context" @@ -94,11 +84,7 @@ Display banner: ```bash PHASE_DESC=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${PHASE}" | jq -r '.section') -# Use requirements_content from INIT (already loaded via --include requirements) -REQUIREMENTS=$(echo "$INIT" | jq -r '.requirements_content // empty' | grep -A100 "## Requirements" | head -50) -PHASE_REQ_IDS=$(echo "$INIT" | jq -r '.roadmap_content // empty' | grep -i "Requirements:" | head -1 | sed 's/.*Requirements:\*\*\s*//' | sed 's/[\[\]]//g' | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -v '^$' | tr '\n' ',' | sed 's/,$//') -STATE_SNAP=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs state-snapshot) -# Extract decisions from state-snapshot JSON: jq '.decisions[] | "\(.phase): \(.summary) - \(.rationale)"' +PHASE_REQ_IDS=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${PHASE}" | jq -r '.section // empty' | grep -i "Requirements:" | head -1 | sed 's/.*Requirements:\*\*\s*//' | sed 's/[\[\]]//g' | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -v '^$' | tr '\n' ',' | sed 's/,$//') ``` Research prompt: @@ -109,20 +95,15 @@ 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** = Locked — research THESE deeply, no alternatives -- **Claude's Discretion** = Freedom areas — research options, recommend -- **Deferred Ideas** = Out of scope — ignore - -{context_content} - + +- {context_path} (USER DECISIONS from /gsd:discuss-phase) +- {requirements_path} (Project requirements) +- {state_path} (Project decisions and history) + **Phase description:** {phase_description} **Phase requirement IDs (MUST address):** {phase_req_ids} -**Requirements:** {requirements} -**Prior decisions:** {decisions} **Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines **Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, research should account for project skill patterns @@ -155,19 +136,18 @@ ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null **If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch. -## 7. Use Context Files from INIT +## 7. Use Context Paths from INIT -All file contents are already loaded via `--include` in step 1 (`@` syntax doesn't work across Task() boundaries): +Extract from INIT JSON: ```bash -# Extract from INIT JSON (no need to re-read files) -STATE_CONTENT=$(echo "$INIT" | jq -r '.state_content // empty') -ROADMAP_CONTENT=$(echo "$INIT" | jq -r '.roadmap_content // empty') -REQUIREMENTS_CONTENT=$(echo "$INIT" | jq -r '.requirements_content // empty') -RESEARCH_CONTENT=$(echo "$INIT" | jq -r '.research_content // empty') -VERIFICATION_CONTENT=$(echo "$INIT" | jq -r '.verification_content // empty') -UAT_CONTENT=$(echo "$INIT" | jq -r '.uat_content // empty') -CONTEXT_CONTENT=$(echo "$INIT" | jq -r '.context_content // empty') +STATE_PATH=$(echo "$INIT" | jq -r '.state_path // empty') +ROADMAP_PATH=$(echo "$INIT" | jq -r '.roadmap_path // empty') +REQUIREMENTS_PATH=$(echo "$INIT" | jq -r '.requirements_path // empty') +RESEARCH_PATH=$(echo "$INIT" | jq -r '.research_path // empty') +VERIFICATION_PATH=$(echo "$INIT" | jq -r '.verification_path // empty') +UAT_PATH=$(echo "$INIT" | jq -r '.uat_path // empty') +CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty') ``` ## 8. Spawn gsd-planner Agent @@ -188,21 +168,17 @@ Planner prompt: **Phase:** {phase_number} **Mode:** {standard | gap_closure} -**Project State:** {state_content} -**Roadmap:** {roadmap_content} + +- {state_path} (Project State) +- {roadmap_path} (Roadmap) +- {requirements_path} (Requirements) +- {context_path} (USER DECISIONS from /gsd:discuss-phase) +- {research_path} (Technical Research) +- {verification_path} (Verification Gaps - if --gaps) +- {uat_path} (UAT Gaps - if --gaps) + + **Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids} -**Requirements:** {requirements_content} - -**Phase Context:** -IMPORTANT: If context exists below, it contains USER DECISIONS from /gsd:discuss-phase. -- **Decisions** = LOCKED — honor exactly, do not revisit -- **Claude's Discretion** = Freedom — make implementation choices -- **Deferred Ideas** = Out of scope — do NOT include - -{context_content} - -**Research:** {research_content} -**Gap Closure (if --gaps):** {verification_content} {uat_content} **Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines **Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules @@ -252,10 +228,6 @@ Display banner: ◆ Spawning plan checker... ``` -```bash -PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null) -``` - Checker prompt: ```markdown @@ -263,17 +235,14 @@ Checker prompt: **Phase:** {phase_number} **Phase Goal:** {goal from ROADMAP} -**Plans to verify:** {plans_content} + +- {PHASE_DIR}/*-PLAN.md (Plans to verify) +- {roadmap_path} (Roadmap) +- {requirements_path} (Requirements) +- {context_path} (USER DECISIONS from /gsd:discuss-phase) + + **Phase requirement IDs (MUST ALL be covered):** {phase_req_ids} -**Requirements:** {requirements_content} - -**Phase Context:** -IMPORTANT: Plans MUST honor user decisions. Flag as issue if plans contradict. -- **Decisions** = LOCKED — plans must implement exactly -- **Claude's Discretion** = Freedom areas — plans can choose approach -- **Deferred Ideas** = Out of scope — plans must NOT include - -{context_content} **Project instructions:** Read ./CLAUDE.md if exists — verify plans honor project guidelines **Project skills:** Check .agents/skills/ directory (if exists) — verify plans account for project skill rules @@ -307,10 +276,6 @@ Track `iteration_count` (starts at 1 after initial plan + check). Display: `Sending back to planner for revision... (iteration {N}/3)` -```bash -PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null) -``` - Revision prompt: ```markdown @@ -318,12 +283,12 @@ Revision prompt: **Phase:** {phase_number} **Mode:** revision -**Existing plans:** {plans_content} -**Checker issues:** {structured_issues_from_checker} + +- {PHASE_DIR}/*-PLAN.md (Existing plans) +- {context_path} (USER DECISIONS from /gsd:discuss-phase) + -**Phase Context:** -Revisions MUST still honor user decisions. -{context_content} +**Checker issues:** {structured_issues_from_checker} diff --git a/get-shit-done/workflows/progress.md b/get-shit-done/workflows/progress.md index 12ae46e58..ea124fb08 100644 --- a/get-shit-done/workflows/progress.md +++ b/get-shit-done/workflows/progress.md @@ -9,23 +9,13 @@ Read all files referenced by the invoking prompt's execution_context before star -**Load progress context (with file contents to avoid redundant reads):** +**Load progress context (paths only):** ```bash -INIT_RAW=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init progress --include state,roadmap,project,config) -# Large payloads are written to a tmpfile — output starts with @file:/path -if [[ "$INIT_RAW" == @file:* ]]; then - INIT_FILE="${INIT_RAW#@file:}" - INIT=$(cat "$INIT_FILE") - rm -f "$INIT_FILE" -else - INIT="$INIT_RAW" -fi +INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init progress) ``` -Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`. - -**File contents (from --include):** `state_content`, `roadmap_content`, `project_content`, `config_content`. These are null if files don't exist. +Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`. If `project_exists` is false (no `.planning/` directory): @@ -47,15 +37,13 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/gsd:new-project`. -**Use project context from INIT:** +**Use structured extraction from gsd-tools:** -All file contents are already loaded via `--include` in init_context step: -- `state_content` — living memory (position, decisions, issues) -- `roadmap_content` — phase structure and objectives -- `project_content` — current state (What This Is, Core Value, Requirements) -- `config_content` — settings (model_profile, workflow toggles) +Instead of reading full files, use targeted tools to get only the data needed for the report: +- `ROADMAP=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap analyze)` +- `STATE=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs state-snapshot)` -No additional file reads needed. +This minimizes orchestrator context usage. @@ -89,9 +77,8 @@ Use this instead of manually reading/parsing ROADMAP.md. **Parse current position from init context and roadmap analysis:** -- Use `current_phase` and `next_phase` from roadmap analyze -- Use phase-level `has_context` and `has_research` flags from analyze -- Note `paused_at` if work was paused (from init context) +- Use `current_phase` and `next_phase` from `$ROADMAP` +- Note `paused_at` if work was paused (from `$STATE`) - Count pending todos: use `init todos` or `list-todos` - Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l` @@ -122,11 +109,12 @@ Plan [M] of [phase-total]: [status] CONTEXT: [✓ if has_context | - if not] ## Key Decisions Made -- [decision 1 from STATE.md] -- [decision 2] +- [extract from $STATE.decisions[]] +- [e.g. jq -r '.decisions[].decision' from state-snapshot] ## Blockers/Concerns -- [any blockers or concerns from STATE.md] +- [extract from $STATE.blockers[]] +- [e.g. jq -r '.blockers[].text' from state-snapshot] ## Pending Todos - [count] pending — /gsd:check-todos to review diff --git a/get-shit-done/workflows/quick.md b/get-shit-done/workflows/quick.md index 6ae1e5477..ba306eaac 100644 --- a/get-shit-done/workflows/quick.md +++ b/get-shit-done/workflows/quick.md @@ -96,10 +96,11 @@ Task( **Directory:** ${QUICK_DIR} **Description:** ${DESCRIPTION} -**Project State:** -@.planning/STATE.md + +- .planning/STATE.md (Project State) +- ./CLAUDE.md (if exists — follow project-specific guidelines) + -**Project instructions:** Read ./CLAUDE.md if exists — follow project-specific guidelines **Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules @@ -146,10 +147,6 @@ Display banner: ◆ Spawning plan checker... ``` -```bash -PLAN_CONTENT=$(cat "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null) -``` - Checker prompt: ```markdown @@ -157,7 +154,9 @@ Checker prompt: **Mode:** quick-full **Task Description:** ${DESCRIPTION} -**Plan to verify:** ${PLAN_CONTENT} + +- ${QUICK_DIR}/${next_num}-PLAN.md (Plan to verify) + **Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal. @@ -200,17 +199,16 @@ Track `iteration_count` (starts at 1 after initial plan + check). Display: `Sending back to planner for revision... (iteration ${N}/2)` -```bash -PLAN_CONTENT=$(cat "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null) -``` - Revision prompt: ```markdown **Mode:** quick-full (revision) -**Existing plan:** ${PLAN_CONTENT} + +- ${QUICK_DIR}/${next_num}-PLAN.md (Existing plan) + + **Checker issues:** ${structured_issues_from_checker} @@ -250,10 +248,12 @@ Task( prompt=" Execute quick task ${next_num}. -Plan: @${QUICK_DIR}/${next_num}-PLAN.md -Project state: @.planning/STATE.md -Project instructions: ./CLAUDE.md (if exists — follow project-specific guidelines) -Project skills: .agents/skills/ (if exists — list skills, read SKILL.md for each, follow relevant rules during implementation) + +- ${QUICK_DIR}/${next_num}-PLAN.md (Plan) +- .planning/STATE.md (Project state) +- ./CLAUDE.md (Project instructions, if exists) +- .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation) + - Execute all tasks in the plan @@ -299,7 +299,11 @@ Task( prompt="Verify quick task goal achievement. Task directory: ${QUICK_DIR} Task goal: ${DESCRIPTION} -Plan: @${QUICK_DIR}/${next_num}-PLAN.md + + +- ${QUICK_DIR}/${next_num}-PLAN.md (Plan) + + Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${next_num}-VERIFICATION.md.", subagent_type="gsd-verifier", model="{verifier_model}", diff --git a/get-shit-done/workflows/research-phase.md b/get-shit-done/workflows/research-phase.md index 771b0e44d..d4ead4536 100644 --- a/get-shit-done/workflows/research-phase.md +++ b/get-shit-done/workflows/research-phase.md @@ -34,12 +34,8 @@ If exists: Offer update/view/skip options. ## Step 3: Gather Phase Context ```bash -# Phase section from roadmap (already loaded in PHASE_INFO) -echo "$PHASE_INFO" | jq -r '.section' -cat .planning/REQUIREMENTS.md 2>/dev/null -cat .planning/phases/${PHASE}-*/*-CONTEXT.md 2>/dev/null -# Decisions from state-snapshot (structured JSON) -node ~/.claude/get-shit-done/bin/gsd-tools.cjs state-snapshot | jq '.decisions' +INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init phase-op "${PHASE}") +# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path ``` ## Step 4: Spawn Researcher @@ -50,12 +46,15 @@ Task( Research implementation approach for Phase {phase}: {name} - + +- {context_path} (USER DECISIONS from /gsd:discuss-phase) +- {requirements_path} (Project requirements) +- {state_path} (Project decisions and history) + + + Phase description: {description} -Requirements: {requirements} -Prior decisions: {decisions} -Phase context: {context_md} - + Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md diff --git a/get-shit-done/workflows/verify-work.md b/get-shit-done/workflows/verify-work.md index b9beb7130..47e286c83 100644 --- a/get-shit-done/workflows/verify-work.md +++ b/get-shit-done/workflows/verify-work.md @@ -365,14 +365,11 @@ Task( **Phase:** {phase_number} **Mode:** gap_closure -**UAT with diagnoses:** -@.planning/phases/{phase_dir}/{phase_num}-UAT.md - -**Project State:** -@.planning/STATE.md - -**Roadmap:** -@.planning/ROADMAP.md + +- {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses) +- .planning/STATE.md (Project State) +- .planning/ROADMAP.md (Roadmap) + @@ -416,8 +413,9 @@ Task( **Phase:** {phase_number} **Phase Goal:** Close diagnosed gaps from UAT -**Plans to verify:** -@.planning/phases/{phase_dir}/*-PLAN.md + +- {phase_dir}/*-PLAN.md (Plans to verify) + @@ -455,8 +453,9 @@ Task( **Phase:** {phase_number} **Mode:** revision -**Existing plans:** -@.planning/phases/{phase_dir}/*-PLAN.md + +- {phase_dir}/*-PLAN.md (Existing plans) + **Checker issues:** {structured_issues_from_checker}