prd-parser 0.3.0 → 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
 
@@ -244,7 +249,10 @@ 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 ./prd.md --from-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
@@ -261,6 +269,7 @@ prd-parser parse ./prd.md --from-json checkpoint.json
 | `--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) |
@@ -281,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:

package/package.json

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