Ralph Tui Create Beads Rust

Ralph TUI - Create Beads (beads-rust)

Converts PRDs to beads (epic + child tasks) for ralph-tui autonomous execution using beads-rust (br CLI).

Note: This skill uses the br command from beads-rust. If you have the original beads (bd) installed instead, use the ralph-tui-create-beads skill.

The Job

Take a PRD (markdown file or text) and create beads using br commands:

1. Extract Quality Gates from the PRD's "Quality Gates" section
2. Create an epic bead for the feature
3. Create child beads for each user story (with quality gates appended)
4. Set up dependencies between beads (schema → backend → UI)
5. Output ready for ralph-tui run --tracker beads-rust

Step 1: Extract Quality Gates

Look for the "Quality Gates" section in the PRD:

## Quality Gates

These commands must pass for every user story:
- `pnpm typecheck` - Type checking
- `pnpm lint` - Linting

For UI stories, also include:
- Verify in browser using dev-browser skill

Extract:

• Universal gates: Commands that apply to ALL stories (e.g., pnpm typecheck)
• UI gates: Commands that apply only to UI stories (e.g., browser verification)

If no Quality Gates section exists: Ask the user what commands should pass, or use a sensible default like npm run typecheck.

Output Format

Beads use br create command with HEREDOC syntax to safely handle special characters:

# Create epic (link back to source PRD)
br create --type=epic \
  --title="[Feature Name]" \
  --description="$(cat <<'EOF'
[Feature description from PRD]
EOF
)" \
  --external-ref="prd:./tasks/feature-name-prd.md"

# Create child bead (with quality gates in acceptance criteria)
br create \
  --parent=EPIC_ID \
  --title="[Story Title]" \
  --description="$(cat <<'EOF'
[Story description with acceptance criteria INCLUDING quality gates]
EOF
)" \
  --priority=[1-4]

CRITICAL: Always use <<'EOF' (single-quoted) for the HEREDOC delimiter. This prevents shell interpretation of backticks, $variables, and () in descriptions.

Story Size: The #1 Rule

Each story must be completable in ONE ralph-tui iteration (~one agent context window).

ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing.

Right-sized stories:

• Add a database column + migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard" → Split into: schema, queries, UI components, filters
• "Add authentication" → Split into: schema, middleware, login UI, session handling
• "Refactor the API" → Split into one story per endpoint or pattern

Rule of thumb: If you can't describe the change in 2-3 sentences, it's too big.

Story Ordering: Dependencies First

Stories execute in dependency order. Earlier stories must not depend on later ones.

Correct order:

1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

Wrong order:

1. ❌ UI component (depends on schema that doesn't exist yet)
2. ❌ Schema change

Dependencies with br dep add

Use the br dep add command to specify which beads must complete first:

# Create the beads first
br create --parent=epic-123 --title="US-001: Add schema" ...
br create --parent=epic-123 --title="US-002: Create API" ...
br create --parent=epic-123 --title="US-003: Build UI" ...

# Then add dependencies (issue depends-on blocker)
br dep add ralph-tui-002 ralph-tui-001  # US-002 depends on US-001
br dep add ralph-tui-003 ralph-tui-002  # US-003 depends on US-002

Syntax: br dep add <issue> <depends-on> — the issue depends on (is blocked by) depends-on.

ralph-tui will:

• Show blocked beads as "blocked" until dependencies complete
• Never select a bead for execution while its dependencies are open
• Include dependency context in the prompt when working on a bead

Correct dependency order:

1. Schema/database changes (no dependencies)
2. Backend logic (depends on schema)
3. UI components (depends on backend)
4. Integration/polish (depends on UI)

Acceptance Criteria: Quality Gates + Story-Specific

Each bead's description should include acceptance criteria with:

1. Story-specific criteria from the PRD (what this story accomplishes)
2. Quality gates from the PRD's Quality Gates section (appended at the end)

Good criteria (verifiable):

• "Add investorType column to investor table with default 'cold'"
• "Filter dropdown has options: All, Cold, Friend"
• "Clicking toggle shows confirmation dialog"

Bad criteria (vague):

• ❌ "Works correctly"
• ❌ "User can do X easily"
• ❌ "Good UX"
• ❌ "Handles edge cases"