🚧 Active Development - This project is new and actively evolving. Expect breaking changes. Contributions and feedback welcome!

Turn your PRD into a ready-to-work beads project in one command.

prd-parser uses LLM guardrails to transform Product Requirements Documents into a hierarchical issue structure (Epics → Tasks → Subtasks) and creates them directly in beads - the git-backed issue tracker for AI-driven development.

# One command: PRD → structured beads issues
prd-parser parse ./docs/prd.md

Starting a new project is exciting. You have a vision, maybe a PRD, and you're ready to build. But then:

1. The breakdown problem - You need to turn that PRD into actionable tasks. This is tedious and error-prone. You lose context as you go.

2. The context problem - By the time you're implementing subtask #47, you've forgotten why it matters. What was the business goal? Who are the users? What constraints apply?

3. The handoff problem - If you're using AI to help implement, it needs that context too. Copy-pasting from your PRD for every task doesn't scale.

prd-parser + beads solves all three. Write your PRD once, run one command, and get a complete project structure with context propagated to every level - ready for you or Claude to start implementing.

For greenfield projects, this is the fastest path from idea to structured, trackable work:

How it works: prd-parser uses Go struct guardrails to force the LLM to output valid, hierarchical JSON with:

• Context propagation - Business purpose flows from PRD → Epic → Task → Subtask
• Testing at every level - Unit, integration, type, and E2E requirements enforced
• Dependencies tracked - Issues know what blocks them
• Direct beads integration - Issues created with one command, ready to work

Via npm/bun (easiest):

npm install -g prd-parser
# or
bun install -g prd-parser
# or
npx prd-parser parse ./docs/prd.md  # run without installing

Via Go:

go install github.com/dhabedank/prd-parser@latest

From source:

cd /tmp && git clone https://github.com/dhabedank/prd-parser.git && cd prd-parser && make install

If you see "Make sure ~/go/bin is in your PATH", run:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Now go back to your project.

mkdir my-project && cd my-project
git init
bd init --prefix my-project

Create docs/prd.md with your product requirements. Include:

• What you're building and why
• Who the target users are
• Technical constraints
• Key features

Example:

# Task Management CLI

## Overview
A fast, developer-friendly command-line task manager for teams
who prefer terminal workflows.

## Target Users
Software developers who live in the terminal and want sub-100ms
task operations without context-switching to a GUI.

## Core Features
1. Create tasks with title, description, priority
2. List and filter tasks by status/priority
3. Update task status (todo → in-progress → done)
4. Local JSON storage for offline-first operation

## Technical Constraints
- Sub-100ms response for all operations
- Single binary, no runtime dependencies
- Config stored in ~/.taskman/

prd-parser parse docs/prd.md

Full context mode is enabled by default - every generation stage has access to your original PRD, producing the most coherent results.

That's it. Your PRD is now a structured beads project with readable hierarchical IDs:

$ bd list
○ my-project-e1 [P1] [epic] - Core Task Management System
○ my-project-e1t1 [P0] [task] - Implement Task Data Model
○ my-project-e1t1s1 [P2] [task] - Define Task struct with JSON tags
○ my-project-e1t1s2 [P2] [task] - Implement JSON file storage
○ my-project-e1t2 [P1] [task] - Build CLI Interface
○ my-project-e2 [P1] [epic] - User Authentication
...

IDs follow a logical hierarchy: e1 (epic 1) → e1t1 (task 1) → e1t1s1 (subtask 1). Use bd show <id> to see parent/children relationships.

# See what's ready to work on
bd ready

# Pick an issue and let Claude implement it
bd show my-project-4og  # Shows full context, testing requirements

# Or let Claude pick and work autonomously
# (beads integrates with Claude Code via the beads skill)

Epic: Core Task Management System
├── Task: Implement Task Data Model
│   ├── Subtask: Define Task struct with JSON tags
│   └── Subtask: Implement JSON file storage
├── Task: Build CLI Interface
│   ├── Subtask: Implement create command
│   └── Subtask: Implement list command
└── ...

Every issue includes propagated context so implementers understand WHY:

**Context:**
- **Business Context:** Developers need fast, frictionless task management
- **Target Users:** Terminal-first developers who want <100ms operations
- **Success Metrics:** All CRUD operations complete in under 100ms

Every issue specifies what testing is needed:

