docs: improve markdown PRD to Beads workflow documentation#51
docs: improve markdown PRD to Beads workflow documentation#51artile wants to merge 2 commits intosubsy:mainfrom
Conversation
Improve Developer Experience for converting markdown PRDs to Beads issues: README changes: - Add "From PRD to Beads: Next Steps" section with clear conversion workflow - Update "Getting Started" to show separate paths for JSON and Beads - Add troubleshooting entry for "PRD file is not valid JSON" error - Clarify that --prd flag expects JSON, not markdown Interactive console improvements: - Enhance Beads detection to check both .beads directory AND bd CLI - Show unavailable options with helpful reasons - Add tip message when Beads is available with epic ID guidance This fixes the common confusion where users try to run "ralph-tui run --prd file.md" with a markdown PRD and don't know how to convert it for Beads. Co-Authored-By: Claude <noreply@anthropic.com>
|
@artile is attempting to deploy a commit to the plgeek Team on Vercel. A member of the Team first needs to authorize it. |
WalkthroughThe README is substantially restructured and condensed; the TUI component Changes
Sequence Diagram(s)sequenceDiagram
participant Component as PrdChatApp Component
participant AsyncFn as getTrackerOptions()
participant Probe as isBdAvailable()
participant Proc as Child Process
participant State as Component State
Component->>AsyncFn: onMount call getTrackerOptions(cwd)
AsyncFn->>Probe: probe for bd CLI
Probe->>Proc: spawn bd probe command
Proc-->>Probe: probe result (exit/code/output)
Probe-->>AsyncFn: return beadsAvailable boolean
AsyncFn->>AsyncFn: assemble TrackerOption[] (set unavailableReason if needed)
AsyncFn-->>Component: resolve TrackerOption[]
Component->>State: set trackerOptions
Component->>Component: render UI with conditional help/explanations
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. Comment |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 705-708: Add a language specifier to the fenced code block
containing the error output so it reads ```text instead of ```, e.g., change the
code fence that wraps "Configuration errors: - PRD file is not valid JSON:
/path/to/my-prd.md" to start with ```text to enable proper syntax highlighting
and accessibility.
In `@src/tui/components/PrdChatApp.tsx`:
- Around line 216-223: The PRD detection can race with the async trackerOptions
load causing an empty trackerOptions when handlePrdDetected builds the message;
to fix, have handlePrdDetected explicitly await getTrackerOptions(cwd) (or use
cached/set state if already loaded) before using trackerOptions, falling back to
the freshly loaded options if state is still empty, and only proceed to
build/send the review message after those options are resolved; update
references in PrdChatApp to use the awaited result (or a helper like
ensureTrackerOptions) instead of relying solely on the mount useEffect-populated
trackerOptions state (also apply same change where handlePrdDetected logic
repeats around lines ~287-296).
🧹 Nitpick comments (1)
src/tui/components/PrdChatApp.tsx (1)
84-104: Potential double resolution in timeout handler.When the timeout fires,
proc.kill()is called followed byresolve(false). However, killing the process will also trigger thecloseevent, which callsresolve(code === 0). Although subsequentresolve()calls are no-ops, this is a code smell. Consider tracking resolution state or removing the redundantresolve(false)afterkill().Proposed fix
async function isBdAvailable(): Promise<boolean> { return new Promise((resolve) => { + let resolved = false; + const safeResolve = (value: boolean) => { + if (!resolved) { + resolved = true; + resolve(value); + } + }; + const proc = spawn('bd', ['--version'], { stdio: ['ignore', 'pipe', 'pipe'], }); proc.on('close', (code) => { - resolve(code === 0); + safeResolve(code === 0); }); proc.on('error', () => { - resolve(false); + safeResolve(false); }); // Timeout after 2 seconds setTimeout(() => { proc.kill(); - resolve(false); + safeResolve(false); }, 2000); }); }
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.mdsrc/tui/components/PrdChatApp.tsx
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{js,ts,jsx,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Start all code files with a file-level JSDoc comment section explaining the file's purpose, prefixed with 'ABOUTME: '
Files:
src/tui/components/PrdChatApp.tsx
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Start all code files with a file-level JSDoc comment section explaining the file's purpose, prefixed with "ABOUTME: "
Files:
src/tui/components/PrdChatApp.tsx
🪛 markdownlint-cli2 (0.18.1)
README.md
705-705: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
README.md (2)
166-185: Clear documentation for PRD-to-Beads workflow.The updated "Getting Started" section and new "From PRD to Beads: Next Steps" subsection effectively clarify the distinction between JSON and Beads paths. The step-by-step instructions for converting markdown PRDs to Beads issues and running with epic IDs address the user confusion mentioned in the PR objectives.
Also applies to: 273-303
702-730: Helpful troubleshooting entry for common error.The new troubleshooting section for "PRD file is not valid JSON" provides clear solutions for both JSON and Beads workflows, directly addressing the user confusion when running
ralph-tui run --prd file.mdwith a markdown file.src/tui/components/PrdChatApp.tsx (3)
1-5: ABOUTME comment present and well-formatted.The file-level JSDoc comment correctly describes the component's purpose with the required "ABOUTME:" prefix. As per coding guidelines, this is correctly implemented.
109-134: BD availability logic is well-structured.The
getTrackerOptionsfunction correctly checks both the.beadsdirectory existence and thebdCLI availability before marking Beads as available. TheunavailableReasonprovides clear guidance for users on how to resolve availability issues.
298-308: Helpful tip for Beads users.The conditional
extraHelpmessage that appears when Beads is available provides useful guidance about the epic ID workflow, aligning well with the documentation updates in README.md.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
README.md
Outdated
| ``` | ||
| Configuration errors: | ||
| - PRD file is not valid JSON: /path/to/my-prd.md | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The error output code block is missing a language identifier. Adding one improves syntax highlighting and accessibility.
Proposed fix
-```
+```text
Configuration errors:
- PRD file is not valid JSON: /path/to/my-prd.md</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
705-705: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@README.md` around lines 705 - 708, Add a language specifier to the fenced
code block containing the error output so it reads ```text instead of ```, e.g.,
change the code fence that wraps "Configuration errors: - PRD file is not valid
JSON: /path/to/my-prd.md" to start with ```text to enable proper syntax
highlighting and accessibility.
| // Load tracker options on mount | ||
| useEffect(() => { | ||
| void getTrackerOptions(cwd).then((options) => { | ||
| if (isMountedRef.current) { | ||
| setTrackerOptions(options); | ||
| } | ||
| }); | ||
| }, [cwd]); |
There was a problem hiding this comment.
Potential race condition: trackerOptions may be empty when PRD is detected.
The trackerOptions state is loaded asynchronously on mount, but handlePrdDetected uses it directly. If the BD availability check is slow and the user completes the PRD chat quickly, trackerOptions could still be an empty array when building the review message, resulting in no options being displayed.
Consider awaiting the tracker options or providing a fallback.
Proposed fix - await options in handlePrdDetected
const handlePrdDetected = async (content: string, name: string) => {
try {
const fullOutputDir = join(cwd, outputDir);
// Ensure output directory exists
try {
await access(fullOutputDir);
} catch {
await mkdir(fullOutputDir, { recursive: true });
}
// Generate filename
const slug = slugify(name);
const filename = `prd-${slug}.md`;
const filepath = join(fullOutputDir, filename);
// Write the file
await writeFile(filepath, content, 'utf-8');
// Update state for review phase
if (isMountedRef.current) {
setPrdContent(content);
setPrdPath(filepath);
setFeatureName(name);
setPhase('review');
+ // Ensure tracker options are loaded
+ const options = trackerOptions.length > 0
+ ? trackerOptions
+ : await getTrackerOptions(cwd);
+
// Build tracker options text with unavailable reasons
- const optionsText = trackerOptions
+ const optionsText = options
.map((t) => {Also applies to: 287-296
🤖 Prompt for AI Agents
In `@src/tui/components/PrdChatApp.tsx` around lines 216 - 223, The PRD detection
can race with the async trackerOptions load causing an empty trackerOptions when
handlePrdDetected builds the message; to fix, have handlePrdDetected explicitly
await getTrackerOptions(cwd) (or use cached/set state if already loaded) before
using trackerOptions, falling back to the freshly loaded options if state is
still empty, and only proceed to build/send the review message after those
options are resolved; update references in PrdChatApp to use the awaited result
(or a helper like ensureTrackerOptions) instead of relying solely on the mount
useEffect-populated trackerOptions state (also apply same change where
handlePrdDetected logic repeats around lines ~287-296).
|
@artile thanks for the contribution! I really like the intent here, but think you've based this on an old branch, Yesterday most of the heavy readme moved to docs (ralph-tui.com/docs). Do you want to take a stab at updating this PR to remove the README changes and update the docs directly? |
The documentation has been moved to ralph-tui.com website. Reverting README changes to match main branch. Code changes in PrdChatApp.tsx remain - Beads detection improvements.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Line 209: Replace the community fork link for OpenTUI in the README entry "-
[OpenTUI](https://github.com/anomalyco/opentui) - Terminal UI framework" with
the official repository URL; update the markdown link target so the list item
referencing "OpenTUI" points to "https://github.com/sst/opentui" instead of
"https://github.com/anomalyco/opentui".
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md
🧰 Additional context used
🪛 LanguageTool
README.md
[locale-violation] ~220-~220: License must be spelled with a “c” when used as a noun in British English. Use “licence”.
Context: ...cept](https://ghuntley.com/ralph/). ## License MIT License - see LICENSE f...
(LICENCE_LICENSE_NOUN_SINGULAR)
[locale-violation] ~222-~222: License must be spelled with a “c” when used as a noun in British English. Use “licence”.
Context: .../ghuntley.com/ralph/). ## License MIT License - see LICENSE for details.
(LICENCE_LICENSE_NOUN_SINGULAR)
[locale-violation] ~222-~222: LICENSE must be spelled with a “c” when used as a noun in British English. Use “licence”.
Context: ...alph/). ## License MIT License - see LICENSE for details.
(LICENCE_LICENSE_NOUN_SINGULAR)
🔇 Additional comments (2)
README.md (2)
32-43: All external documentation links are live and accessible. No action required.
1-222: No changes needed—the README state is correct.The commit correctly reverts expanded documentation to match the main branch's consolidated state. The message "revert: remove README changes (docs moved to external site)" means the commit removes unnecessary README expansions from a feature branch and returns to main's intended state, which points users to ralph-tui.com for comprehensive documentation whilst keeping essential reference content in the README itself.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
|
|
||
| - [Bun](https://bun.sh) - JavaScript runtime | ||
| - [OpenTUI](https://github.com/AshMartian/opentui) - Terminal UI framework | ||
| - [OpenTUI](https://github.com/anomalyco/opentui) - Terminal UI framework |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
OpenTUI GitHub anomalyco opentui repository
💡 Result:
There’s an OpenTUI repository under anomalyco on GitHub (anomalyco/opentui) that hosts releases (latest listed v0.1.72). It appears to be a community fork/package of the OpenTUI project; the primary/official OpenTUI repo is sst/opentui. Sources: [anomalyco release listing][1], repo summary page [2], and the official sst/opentui GitHub README [3].
Sources:
- anomalyco/opentui release v0.1.72 — NewReleases. [1]
- anomalyco/opentui repository details — GitGenius. [2]
- sst/opentui (official OpenTUI) — GitHub README. [3]
Link to official OpenTUI repository instead of community fork.
The README links to anomalyco/opentui, which is a community fork/package of OpenTUI. The official and primary OpenTUI repository is sst/opentui. Update the link to point to the authoritative source: https://github.com/sst/opentui.
🤖 Prompt for AI Agents
In `@README.md` at line 209, Replace the community fork link for OpenTUI in the
README entry "- [OpenTUI](https://github.com/anomalyco/opentui) - Terminal UI
framework" with the official repository URL; update the markdown link target so
the list item referencing "OpenTUI" points to "https://github.com/sst/opentui"
instead of "https://github.com/anomalyco/opentui".
|
@artile this is now quite diverged from the current codebase so Im going to work on implementing these things in a separate branch |
2 participants
Summary
Improve Developer Experience for converting markdown PRDs to Beads issues.
README changes:
Interactive console improvements:
Problem Solved
Fixes the common confusion where users try to run ralph-tui run --prd file.md with a markdown PRD and don't know how to convert it for Beads.
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.