plan-to-beads-conversion_skill

Overview

This skill converts a DevAgent plan into a Beads epic and task set so Ralph can run an execution loop reliably. It ensures every epic and direct child task has the required fields, exactly one routing label, correct parent linkage, and dependency edges. The output is a JSON payload ready to write to beads-payload.json for subsequent bd CLI operations.

How this skill works

The skill reads the plan path and Ralph config mapping, extracts the plan title, summary/functional narrative, tasks, acceptance criteria, and any UI signals. It emits an epic object with plan references and detected quality gates, then generates direct child tasks (and optional subtasks) with descriptions, notes including the plan path, acceptance criteria, and exactly one routing label. Creation is split into create-first and link-second phases: tasks are created individually, then dependencies and parent fields are added in a separate pass to remain resumable.

When to use it

• After a plan is drafted/approved and before starting Ralph execution
• When you need to ensure each direct epic child has exactly one routing label for Ralph
• When you must embed plan path, deliverable summary, and detected quality gates into Beads fields
• When you want a resumable, idempotent creation flow that avoids brittle one-shot commands
• When adding the mandatory final revise report task and wiring its dependencies

Best practices

• Create the epic and each direct child task individually, then add dependencies in a second pass
• Apply exactly one routing label (engineering, qa, design, or project-manager) to each direct epic child
• Always include the absolute plan path in the epic description and each task notes field
• Detect quality gates from project files (package.json / quality-gates template) and list them in the epic
• Use bd update --set-labels to replace labels if corrections are needed; do not rely on bd create flags alone

Example use cases

• Preparing Beads for a TypeScript feature plan so Ralph routes work to engineering and qa agents
• Converting a UI-sensitive plan into an epic with a design task when UI file extensions or UI keywords are present
• Adding the mandatory "Generate Epic Revise Report" task that depends on all top-level tasks
• Recovering mid-run by re-running the link-second pass to add missing dependencies after a timeout
• Verifying readiness with bd ready --parent <EPIC_ID> --limit 200 and bd dep tree <EPIC_ID>