feat: add PRD context support to beads and JSON trackers by subsy · Pull Request #168 · subsy/ralph-tui

subsy · 2026-01-20T14:17:39Z

Summary

Beads tracker: Add getPrdContext() method to read PRD content from epic's external_ref field
JSON tracker: Populate metadata.sourcePrd during conversion (fixes convert --to json does not set metadata.sourcePrd field #160)
Convert command: Pass PRD path to both beads and JSON conversion, adding --external-ref to all created tasks

Changes

Beads Tracker (`src/plugins/trackers/builtin/beads/index.ts`)

Add external_ref?: string to BeadJson interface
Implement getPrdContext() method that:
- Reads epic's external_ref field (format: prd:./path/to/file.md)
- Resolves relative paths against working directory
- Returns PRD content with completion stats (completedCount/totalCount)
BeadsBvTrackerPlugin inherits this automatically

JSON Tracker (`src/prd/generator.ts`)

Add optional sourcePrd parameter to convertToPrdJson()
Include sourcePrd in metadata when provided

Convert Command (`src/commands/convert.ts`)

Beads format: Add --external-ref prd:<path> to both epic and child task creation
JSON format: Compute relative path from output JSON to input PRD, pass to convertToPrdJson()

Why This Matters

Previously, agents only received user story title and acceptance criteria from the tracker. With this change, agents can access the full PRD content including:

Goals and Non-Goals
Technical Considerations
Functional Requirements
Quality Gates
Success Metrics

This enables more informed implementation decisions.

Test plan

Run ralph-tui convert --to beads ./tasks/test.md and verify epic + tasks have External: prd:./tasks/test.md
Run ralph-tui convert --to json ./tasks/test.md -o ./tasks/prd.json and verify metadata.sourcePrd is set
Verify getPrdContext() returns content when epic has external_ref
Verify getPrdContext() returns null gracefully when no external_ref

Summary by CodeRabbit

New Features
- Optionally link source PRD files to Beads and JSON exports for improved traceability.
- Expose PRD context (name, description, content, progress counts) for linked epics.
Bug Fixes / Improvements
- More robust path handling for source PRD resolution and metadata inclusion.
Tests
- Expanded test coverage for PRD linking, JSON output and PRD-context scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

vercel · 2026-01-20T14:17:44Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
ralph-tui	Ignored		Jan 20, 2026 2:33pm

coderabbitai · 2026-01-20T14:18:15Z

Walkthrough

Conversion flows now propagate an optional PRD source path: JSON output gains metadata.sourcePrd, beads creation can attach prd:<path> external refs, and the Beads tracker can read linked PRD content via a new getPrdContext method.

Changes

Cohort / File(s)	Summary
Convert command & flow `src/commands/convert.ts`	Threaded an optional `prdPath`/`inputPath` through convert, updated signatures for `convertToBeads`, `executeBeadsConversion`, and `executeJsonConversion`; added `relative` import and adjusted path resolution to compute source PRD relative to outputs.
PRD JSON generation `src/prd/generator.ts`	`convertToPrdJson(prd, sourcePrd?)` added; when provided, `metadata.sourcePrd` is included in generated JSON.
Beads tracker plugin `src/plugins/trackers/builtin/beads/index.ts`	Added optional `external_ref?: string` to `BeadJson`; introduced `getPrdContext()` to read `bd show` external_ref `prd:<path>`, resolve and load PRD content, and compute epic child counts. Note: `getPrdContext` implementation appears duplicated.
Tests & mocks `src/plugins/trackers/builtin/beads.test.ts`, `src/prd/generator.test.ts`	Added tests for `getPrdContext` scenarios and for `convertToPrdJson` including sourcePrd handling; added fs and spawn mocks and multi-call spawn responses.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as Convert Command
    participant Path as Path Resolver
    participant Json as PRD Generator
    participant Beads as Beads Executor
    participant Tracker as BeadsTrackerPlugin
    participant FS as File System

    User->>CLI: convert --to json input.md -o out/prd.json
    CLI->>Path: resolve input & output dirs
    Path->>CLI: return resolved paths
    CLI->>Path: compute relative sourcePrd (out -> input.md)
    Path->>CLI: return "../input.md"
    CLI->>Json: convertToPrdJson(prd, sourcePrd="../input.md")
    Json->>FS: write prd.json with metadata.sourcePrd
    FS->>User: prd.json created

    User->>CLI: convert --to beads input.md
    CLI->>Beads: executeBeadsConversion(..., prdPath="input.md")
    Beads->>Beads: create epic with --external-ref prd:input.md
    Beads->>Beads: create stories with --external-ref prd:input.md

    Tracker->>Beads: bd show <epicId> (reads external_ref)
    Beads->>Tracker: external_ref "prd:./input.md"
    Tracker->>FS: resolve path and read PRD content
    FS->>Tracker: return PRD content
    Tracker->>Tracker: compute completedCount / totalCount and return PRD context

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

feat: prompt engine v2 - templates, preview panel, and UX improvements #128: Related changes to PRD-context handling and propagation of source PRD paths into tracker/template flows.

Poem

🐰 I hopped through paths both near and far,
I nested refs beneath each bead and star,
JSON now whispers where the PRD came from,
Beads can fetch its contents, clear and plumb.
Hooray — a trail of crumbs for every scrum!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarises the main change: adding PRD context support to beads and JSON trackers, which aligns with all file modifications.
Linked Issues check	✅ Passed	The PR successfully addresses issue `#160` by adding sourcePrd to convertToPrdJson() and extending PRD context support across beads tracker and convert command as intended.
Out of Scope Changes check	✅ Passed	All changes are scoped to PRD context support: beads tracker external_ref field, getPrdContext() implementation, JSON metadata sourcePrd parameter, and convert command path handling.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-01-20T14:18:36Z

Codecov Report

❌ Patch coverage is 66.21622% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 40.95%. Comparing base (93408e2) to head (c474c4e).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/plugins/trackers/builtin/beads/index.ts	66.21%	25 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #168      +/-   ##
==========================================
+ Coverage   40.87%   40.95%   +0.07%     
==========================================
  Files          72       72              
  Lines       19912    19994      +82     
==========================================
+ Hits         8140     8188      +48     
- Misses      11772    11806      +34

Files with missing lines	Coverage Δ
src/plugins/trackers/builtin/beads/index.ts	`50.46% <66.21%> (+1.16%)`	⬆️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Beads tracker: - Add `external_ref` field to BeadJson interface - Implement `getPrdContext()` method to read PRD content from epic's external_ref field (format: prd:./path/to/file.md) - Return PRD content with completion stats for template rendering JSON tracker (fixes #160): - Add `sourcePrd` parameter to `convertToPrdJson()` - Populate `metadata.sourcePrd` field during conversion - Compute relative path from JSON output to PRD input Convert command: - Pass PRD path through conversion chain for both formats - Add `--external-ref prd:<path>` to epic AND child task creation - Use relative paths for portability across machines This enables agents to access full PRD context (goals, technical considerations, quality gates) during task execution, not just the user story title and acceptance criteria.

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/plugins/trackers/builtin/beads/index.ts`:
- Around line 724-770: The code parses epicResult.stdout as a single BeadJson
object which causes epic.external_ref, title, and description to be undefined;
instead parse JSON.parse(epicResult.stdout) as an array, extract the first
element (e.g., const [epic] = ...), validate that the array has at least one
element (return null if empty), then use epic.external_ref, epic.title, and
epic.description for the PRD lookup and return payload; update any subsequent
references in this function (the epicResult parsing block around execBd, the
externalRef/ prdPath resolution, and the final return object) to use the
extracted epic element.

src/plugins/trackers/builtin/beads/index.ts

- Add tests for BeadsTrackerPlugin.getPrdContext(): - Returns null when no epicId set - Returns null when epic has no external_ref - Returns null when external_ref doesn't start with prd: - Returns PRD content with completion stats for valid prd: ref - Handles file read failures gracefully - Handles bd show failures gracefully - Supports absolute paths - Add tests for convertToPrdJson(): - Generates valid prd.json without sourcePrd - Includes sourcePrd in metadata when provided - Handles relative and absolute paths - Does not include sourcePrd for empty string - Fix getPrdContext() to parse bd show output as array (bd show --json returns an array with one element)

feat: add PRD context support to beads and JSON trackers

coderabbitai bot reviewed Jan 20, 2026

View reviewed changes

src/plugins/trackers/builtin/beads/index.ts Show resolved Hide resolved

subsy force-pushed the feat/prd-context-support branch from 843f358 to c474c4e Compare January 20, 2026 14:33

subsy merged commit 2f8b65d into main Jan 20, 2026
9 checks passed

subsy deleted the feat/prd-context-support branch January 20, 2026 14:39

This was referenced Jan 21, 2026

feat: beads-rust tracker plugin and improvements #179

Merged

Use br dep list instead of br show for parent-child filtering #230

Merged

Improve beads tracker detection and markdown PRD handling #232

Merged

coderabbitai bot mentioned this pull request Feb 4, 2026

Remove PRD link inclusion from bead conversion #282

Merged

sakaman pushed a commit to sakaman/ralph-tui that referenced this pull request Feb 15, 2026

Merge pull request subsy#168 from subsy/feat/prd-context-support

510703e

feat: add PRD context support to beads and JSON trackers

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add PRD context support to beads and JSON trackers#168

feat: add PRD context support to beads and JSON trackers#168
subsy merged 2 commits intomainfrom
feat/prd-context-support

subsy commented Jan 20, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

Conversation

subsy commented Jan 20, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Beads Tracker (src/plugins/trackers/builtin/beads/index.ts)

JSON Tracker (src/prd/generator.ts)

Convert Command (src/commands/convert.ts)

Why This Matters

Test plan

Summary by CodeRabbit

Uh oh!

vercel bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

codecov bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

subsy commented Jan 20, 2026 •

edited by coderabbitai bot

Loading

Beads Tracker (`src/plugins/trackers/builtin/beads/index.ts`)

JSON Tracker (`src/prd/generator.ts`)

Convert Command (`src/commands/convert.ts`)

vercel bot commented Jan 20, 2026 •

edited

Loading

coderabbitai bot commented Jan 20, 2026 •

edited

Loading

codecov bot commented Jan 20, 2026 •

edited

Loading