diff --git a/commands/gsd/execute-phase.md b/commands/gsd/execute-phase.md index 0fafa18a0..4bd969544 100644 --- a/commands/gsd/execute-phase.md +++ b/commands/gsd/execute-phase.md @@ -52,8 +52,7 @@ Phase: $ARGUMENTS 4. **Execute waves** For each wave in order: - - Fill subagent-task-prompt template for each plan - - Spawn all agents in wave simultaneously (parallel Task calls) + - Spawn `gsd-executor` for each plan in wave (parallel Task calls) - Wait for completion (Task blocks) - Verify SUMMARYs created - Proceed to next wave diff --git a/get-shit-done/templates/checkpoint-return.md b/get-shit-done/templates/checkpoint-return.md deleted file mode 100644 index 96adcd22a..000000000 --- a/get-shit-done/templates/checkpoint-return.md +++ /dev/null @@ -1,204 +0,0 @@ -# Checkpoint Return Template - -Structured format for subagent checkpoint returns. Enables orchestrator to spawn continuation agents without relying on resume. - ---- - -## Template - -```markdown -## CHECKPOINT REACHED - -**Type:** [human-verify | decision | human-action] -**Plan:** {phase}-{plan} -**Progress:** {completed}/{total} tasks complete - -### Completed Tasks - -| Task | Name | Commit | Files | -|------|------|--------|-------| -| 1 | [task name] | [hash] | [key files created/modified] | -| 2 | [task name] | [hash] | [key files created/modified] | - -### Current Task - -**Task {N}:** [task name] -**Status:** [blocked | awaiting verification | awaiting decision] -**Blocked by:** [specific blocker - auth required, user verification needed, decision needed] - -### Checkpoint Details - -[Checkpoint-specific content based on type - see below] - -### Awaiting - -[What user needs to do/provide] -``` - ---- - -## Checkpoint Type Details - -### For human-verify - -```markdown -### Checkpoint Details - -**What was built:** -[Description of completed work] - -**How to verify:** -1. [Step 1 - exact command/URL] -2. [Step 2 - what to check] -3. [Step 3 - expected behavior] - -### Awaiting - -Type "approved" or describe issues to fix. -``` - -### For human-action - -```markdown -### Checkpoint Details - -**Automation attempted:** -[What Claude tried to do] - -**Error encountered:** -[Exact error message or auth failure] - -**What you need to do:** -1. [Step 1] -2. [Step 2] - -**I'll verify after:** -[How Claude will confirm completion] - -### Awaiting - -Type "done" when complete. -``` - -### For decision - -```markdown -### Checkpoint Details - -**Decision needed:** -[What's being decided] - -**Context:** -[Why this matters] - -**Options:** - -| Option | Pros | Cons | -|--------|------|------| -| [option-a] | [benefits] | [tradeoffs] | -| [option-b] | [benefits] | [tradeoffs] | - -### Awaiting - -Select: [option-a | option-b | ...] -``` - ---- - -## Why This Structure - -**Completed Tasks table:** Orchestrator knows exactly what's done. Fresh agent won't redo work. - -**Commit hashes:** Verification that work was committed. Fresh agent can check git log. - -**Files column:** Quick reference for what exists. Fresh agent can verify state. - -**Current Task + Blocked by:** Precise continuation point. Fresh agent knows exactly where to pick up. - -**Checkpoint Details:** User-facing content. Orchestrator presents this directly. - ---- - -## Example: Auth Gate - -```markdown -## CHECKPOINT REACHED - -**Type:** human-action -**Plan:** 01-01 -**Progress:** 1/3 tasks complete - -### Completed Tasks - -| Task | Name | Commit | Files | -|------|------|--------|-------| -| 1 | Initialize Next.js 15 project | d6fe73f | package.json, tsconfig.json, next.config.js, app/ | - -### Current Task - -**Task 2:** Initialize Convex backend -**Status:** blocked -**Blocked by:** Convex CLI authentication required - -### Checkpoint Details - -**Automation attempted:** -Ran `npx convex dev` to initialize Convex backend - -**Error encountered:** -"Error: Not authenticated. Run `npx convex login` first." - -**What you need to do:** -1. Run: `npx convex login` -2. Complete browser authentication -3. Run: `npx convex dev` -4. Create project named "convex-saas-community" when prompted - -**I'll verify after:** -`cat .env.local | grep CONVEX` returns the Convex URL - -### Awaiting - -Type "done" when Convex is authenticated and project created. -``` - ---- - -## Example: Visual Verification - -```markdown -## CHECKPOINT REACHED - -**Type:** human-verify -**Plan:** 03-02 -**Progress:** 2/3 tasks complete - -### Completed Tasks - -| Task | Name | Commit | Files | -|------|------|--------|-------| -| 1 | Create dashboard layout | a1b2c3d | src/app/dashboard/layout.tsx, src/components/Sidebar.tsx | -| 2 | Add responsive navigation | e4f5g6h | src/components/NavBar.tsx, src/styles/nav.css | - -### Current Task - -**Task 3:** Verify responsive behavior -**Status:** awaiting verification -**Blocked by:** Human visual verification required - -### Checkpoint Details - -**What was built:** -Responsive dashboard with collapsible sidebar navigation - -**How to verify:** -1. Run: `npm run dev` -2. Visit: http://localhost:3000/dashboard -3. Desktop (>1024px): Sidebar visible on left, content on right -4. Tablet (768px): Sidebar collapses to icons -5. Mobile (375px): Sidebar hidden, hamburger menu appears - -### Awaiting - -Type "approved" or describe issues to fix. -``` diff --git a/get-shit-done/templates/continuation-prompt.md b/get-shit-done/templates/continuation-prompt.md deleted file mode 100644 index 800afa1d1..000000000 --- a/get-shit-done/templates/continuation-prompt.md +++ /dev/null @@ -1,235 +0,0 @@ -# Continuation Prompt Template - -Template for spawning fresh agent to continue plan execution after checkpoint resolution. - ---- - -## Template - -```markdown - -Continue executing plan {plan_number} of phase {phase_number}-{phase_name}. - -**DO NOT REDO completed tasks.** They are already committed. Start from the resume point below. - -Commit each remaining task atomically. Create SUMMARY.md when all tasks complete. Update STATE.md. - - - -The following tasks are ALREADY DONE. Do not repeat them. - -{completed_tasks_table} - -**Verify before continuing:** Check that these commits exist with `git log --oneline -5` - - - -**Resume from:** Task {resume_task_number} - {resume_task_name} -**Status:** {resume_status} -**User response:** {user_response} - -{resume_instructions} - - - -@~/.claude/get-shit-done/workflows/execute-plan.md -@~/.claude/get-shit-done/templates/summary.md -@~/.claude/get-shit-done/references/checkpoints.md -@~/.claude/get-shit-done/references/tdd.md - - - -Plan: @{plan_path} -Project state: @.planning/STATE.md -Config: @.planning/config.json (if exists) - - - -If you hit another checkpoint, return using the format in: -@~/.claude/get-shit-done/templates/checkpoint-return.md - -Include ALL completed tasks (both previous and new) in the Completed Tasks table. - - - -When plan completes successfully, return: - -## PLAN COMPLETE - -**Plan:** {phase}-{plan} -**Tasks:** {total}/{total} -**SUMMARY:** {path to SUMMARY.md} - -**Commits:** -- {hash}: {message} -... - -Include commits from both previous execution and this continuation. - - - -- [ ] Verified previous commits exist (did not redo work) -- [ ] Remaining tasks executed -- [ ] Each new task committed individually -- [ ] SUMMARY.md created in plan directory (covers ALL tasks) -- [ ] STATE.md updated with position and decisions - -``` - ---- - -## Placeholders - -| Placeholder | Source | Example | -|-------------|--------|---------| -| `{phase_number}` | Checkpoint return | `01` | -| `{phase_name}` | Checkpoint return | `foundation` | -| `{plan_number}` | Checkpoint return | `01` | -| `{plan_path}` | Original prompt | `.planning/phases/01-foundation/01-01-PLAN.md` | -| `{completed_tasks_table}` | Checkpoint return | Markdown table of completed tasks | -| `{resume_task_number}` | Checkpoint return | `2` | -| `{resume_task_name}` | Checkpoint return | `Initialize Convex backend` | -| `{resume_status}` | Derived from checkpoint type | `User completed authentication` | -| `{user_response}` | User input | `done` or `approved` or `option-a` | -| `{resume_instructions}` | Derived from checkpoint type | See below | - ---- - -## Resume Instructions by Checkpoint Type - -### After human-action (e.g., auth gate) - -```markdown -**Resume from:** Task 2 - Initialize Convex backend -**Status:** User completed authentication -**User response:** done - -The user has completed the manual action. Verify it worked, then continue: -1. Verify: `cat .env.local | grep CONVEX` shows Convex URL -2. If verified: Continue with remaining Task 2 steps (if any), then Task 3 -3. If not verified: Report what's missing, create new checkpoint -``` - -### After human-verify (e.g., visual check) - -```markdown -**Resume from:** Task 3 - Verify responsive behavior -**Status:** User approved verification -**User response:** approved - -User confirmed the implementation is correct. Continue to next task. -``` - -Or if issues reported: - -```markdown -**Resume from:** Task 3 - Verify responsive behavior -**Status:** User reported issues -**User response:** "Sidebar overlaps content on tablet view" - -Fix the reported issues: -1. Address: "Sidebar overlaps content on tablet view" -2. After fixing, re-present the verification checkpoint -``` - -### After decision - -```markdown -**Resume from:** Task 4 - Select authentication provider -**Status:** User made decision -**User response:** clerk - -Proceed with the selected option (Clerk). Implement accordingly. -``` - ---- - -## Example: Continuation After Auth Gate - -```markdown - -Continue executing plan 01 of phase 01-foundation. - -**DO NOT REDO completed tasks.** They are already committed. Start from the resume point below. - -Commit each remaining task atomically. Create SUMMARY.md when all tasks complete. Update STATE.md. - - - -The following tasks are ALREADY DONE. Do not repeat them. - -| Task | Name | Commit | Files | -|------|------|--------|-------| -| 1 | Initialize Next.js 15 project | d6fe73f | package.json, tsconfig.json, next.config.js, app/ | - -**Verify before continuing:** Check that these commits exist with `git log --oneline -5` - - - -**Resume from:** Task 2 - Initialize Convex backend -**Status:** User completed authentication -**User response:** done - -The user has completed the manual action. Verify it worked, then continue: -1. Verify: `cat .env.local | grep CONVEX` shows Convex URL -2. If verified: Continue with remaining Task 2 steps (create schema, verify deployment), then Task 3 -3. If not verified: Report what's missing, create new checkpoint - - - -@~/.claude/get-shit-done/workflows/execute-plan.md -@~/.claude/get-shit-done/templates/summary.md -@~/.claude/get-shit-done/references/checkpoints.md -@~/.claude/get-shit-done/references/tdd.md - - - -Plan: @.planning/phases/01-foundation/01-01-PLAN.md -Project state: @.planning/STATE.md - - - -If you hit another checkpoint, return using the format in: -@~/.claude/get-shit-done/templates/checkpoint-return.md - -Include ALL completed tasks (both previous and new) in the Completed Tasks table. - - - -When plan completes successfully, return: - -## PLAN COMPLETE - -**Plan:** 01-01 -**Tasks:** 3/3 -**SUMMARY:** .planning/phases/01-foundation/01-01-SUMMARY.md - -**Commits:** -- d6fe73f: feat(01-01): initialize Next.js 15 with TypeScript and Tailwind -- [new]: feat(01-01): initialize Convex backend with schema -- [new]: feat(01-01): integrate Clerk authentication - - - -- [ ] Verified previous commits exist (did not redo work) -- [ ] Remaining tasks executed -- [ ] Each new task committed individually -- [ ] SUMMARY.md created in plan directory (covers ALL tasks) -- [ ] STATE.md updated with position and decisions - -``` - ---- - -## Usage - -Orchestrator fills placeholders from checkpoint return and user response: - -```python -Task( - prompt=filled_continuation_template, - subagent_type="gsd-executor" -) -``` - -Fresh agent loads @-references, verifies completed work, continues from resume point. diff --git a/get-shit-done/templates/subagent-task-prompt.md b/get-shit-done/templates/subagent-task-prompt.md deleted file mode 100644 index 537f21e7b..000000000 --- a/get-shit-done/templates/subagent-task-prompt.md +++ /dev/null @@ -1,95 +0,0 @@ -# Subagent Task Prompt Template - -Template for spawning plan execution agents. Used by execute-phase (parallel) and execute-plan (single) orchestrators. - ---- - -## Template - -```markdown - -Execute plan {plan_number} of phase {phase_number}-{phase_name}. - -Commit each task atomically. Create SUMMARY.md. Update STATE.md. - -**Checkpoint handling:** If you hit a checkpoint task or auth gate, STOP and return a structured checkpoint message. The orchestrator will spawn a fresh agent to continue after the user responds. - - - -@~/.claude/get-shit-done/workflows/execute-plan.md -@~/.claude/get-shit-done/templates/summary.md -@~/.claude/get-shit-done/references/checkpoints.md -@~/.claude/get-shit-done/references/tdd.md - - - -Plan: @{plan_path} -Project state: @.planning/STATE.md -Config: @.planning/config.json (if exists) - - - -When you encounter a checkpoint task (type="checkpoint:*") or auth gate, STOP execution and return using the structured format in: - -@~/.claude/get-shit-done/templates/checkpoint-return.md - -**Required in your return:** -1. Completed Tasks table with commit hashes and files -2. Current task name and what's blocking it -3. Checkpoint details for the user -4. What you're awaiting from the user - -The orchestrator will present this to the user. After they respond, a FRESH agent will continue from your checkpoint using the continuation-prompt template. You will NOT be resumed. - - - -When plan completes successfully, return: - -## PLAN COMPLETE - -**Plan:** {phase}-{plan} -**Tasks:** {completed}/{total} -**SUMMARY:** {path to SUMMARY.md} - -**Commits:** -- {hash}: {message} -... - - - -- [ ] All tasks executed (or paused at checkpoint with full state returned) -- [ ] Each task committed individually -- [ ] SUMMARY.md created in plan directory -- [ ] STATE.md updated with position and decisions - -``` - ---- - -## Placeholders - -| Placeholder | Source | Example | -|-------------|--------|---------| -| `{phase_number}` | Phase directory name | `01` | -| `{phase_name}` | Phase directory name | `foundation` | -| `{plan_number}` | Plan filename | `01` | -| `{plan_path}` | Full path to PLAN.md | `.planning/phases/01-foundation/01-01-PLAN.md` | - ---- - -## Usage - -Orchestrator fills placeholders and passes to Task tool: - -```python -Task( - prompt=filled_template, - subagent_type="general-purpose" -) -``` - -Agent reads @-references, loads full workflow context, executes plan. - -When agent returns: -- If contains "## CHECKPOINT REACHED": Parse checkpoint, present to user, spawn fresh agent with continuation-prompt.md -- If contains "## PLAN COMPLETE": Finalize execution diff --git a/get-shit-done/templates/subagent-verify-prompt.md b/get-shit-done/templates/subagent-verify-prompt.md deleted file mode 100644 index a0b123b8a..000000000 --- a/get-shit-done/templates/subagent-verify-prompt.md +++ /dev/null @@ -1,216 +0,0 @@ -# Subagent Verify Prompt Template - -Template for spawning a verification subagent from execute-phase.md. - ---- - -## Template - -```markdown - -Verify Phase {phase_number} achieved its GOAL, not just completed its TASKS. - -Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase. - -**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. - - - -@~/.claude/get-shit-done/workflows/verify-phase.md -@~/.claude/get-shit-done/templates/verification-report.md -@~/.claude/get-shit-done/references/verification-patterns.md -@~/.claude/get-shit-done/references/goal-backward.md - - - -**Phase being verified:** -- Phase: {phase_number} - {phase_name} -- Phase goal: {phase_goal_from_roadmap} -- Phase directory: .planning/phases/{phase_dir}/ - -**Must-haves to verify:** -{must_haves_yaml_from_plan_frontmatter} - -**If must_haves not in frontmatter, derive from:** -- Phase goal (above) -- @.planning/ROADMAP.md (phase description) -- @.planning/REQUIREMENTS.md (requirements mapped to this phase) - -**Context for verification:** -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/REQUIREMENTS.md (if exists) -@.planning/phases/{phase_dir}/*-SUMMARY.md (claims to verify against) - - - - -## Step 1: Establish Must-Haves - -**If must_haves provided in context above:** Use them directly. - -**If must_haves NOT provided:** Derive using goal-backward process: -1. State the phase goal -2. Ask: "What must be TRUE for this goal to be achieved?" (3-7 observable truths) -3. For each truth: "What must EXIST?" (concrete artifacts) -4. For each artifact: "What must be WIRED?" (connections between artifacts) -5. Identify key links (critical connections most likely to be stubs) - -Document your derived must-haves before proceeding. - -## Step 2: Verify Observable Truths - -For each truth, determine if it's achievable given the codebase state. - -A truth is: -- ✓ VERIFIED: Codebase makes this truth achievable -- ✗ FAILED: Codebase prevents this truth (missing/stub code) -- ? UNCERTAIN: Can't verify programmatically (needs human) - -## Step 3: Verify Required Artifacts - -For each artifact, check three levels: - -**Level 1 - Exists:** -```bash -[ -f "{artifact_path}" ] && echo "EXISTS" || echo "MISSING" -``` - -**Level 2 - Substantive:** -- Is it more than a stub? (check line count, grep for stub patterns) -- Does it have expected exports/structure? -- Are there TODO/placeholder comments? - -Use patterns from verification-patterns.md. - -**Level 3 - Wired:** -- Is it imported somewhere? -- Is it called/used? -- Does data flow through it? - -## Step 4: Verify Key Links - -Key links are the critical connections. For each: - -```bash -# Check if A calls B -grep -E "{pattern_for_call}" "{file_A}" - -# Check if the call uses the response -grep -A 5 "{call_pattern}" "{file_A}" | grep -E "await|then|set" -``` - -Key links are where stubs hide. A component might exist and an API might exist, but the component doesn't actually call the API. - -## Step 5: Check Requirements Coverage - -If REQUIREMENTS.md exists and has requirements mapped to this phase: -- For each requirement, determine if the codebase satisfies it -- A requirement is BLOCKED if any supporting artifact is missing/stub - -## Step 6: Scan for Anti-Patterns - -Run stub detection across all phase-related files: - -```bash -# Find all files modified in this phase (from SUMMARYs) -# Then scan for anti-patterns - -grep -r -E "TODO|FIXME|placeholder|not implemented" {phase_files} -i -grep -r -E "return null|return \{\}|return \[\]" {phase_files} -grep -r -E "console\.log\(.*\)" {phase_files} | grep -v "error\|warn" -``` - -## Step 7: Generate Report - -Create `.planning/phases/{phase_dir}/{phase}-VERIFICATION.md` using the verification-report.md template. - -Include: -- All truths with status and evidence -- All artifacts with status and details -- All key links with status and details -- Requirements coverage -- Anti-patterns found -- Human verification needs -- Gap summary with fix recommendations - - - - - -**DO NOT trust SUMMARY claims.** SUMMARYs say "implemented chat component" — you verify the component actually renders messages, not a placeholder. - -**DO NOT assume existence = implementation.** A file existing is level 1. You need level 2 (substantive) and level 3 (wired) verification. - -**DO NOT skip key link verification.** This is where 80% of stubs hide. The pieces exist but aren't connected. - -**DO generate fix plans if gaps found.** Don't just report "this is broken" — recommend specific fix plans with tasks. - -**DO flag for human verification when uncertain.** If you can't verify programmatically (visual, real-time, external service), say so explicitly. - -**DO keep verification fast.** Use grep/file checks, not running the app. Goal is structural verification, not functional testing. - - - - -Create: `.planning/phases/{phase_dir}/{phase}-VERIFICATION.md` - -Use the verification-report.md template structure. - -Return to orchestrator with: -- Status: passed | gaps_found | human_needed -- Score: N/M must-haves verified -- If gaps_found: Summary of gaps and recommended fix plans -- If human_needed: List of items requiring human verification - - - -- [ ] Must-haves established (from frontmatter or derived) -- [ ] All truths verified with evidence -- [ ] All artifacts checked (exists + substantive + wired) -- [ ] All key links traced -- [ ] Requirements coverage assessed -- [ ] Anti-patterns scanned -- [ ] VERIFICATION.md created with full report -- [ ] Fix plans recommended if gaps found -- [ ] Human verification items listed if uncertain - -``` - ---- - -## Usage - -The execute-phase orchestrator fills this template and spawns a subagent: - -```typescript -Task( - prompt: filled_template, - subagent_type: "general-purpose", - description: "Verify phase {X} goal achievement" -) -``` - -The subagent: -1. Loads the verification workflow and references -2. Establishes must-haves (from frontmatter or derived) -3. Runs verification checks against codebase -4. Creates VERIFICATION.md report -5. Returns status to orchestrator - -The orchestrator then: -- If `passed`: Proceeds to update_roadmap -- If `gaps_found`: Creates fix plans, executes them, re-verifies -- If `human_needed`: Presents human verification items to user - ---- - -## Template Variables - -| Variable | Source | Example | -|----------|--------|---------| -| `{phase_number}` | From execute-phase | `03` | -| `{phase_name}` | From ROADMAP.md | `chat-interface` | -| `{phase_goal_from_roadmap}` | From ROADMAP.md phase description | `Working chat interface where users can send and receive messages` | -| `{phase_dir}` | From filesystem | `03-chat-interface` | -| `{must_haves_yaml_from_plan_frontmatter}` | From PLAN.md frontmatter | YAML block with truths, artifacts, key_links | diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index 24cbfde46..21ce4d7d9 100644 --- a/get-shit-done/workflows/execute-plan.md +++ b/get-shit-done/workflows/execute-plan.md @@ -1119,9 +1119,6 @@ If you were spawned via Task tool and hit a checkpoint, you cannot directly inte **Return format for checkpoints:** -Use the structured format from: -@~/.claude/get-shit-done/templates/checkpoint-return.md - **Required in your return:** 1. **Completed Tasks table** - Tasks done so far with commit hashes and files created