# Beads Planner

> Create Beads tasks from a user plan, decompose into parallelizable work, and encode dependencies. Use when a user provides a plan and wants it broken into Beads tasks before execution.

- Skill: `vega113/beads-planner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vega113/beads-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vega113/beads-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vega113 (https://skillmd.com/u/vega113)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/vega113/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.