dotfiles/dot_claude/commands/create-task.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Plan a task by decomposing it into beads issues with dependencies, acceptance criteria, and priorities	<task description or goal>	Bash(bd:*), Bash(git log:*), Bash(git status:*), Bash(rg:*), Task

/create-task — Plan work into beads

• /create-task — Plan work into beads
  • Current workspace state
  • Task to plan
  • Instructions
    • 1. Understand before creating
    • 2. Decompose
    • 3. Create issues
    • 4. Wire dependencies
    • 5. Report the plan

Current workspace state

• Ready work: !bd ready 2>/dev/null | head -30
• In progress: !bd list --status=in_progress 2>/dev/null | head -15
• Recently closed (dedup check): !bd list --status=closed 2>/dev/null | head -10
• Stats: !bd stats 2>/dev/null
• Relevant memories: !bd memories "$ARGUMENTS" 2>/dev/null | head -40

Task to plan

$ARGUMENTS

Instructions

You are planning this task using beads as the sole tracker. Do NOT use TodoWrite, TaskCreate, or markdown checklists. Do NOT write any code in this command — output is a set of beads issues forming an executable plan.

1. Understand before creating

• Search for prior art first: bd search "<keywords>" — the task (or part of it) may already exist. Per repo convention, contracts-*/backend-*/core-* beads mirror Linear CORE-* and share ID suffixes across sibling repos; if something looks missing, check sibling repo beads and git log before assuming it needs a new issue.
• Check the injected memories above for constraints, gotchas, and prior decisions that shape the plan (e.g., root-file serialization, generated-file rules, runtime conventions).
• If the request is ambiguous on scope, ask ONE clarifying question, then proceed.

2. Decompose

Break the task into issues sized for a single focused session (roughly ≤ half a day each). For each issue decide:

• type: feature (new capability), task (chore/refactor/infra), bug (defect)
• priority: numeric only — 0 critical / 1 high / 2 medium / 3 low / 4 backlog. Never "high"/"medium"/"low".
• description: WHY the issue exists + WHAT done looks like. Never a bare title restatement.
• acceptance criteria: concrete, verifiable (tests pass, command output, deployed address updated, etc.)
• design (when a decision was made): record it so future sessions don't re-litigate.

If the plan touches shared root files (turbo.json, pnpm-workspace.yaml, pnpm-lock.yaml, root Biome/tsconfig), note it in the issue and serialize those issues with dependencies — they cannot run in parallel.

3. Create issues

Use the full quality flags:

bd create \
  --title="<imperative summary>" \
  --description="<why + what>" \
  --type=<task|bug|feature> \
  --priority=<0-4> \
  --acceptance="<verifiable criteria>" \
  --design="<decisions, if any>" \
  --notes="<gotchas from memories, file paths, related beads/Linear IDs>" \
  --validate

• 3+ issues → spawn parallel subagents, one bd create batch each, then collect the returned IDs.
• Quote every string flag (descriptions contain &, $, backticks).
• NEVER use bd edit (opens $EDITOR and blocks). Amend with bd update <id> --description/--notes/--design.

4. Wire dependencies

bd dep add <dependent> <blocker>   # dependent depends on blocker

• Model the real execution order: tests depend on implementation, redeploys depend on ABI changes, root-file edits form a chain.
• Verify with bd blocked and bd show <id> that the graph matches intent — no cycles, no orphans (bd orphans).

5. Report the plan

Output a concise summary:

1. Created issues — table of id | title | type | priority
2. Dependency graph — short text sketch of the ordering (e.g. x8y → oto → 53x)
3. Entry point — which issue(s) show in bd ready right now, i.e., where work starts
4. Deferred/skipped — anything that already existed (with the existing ID) or was intentionally left out

Then persist and finish:

bd ready          # confirm entry points are unblocked
git status        # beads auto-commits to Dolt; push if session ends here

If planning surfaced a durable insight (a constraint, a decision, a gotcha), store it: bd remember "<insight>" — never a MEMORY.md file.

Do NOT start implementing any issue. Planning ends when the graph is created, validated, and reported. Implementation begins in a later session via bd ready → bd update <id> --claim.