roadmap

Roadmap: Lightweight Project Idea Tracker

Manage a project's feature backlog in a gitignored ROADMAP.md. Quick idea capture, progress tracking after PRs and releases, competitive intelligence from similar repos, and periodic review to keep priorities honest.

Not a project management system. No phases, no execution plans, no milestones. Just a scratchpad that evolves with the project.

When to use

• Capturing feature ideas, brainstorms, or "what if" thoughts for a project
• Tracking which ideas shipped via PRs or releases
• Scanning competing or similar repos for feature inspiration
• Reviewing and prioritizing the idea backlog
• Bootstrapping a fresh ROADMAP.md for a project that doesn't have one
• User says "add to roadmap", "what should I build next", or "what are competitors doing"

When NOT to use

• Structured project management with phases, milestones, execution plans
• Sprint or iteration planning with task dependencies
• Code review or PR review - use code-review
• Writing project docs or READMEs - use update-docs
• Factual drift in ROADMAP.md's stated version numbers or release-highlight prose - use update-docs. This skill owns item status itself: Mode 2 moves shipped [planned] / [exploring] items to Shipped. update-docs owns the header version and highlight text; roadmap owns which items count as shipped.
• Tracking bugs or incidents - use issue trackers directly

---

AI Self-Check

Before writing or modifying ROADMAP.md, verify:

• Gitignored: ROADMAP.md is in .gitignore (or user explicitly opted out of gitignoring)
• No secrets: entries don't contain API keys, internal URLs, or sensitive business info
• Attribution preserved: competitive intel cites the source repo or project
• No duplicates: new ideas don't repeat existing entries (check intent, not just wording)
• Format preserved: edits work within the existing file structure - don't reformat sections the user didn't ask to change
• Shipped items attributed: completed entries reference the PR, release, or commit
• No hallucinated competitive data: every feature, issue count, or user demand claim from a competitor repo is backed by an actual link or quote - not inferred
• No priority inflation: P0 items are genuine blockers, not aspirational wishes
• Evidence quality marked: competitive intel, user feedback, and assumptions are labeled with source and confidence
• Backlog hygiene kept: stale ideas are parked or deleted instead of endlessly reprioritized
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

Roadmap Format

Sections (fixed order)

Every ROADMAP.md uses these sections in this order. Empty sections can be omitted but the order is not negotiable - consistency makes the file scannable. When adding content to a previously omitted section, create it in the canonical position relative to existing sections.

# Roadmap

> Project: {name} | Updated: {date} | Current: v{version}
> Local planning doc, gitignored. Not a commitment.

## Snapshot

{1-2 paragraphs: project state, what the next milestone means, current focus}

## Exit Criteria

What "done" means for the next milestone. Each criterion has a verdict.

### {Criterion Name}

**Verdict**: Pass | Fail | Partial

- {Requirement}
- {Requirement}

## Now - P0

Blocks the next milestone or release. Active work only.

- [in-progress] {Description} - {area} | PR #{n}
- [planned] {Description} - {area}

## Next - P1

Committed direction. Happens after Now is clear.

- [planned] {Description} - {area}
- [exploring] {Description} - {area}

## Later - P2

Good ideas, no timeline. Revisit during review.

- {Description} - {context}

## Experiments

Low confidence. Build only with real demand signal.

- {Description} - {what would validate it}

## Shipped

### v{X.Y.Z} ({date})

- ~~{Description}~~ - {area} | PR #{n}, v{X.Y.Z} ({date})

## Competitive Intel

### {owner/repo}

- {Feature} ({strong signal | weak signal | noise}) - {evidence}
- User demand: {issue links, discussion quotes, vote counts}

## Parked

Items deferred with reason.

- {Description} - {reason for parking}

Item format

Items have two tiers depending on where they live:

Active items (Now, Next) - structured, with status and tracking:

- [status] Description - area | tracking

Status values: exploring, planned, in-progress

Area values are project-specific shorthand for the component or domain (e.g., ui, api, backend, infra, docs, auth). Infer from the project's structure. If unclear, omit the area rather than guessing.

Backlog items (Later, Experiments) - lightweight, quick capture:

- Description - context or source

Items gain structure as they're promoted. A quick idea in Later becomes a tracked item when it moves to Next.

Shipped items always get attribution:

- ~~Description~~ - area | PR #N (or MR #N), vX.Y.Z (date)

When a ROADMAP.md already exists

Read the existing structure first. If it doesn't match this format:

• In add or update modes: work within the existing structure, don't restructure
• In review mode: suggest migrating to this format if the current one is disorganized
• If the user asks to restructure: migrate section by section, preserving all content

