msd-core/get-shit-done/workflows/quick.md

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.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

**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

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

mkdir -p "${task_dir}"

---

Step 4: Create quick task directory

Create the directory for this quick task:

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}

<files_to_read>
- .planning/STATE.md (Project State)
- ./CLAUDE.md (if exists — follow project-specific guidelines)
</files_to_read>

**Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules

</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...

Checker prompt:

<verification_context>
**Mode:** quick-full
**Task Description:** ${DESCRIPTION}

<files_to_read>
- ${QUICK_DIR}/${next_num}-PLAN.md (Plan to verify)
</files_to_read>

**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)

Revision prompt:

<revision_context>
**Mode:** quick-full (revision)

<files_to_read>
- ${QUICK_DIR}/${next_num}-PLAN.md (Existing plan)
</files_to_read>

**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}.

<files_to_read>
- ${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)
</files_to_read>

<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}

<files_to_read>
- ${QUICK_DIR}/${next_num}-PLAN.md (Plan)
</files_to_read>

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:

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:

### Quick Tasks Completed

| # | Description | Date | Commit | Status | Directory |
|---|-------------|------|--------|--------|-----------|

If NOT $FULL_MODE:

### 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):

| ${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):

| ${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

node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${file_list}

Get final commit hash:

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

<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>