**Testing Requirements:**
- **Unit Tests:** Task struct validation, JSON marshaling/unmarshaling
- **Integration Tests:** Full storage layer integration, concurrent access
- **Type Tests:** Go struct tags validation, JSON schema compliance

The LLM evaluates each task and assigns appropriate priority (not just a default):

Foundation/setup work gets higher priority. Polish/UI tweaks get lower priority.

Issues are automatically labeled based on:

• Layer: frontend, backend, api, database, infra
• Domain: auth, payments, search, notifications
• Skill: react, go, sql, typescript
• Type: setup, feature, refactor, testing

Labels are extracted from the PRD's tech stack and feature descriptions.

• Epics include acceptance criteria for when the epic is complete
• Tasks include design notes for technical approach

All items include time estimates that flow to beads:

• Epics: estimated days
• Tasks: estimated hours
• Subtasks: estimated minutes

Issues are linked with proper blocking relationships:

• Tasks depend on setup tasks
• Subtasks depend on parent task completion
• Cross-epic dependencies are tracked

The easiest way to configure prd-parser is with the interactive setup wizard:

prd-parser setup

The wizard guides you through selecting models for each parsing stage:

• Epic Model (Stage 1): Generates epics from your PRD
• Task Model (Stage 2): Generates tasks for each epic
• Subtask Model (Stage 3): Generates subtasks for each task

Configuration is saved to ~/.prd-parser.yaml.

To reset to defaults:

prd-parser setup --reset

Use different models for different stages to optimize for cost vs. quality:

# Use Opus for epics (complex), Sonnet for tasks, Haiku for subtasks (fast)
prd-parser parse docs/prd.md \
  --epic-model claude-opus-4-20250514 \
  --task-model claude-sonnet-4-20250514 \
  --subtask-model claude-3-5-haiku-20241022

Or configure in ~/.prd-parser.yaml:

epic_model: claude-opus-4-20250514
task_model: claude-sonnet-4-20250514
subtask_model: claude-3-5-haiku-20241022

Command-line flags always override config file settings.

# Basic parse (full context mode is on by default)
prd-parser parse ./prd.md

# Control structure size
prd-parser parse ./prd.md --epics 5 --tasks 8 --subtasks 4

# Set default priority
prd-parser parse ./prd.md --priority high

# Choose testing level
prd-parser parse ./prd.md --testing comprehensive  # or minimal, standard

# Preview without creating (dry run)
prd-parser parse ./prd.md --dry-run

# Save/resume from checkpoint (useful for large PRDs)
prd-parser parse ./prd.md --save-json checkpoint.json
prd-parser parse --from-json checkpoint.json

# Disable full context mode (not recommended)
prd-parser parse ./prd.md --full-context=false

prd-parser automatically chooses the best parsing strategy based on PRD size:

• Small PRDs (< 300 lines): Single-shot parsing (faster)
• Large PRDs (≥ 300 lines): Multi-stage parallel parsing (more reliable)

Override with --single-shot or --multi-stage flags, or adjust threshold with --smart-threshold.

Full context mode is enabled by default. Every stage gets the original PRD as their "north star":

prd-parser parse docs/prd.md  # full context is on by default

To disable (not recommended):

prd-parser parse docs/prd.md --full-context=false

Why this matters:

With --full-context, each agent:

• Stays grounded in original requirements
• Doesn't invent features not in the PRD
• Doesn't miss requirements that ARE in the PRD
• Produces more focused, coherent output

Results comparison (same PRD):

Fewer items with full context = less redundancy, more focused on actual requirements.

Standard parse (full context on by default):

prd-parser parse docs/prd.md

Every stage sees the PRD. Best for accuracy and coherence.

Preview before committing:

prd-parser parse docs/prd.md --dry-run

See what would be created without actually creating issues.

Save checkpoint for manual review:

prd-parser parse docs/prd.md --save-json draft.json --dry-run
# Edit draft.json manually
prd-parser parse --from-json draft.json

Human-in-the-loop for large/complex PRDs:

prd-parser parse docs/prd.md --interactive

Review and edit epics before task generation.

Quick parse for small PRDs:

prd-parser parse docs/prd.md --single-shot

Faster single LLM call. Works well for PRDs under 300 lines.

Cost-optimized for large PRDs:

prd-parser parse docs/prd.md \
  --epic-model claude-opus-4-20250514 \
  --task-model claude-sonnet-4-20250514 \
  --subtask-model claude-3-5-haiku-20241022