---

Prioritization Practices

• Limit active P0/P1 items so prioritization remains meaningful.
• Group duplicate ideas and link evidence instead of copying long notes repeatedly.
• Tie each near-term item to a clear user, business, or technical outcome.
• Record exit criteria before implementation starts.
• Separate commitments from experiments so speculative work does not crowd delivery.

---

Workflow

Step 0: Activity Detection (runs on every invocation)

Before reporting roadmap state, inspect the available repository root, ROADMAP.md, ignore rules, README, and primary package/project metadata. Distinguish observed, missing, and unavailable state; never infer that a roadmap is absent or ignored when the repository cannot be inspected. Name any project context that was unavailable.

If no ROADMAP.md exists yet or a successful activity query returns no recent activity, skip the reminder. Report query failures as unavailable evidence.

Otherwise, check for recent project activity:

command -v gh; command -v glab   # forge CLI: gh (GitHub), glab (GitLab), or git-only
# GitHub
gh pr list --state merged --limit 10 \
  --json number,title,mergedAt
# GitLab
glab mr list --merged --per-page 10

# Always available (portable - no GNU date required)
git tag --sort=-creatordate | head -5
git log --oneline --since="2 weeks ago" | head -15

If neither gh nor glab is available, note it once ("PR tracking unavailable - install gh or glab for full coverage") and continue with git-only data (tags + commits).

If merged PRs or new releases look like they match open roadmap items, mention it briefly before proceeding:

"Heads up: PR #142 and v0.15.0 landed since the last roadmap update. Want me to check those off first, or continue with {requested mode}?"

Don't block. If the user ignores it, proceed with their request.

---

Mode 1: Add Ideas (default)

Trigger: user throws ideas at the project, says "add to roadmap", or describes features.

Step 1: Bootstrap if needed

1. Check if ROADMAP.md exists in the project root (in monorepos, default to the git root unless the user specifies a package - if multiple ROADMAP.md files exist, ask)
2. Before writing any content, ensure /ROADMAP.md is ignored unless the user explicitly opted into tracking. If needed, add:

   # Project roadmap (local planning doc)
   /ROADMAP.md
   

   Verify with git check-ignore --no-index ROADMAP.md and check git ls-files --error-unmatch ROADMAP.md: an already tracked file remains tracked despite ignore rules; do not silently untrack it.
3. If absent, create it using the starter structure. Read README or the primary manifest to fill Snapshot with real context. Report any ignore entry added.

Step 2: Parse and place ideas

Extract actionable items from the user's input. For each idea:

