Convert a PRD to br (beads_rust) issues. Creates an epic with child issues for each user story, sets up dependencies, and appends quality gates. Triggers on: convert prd, prd to beads, create beads from prd, prd to br, create issues from prd.
Convert a PRD to br (beads_rust) issues. Creates an epic with child issues for each user story, sets up dependencies, and appends quality gates. Triggers on: convert prd, prd to beads, create beads from prd, prd to br, create issues from prd.
PRD → br (beads_rust) Converter
Convert a Product Requirements Document into br issues: one epic + one issue per user story, with dependencies and quality gates.
The Job
Read the PRD (file path or inline text)
Extract Quality Gates section
Create an epic for the feature
Create one issue per user story as children of the epic
Set up dependencies between issues using the PRD's dependency graph
Append quality gates to each issue's acceptance criteria
Sync to JSONL for git tracking
Do NOT start implementing any stories. Just create the issues.
Step 1: Extract Quality Gates
Find the PRD's "Quality Gates" section and extract:
Universal gates: Commands that apply to ALL stories
Conditional gates: Commands for specific story types (e.g., "agent-editing stories")
If a PRD story is too large, split it into sub-stories before creating issues. Note the split in the epic description.
Handling Phased PRDs
For PRDs with multiple phases:
Create ONE epic for the entire feature
All stories across all phases are children of that epic
Dependencies between phases are explicit (br dep add)
Phase 0 stories have no dependencies
Phase 1 stories may depend on Phase 0
Phase 2 stories depend on relevant Phase 1 stories
etc.
Step 6: Beads QA Review Passes
"Check your beads N times, implement once." After creating all issues, run iterative QA passes to catch missing context, unclear criteria, and dependency errors. This saves implementation tokens by front-loading planning quality.
How It Works
Run review passes until changes flatline (typically 2-4 passes):
Pass 1 → significant changes (missing stories, wrong deps, unclear criteria)
Pass 2 → moderate changes (edge cases, missing test criteria, context gaps)
Pass 3 → minor changes (wording, small clarifications)
Pass 4 → no meaningful changes → STOP
What to Check Each Pass
For EACH bead, review:
Self-containment: Can an agent implement this bead WITHOUT re-reading the PRD or other beads? If not, add the missing context directly into the bead's description.
Acceptance criteria quality: Are criteria machine-verifiable? "Works correctly" → BAD. "Returns 401 for non-initialforce.com emails" → GOOD.
Dependencies: Are all upstream beads listed? Are there false dependencies that could be removed to parallelize work?
Missing stories: Are there implicit tasks (test setup, config, migrations, observability) not covered by any bead?
Sizing: Can each bead be completed in ONE agent session? If not, split it.
Architecture context: Does the bead include enough context about the tech stack, file paths, and patterns for the implementing agent?
Pass Format
For each proposed change, output:
BEAD: bd-s4s.3
CHANGE: Add missing context about OAuth redirect URI for dev mode
DIFF: + "Local dev: redirect to http://localhost:3000/auth/callback"
RATIONALE: Implementing agent won't know the callback URL pattern
After each pass, apply changes via br update, then re-review.
Stop Condition
Stop when a pass produces only trivial wording changes or no changes at all. Never run more than 5 passes.
Making Beads Self-Contained
Critical principle: Each bead must be independently implementable. An agent picking up a bead should NOT need to:
Re-read the full PRD
Look at sibling beads for context
Guess at tech stack decisions
What to Include in Each Bead
Tech stack context: What framework, libraries, and patterns to use
File paths: Where to create/modify files (if known from scaffolding decisions)
Integration points: How this bead connects to upstream dependencies
Specific API/CLI commands: Exact commands or API signatures, not vague references
Error cases: What should happen when things go wrong
Example: BAD vs GOOD
BAD bead:
"Implement Google SSO authentication"
OAuth flow works
Only company emails accepted
GOOD bead:
"Implement Google SSO using @fastify/oauth2 plugin on the Fastify backend (packages/backend).
Uses JWT stored in httpOnly/secure/sameSite=strict cookie. Check hd claim equals 'initialforce.com'.
Session timeout: 8h max, 30min inactivity. Local dev mode: skip OAuth, use DEV_USER_EMAIL env var."
@fastify/oauth2 configured with Google provider
hd claim checked, non-initialforce.com returns 403 with error message
JWT issued with {email, name, role} claims, 8h expiry
Cookie: httpOnly, secure, sameSite=strict
GET /auth/me returns current user or 401
DEV_USER_EMAIL env var bypasses OAuth in development
Verification
After creating all issues and completing QA passes, verify:
# List all issues
br list
# Verify no orphaned dependencies
br doctor
Checklist
Before finishing:
Quality gates extracted from PRD
Epic created with PRD overview and external-ref
One issue per user story (no merging, no splitting unless too large)
Acceptance criteria copied verbatim from PRD
Quality gates appended to every issue
Dependencies match PRD's dependency graph
No circular dependencies
Priorities set by phase (P0-P3)
Beads are self-contained (implementable without re-reading PRD)
QA review passes completed (changes flatlined)
br sync --flush-only executed
.beads/ committed to git
Related Skills
/swarm-beads-create — Multi-agent version: uses 3-6 parallel agents for complex plans with many beads
/swarm-beads-quality — Run quality pipeline on created beads (review, oracle, harden)
/beads-polish — Single-agent bead review and polish (lighter than swarm-beads-quality)
