File detailed Beads epics and issues from a plan
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Convert a plan into Beads epics and issues using sequential subagents to keep the main context clean.
Why Sequential? The
bdCLI does not have file locking or atomic ID generation. Parallelbd createcalls cause race conditions (ID collisions, data corruption). Each epic must complete before the next begins.
Review the plan context: $ARGUMENTS
If no plan provided, check:
docs/plans/ directoryconductor/tracks/ for spec.md and plan.md filesIdentify for each epic:
| Field | Description |
|---|---|
| Epic title | Clear workstream name |
| Child tasks | Individual issues under this epic |
| Intra-epic deps | Dependencies within the epic |
| Cross-epic hints | Tasks that depend on other epics (by name, not ID) |
| Priority | 0-4 scale |
Dispatch one subagent per epic. Wait for each to complete before starting the next to avoid ID collisions.
File Epic: "<EPIC_TITLE>"
## Your Task
Create one epic and all its child issues in Beads.
## Epic Context
<PASTE_EPIC_SECTION_FROM_PLAN>
## Steps
1. Create the epic:
```bash
bd create "Epic: <title>" -t epic -p <priority> --json
For each task, create an issue with parent dependency:
bd create "<task title>" -t <type> -p <priority> --deps bd-<epic-id> --json
Include in each issue:
Link intra-epic dependencies:
bd dep add bd-<child> bd-<blocker> --type blocks --json
Return ONLY this JSON (no other text):
{
"epicId": "bd-XXX",
"epicTitle": "<title>",
"issues": [
{"id": "bd-XXX", "title": "...", "deps": ["bd-XXX"]}
],
"crossEpicDeps": [
{"issueId": "bd-XXX", "needsLinkTo": "<epic or task name>"}
]
}
### Dispatch Example
Task(description: "File Epic: Authentication", prompt: <above template>) // Wait for result...
Task(description: "File Epic: Database Layer", prompt: <above template>) // Wait for result...
Task(description: "File Epic: API Endpoints", prompt: <above template>) // Wait for result...
**Execute sequentially** — each subagent must return before dispatching the next.
## Phase 3: Collect & Link Cross-Epic Dependencies
When subagents return:
1. Parse JSON results from each subagent
2. Build ID lookup table:
"Authentication" → bd-101 "Database Layer" → bd-102 "Setup user table" → bd-105
3. Resolve cross-epic dependencies:
```bash
bd dep add bd-<from> bd-<to> --type blocks --json
Run verification:
bd list --json
bd ready --json
Check:
Present to user:
## Filed Beads Summary
**Epics created:** 3
**Issues created:** 12
| Epic | Issues | Ready |
|------|--------|-------|
| Authentication | 4 | 2 |
| Database Layer | 5 | 1 |
| API Endpoints | 3 | 0 (blocked) |
**Start with:** bd-105 (Setup user table), bd-108 (Init auth config)
**Cross-epic deps linked:** 2
| Priority | Use For |
|---|---|
| 0 | Critical path blockers, security |
| 1 | Core functionality, high value |
| 2 | Standard work (default) |
| 3 | Nice-to-haves, polish |
| 4 | Backlog, future |
bd CLI lacks file locking; serial execution prevents ID collisionsbd create output stays in subagent contextsAfter filing, save handoff state and output for next session:
bd update <epic-id> --notes "HANDOFF_READY: true. PLAN: <plan-path>"
Where <plan-path> is the source plan (e.g., conductor/plans/2024-12-20-feature-design.md or conductor/tracks/<id>/plan.md)
## HANDOFF
**Command:** `Start epic <epic-id>`
**Epic:** <epic-id> - <epic-title>
**Plan:** <plan-path>
**Ready issues:** <count>
**First task:** <first-issue-id> - <title>
Copy the command above to start a new session.
This enables the execution-workflow to detect handoffs and load epic context automatically.