207 lines
6.9 KiB
Markdown
207 lines
6.9 KiB
Markdown
---
|
|
name: roadmap
|
|
description: "When the user invokes /roadmap commands, manage ROADMAP.md as a living development journal. Track milestones, log progress, and maintain a searchable history of what was learned."
|
|
---
|
|
|
|
# Roadmap Skill
|
|
|
|
When the user invokes `/roadmap` commands, you are managing a **living development journal** stored in `ROADMAP.md`. This file serves as both a task list and a chronological record of development progress.
|
|
|
|
## Core Principles
|
|
|
|
1. **ROADMAP.md is the source of truth** - All task definitions, status, and journal entries live here
|
|
2. **Milestones are headings** - Each `### X.Y` heading is a milestone identifier
|
|
3. **Checkboxes track status** - `[ ]` = not started, `[x]` = complete
|
|
4. **Journal entries are indented** - Added as nested list items under milestones
|
|
5. **You modify ROADMAP.md directly** - Use `read`, `edit`, or `write` tools as appropriate
|
|
|
|
## Milestone Identification
|
|
|
|
A milestone is any level-3 heading (`###`) or deeper that starts with a number pattern:
|
|
- Valid: `### 1.1 Analyze Architecture`, `#### 1.2.1 Subtask`
|
|
- Invalid: `### Introduction`, `### Phase 1` (no number)
|
|
|
|
The milestone ID is the number part: `1.1`, `1.2.1`, etc.
|
|
|
|
## Journal Entry Format
|
|
|
|
Journal entries are appended under their milestone as indented list items with these prefixes:
|
|
|
|
```markdown
|
|
- **Journal**: [timestamp] - [message]
|
|
- **Time**: [elapsed minutes]
|
|
- **Blockers**: [what's preventing progress]
|
|
- **Decision**: [rationale for choices]
|
|
- **Tau Notes**: [observations about Tau's capabilities]
|
|
- **Lesson**: [general development learning]
|
|
```
|
|
|
|
Always include a timestamp in `YYYY-MM-DD HH:MM` format for Journal entries.
|
|
|
|
## Commands
|
|
|
|
### `/roadmap` or `/roadmap status`
|
|
Show a compact status summary:
|
|
1. Read `ROADMAP.md`
|
|
2. Count total milestones (level-3+ headings matching number pattern)
|
|
3. Count completed milestones (checkbox is `[x]`)
|
|
4. Calculate percentage: `(completed / total) * 100`
|
|
5. List the next 3 incomplete milestones by ID order
|
|
|
|
Format:
|
|
```
|
|
Roadmap Progress: 2/17 (11.76%)
|
|
Next:
|
|
1.3 Add Configuration File Support
|
|
2.1 Add Type Hints
|
|
2.2 Create Unit Tests
|
|
```
|
|
|
|
### `/roadmap view`
|
|
Display the full contents of `ROADMAP.md` using the `read` tool.
|
|
|
|
### `/roadmap view [milestone-id]`
|
|
1. Find the milestone heading matching `[milestone-id]`
|
|
2. Display that heading and all its content (tasks + journal entries)
|
|
|
|
### `/roadmap next`
|
|
1. Find all milestones with `[ ]` status
|
|
2. Sort by milestone ID (natural sort: 1.1 < 1.2 < 1.10 < 2.1)
|
|
3. Show the first one with its description
|
|
|
|
Format:
|
|
```
|
|
Next milestone: 1.3 Add Configuration File Support
|
|
Description: Use Tau to add TOML-based configuration
|
|
Prompt: "Add support for a ~/.config/peak-monitor.toml configuration file..."
|
|
```
|
|
|
|
### `/roadmap complete [milestone-id]`
|
|
1. Find the milestone with ID `[milestone-id]`
|
|
2. Change its checkbox from `[ ]` to `[x]`
|
|
3. Prompt the user: "Enter journal notes (or 'skip'): "
|
|
4. If user provides text, append it as a Journal entry with timestamp
|
|
5. Use `edit` tool to modify ROADMAP.md
|
|
|
|
### `/roadmap journal [milestone-id] [message]`
|
|
1. Find the milestone with ID `[milestone-id]`
|
|
2. Append a new journal entry under it with current timestamp
|
|
3. Format: `- **Journal**: YYYY-MM-DD HH:MM - [message]`
|
|
4. Use `edit` tool to add the line
|
|
|
|
### `/roadmap start [milestone-id]`
|
|
1. Find the milestone
|
|
2. Record the start time (store in memory for this session)
|
|
3. Reply: "Started milestone [milestone-id]. Timer running..."
|
|
|
|
### `/roadmap stop [milestone-id]`
|
|
1. Calculate elapsed time since start
|
|
2. Append a Time entry: `- **Time**: [minutes]min`
|
|
3. Clear the timer for this milestone
|
|
|
|
### `/roadmap search [query]`
|
|
1. Read ROADMAP.md
|
|
2. Find all journal entries (lines starting with `- **Journal**`, `- **Tau Notes**`, etc.)
|
|
3. Filter entries containing [query] (case-insensitive)
|
|
4. Display matching entries with their milestone ID
|
|
|
|
Format:
|
|
```
|
|
Found 2 matches:
|
|
1.1: 2026-07-11 14:32 - Noticed that GTK initialization needs error handling
|
|
1.3: 2026-07-11 15:01 - Tau successfully added config file support
|
|
```
|
|
|
|
### `/roadmap add [description]`
|
|
1. Find the highest existing milestone ID
|
|
2. Increment it (1.1 -> 1.2, 1.9 -> 1.10, 2.1 -> 2.2)
|
|
3. Append a new milestone at the end of the file:
|
|
```markdown
|
|
|
|
### [new-id] [first line of description]
|
|
- [ ] [full description]
|
|
```
|
|
|
|
### `/roadmap blockers`
|
|
1. Find all milestones with Blockers entries
|
|
2. Display each with its blocker notes
|
|
|
|
Format:
|
|
```
|
|
Blocked milestones:
|
|
3.2 CLI Mode
|
|
- **Blockers**: Requires refactoring from 1.2 to be complete first
|
|
4.3 Systemd Service
|
|
- **Blockers**: Need to understand systemd user services better
|
|
```
|
|
|
|
## File Location
|
|
|
|
Always look for `ROADMAP.md` in the current working directory. If not found:
|
|
1. Check parent directories up to project root
|
|
2. If still not found, reply: "No ROADMAP.md found. Would you like me to create one?"
|
|
|
|
## Error Handling
|
|
|
|
- If milestone ID not found: "Milestone [id] not found. Use /roadmap view to see available milestones."
|
|
- If command invalid: "Unknown roadmap command. Available: status, view, next, complete, journal, start, stop, search, add, blockers"
|
|
- If file write fails: Report the error and suggest manual edit
|
|
|
|
## Integration with Development Workflow
|
|
|
|
When a milestone involves using Tau to complete a task:
|
|
1. The milestone should include a **Prompt** field with the exact prompt to use
|
|
2. After completing the task via Tau, use `/roadmap complete` to mark it done
|
|
3. Add journal entries documenting:
|
|
- What Tau did well
|
|
- What Tau struggled with
|
|
- What you had to do manually
|
|
- Lessons learned about prompting Tau
|
|
|
|
## Example Session
|
|
|
|
```
|
|
User: /roadmap next
|
|
|
|
You: (read ROADMAP.md, find first [ ] milestone)
|
|
Next milestone: 1.1 Analyze Current Architecture
|
|
Description: Use Tau to analyze peak_monitor.py and identify structural improvements
|
|
Prompt: "Analyze peak_monitor.py and suggest a better project structure. Do not implement yet."
|
|
|
|
User: /roadmap start 1.1
|
|
|
|
You: (record start time)
|
|
Started milestone 1.1. Timer running...
|
|
|
|
User: (user works with Tau on the task...)
|
|
|
|
User: /roadmap journal 1.1 "Tau successfully parsed the GTK code and identified 3 structural issues"
|
|
|
|
You: (append to ROADMAP.md)
|
|
- **Journal**: 2026-07-11 14:32 - Tau successfully parsed the GTK code and identified 3 structural issues
|
|
|
|
User: /roadmap stop 1.1
|
|
|
|
You: (calculate elapsed, append Time entry)
|
|
- **Time**: 23min
|
|
|
|
User: /roadmap complete 1.1
|
|
|
|
You: (change [ ] to [x], prompt for final notes)
|
|
Milestone 1.1 completed!
|
|
Enter journal notes (or 'skip'):
|
|
|
|
User: The analysis revealed we need to separate GUI from core logic
|
|
|
|
You: (append final journal entry)
|
|
- **Journal**: 2026-07-11 14:55 - The analysis revealed we need to separate GUI from core logic
|
|
- **Decision**: Will refactor into config, core, and gui modules
|
|
```
|
|
|
|
## Remember
|
|
|
|
- Always read ROADMAP.md before modifying it
|
|
- Always use the exact milestone ID from the heading
|
|
- Always include timestamps in Journal entries
|
|
- Always preserve existing content
|
|
- Never delete or reorder milestones without explicit user request
|