| name | q-roadmaps |
| description | Roadmap planning skill for Q agent. Provides qr CLI for roadmap CRUD and project aggregation. Use when planning quarterly roadmaps or coordinating across teams. |
Q Roadmaps Skill
Strategic planning layer for the Q agent system. Aggregates projects into roadmaps.
What I Do
- Create, update, and query roadmaps
- Aggregate projects into roadmaps
- Calculate roadmap progress from projects
- Coordinate across teams via repo ownership
When to Use Me
Use this skill when:
- Creating or editing roadmaps (
qr new)
- Viewing roadmap project lists (
qr projects)
- Checking roadmap progress (
qr progress)
- Planning quarterly goals
Do NOT use for:
- Individual task operations (use q-tasks skill)
- Project management (use q-projects skill)
- Cross-module sync (use q-review skill)
Script Location
The qr CLI script is located at:
scripts/qr
Run with full path: scripts/qr <command>
Quick Start
scripts/qr new "Q1 2026" --teams frontend,backend
qr list
qr projects myorg-q1-2026
qr progress myorg-q1-2026
CLI Reference
Core Operations
| Command | Description |
|---|
qr list | List all roadmaps |
qr show <id> | Display roadmap details |
qr new "name" --teams <t> | Create new roadmap |
New options:
--teams <teams> - Comma-separated team names (required)
--start YYYY-MM-DD - Start date
--end YYYY-MM-DD - End date
Project Composition
| Command | Description |
|---|
qr projects <id> | List roadmap projects |
qr progress <id> | Calculate progress |
Publishing
| Command | Description |
|---|
qr publish <id> | Move to public/roadmaps/ |
Update Log
| Command | Description |
|---|
qr log | Recent updates |
qr log <id> | Updates for roadmap |
Roadmap Lifecycle
Roadmaps are living documents - they are NEVER archived.
active -> completed (when all projects done)
Progress Calculation
progress = avg(project_progress for each project)
Health derivation (based on blockers, NOT calendar):
- green: No blockers, work progressing
- yellow: Has blockers, but path forward exists
- red: Critical blockers, needs intervention
Planning Philosophy
Focus on ORDER and EFFORT, not calendar predictions:
- List goals in priority/dependency order
- Use effort points (0-10), not time estimates
- Define milestones as completions ("after X") not dates ("by Jan 15")
- NO monthly breakdowns (January goals, February goals, etc.)
File Format
---
id: myorg-q1-2026
title: Platform Q1 2026 Roadmap
status: active
created: 2026-01-01
updated: 2026-01-08
owner: alice
teams: [frontend, backend]
repos:
- github/myorg/*
projects: [tsl-myproject, market-protection]
start: 2026-01-01
end: 2026-03-31
health: green
progress: 0.45
---
...
Detailed References