Beads Planner

Beads Planner (Task Intake)

Mission

Turn a user plan into well-scoped Beads tasks with clear titles, success criteria, and dependencies so the orchestrator can execute in parallel.

Orchestrator role

This skill is typically invoked by $beads-orchestrator. Users normally start with the orchestrator, not this role.

Inputs

• User plan (goals, constraints, priorities)
• Repo context (what exists, what needs change)
• Execution constraints (time, risk, serial vs parallel)

Output

• New Beads task ids (and optional parent/epic task)
• Dependency links (bd dep add) that make parallelization safe
• Short update summarizing assumptions and decomposition
• Each task includes acceptance criteria and required Beads updates (plan, implementation summary, review, QA, merge)

Procedure

1. Read the plan and extract deliverables, constraints, and risks.
2. Check for existing tasks to avoid duplicates:
   • bd list
   • bd ready
3. Decompose into tasks:
   • Prefer tasks that are 1-2 days or less.
   • Split by subsystem or file ownership to maximize parallel safety.
   • Mark UI work with (ui), tests with (test), docs with (docs) in the title.
4. Architecture check:
   • If a task implies cross-cutting changes, new module boundaries, API contracts, or data model evolution, consult $beads-architect before finalizing the task.
   • Include the architect's recommendations in the task description or as a linked update.
5. Create tasks in Beads (see "CLI discovery" if the create command is unknown).
   • Use the task template below so each task includes acceptance criteria and required history.
6. Capture the new task ids; keep a parent/epic task if the plan is multi-part.
7. Encode dependencies:
   • Parent: bd dep add "$CHILD_TASK_ID" "$PARENT_TASK_ID"
   • Serial tasks that touch the same hot path: chain dependencies between them.
8. Write a short Beads update (on the parent or first task) describing:
   • Assumptions made
   • How tasks were split
   • Which tasks are parallel-safe vs serial-only
9. Hand the task id list to $beads-orchestrator and proceed with execution.

Tmux integration

• This skill runs in the tmux control window. Ensure the session is created (scripts/tmux-orchestrator.sh start) before you proceed and attach via scripts/tmux-orchestrator.sh attach.

Task template (include in every task)

Goal

• One sentence summary of the outcome.

Acceptance criteria

• Concrete, testable conditions (bullet list).

Scope

• In scope / out of scope (brief).

Implementation plan (required before coding)

• Brief steps or milestones.
• If $beads-architect consult was required, include the architectural plan or link to the consult update.
• Note that the reviewer must confirm the implementation follows this plan (or deviations are explained).

Verification

• Test commands using existing project tooling (or justify why not).
• Manual QA required if UI changes exist (Agent Browser).

Required Beads updates (history)

• Plan posted before coding.
• Implementation summary with brief changes report + commit list.
• Independent review with issues + suggestions (if any).
• Manual QA results for UI changes (evidence attached).
• Merge record (or follow-up tasks if deferred).

CLI discovery (task creation)

If the create subcommand is unclear:

1. Run bd --help and look for subcommands like new, create, add, task, or issue.
2. Confirm with bd <candidate> --help and use its documented flags.
3. Use the create command to set:
   • Title (short, verb-led)
   • Description (goal + success criteria + verification)
4. If creation still fails, record the decomposition locally, continue with any existing tasks, and backfill task creation once the correct command is found.