Skip to content

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

docs: Recommend .md extension for PRD files (#1397)

Ben Coombsae4fbc03a46f
diff --git a/.taskmaster/templates/example_prd.txt b/.taskmaster/templates/example_prd.md
similarity index 100%
rename from .taskmaster/templates/example_prd.txt
rename to .taskmaster/templates/example_prd.md
diff --git a/.taskmaster/templates/example_prd_rpg.txt b/.taskmaster/templates/example_prd_rpg.md
similarity index 100%
rename from .taskmaster/templates/example_prd_rpg.txt
rename to .taskmaster/templates/example_prd_rpg.md
diff --git a/CLAUDE.md b/CLAUDE.md
index b2001421..38fd00bd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -147,4 +147,5 @@ Apply standard software engineering principles:
## Changeset Guidelines
-- When creating changesets, remember that it's user-facing, meaning we don't have to get into the specifics of the code, but rather mention what the end-user is getting or fixing from this changeset.
+- **Add a changeset for code changes** - Run `npx changeset` after making code changes (not needed for docs-only PRs)
+- When creating changesets, remember that it's user-facing, meaning we don't have to get into the specifics of the code, but rather mention what the end-user is getting or fixing from this changeset
diff --git a/apps/docs/capabilities/rpg-method.mdx b/apps/docs/capabilities/rpg-method.mdx
index 360c5745..0c61855c 100644
--- a/apps/docs/capabilities/rpg-method.mdx
+++ b/apps/docs/capabilities/rpg-method.mdx
@@ -9,14 +9,14 @@ The RPG (Repository Planning Graph) method is an advanced approach to creating P
## When to Use RPG
-Use the RPG template (`example_prd_rpg.txt`) for:
+Use the RPG template (`example_prd_rpg.md`) for:
- **Complex multi-module systems** with intricate dependencies
- **Large-scale codebases** being built from scratch
- **Projects requiring explicit architecture** and clear module boundaries
- **Teams needing dependency visibility** for parallel development
-For simpler features or smaller projects, the standard `example_prd.txt` template may be more appropriate.
+For simpler features or smaller projects, the standard `example_prd.md` template may be more appropriate.
---
@@ -180,7 +180,7 @@ Use a code-context-aware tool to fill out the template:
### Step 2: Parse PRD into Tasks
```bash
-task-master parse-prd .taskmaster/docs/your-prd.txt --research
+task-master parse-prd .taskmaster/docs/your-prd.md --research
```
Task Master will:
@@ -303,10 +303,10 @@ Without test strategy, the AI won't know what to test during implementation.
## Example Workflow
1. **Discuss idea with AI**: Explain your project concept
-2. **Reference RPG template**: Show AI the `example_prd_rpg.txt`
+2. **Reference RPG template**: Show AI the `example_prd_rpg.md`
3. **Co-create PRD**: Work through each section with AI guidance
-4. **Save to docs**: Place in `.taskmaster/docs/your-project.txt`
-5. **Parse PRD**: `task-master parse-prd .taskmaster/docs/your-project.txt --research`
+4. **Save to docs**: Place in `.taskmaster/docs/your-project.md` (use `.md` for better editor support)
+5. **Parse PRD**: `task-master parse-prd .taskmaster/docs/your-project.md --research`
6. **Analyze**: `task-master analyze-complexity --research`
7. **Expand**: `task-master expand --all --research`
8. **Start work**: `task-master next`
diff --git a/apps/docs/getting-started/quick-start/prd-quick.mdx b/apps/docs/getting-started/quick-start/prd-quick.mdx
index 6b38aef3..b1f40c57 100644
--- a/apps/docs/getting-started/quick-start/prd-quick.mdx
+++ b/apps/docs/getting-started/quick-start/prd-quick.mdx
@@ -34,8 +34,10 @@ The more context you give the model, the better the breakdown and results.
<Note>
Two example PRD templates are available in `.taskmaster/templates/`:
-- `example_prd.txt` - Simple template for straightforward projects
-- `example_prd_rpg.txt` - Advanced RPG (Repository Planning Graph) template for complex projects with dependencies
+- `example_prd.md` - Simple template for straightforward projects (`.md` recommended for better editor support)
+- `example_prd_rpg.md` - Advanced RPG (Repository Planning Graph) template for complex projects with dependencies
+
+**Why `.md`?** While both `.txt` and `.md` work, Markdown files provide syntax highlighting, proper rendering in VS Code/GitHub, and better collaboration through formatted documentation.
</Note>
@@ -49,12 +51,12 @@ This approach works great in Cursor, or anywhere you use a chat-based LLM.
### Choosing Between Templates
-**Use `example_prd.txt` when:**
+**Use `example_prd.md` when:**
- Building straightforward features
- Working on smaller projects
- Dependencies are simple and obvious
-**Use `example_prd_rpg.txt` when:**
+**Use `example_prd_rpg.md` when:**
- Building complex systems with multiple modules
- Need explicit dependency management
- Want structured guidance on architecture decisions
@@ -77,8 +79,9 @@ For complex projects, using the RPG template with a code-context-aware ai agent
Place your PRD file in the `.taskmaster/docs` folder in your project.
- You can have **multiple PRDs** per project.
-- Name your PRDs clearly so they’re easy to reference later.
- - Examples: `dashboard_redesign.txt`, `user_onboarding.txt`
+- Name your PRDs clearly so they're easy to reference later.
+ - Examples: `dashboard_redesign.md`, `user_onboarding.md`
+ - Tip: Use `.md` extension for better editor support and syntax highlighting
---
@@ -89,13 +92,13 @@ This is where the Task Master magic begins.
In Cursor's AI chat, instruct the agent to generate tasks from your PRD:
```
-Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at .taskmaster/docs/<prd-name>.txt.
+Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at .taskmaster/docs/<prd-name>.md.
```
The agent will execute the following command which you can alternatively paste into the CLI:
```bash
-task-master parse-prd .taskmaster/docs/<prd-name>.txt
+task-master parse-prd .taskmaster/docs/<prd-name>.md
```
This will:
diff --git a/assets/AGENTS.md b/assets/AGENTS.md
index f063eecf..a6c9f7d3 100644
--- a/assets/AGENTS.md
+++ b/assets/AGENTS.md
@@ -7,7 +7,7 @@
```bash
# Project Setup
task-master init # Initialize Task Master in current project
-task-master parse-prd .taskmaster/docs/prd.txt # Generate tasks from PRD document
+task-master parse-prd .taskmaster/docs/prd.md # Generate tasks from PRD document
task-master models --setup # Configure AI models interactively
# Daily Development Workflow
@@ -41,10 +41,15 @@ task-master generate # Update task markd
- `.taskmaster/tasks/tasks.json` - Main task data file (auto-managed)
- `.taskmaster/config.json` - AI model configuration (use `task-master models` to modify)
-- `.taskmaster/docs/prd.txt` - Product Requirements Document for parsing
+- `.taskmaster/docs/prd.md` - Product Requirements Document for parsing (`.md` extension recommended for better editor support)
- `.taskmaster/tasks/*.txt` - Individual task files (auto-generated from tasks.json)
- `.env` - API keys for CLI usage
+**PRD File Format:** While both `.txt` and `.md` extensions work, **`.md` is recommended** because:
+- Markdown syntax highlighting in editors improves readability
+- Proper rendering when previewing in VS Code, GitHub, or other tools
+- Better collaboration through formatted documentation
+
### Claude Code Integration Files
- `CLAUDE.md` - Auto-loaded context for Claude Code (this file)
@@ -62,11 +67,11 @@ project/
│ │ ├── task-1.md # Individual task files
│ │ └── task-2.md
│ ├── docs/ # Documentation directory
-│ │ ├── prd.txt # Product requirements
+│ │ ├── prd.md # Product requirements (.md recommended)
│ ├── reports/ # Analysis reports directory
│ │ └── task-complexity-report.json
│ ├── templates/ # Template files
-│ │ └── example_prd.txt # Example PRD template
+│ │ └── example_prd.md # Example PRD template (.md recommended)
│ └── config.json # AI models & settings
├── .claude/
│ ├── settings.json # Claude Code configuration
@@ -138,8 +143,8 @@ complexity_report; // = task-master complexity-report
# Initialize Task Master
task-master init
-# Create or obtain PRD, then parse it
-task-master parse-prd .taskmaster/docs/prd.txt
+# Create or obtain PRD, then parse it (use .md extension for better editor support)
+task-master parse-prd .taskmaster/docs/prd.md
# Analyze complexity and expand tasks
task-master analyze-complexity --research