• Write a clear, concise description (keep the user's voice - clean up only if unclear)
• Place it in the right priority tier (ask if genuinely ambiguous, default to P1)
• Add context: where the idea came from, what it enables, any constraints mentioned

Append to the appropriate section. Don't reorder existing items.

Step 3: Offer competitive scan

If the roadmap has no competitive intel section and this is the first batch of ideas, ask:

"Want me to scan similar repos for feature ideas that might fit {project-name}?"

Ask once per session. If declined, don't ask again.

---

Mode 2: Update / Check Off

Trigger: user says "update roadmap", asks to check off items, or after a PR merge / release.

If no ROADMAP.md exists, redirect to Mode 1 (bootstrap) first.

Copy this checklist and track progress:

• Step 1: Recent activity gathered (or named PRs fetched)
• Step 2: Matches presented and confirmed
• Step 3: Confirmed items moved to Shipped with attribution; header date updated
• Step 4: File re-read; if a confirmed item is still in an active tier or lacks attribution, fix it and return to Step 4

Step 1: Gather recent activity

# Always available (portable - no GNU date required)
git log --oneline --since="2 weeks ago"
git tag --sort=-creatordate | head -5

# GitHub
gh pr list --state merged --limit 20 \
  --json title,number,mergedAt
# GitLab
glab mr list --merged --per-page 20

Adjust the time range if the user specifies one. If the user names specific PRs directly (e.g., "PR #45"), fetch those with gh pr view 45 --json title,mergedAt (or glab mr view 45) instead of relying on the time-windowed list.

Step 2: Match activity to roadmap items

Compare commit messages, PR titles, and release notes against open roadmap items. Use semantic matching - "add dark mode support" matches "Dark mode theme option".

Present matches to the user before making changes:

Found these potential matches:

• PR #142 "Add dark mode toggle" -> matches "Dark mode theme option" (P1)
• v0.15.0 release includes backup/restore -> matches "Backup and restore" (P0)

Check these off?

Step 3: Update the file

If the user already stated which items shipped (e.g., "PR #45 adds dark mode"), treat that as pre-confirmed - present the planned changes for review rather than re-asking "check these off?"

For confirmed matches:

1. Apply strikethrough: ~~description~~
2. Add attribution in the shipped-item shape from Item format: - area | PR #N, vX.Y.Z (date) (include both when a PR and release apply)
3. Move to the "Shipped" section (create it if missing), grouped by version or date

Update the Updated: date in the header.

Step 4: Verify the edit

Re-read ROADMAP.md. Each confirmed item appears once, under Shipped, with its PR or release attribution, and unconfirmed items are untouched. Fix any miss and repeat this step.

---

Mode 3: Competitive Scan

Trigger: user asks to scan competitors, provides repo URLs, or accepts the Mode 1 offer.

Read references/competitive-scan.md for target selection, forge CLI commands, strict fit filtering, approval flow, and Competitive Intel formatting.

Mode 3 requires a bounded, reaction-sorted forge query, or a documented equivalent when that forge cannot sort by reactions. Apply the reference's repository-size-calibrated strong/weak/noise thresholds, attribute every candidate, and present candidates for approval before writing them.

---

Mode 4: Review / Prioritize

Trigger: user asks to review the roadmap, prioritize, or "what should I work on next".

Step 1: Load and summarize

Read ROADMAP.md. Present a summary:

• Item counts by priority tier
• Items currently in progress (if tracked)
• Recently shipped items
• Stale items: items untouched for 60+ days are candidates for archival or re-prioritization (use per-item dates or recorded history; git blame cannot date an ignored file, and file mtime does not establish individual item age)

Step 2: Suggest actions

Based on the current state, flag any of these:

• P0 items not being worked on - supposed to be urgent; needs explanation or demotion
• Items untouched 60+ days - park with reason or promote; sitting isn't a priority
• Related items scattered across tiers - group into a cohesive effort
• Shipped items still in active sections - move to Shipped
• Missing structure - suggest organizational improvements

Step 3: Offer structural improvements

If the roadmap lacks clear organization, suggest improvements:

• Adding priority tiers if everything is a flat list
• Separating product work from promotion/go-to-market
• Adding a Snapshot section for project context
• Adding exit criteria for major milestones
• Creating an Experiments section for low-confidence ideas

Present suggestions. Apply only what the user approves.

Step 4: Apply changes

With user approval, reorganize, re-prioritize, park, or remove items. Never delete silently - move to Parked with a reason, or confirm deletion explicitly.

---

Reference Files

• references/trigger-integration.md - optional auto-trigger setup for Claude Code hooks, GitHub Actions, and git hooks. Read this when the user wants push-based roadmap updates instead of (or in addition to) the built-in activity detection.
• references/competitive-scan.md - competitor/repo scan workflow, evidence thresholds, and ROADMAP.md Competitive Intel formatting.

Output Contract

See references/output-contract.md for the full contract.

• Skill name: ROADMAP
• Deliverable bucket: deliverables
• Mode: conditional. When invoked to analyze, review, audit, or improve an existing roadmap (e.g., "review my ROADMAP.md"), apply the reporting size and evidence rules in references/output-contract.md and write the deliverable to docs/local/deliverables/roadmap/<YYYY-MM-DD>-<slug>.md. When invoked to build or update a roadmap (its primary mode, writing to the user's working-directory ROADMAP.md), respond freely without the contract; build-mode output goes to ROADMAP.md in the working directory, not to docs/local/.
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

• Use the host's browsing tools during competitive scans (Mode 3) to read competitor repos and documentation when web fetch alone isn't sufficient
• git - update mode (Mode 2) reads git history and PR data to match shipped work
• code-review - reviews code correctness. This skill tracks what to build; code-review evaluates the code that implements it
• update-docs - updates project documentation AND audits ROADMAP.md for factual drift in the header version and release-highlight prose. This skill owns prioritisation, capture, competitive intel, and item status (Mode 2 moves shipped items out of the active tiers); update-docs owns the stated version and highlight text staying in sync with HEAD.

Rules

1. Gitignore by default. Ensure ROADMAP.md is in .gitignore before creating or writing it. Skip only if the user explicitly asks to track it in git.
2. Attribute competitive intel. Every idea from another repo gets a source tag. Never present external features as original ideas.
3. Ask before checking off. Present matches and let the user confirm. Don't auto-complete roadmap items based on fuzzy matches alone.
4. Headless mode. In non-interactive contexts (--bare, Cursor Automations, Codex exec): skip confirmation prompts, apply only exact matches in Mode 2, add only strong-signal items in Mode 3, and don't offer competitive scans in Mode 1.