beads-backed-planning

Beads-Backed Planning Skill

Create a structured implementation plan using Beads as the source of truth. The plan becomes an epic with tasks that persist across sessions and conversation compaction.

When to Use This Skill

Use this skill when:

• You have a clear understanding of what to build (from brainstorming or a design doc)
• A feature branch/worktree is set up
• You're ready to break work into implementable tasks

Prerequisites

1. Threadwork initialized (.threadwork.yaml exists)
2. Beads initialized (bd --no-daemon status works)
3. A design doc or clear problem statement

Core Principle: Beads is Source of Truth

The plan IS the Beads structure. Markdown is generated for human review but can always be regenerated from Beads. This ensures:

• Plans survive conversation compaction
• Dependencies are queryable with bd ready
• Progress persists across sessions

Skill Workflow

Step 1: Understand the Feature

Review the design doc or problem statement. Identify:

• The main goal (this becomes the epic)
• Discrete, implementable pieces (these become tasks)
• Dependencies between pieces

Step 2: Create the Epic

bd --no-daemon create \
  --type epic \
  --title "Feature: {Feature Name}" \
  --description "{Why this feature exists, the problem it solves}" \
  --design "{High-level approach, key decisions}" \
  --acceptance "{What 'done' looks like for the whole feature}"

Capture the epic ID (e.g., bd-a3f) for linking tasks.

Step 3: Break Down Into Tasks

For each discrete piece of work, create a task. Tasks should be:

• Implementable in one session (roughly 1-4 hours of work)
• Independently testable (has clear acceptance criteria)
• Ordered by dependency (can't do task 3 without task 2)

Task fields:

Field	Purpose	Content
title	Short identifier	"Task 1: Set up JWT middleware"
description	WHY (context)	Problem this task addresses
design	WHAT to build	Files to create/modify, behavior, test cases
acceptance	Done criteria	Specific, testable outcomes
parent	Links to epic	The epic ID
blocked-by	Dependencies	Previous task ID (linear chain initially)