Use Opus for epics (complex analysis), Sonnet for tasks, Haiku for subtasks (fast, cost-effective).

Maximum validation:

prd-parser parse docs/prd.md --validate

Full context + validation pass to catch gaps.

Debug/iterate on structure:

prd-parser parse docs/prd.md --save-json iter1.json --dry-run
# Review iter1.json, note issues
prd-parser parse docs/prd.md --save-json iter2.json --dry-run
# Compare, pick the better one
prd-parser parse --from-json iter2.json

Use --validate to run a final review that checks for gaps in the generated plan:

prd-parser parse ./prd.md --validate

This asks the LLM to review the complete plan and identify:

• Missing setup/initialization tasks
• Backend without UI to test it
• Dependencies not installed
• Acceptance criteria that can't be verified
• Tasks in wrong order

Example output:

✓ Plan validation passed - no gaps found

or

⚠ Plan validation found gaps:
  • No task to install dependencies after adding @clerk/nextjs
  • Auth API built but no login page to test it

By default, prd-parser runs an automatic review pass after generation that checks for and fixes structural issues:

• Missing "Project Foundation" epic as Epic 1 (setup should come first)
• Feature epics not depending on Epic 1 (all work depends on setup)
• Missing setup tasks in foundation epic
• Incorrect dependency chains (setup → backend → frontend)

# Review is on by default
prd-parser parse ./prd.md

# See: "Reviewing structure..."
# See: "✓ Review fixed issues: Added Project Foundation epic..."
# Or:  "✓ Review passed - no changes needed"

# Disable if you want raw output
prd-parser parse ./prd.md --no-review

For human-in-the-loop review during generation:

prd-parser parse docs/prd.md --interactive

In interactive mode, you'll review epics after Stage 1 before task generation continues:

=== Stage 1 Complete: 4 Epics Generated ===

Proposed Epics:
  1. Project Foundation (depends on: none)
      Initialize Next.js, Convex, Clerk setup
  2. Voice Infrastructure (depends on: 1)
      Telnyx phone system integration
  3. AI Conversations (depends on: 1)
      LFM 2.5 integration for call handling
  4. CRM Integration (depends on: 1)
      Follow Up Boss sync

[Enter] continue, [e] edit in $EDITOR, [r] regenerate, [a] add epic:

Options:

• Enter - Accept epics and continue to task generation
• e - Open epics in your $EDITOR for manual editing
• r - Regenerate epics from scratch
• a - Add a new epic

Interactive mode skips the automatic review pass since you are the reviewer.

For full manual control over the generated structure:

Step 1: Generate Draft

prd-parser parse docs/prd.md --save-json draft.json --dry-run

Step 2: Review and Edit

Open draft.json in your editor. You can:

• Reorder epics (change array order)
• Add/remove epics, tasks, or subtasks
• Fix dependencies
• Adjust priorities and estimates

Step 3: Create from Edited Draft

prd-parser parse --from-json draft.json

The PRD file argument is optional when using --from-json.

Auto-Recovery: If creation fails mid-way, prd-parser saves a checkpoint to /tmp/prd-parser-checkpoint.json. Retry with:

prd-parser parse --from-json /tmp/prd-parser-checkpoint.json

After parsing, you may find issues that are misaligned with your product vision. The refine command lets you correct an issue and automatically propagate fixes to related issues.

# Correct an epic that went off-track
prd-parser refine test-e6 --feedback "RealHerd is voice-first lead intelligence, not a CRM with pipeline management"

# Preview changes without applying
prd-parser refine test-e3t2 --feedback "Should use OpenRouter, not direct OpenAI" --dry-run

# Include PRD for better context
prd-parser refine test-e6 --feedback "Focus on conversation insights" --prd docs/prd.md

1. Analyze: LLM identifies wrong concepts in the target issue (e.g., "pipeline tracking", "deal stages")
2. Correct: Generates corrected version with right concepts ("conversation insights", "activity visibility")
3. Scan: Searches ALL issues (across all epics) for the same wrong concepts
4. Propagate: Regenerates affected issues with correction context
5. Update: Applies changes via bd update

$ prd-parser refine test-e6 --feedback "RealHerd is voice-first, not CRM"

Loading issue test-e6...
  Found: Brokerage Dashboard & Reporting

Analyzing misalignment...

Identified misalignment:
  - pipeline tracking
  - deal management
  - contract stages

