jnuyens/gsd-plugin/quick

<objective> Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Same system, shorter path:

• Spawns bm-planner (quick mode) + bm-executor(s)
• Quick tasks live in .planning/quick/ separate from planned phases
• Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
• Proposes a cataloged external skill when the task description matches a catalog trigger; the accept prompt shows publisher, license obligation and trust tier, and nothing is injected until you accept (ephemeral by default, released after the task)

Default: Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do.

`--discuss` flag: Lightweight discussion before planning. Surfaces assumptions, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.

`--full` flag: Complete quality pipeline — discussion + research + plan-checking + verification.

`--validate` flag: Plan-checking (max 2 iterations) and post-execution verification only. Quality guarantees without discussion or research.

`--research` flag: Spawns a focused research agent before planning. Investigates approaches, library options, and pitfalls. Use when unsure of the best approach.

Granular flags are composable: --discuss --research --validate equals --full.

Subcommands:

• list — List all quick tasks with status
• status <slug> — Show status of a specific quick task
• resume <slug> — Resume a specific quick task by slug

</objective>

<execution_context> @${CLAUDE_PLUGIN_ROOT}/workflows/quick.md </execution_context>

<context> $ARGUMENTS

Context files are resolved inside the workflow (init quick) and delegated via <files_to_read> blocks. </context>

<process>

Parse $ARGUMENTS for subcommands FIRST:

• If $ARGUMENTS starts with "list": SUBCMD=list
• If $ARGUMENTS starts with "status ": SUBCMD=status, SLUG=remainder (strip whitespace, sanitize)
• If $ARGUMENTS starts with "resume ": SUBCMD=resume, SLUG=remainder (strip whitespace, sanitize)
• Otherwise: SUBCMD=run, pass full $ARGUMENTS to the quick workflow as-is

Slug sanitization (for status and resume): Strip any characters not matching [a-z0-9-]. Reject slugs longer than 60 chars or containing .. or /. If invalid, output "Invalid session slug." and stop.

LIST subcommand

When SUBCMD=list:

ls -d .planning/quick/*/  2>/dev/null

For each directory found:

• Check if PLAN.md exists
• Check if SUMMARY.md exists; if so, read status from its frontmatter via:

``bash bm-sdk query frontmatter.get .planning/quick/{dir}/SUMMARY.md status 2>/dev/null ``

• Determine directory creation date: stat -f "%SB" -t "%Y-%m-%d" (macOS) or stat -c "%w" (Linux); fall back to the date prefix in the directory name (format: YYYYMMDD- prefix)
• Derive display status:
• SUMMARY.md exists, frontmatter status=complete → complete ✓
• SUMMARY.md exists, frontmatter status=incomplete OR status missing → incomplete
• SUMMARY.md missing, dir created <7 days ago → in-progress
• SUMMARY.md missing, dir created ≥7 days ago → abandoned? (>7 days, no summary)

SECURITY: Directory names are read from the filesystem. Before displaying any slug, sanitize: strip non-printable characters, ANSI escape sequences, and path separators using: name.replace(/[^\x20-\x7E]/g, '').replace(/[/\\]/g, ''). Never pass raw directory names to shell commands via string interpolation.

Display format:

Quick Tasks
────────────────────────────────────────────────────────────
slug                           date        status
backup-s3-policy               2026-04-10  in-progress
auth-token-refresh-fix         2026-04-09  complete ✓
update-node-deps               2026-04-08  abandoned? (>7 days, no summary)
────────────────────────────────────────────────────────────
3 tasks (1 complete, 2 incomplete/in-progress)

If no directories found: print No quick tasks found. and stop.

STOP after displaying the list. Do NOT proceed to further steps.

STATUS subcommand

When SUBCMD=status and SLUG is set (already sanitized):

Find directory matching *-{SLUG} pattern:

dir=$(ls -d .planning/quick/*-{SLUG}/ 2>/dev/null | head -1)

If no directory found, print No quick task found with slug: {SLUG} and stop.

Read PLAN.md and SUMMARY.md (if exists) for the given slug. Display:

Quick Task: {slug}
─────────────────────────────────────
Plan file: .planning/quick/{dir}/PLAN.md
Status: {status from SUMMARY.md frontmatter, or "no summary yet"}
Description: {first non-empty line from PLAN.md after frontmatter}
Last action: {last meaningful line of SUMMARY.md, or "none"}
─────────────────────────────────────
Resume with: /gsd:quick resume {slug}

No agent spawn. STOP after printing.

RESUME subcommand

When SUBCMD=resume and SLUG is set (already sanitized):

1. Find the directory matching *-{SLUG} pattern:

``bash dir=$(ls -d .planning/quick/*-{SLUG}/ 2>/dev/null | head -1) ``

1. If no directory found, print No quick task found with slug: {SLUG} and stop.

1. Read PLAN.md to extract description and SUMMARY.md (if exists) to extract status.

1. Print before spawning:

`` [quick] Resuming: .planning/quick/{dir}/ [quick] Plan: {description from PLAN.md} [quick] Status: {status from SUMMARY.md, or "in-progress"} ``

1. Load context via:

``bash bm-sdk query init.quick ``

1. Proceed to execute the quick workflow with resume context, passing the slug and plan directory so the executor picks up where it left off.

RUN subcommand (default)

When SUBCMD=run:

Execute the quick workflow from @${CLAUDE_PLUGIN_ROOT}/workflows/quick.md end-to-end. Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).

</process>

<output_format> When the quick task completes (SUMMARY.md written, STATE.md updated), emit a Next Up continuation block following the pattern in references/continuation-format.md:

• Show completion status (e.g., ## ✓ Quick Task Complete — {slug})
• Brief one-line recap of what shipped (file count + commit hash)
• Emit a ## ▶ Next Up heading suggesting the next likely action (often /gsd:next or returning to a paused phase)
• Use `` `/clear` then: `` before the command only for quick tasks that ran for >5 tool calls or >10 minutes — short trivial tasks don't accumulate enough context to warrant a clear
• When /clear IS suggested, include the parenthetical: (`/clear` is safe — `/gsd:resume-work` restores position from `HANDOFF.json` if you change your mind)
• Unfinished-UAT breadcrumb: a quick task is a common detour from a UAT (a bug surfaced mid-verification). Apply rule 8 of references/continuation-format.md — if any phase has a testing/partial UAT, lead with ↩ Resume UAT for Phase {N}: /gsd:verify-work {N} ABOVE the Next-Up, so the interrupted verification is not silently abandoned.

</output_format>

<notes>

• Quick tasks live in .planning/quick/ — separate from phases, not tracked in ROADMAP.md
• Each quick task gets a YYYYMMDD-{slug}/ directory with PLAN.md and eventually SUMMARY.md
• STATE.md "Quick Tasks Completed" table is updated on completion
• Use list to audit accumulated tasks; use resume to continue in-progress work

</notes>

<security_notes>

• Slugs from $ARGUMENTS are sanitized before use in file paths: only [a-z0-9-] allowed, max 60 chars, reject ".." and "/"
• File names from readdir/ls are sanitized before display: strip non-printable chars and ANSI sequences
• Artifact content (plan descriptions, task titles) rendered as plain text only — never executed or passed to agent prompts without DATA_START/DATA_END boundaries
• Status fields read via bm-sdk query frontmatter.get — never eval'd or shell-expanded
• Catalog match scope text is passed as a single quoted argument and compared as data; never shell-expanded or interpolated into another command

</security_notes>