gsd-codex-cli 1.20.0

package/get-shit-done/workflows/quick.md

@@ -0,0 +1,444 @@
+<purpose>
+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.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+**Step 1: Parse arguments and get 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(
+  header: "Quick Task",
+  question: "What do you want to do?",
+  followUp: null
+)
+```
+
+Store response as `$DESCRIPTION`.
+
+If still empty, re-prompt: "Please provide a task description."
+
+If `$FULL_MODE`:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► QUICK TASK (FULL MODE)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Plan checking + verification enabled
+```
+
+---
+
+**Step 2: Initialize**
+
+```bash
+INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init quick "$DESCRIPTION")
+```
+
+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.
+
+Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.
+
+---
+
+**Step 3: Create task directory**
+
+```bash
+mkdir -p "${task_dir}"
+```
+
+---
+
+**Step 4: Create quick task directory**
+
+Create the directory for this quick task:
+
+```bash
+QUICK_DIR=".planning/quick/${next_num}-${slug}"
+mkdir -p "$QUICK_DIR"
+```
+
+Report to user:
+```
+Creating quick task ${next_num}: ${DESCRIPTION}
+Directory: ${QUICK_DIR}
+```
+
+Store `$QUICK_DIR` for use in orchestration.
+
+---
+
+**Step 5: Spawn planner (quick mode)**
+
+**If `$FULL_MODE`:** Use `quick-full` mode with stricter constraints.
+
+**If NOT `$FULL_MODE`:** Use standard `quick` mode.
+
+```
+Task(
+  prompt="
+<planning_context>
+
+**Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
+**Directory:** ${QUICK_DIR}
+**Description:** ${DESCRIPTION}
+
+**Project State:**
+@.planning/STATE.md
+
+</planning_context>
+
+<constraints>
+- Create a SINGLE plan with 1-3 focused tasks
+- Quick tasks should be atomic and self-contained
+- 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' : ''}
+</constraints>
+
+<output>
+Write plan to: ${QUICK_DIR}/${next_num}-PLAN.md
+Return: ## PLANNING COMPLETE with plan path
+</output>
+",
+  subagent_type="gsd-planner",
+  model="{planner_model}",
+  description="Quick plan: ${DESCRIPTION}"
+)
+```
+
+After planner returns:
+1. Verify plan exists at `${QUICK_DIR}/${next_num}-PLAN.md`
+2. Extract plan count (typically 1 for quick tasks)
+3. Report: "Plan created: ${QUICK_DIR}/${next_num}-PLAN.md"
+
+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
+<verification_context>
+**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.
+</verification_context>
+
+<check_dimensions>
+- 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
+</check_dimensions>
+
+<expected_output>
+- ## VERIFICATION PASSED — all checks pass
+- ## ISSUES FOUND — structured issue list
+</expected_output>
+```
+
+```
+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
+<revision_context>
+**Mode:** quick-full (revision)
+
+**Existing plan:** ${PLAN_CONTENT}
+**Checker issues:** ${structured_issues_from_checker}
+
+</revision_context>
+
+<instructions>
+Make targeted updates to address checker issues.
+Do NOT replan from scratch unless issues are fundamental.
+Return what changed.
+</instructions>
+```
+
+```
+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:
+
+```
+Task(
+  prompt="
+Execute quick task ${next_num}.
+
+Plan: @${QUICK_DIR}/${next_num}-PLAN.md
+Project state: @.planning/STATE.md
+
+<constraints>
+- Execute all tasks in the plan
+- Commit each task atomically
+- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md
+- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
+</constraints>
+",
+  subagent_type="gsd-executor",
+  model="{executor_model}",
+  description="Execute: ${DESCRIPTION}"
+)
+```
+
+After executor returns:
+1. Verify summary exists at `${QUICK_DIR}/${next_num}-SUMMARY.md`
+2. Extract commit hash from executor output
+3. Report completion status
+
+**Known Claude Code bug (classifyHandoffIfNeeded):** If executor reports "failed" with error `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Check if summary file exists and git log shows commits. If so, treat as successful.
+
+If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md"
+
+Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns.
+
+---
+
+**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.
+
+**7a. Check if "Quick Tasks Completed" section exists:**
+
+Read STATE.md and check for `### Quick Tasks Completed` section.
+
+**7b. If section doesn't exist, create it:**
+
+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
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+```
+
+**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}/) |
+```
+
+**7d. Update "Last activity" line:**
+
+Use `date` from init:
+```
+Last activity: ${date} - Completed quick task ${next_num}: ${DESCRIPTION}
+```
+
+Use Edit tool to make these changes atomically
+
+---
+
+**Step 8: Final commit and completion**
+
+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 ${file_list}
+```
+
+Get final commit hash:
+```bash
+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`:**
+```
+---
+
+GSD > QUICK TASK COMPLETE
+
+Quick Task ${next_num}: ${DESCRIPTION}
+
+Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md
+Commit: ${commit_hash}
+
+---
+
+Ready for next task: /gsd:quick
+```
+
+</process>
+
+<success_criteria>
+- [ ] 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
+- [ ] (--full) `${next_num}-VERIFICATION.md` created by verifier
+- [ ] STATE.md updated with quick task row (Status column when --full)
+- [ ] Artifacts committed
+</success_criteria>

package/get-shit-done/workflows/remove-phase.md

@@ -0,0 +1,154 @@
+<purpose>
+Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- Argument is the phase number to remove (integer or decimal)
+- Example: `/gsd:remove-phase 17` → phase = 17
+- Example: `/gsd:remove-phase 16.1` → phase = 16.1
+
+If no argument provided:
+
+```
+ERROR: Phase number required
+Usage: /gsd:remove-phase <phase-number>
+Example: /gsd:remove-phase 17
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init phase-op "${target}")
+```
+
+Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
+
+Also read STATE.md and ROADMAP.md content for parsing current position.
+</step>
+
+<step name="validate_future_phase">
+Verify the phase is a future phase (not started):
+
+1. Compare target phase to current phase from STATE.md
+2. Target must be > current phase number
+
+If target <= current phase:
+
+```
+ERROR: Cannot remove Phase {target}
+
+Only future phases can be removed:
+- Current phase: {current}
+- Phase {target} is current or completed
+
+To abandon current work, use /gsd:pause-work instead.
+```
+
+Exit.
+</step>
+
+<step name="confirm_removal">
+Present removal summary and confirm:
+
+```
+Removing Phase {target}: {Name}
+
+This will:
+- Delete: .planning/phases/{target}-{slug}/
+- Renumber all subsequent phases
+- Update: ROADMAP.md, STATE.md
+
+Proceed? (y/n)
+```
+
+Wait for confirmation.
+</step>
+
+<step name="execute_removal">
+**Delegate the entire removal operation to gsd-tools:**
+
+```bash
+RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase remove "${target}")
+```
+
+If the phase has executed plans (SUMMARY.md files), gsd-tools will error. Use `--force` only if the user confirms:
+
+```bash
+RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase remove "${target}" --force)
+```
+
+The CLI handles:
+- Deleting the phase directory
+- Renumbering all subsequent directories (in reverse order to avoid conflicts)
+- Renaming all files inside renumbered directories (PLAN.md, SUMMARY.md, etc.)
+- Updating ROADMAP.md (removing section, renumbering all phase references, updating dependencies)
+- Updating STATE.md (decrementing phase count)
+
+Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
+</step>
+
+<step name="commit">
+Stage and commit the removal:
+
+```bash
+node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
+```
+
+The commit message preserves the historical record of what was removed.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {target} ({original-name}) removed.
+
+Changes:
+- Deleted: .planning/phases/{target}-{slug}/
+- Renumbered: {N} directories and {M} files
+- Updated: ROADMAP.md, STATE.md
+- Committed: chore: remove phase {target} ({original-name})
+
+---
+
+## What's Next
+
+Would you like to:
+- `/gsd:progress` — see updated roadmap status
+- Continue with current phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't remove completed phases (have SUMMARY.md files) without --force
+- Don't remove current or past phases
+- Don't manually renumber — use `gsd-tools phase remove` which handles all renumbering
+- Don't add "removed phase" notes to STATE.md — git commit is the record
+- Don't modify completed phase directories
+</anti_patterns>
+
+<success_criteria>
+Phase removal is complete when:
+
+- [ ] Target phase validated as future/unstarted
+- [ ] `gsd-tools phase remove` executed successfully
+- [ ] Changes committed with descriptive message
+- [ ] User informed of changes
+</success_criteria>

package/get-shit-done/workflows/research-phase.md

@@ -0,0 +1,74 @@
+<purpose>
+Research how to implement a phase. Spawns gsd-phase-researcher with phase context.
+
+Standalone research command. For most workflows, use `/gsd:plan-phase` which integrates research automatically.
+</purpose>
+
+<process>
+
+## Step 0: Resolve Model Profile
+
+@~/.claude/get-shit-done/references/model-profile-resolution.md
+
+Resolve model for:
+- `gsd-phase-researcher`
+
+## Step 1: Normalize and Validate Phase
+
+@~/.claude/get-shit-done/references/phase-argument-parsing.md
+
+```bash
+PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "${PHASE}")
+```
+
+If `found` is false: Error and exit.
+
+## Step 2: Check Existing Research
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+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'
+```
+
+## Step 4: Spawn Researcher
+
+```
+Task(
+  prompt="<objective>
+Research implementation approach for Phase {phase}: {name}
+</objective>
+
+<context>
+Phase description: {description}
+Requirements: {requirements}
+Prior decisions: {decisions}
+Phase context: {context_md}
+</context>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>",
+  subagent_type="gsd-phase-researcher",
+  model="{researcher_model}"
+)
+```
+
+## Step 5: Handle Return
+
+- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
+- `## CHECKPOINT REACHED` — Present to user, spawn continuation
+- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
+
+</process>