Corrected version:
  Title: Agent Activity Dashboard & Conversation Insights
  Description: Real-time visibility into agent conversations...

Scanning for affected issues...
  Found 3 children
  Found 2 issues with similar misalignment

--- Changes to apply ---
Target: test-e6
  + test-e6t3: Pipeline Overview Component
  + test-e6t4: Deal Tracking Interface
  + test-e3t5: CRM Pipeline Sync

Applying corrections...
  ✓ Updated test-e6
  ✓ Updated test-e6t3
  ✓ Updated test-e6t4
  ✓ Updated test-e3t5

--- Summary ---
Updated: 1 target + 4 related issues

prd-parser auto-detects installed LLM CLIs - no API keys needed:

# If you have Claude Code installed, it just works
prd-parser parse ./prd.md

# If you have Codex installed, it just works
prd-parser parse ./prd.md

1. Claude Code CLI (claude) - Preferred, already authenticated
2. Codex CLI (codex) - Already authenticated
3. Anthropic API - Fallback if ANTHROPIC_API_KEY is set

# Force specific provider
prd-parser parse ./prd.md --llm claude-cli
prd-parser parse ./prd.md --llm codex-cli
prd-parser parse ./prd.md --llm anthropic-api

# Specify model
prd-parser parse ./prd.md --llm claude-cli --model claude-sonnet-4-20250514
prd-parser parse ./prd.md --llm codex-cli --model o3

Creates issues directly in the current beads-initialized project:

bd init --prefix myproject
prd-parser parse ./prd.md --output beads
bd list  # See created issues

Export to JSON for inspection or custom processing:

# Write to file
prd-parser parse ./prd.md --output json --output-path tasks.json

# Write to stdout (pipe to other tools)
prd-parser parse ./prd.md --output json | jq '.epics[0].tasks'

prd-parser isn't just a prompt wrapper. It uses Go structs as guardrails to enforce valid output:

type Epic struct {
    TempID             string              `json:"temp_id"`
    Title              string              `json:"title"`
    Description        string              `json:"description"`
    Context            interface{}         `json:"context"`
    AcceptanceCriteria []string            `json:"acceptance_criteria"`
    Testing            TestingRequirements `json:"testing"`
    Tasks              []Task              `json:"tasks"`
    DependsOn          []string            `json:"depends_on"`
}

type TestingRequirements struct {
    UnitTests        *string `json:"unit_tests,omitempty"`
    IntegrationTests *string `json:"integration_tests,omitempty"`
    TypeTests        *string `json:"type_tests,omitempty"`
    E2ETests         *string `json:"e2e_tests,omitempty"`
}

The LLM MUST produce output that matches these structs. Missing required fields? Validation fails. Wrong types? Parse fails. This ensures every PRD produces consistent, complete issue structures.

prd-parser/
├── cmd/                    # CLI commands (Cobra)
│   └── parse.go           # Main parse command
├── internal/
│   ├── core/              # Core types and orchestration
│   │   ├── types.go       # Hierarchical structs (guardrails)
│   │   ├── prompts.go     # Single-shot system/user prompts
│   │   ├── stage_prompts.go # Multi-stage prompts (Stages 1-3)
│   │   ├── parser.go      # Single-shot LLM → Output orchestration
│   │   ├── multistage.go  # Multi-stage parallel parser
│   │   └── validate.go    # Validation pass logic
│   ├── llm/               # LLM adapters
│   │   ├── adapter.go     # Interface definition
│   │   ├── claude_cli.go  # Claude Code CLI adapter
│   │   ├── codex_cli.go   # Codex CLI adapter
│   │   ├── anthropic_api.go # API fallback
│   │   ├── detector.go    # Auto-detection logic
│   │   └── multistage_generator.go # Multi-stage LLM calls
│   └── output/            # Output adapters
│       ├── adapter.go     # Interface definition
│       ├── beads.go       # beads issue tracker
│       └── json.go        # JSON file output
└── tests/                 # Unit tests

type Adapter interface {
    Name() string
    IsAvailable() bool
    Generate(ctx context.Context, systemPrompt, userPrompt string) (*core.ParseResponse, error)
}

type Adapter interface {
    Name() string
    IsAvailable() (bool, error)
    CreateItems(response *core.ParseResponse, config Config) (*CreateResult, error)
}

• beads - Git-backed issue tracker for AI-driven development
• Claude Code - Claude's official CLI with beads integration

MIT