docs: Recommend .md extension for PRD files

[bjcoombs]

Summary

Updates documentation to recommend using .md (Markdown) extension for PRD files instead of .txt, providing better developer experience through syntax highlighting and proper rendering in editors.

Changes Made

PRD Format Recommendation (assets/AGENTS.md)

• Updated all PRD file references from .txt to .md:
  • Command examples: task-master parse-prd .taskmaster/docs/prd.md
  • Directory structure diagrams
  • Workflow examples
• Added prominent note explaining benefits of .md format:
  • Markdown syntax highlighting in editors
  • Proper rendering when previewing in VS Code, GitHub, etc.
  • Better collaboration through formatted documentation
• Clarified that both extensions work, but .md is recommended

Changeset Guidelines (CLAUDE.md)

• Updated changeset requirement: "Add a changeset for code changes (not needed for docs-only PRs)"
• Previously said "Every PR requires a changeset" which was too broad

Why .md Over .txt?

While both formats work with Task Master's parse-prd command, .md provides:

1. Better editing experience: Syntax highlighting for headers, lists, code blocks
2. Preview rendering: Proper formatting in VS Code, GitHub, and other tools
3. Team collaboration: Easier to read and review formatted PRDs
4. No drawbacks: Task Master's parser handles both formats identically

Related Issues

Related to discussion in #1180 (though this PR no longer addresses the .claude configuration question from that issue)

---

Note: This PR originally included Claude Code .claude configuration documentation, but that was removed based on feedback that it would become stale when upgrading to ai-sdk-provider-claude-code v2.0.0+.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4aef5eb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@bjcoombs has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 21 minutes and 27 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 8cf5ef0 and 4aef5eb.

📒 Files selected for processing (2)

• apps/docs/capabilities/rpg-method.mdx (3 hunks)
• apps/docs/getting-started/quick-start/prd-quick.mdx (4 hunks)

Walkthrough

Two documentation files updated: assets/AGENTS.md changes PRD file extension references from .txt to .md with added formatting recommendations, and CLAUDE.md adds a changeset guideline for code changes.

Changes

Cohort / File(s)	Summary
PRD extension migration assets/AGENTS.md	Replace all references to PRD documents from .txt to .md extension, add PRD File Format note recommending .md for editor support and collaboration, update Claude Code integration examples to use prd.md and example_prd.md
Changeset guidelines CLAUDE.md	Add bold guideline under Changeset Guidelines stating "Add a changeset for code changes - Run npx changeset after making code changes (not needed for docs-only PRs)" and re-add user-facing explanation about changeset impact

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• Documentation-only changes with no code modifications
• Straightforward extension name updates (txt → md) and guideline additions
• No logic, behavior, or API changes

Suggested reviewers

• eyaltoledano
• Crunchyman-ralph

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR successfully addresses issue #1180 by adding comprehensive documentation on Claude Code configuration behavior, explaining precedence between global and project-level settings, and providing practical examples as requested.
Out of Scope Changes check	✅ Passed	Changes are in-scope: AGENTS.md updates align with the .md recommendation goal, and CLAUDE.md changeset guideline addition is a minor clarification aligned with documentation objectives; no unrelated functional changes present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'docs: Recommend .md extension for PRD files' accurately reflects one of the two main changes in this PR, but it omits the significant Claude Code configuration documentation (the larger change per PR objectives).

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[Crunchyman-ralph]

lgtm, just please address my single comment, and if you want to go the extra mile, add the equivalent doc changes or add the missing docs on apps/docs please

[Crunchyman-ralph]

When we make improvements to the docs, we don't add it in the changeset since its not very user-facing or feature oriented, its just docs hehe.

Remove this file

[ben-vargas]

If this PR is based on my old comments/analysis of how claude-code-sdk used to work, it may no longer be accurate and you guys will want to make sure documentation is written to how the newer claude-agent-sdk actually works. Anthropic's release of claude-agent-sdk was a breaking change and the significantly changed functionality (no default system prompt, new append system prompt, nothing loading from default cli unless settingSources is passed).

I see the comment referenced was from Sep 3, but @anthropic-ai/claude-agent-sdk was released Sep 29 and became a dependency (adopted) in v2.0.0 ai-sdk-provider-claude-code package.

Timeline:

  | Date          | Package                               | Event                                                               |
  |---------------|---------------------------------------|---------------------------------------------------------------------|
  | Sept 18, 2025 | ai-sdk-provider-claude-code v1.1.4    | Last version using @anthropic-ai/claude-code@1.0.94                 |
  | Sept 29, 2025 | @anthropic-ai/claude-agent-sdk v0.1.0 | Claude Agent SDK first released with breaking changes               |
  | Oct 2, 2025   | ai-sdk-provider-claude-code v1.2.0    | Still using old SDK (@anthropic-ai/claude-code@^1.0.128)            |
  | Oct 2, 2025   | ai-sdk-provider-claude-code v2.0.0    | Migrated to @anthropic-ai/claude-agent-sdk@^0.1.0                   |
  | Oct 16, 2025  | ai-sdk-provider-claude-code v2.0.3    | Updated to @anthropic-ai/claude-agent-sdk@^0.1.20                   |
  | Oct 21, 2025  | ai-sdk-provider-claude-code v2.1.0    | Current version, still using @anthropic-ai/claude-agent-sdk@^0.1.20 |

[ben-vargas]

Looking at the package.json it looks like 1.1.4 is being used, so probably okay to base the documentation on the older comments, just be aware of the significant changes in future versions of ai-sdk-provider-claude-code in 2.0.0+ when it migrates to using @anthropic-ai/claude-agent-sdk

[bjcoombs]

Updates Based on Feedback

Thanks for the review! I've simplified this PR based on the feedback:

Removed

1. Changeset - Not needed for docs-only PRs (updated CLAUDE.md to clarify this)
2. Claude Code .claude configuration documentation - Per @ben-vargas's feedback, this documentation would become stale soon when upgrading to ai-sdk-provider-claude-code v2.0.0+ which uses @anthropic-ai/claude-agent-sdk (released Sept 29) instead of the current @anthropic-ai/claude-code dependency

Updated

• CLAUDE.md changeset guidelines: Clarified that changesets are only needed for code changes, not docs-only PRs

Kept

• PRD .md extension recommendation: All examples now use .md instead of .txt
• Added clear explanation of benefits (syntax highlighting, proper rendering in editors, better collaboration)
• Updated directory structure diagrams and workflow examples

This keeps the PR focused on the non-controversial PRD format improvement.

Ready for review! 🚀

[bjcoombs]

✅ @Crunchyman-ralph - Added the equivalent documentation updates to apps/docs:

• apps/docs/getting-started/quick-start/prd-quick.mdx: Updated all PRD references to use .md extension, added explanation of benefits
• apps/docs/capabilities/rpg-method.mdx: Updated RPG template references and command examples

All user-facing documentation now consistently recommends .md format for PRD files!

[Crunchyman-ralph]

sure, we can recommend .md

[Crunchyman-ralph]

@bjcoombs we already upgraded to claude code 2.0 (its in the next branch, so make sure this PR reflects that

[bjcoombs]

@Crunchyman-ralph I reverted the summary of @ben-vargas earlier comments around claud api due to the upgrade, so this is just about .md files now..

I've updated the pr description to reflect that..

[Crunchyman-ralph]

lgtm