From 7510a8a84acb180e2ec3e1b01ad4db5e99f37df5 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Sun, 15 Feb 2026 16:56:31 -0600 Subject: [PATCH] feat(quick): add --full flag for plan-checking and verification Enables quality guarantees on quick tasks without full milestone ceremony. --full spawns plan-checker (max 2 iterations) and post-execution verifier, produces VERIFICATION.md, and adds Status column to STATE.md table. Co-Authored-By: Claude Opus 4.6 --- commands/gsd/quick.md | 10 +- get-shit-done/bin/gsd-tools.cjs | 2 + get-shit-done/workflows/quick.md | 236 +++++++++++++++++++++++++++++-- 3 files changed, 233 insertions(+), 15 deletions(-) diff --git a/commands/gsd/quick.md b/commands/gsd/quick.md index f7269c0b5..06fe80e30 100644 --- a/commands/gsd/quick.md +++ b/commands/gsd/quick.md @@ -1,7 +1,7 @@ --- name: gsd:quick description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents -argument-hint: "" +argument-hint: "[--full]" allowed-tools: - Read - Write @@ -13,15 +13,16 @@ allowed-tools: - AskUserQuestion --- -Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking) while skipping optional agents (research, plan-checker, verifier). +Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Quick mode is the same system with a shorter path: - Spawns gsd-planner (quick mode) + gsd-executor(s) -- Skips gsd-phase-researcher, gsd-plan-checker, gsd-verifier - Quick tasks live in `.planning/quick/` separate from planned phases - Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md) -Use when: You know exactly what to do and the task is small enough to not need research or verification. +**Default:** Skips research, plan-checker, verifier. Use when you know exactly what to do. + +**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony. @@ -30,6 +31,7 @@ Use when: You know exactly what to do and the task is small enough to not need r @.planning/STATE.md +$ARGUMENTS diff --git a/get-shit-done/bin/gsd-tools.cjs b/get-shit-done/bin/gsd-tools.cjs index 9d1d5bda7..28dc49234 100755 --- a/get-shit-done/bin/gsd-tools.cjs +++ b/get-shit-done/bin/gsd-tools.cjs @@ -4437,6 +4437,8 @@ function cmdInitQuick(cwd, description, raw) { // Models planner_model: resolveModelInternal(cwd, 'gsd-planner'), executor_model: resolveModelInternal(cwd, 'gsd-executor'), + checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'), + verifier_model: resolveModelInternal(cwd, 'gsd-verifier'), // Config commit_docs: config.commit_docs, diff --git a/get-shit-done/workflows/quick.md b/get-shit-done/workflows/quick.md index bb463cd15..0c4bd0efe 100644 --- a/get-shit-done/workflows/quick.md +++ b/get-shit-done/workflows/quick.md @@ -1,5 +1,7 @@ -Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking) while skipping optional agents (research, plan-checker, verifier). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table. +Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table. + +With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony. @@ -7,9 +9,13 @@ Read all files referenced by the invoking prompt's execution_context before star -**Step 1: Get task description** +**Step 1: Parse arguments and get task description** -Prompt user interactively for the task description: +Parse `$ARGUMENTS` for: +- `--full` flag → store as `$FULL_MODE` (true/false) +- Remaining text → use as `$DESCRIPTION` if non-empty + +If `$DESCRIPTION` is empty after parsing, prompt user interactively: ``` AskUserQuestion( @@ -21,7 +27,16 @@ AskUserQuestion( Store response as `$DESCRIPTION`. -If empty, re-prompt: "Please provide a task description." +If still empty, re-prompt: "Please provide a task description." + +If `$FULL_MODE`: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (FULL MODE) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Plan checking + verification enabled +``` --- @@ -31,7 +46,7 @@ If empty, re-prompt: "Please provide a task description." INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init quick "$DESCRIPTION") ``` -Parse JSON for: `planner_model`, `executor_model`, `commit_docs`, `next_num`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`. +Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `next_num`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`. **If `roadmap_exists` is false:** Error — Quick mode requires an active project with ROADMAP.md. Run `/gsd:new-project` first. @@ -68,14 +83,16 @@ Store `$QUICK_DIR` for use in orchestration. **Step 5: Spawn planner (quick mode)** -Spawn gsd-planner with quick mode context: +**If `$FULL_MODE`:** Use `quick-full` mode with stricter constraints. + +**If NOT `$FULL_MODE`:** Use standard `quick` mode. ``` Task( prompt=" -**Mode:** quick +**Mode:** ${FULL_MODE ? 'quick-full' : 'quick'} **Directory:** ${QUICK_DIR} **Description:** ${DESCRIPTION} @@ -87,8 +104,10 @@ Task( - Create a SINGLE plan with 1-3 focused tasks - Quick tasks should be atomic and self-contained -- No research phase, no checker phase -- Target ~30% context usage (simple, focused) +- No research phase +${FULL_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'} +${FULL_MODE ? '- MUST generate `must_haves` in plan frontmatter (truths, artifacts, key_links)' : ''} +${FULL_MODE ? '- Each task MUST have `files`, `action`, `verify`, `done` fields' : ''} @@ -111,6 +130,114 @@ If plan not found, error: "Planner failed to create ${next_num}-PLAN.md" --- +**Step 5.5: Plan-checker loop (only when `$FULL_MODE`)** + +Skip this step entirely if NOT `$FULL_MODE`. + +Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► CHECKING PLAN +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Spawning plan checker... +``` + +```bash +PLAN_CONTENT=$(cat "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null) +``` + +Checker prompt: + +```markdown + +**Mode:** quick-full +**Task Description:** ${DESCRIPTION} + +**Plan to verify:** ${PLAN_CONTENT} + +**Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal. + + + +- Requirement coverage: Does the plan address the task description? +- Task completeness: Do tasks have files, action, verify, done fields? +- Key links: Are referenced files real? +- Scope sanity: Is this appropriately sized for a quick task (1-3 tasks)? +- must_haves derivation: Are must_haves traceable to the task description? + +Skip: context compliance (no CONTEXT.md), cross-plan deps (single plan), ROADMAP alignment + + + +- ## VERIFICATION PASSED — all checks pass +- ## ISSUES FOUND — structured issue list + +``` + +``` +Task( + prompt=checker_prompt, + subagent_type="gsd-plan-checker", + model="{checker_model}", + description="Check quick plan: ${DESCRIPTION}" +) +``` + +**Handle checker return:** + +- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 6. +- **`## ISSUES FOUND`:** Display issues, check iteration count, enter revision loop. + +**Revision loop (max 2 iterations):** + +Track `iteration_count` (starts at 1 after initial plan + check). + +**If iteration_count < 2:** + +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} +**Checker issues:** ${structured_issues_from_checker} + + + + +Make targeted updates to address checker issues. +Do NOT replan from scratch unless issues are fundamental. +Return what changed. + +``` + +``` +Task( + prompt="First, read ~/.claude/agents/gsd-planner.md for your role and instructions.\n\n" + revision_prompt, + subagent_type="general-purpose", + model="{planner_model}", + description="Revise quick plan: ${DESCRIPTION}" +) +``` + +After planner returns → spawn checker again, increment iteration_count. + +**If iteration_count >= 2:** + +Display: `Max iterations reached. ${N} issues remain:` + issue list + +Offer: 1) Force proceed, 2) Abort + +--- + **Step 6: Spawn executor** Spawn gsd-executor with plan reference: @@ -149,6 +276,47 @@ Note: For quick tasks producing multiple plans (rare), spawn executors in parall --- +**Step 6.5: Verification (only when `$FULL_MODE`)** + +Skip this step entirely if NOT `$FULL_MODE`. + +Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► VERIFYING RESULTS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Spawning verifier... +``` + +``` +Task( + prompt="Verify quick task goal achievement. +Task directory: ${QUICK_DIR} +Task goal: ${DESCRIPTION} +Plan: @${QUICK_DIR}/${next_num}-PLAN.md +Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${next_num}-VERIFICATION.md.", + subagent_type="gsd-verifier", + model="{verifier_model}", + description="Verify: ${DESCRIPTION}" +) +``` + +Read verification status: +```bash +grep "^status:" "${QUICK_DIR}/${next_num}-VERIFICATION.md" | cut -d: -f2 | tr -d ' ' +``` + +Store as `$VERIFICATION_STATUS`. + +| Status | Action | +|--------|--------| +| `passed` | Store `$VERIFICATION_STATUS = "Verified"`, continue to step 7 | +| `human_needed` | Display items needing manual check, store `$VERIFICATION_STATUS = "Needs Review"`, continue | +| `gaps_found` | Display gap summary, offer: 1) Re-run executor to fix gaps, 2) Accept as-is. Store `$VERIFICATION_STATUS = "Gaps"` | + +--- + **Step 7: Update STATE.md** Update STATE.md with quick task completion record. @@ -161,6 +329,15 @@ Read STATE.md and check for `### Quick Tasks Completed` section. Insert after `### Blockers/Concerns` section: +**If `$FULL_MODE`:** +```markdown +### Quick Tasks Completed + +| # | Description | Date | Commit | Status | Directory | +|---|-------------|------|--------|--------|-----------| +``` + +**If NOT `$FULL_MODE`:** ```markdown ### Quick Tasks Completed @@ -168,9 +345,18 @@ Insert after `### Blockers/Concerns` section: |---|-------------|------|--------|-----------| ``` +**Note:** If the table already exists, match its existing column format. If adding `--full` to a project that already has quick tasks without a Status column, add the Status column to the header and separator rows, and leave Status empty for the new row's predecessors. + **7c. Append new row to table:** Use `date` from init: + +**If `$FULL_MODE` (or table has Status column):** +```markdown +| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) | +``` + +**If NOT `$FULL_MODE` (and table has no Status column):** ```markdown | ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) | ``` @@ -190,8 +376,14 @@ Use Edit tool to make these changes atomically Stage and commit quick task artifacts: +Build file list: +- `${QUICK_DIR}/${next_num}-PLAN.md` +- `${QUICK_DIR}/${next_num}-SUMMARY.md` +- `.planning/STATE.md` +- If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${next_num}-VERIFICATION.md` + ```bash -node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${QUICK_DIR}/${next_num}-PLAN.md ${QUICK_DIR}/${next_num}-SUMMARY.md .planning/STATE.md +node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${file_list} ``` Get final commit hash: @@ -200,6 +392,25 @@ commit_hash=$(git rev-parse --short HEAD) ``` Display completion output: + +**If `$FULL_MODE`:** +``` +--- + +GSD > QUICK TASK COMPLETE (FULL MODE) + +Quick Task ${next_num}: ${DESCRIPTION} + +Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md +Verification: ${QUICK_DIR}/${next_num}-VERIFICATION.md (${VERIFICATION_STATUS}) +Commit: ${commit_hash} + +--- + +Ready for next task: /gsd:quick +``` + +**If NOT `$FULL_MODE`:** ``` --- @@ -220,11 +431,14 @@ Ready for next task: /gsd:quick - [ ] ROADMAP.md validation passes - [ ] User provides task description +- [ ] `--full` flag parsed from arguments when present - [ ] Slug generated (lowercase, hyphens, max 40 chars) - [ ] Next number calculated (001, 002, 003...) - [ ] Directory created at `.planning/quick/NNN-slug/` - [ ] `${next_num}-PLAN.md` created by planner +- [ ] (--full) Plan checker validates plan, revision loop capped at 2 - [ ] `${next_num}-SUMMARY.md` created by executor -- [ ] STATE.md updated with quick task row +- [ ] (--full) `${next_num}-VERIFICATION.md` created by verifier +- [ ] STATE.md updated with quick task row (Status column when --full) - [ ] Artifacts committed