Ralph TUI - Create Beads
Converts PRDs to beads (epic + child tasks) for ralph-tui autonomous execution.
Note: This skill is bundled with ralph-tui's Beads tracker plugin. Future tracker plugins (Linear, GitHub Issues, etc.) will bundle their own task creation skills.
The Job
Take a PRD (markdown file or text) and create beads in .beads/beads.jsonl:
- Extract Quality Gates from the PRD's "Quality Gates" section
- Create an epic bead for the feature
- Create child beads for each user story (with quality gates appended)
- Set up dependencies between beads (schema → backend → UI)
- Output ready for
ralph-tui run --tracker beads
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 bd create command with HEREDOC syntax to safely handle special characters:
bd create --type=epic \
--title="[Feature Name]" \
--description="$(cat <<'EOF'
[Feature description from PRD]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
bd 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:
- Schema/database changes (migrations)
- Server actions / backend logic
- UI components that use the backend
- Dashboard/summary views that aggregate data
Wrong order:
- ❌ UI component (depends on schema that doesn't exist yet)
- ❌ Schema change
Dependencies with bd dep add
Use the bd dep add command to specify which beads must complete first:
bd create --parent=epic-123 --title="US-001: Add schema" ...
bd create --parent=epic-123 --title="US-002: Create API" ...
bd create --parent=epic-123 --title="US-003: Build UI" ...
bd dep add ralph-tui-002 ralph-tui-001
bd dep add ralph-tui-003 ralph-tui-002
Syntax: bd 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:
- Schema/database changes (no dependencies)
- Backend logic (depends on schema)
- UI components (depends on backend)
- Integration/polish (depends on UI)
Acceptance Criteria: Quality Gates + Story-Specific
Each bead's description should include acceptance criteria with:
- Story-specific criteria from the PRD (what this story accomplishes)
- 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"
Conversion Rules
- Extract Quality Gates from PRD first
- Each user story → one bead
- First story: No dependencies (creates foundation)
- Subsequent stories: Depend on their predecessors (UI depends on backend, etc.)
- Priority: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
- All stories:
status: "open"
- Acceptance criteria: Story criteria + quality gates appended
- UI stories: Also append UI-specific gates (browser verification)
Splitting Large PRDs
If a PRD has big features, split them:
Original:
"Add friends outreach track with different messaging"
Split into:
- US-001: Add investorType field to database
- US-002: Add type toggle to investor list UI
- US-003: Create friend-specific phase progression logic
- US-004: Create friend message templates
- US-005: Wire up task generation for friends
- US-006: Add filter by type
- US-007: Update new investor form
- US-008: Update dashboard counts
Each is one focused change that can be completed and verified independently.
Example
Input PRD:
# PRD: Friends Outreach
Add ability to mark investors as "friends" for warm outreach.
## 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
## User Stories
### US-001: Add investorType field to investor table
**Description:** As a developer, I need to categorize investors as 'cold' or 'friend'.
**Acceptance Criteria:**
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully
### US-002: Add type toggle to investor list rows
**Description:** As Ryan, I want to toggle investor type directly from the list.
**Acceptance Criteria:**
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
### US-003: Filter investors by type
**Description:** As Ryan, I want to filter the list to see just friends or cold.
**Acceptance Criteria:**
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params
Output beads:
bd create --type=epic \
--title="Friends Outreach Track" \
--description="$(cat <<'EOF'
Warm outreach for deck feedback
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
bd create --parent=ralph-tui-abc \
--title="US-001: Add investorType field to investor table" \
--description="$(cat <<'EOF'
As a developer, I need to categorize investors as 'cold' or 'friend'.
## Acceptance Criteria
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
EOF
)" \
--priority=1
bd create --parent=ralph-tui-abc \
--title="US-002: Add type toggle to investor list rows" \
--description="$(cat <<'EOF'
As Ryan, I want to toggle investor type directly from the list.
## Acceptance Criteria
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
--priority=2
bd dep add ralph-tui-002 ralph-tui-001
bd create --parent=ralph-tui
