prd-parser 0.2.1 → 0.3.1

package/README.md

@@ -117,6 +117,8 @@ task operations without context-switching to a GUI.
 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**:
 
 ```bash
@@ -230,6 +232,9 @@ Issues are linked with proper blocking relationships:
 ### Parse Options
 
 ```bash
+# 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
 
@@ -242,8 +247,12 @@ prd-parser parse ./prd.md --testing comprehensive  # or minimal, standard
 # Preview without creating (dry run)
 prd-parser parse ./prd.md --dry-run
 
-# Include/exclude sections in issue descriptions
-prd-parser parse ./prd.md --include-context --include-testing
+# 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
 ```
 
 ### Full Options
@@ -257,17 +266,20 @@ prd-parser parse ./prd.md --include-context --include-testing
 | `--testing` | | comprehensive | Testing level (minimal/standard/comprehensive) |
 | `--llm` | `-l` | auto | LLM provider (auto/claude-cli/codex-cli/anthropic-api) |
 | `--model` | `-m` | | Model to use (provider-specific) |
-| `--multi-stage` | | | Force multi-stage parsing |
-| `--single-shot` | | | Force single-shot parsing |
+| `--multi-stage` | | false | Force multi-stage parsing |
+| `--single-shot` | | false | Force single-shot parsing |
 | `--smart-threshold` | | 300 | Line count for auto multi-stage (0 to disable) |
+| `--full-context` | | **true** | Pass PRD to all stages (use `=false` to disable) |
 | `--validate` | | false | Run validation pass to check for gaps |
+| `--no-review` | | false | Disable automatic LLM review pass (review ON by default) |
+| `--interactive` | | false | Human-in-the-loop mode (review epics before task generation) |
 | `--subtask-model` | | | Model for subtasks in multi-stage (can be faster/cheaper) |
 | `--output` | `-o` | beads | Output adapter (beads/json) |
 | `--output-path` | | | Output path for JSON adapter |
-| `--working-dir` | `-w` | . | Working directory for beads |
 | `--dry-run` | | false | Preview without creating items |
-| `--include-context` | | true | Include context in descriptions |
-| `--include-testing` | | true | Include testing requirements |
+| `--from-json` | | | Resume from saved JSON checkpoint (skip LLM) |
+| `--save-json` | | | Save generated JSON to file (for resume) |
+| `--config` | | | Config file path (default: .prd-parser.yaml) |
 
 ### Smart Parsing (Default Behavior)
 
@@ -278,6 +290,96 @@ prd-parser automatically chooses the best parsing strategy based on PRD size:
 
 Override with `--single-shot` or `--multi-stage` flags, or adjust threshold with `--smart-threshold`.
 
+### Full Context Mode (Default)
+
+Full context mode is **enabled by default**. Every stage gets the original PRD as their "north star":
+
+```bash
+prd-parser parse docs/prd.md  # full context is on by default
+```
+
+To disable (not recommended):
+```bash
+prd-parser parse docs/prd.md --full-context=false
+```
+
+**Why this matters:**
+
+| Mode | Stage 1 (Epics) | Stage 2 (Tasks) | Stage 3 (Subtasks) |
+|------|----------------|-----------------|-------------------|
+| Default | Full PRD | Epic summary only | Task summary only |
+| `--full-context` | Full PRD | Epic + **PRD** | Task + **PRD** |
+
+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):
+
+| Metric | Default | Full Context |
+|--------|---------|--------------|
+| Epics | 11 | 8 |
+| Tasks | 65 | 49 |
+| Subtasks | 264 | 202 |
+
+Fewer items with full context = less redundancy, more focused on actual requirements.
+
+### Common Flag Combinations
+
+**Standard parse (full context on by default):**
+```bash
+prd-parser parse docs/prd.md
+```
+Every stage sees the PRD. Best for accuracy and coherence.
+
+**Preview before committing:**
+```bash
+prd-parser parse docs/prd.md --dry-run
+```
+See what would be created without actually creating issues.
+
+**Save checkpoint for manual review:**
+```bash
+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:**
+```bash
+prd-parser parse docs/prd.md --interactive
+```
+Review and edit epics before task generation.
+
+**Quick parse for small PRDs:**
+```bash
+prd-parser parse docs/prd.md --single-shot
+```
+Faster single LLM call. Works well for PRDs under 300 lines.
+
+**Cost-optimized for large PRDs:**
+```bash
+prd-parser parse docs/prd.md --subtask-model claude-sonnet-4-20250514
+```
+Use Opus for epics/tasks, Sonnet for subtasks (cheaper, still good quality).
+
+**Maximum validation:**
+```bash
+prd-parser parse docs/prd.md --validate
+```
+Full context + validation pass to catch gaps.
+
+**Debug/iterate on structure:**
+```bash
+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
+```
+
 ### Validation Pass
 
 Use `--validate` to run a final review that checks for gaps in the generated plan:
@@ -304,6 +406,164 @@ or
   • Auth API built but no login page to test it
 ```
 
+### Review Pass (Default)
+
+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)
+
+```bash
+# 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
+```
+
+### Interactive Mode
+
+For human-in-the-loop review during generation:
+
+```bash
+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.
+
+### Checkpoint Workflow (Manual Review)
+
+For full manual control over the generated structure:
+
+**Step 1: Generate Draft**
+```bash
+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**
+```bash
+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:
+```bash
+prd-parser parse --from-json /tmp/prd-parser-checkpoint.json
+```
+
+## Refining Issues After Generation
+
+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.
+
+### Basic Usage
+
+```bash
+# 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
+```
+
+### How It Works
+
+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`
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--feedback`, `-f` | required | What's wrong and how to fix it |
+| `--cascade` | true | Also update children of target issue |
+| `--scan-all` | true | Scan all issues for same misalignment |
+| `--dry-run` | false | Preview changes without applying |
+| `--prd` | | Path to PRD file for context |
+
+### Example Output
+
+```
+$ 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
+```
+
 ## LLM Providers
 
 ### Zero-Config (Recommended)
@@ -396,14 +656,18 @@ prd-parser/
 ├── internal/
 │   ├── core/              # Core types and orchestration
 │   │   ├── types.go       # Hierarchical structs (guardrails)
-│   │   ├── prompts.go     # Embedded system/user prompts
-│   │   └── parser.go      # LLM → Output orchestration
+│   │   ├── 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
+│   │   ├── detector.go    # Auto-detection logic
+│   │   └── multistage_generator.go # Multi-stage LLM calls
 │   └── output/            # Output adapters
 │       ├── adapter.go     # Interface definition
 │       ├── beads.go       # beads issue tracker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prd-parser",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Turn your PRD into a ready-to-work beads project in one command",
   "keywords": [
     "prd",