From agentsmith
Use when a markdown implementation plan, spec, or design doc needs to be translated into Beads issues — epic, tasks, dependencies, and acceptance criteria. Plans (how to get there) are preferred over specs (what the goals are) since they already have discrete steps and sequencing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agentsmith:to-beadsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Convert a markdown implementation plan, spec, or design document into a structured set of Beads issues: one epic for the initiative, one task per discrete workstream, and dependency links between them.
Convert a markdown implementation plan, spec, or design document into a structured set of Beads issues: one epic for the initiative, one task per discrete workstream, and dependency links between them.
Prefer plans over specs. A plan already has discrete steps and sequencing — use it directly. Only fall back to a spec if no plan exists.
digraph beads_from_spec {
"Read document fully" [shape=box];
"Identify epic + tasks + deps" [shape=box];
"Create/update epic" [shape=box];
"3+ tasks?" [shape=diamond];
"Parallel subagents" [shape=box];
"Sequential bd create" [shape=box];
"Set dependencies" [shape=box];
"Gap review vs document" [shape=box];
"Gaps found?" [shape=diamond];
"Update beads" [shape=box];
"bd dolt push" [shape=box];
"Read document fully" -> "Identify epic + tasks + deps";
"Identify epic + tasks + deps" -> "Create/update epic";
"Create/update epic" -> "3+ tasks?";
"3+ tasks?" -> "Parallel subagents" [label="yes"];
"3+ tasks?" -> "Sequential bd create" [label="no"];
"Parallel subagents" -> "Set dependencies";
"Sequential bd create" -> "Set dependencies";
"Set dependencies" -> "Gap review vs document";
"Gap review vs document" -> "Gaps found?";
"Gaps found?" -> "Update beads" [label="yes"];
"Gaps found?" -> "bd dolt push" [label="no"];
"Update beads" -> "bd dolt push";
}
Read the entire document before creating anything. Map sections to Beads fields:
| Document element | Beads field |
|---|---|
| Title / Overview | Epic title + description |
| Steps / Tasks / Workstreams | One task per independently implementable unit |
| Acceptance criteria | Included in each task --description |
| Sequencing / "depends on" / numbered steps | bd dep add relationships |
| File path | Epic --notes="Plan: <path>" or --notes="Spec: <path>" |
| Design decisions | --notes on relevant task |
Task granularity: If two things must always be done together → merge into one task. If they can be worked independently or in parallel → separate tasks.
New epic:
bd create \
--title="<initiative title>" \
--type=feature \
--priority=<P0-P4> \
--description="<overview paragraph from document>" \
--notes="Plan: <path/to/file.md>"
Existing bead as epic (e.g. a pre-existing feature bead):
bd update <existing-id> --notes="Plan: <path/to/file.md>"
3+ tasks → use superpowers:dispatching-parallel-agents
1–2 tasks → run bd create calls in the same message
Each task --description MUST include:
IMPORTANT: bd renders descriptions as markdown. Numbered list markers (1. ) get their period+space stripped, turning 1. Write into 1Write. Plain text without list syntax collapses into one paragraph with no line breaks.
The correct pattern: use unordered list syntax (- ) combined with Step N: / ACN: prefixes. The - provides line breaks; the prefix provides readable labels after the - is stripped:
Steps:
- Step 1: Write the failing test
- Step 2: Implement the feature
- Step 3: Verify the test passes
Acceptance criteria:
- AC1: <measurable outcome>
- AC2: <measurable outcome>
bd create \
--title="<task title>" \
--type=task \
--priority=<match epic> \
--parent=<epic-id> \
--description="<steps + acceptance criteria>"
# Y depends on X (X must finish before Y can start)
bd dep add <Y-id> <X-id>
# Epic blocked until key task is done
bd dep add <epic-id> <final-task-id>
Derive order from spec sequencing language: "before", "after", "once X is done", "requires X".
Direction: bd dep add <the-thing-that-waits> <the-thing-it-waits-for>.
Re-read the spec section by section. For each bead, verify:
bd show <id> to confirm)The gap review always finds something. Do not skip it.
Fix gaps inline:
bd update <id> --description="<updated description>"
bd dolt push
bd edit — opens $EDITOR, blocks agents; use bd update --description instead--notes| Mistake | Fix |
|---|---|
| Skipping gap review because "it looks complete" | The gap review always finds something. Run it. |
| Wrong dependency direction | bd dep add <waits> <provides> — the waiter comes first |
| Vague acceptance criteria ("works correctly") | Spec what is measurable: inputs, outputs, observable behavior |
| One giant task for everything | Split on independent implementability, not on topic |
| Forgetting to push | bd dolt push or changes are local-only |
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub dlstadther/agentsmith --plugin agentsmith