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 itself (stated version mismatch, shipped highlights out of date, [planned] / [exploring] items that already shipped) - use update-docs. This skill owns prioritisation and idea capture; update-docs owns keeping the file's stated facts honest.
• 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
• Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• Routing overlap checked: overlapping skills, trigger terms, and "When NOT to use" boundaries are checked before returning guidance
• Spec claims verified: claims about tool behavior, output contracts, or repo conventions are checked against current docs, scripts, or skill files
• 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

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} ({relevant | 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

Performance

• Keep roadmap edits small and frequent; avoid rewriting the whole backlog for one new idea.
• Limit active P0/P1 items so prioritization remains meaningful.
• Group duplicate ideas and link evidence instead of copying long notes repeatedly.

Best Practices

• 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)

If no ROADMAP.md exists yet or no recent activity is found, skip silently.

Otherwise, check for recent project activity:

# Detect forge CLI: gh (GitHub), glab (GitLab), or git-only fallback
# GitHub
gh pr list --state merged --limit 10 \
  --json number,title,mergedAt 2>/dev/null
# GitLab
glab mr list --state merged --per-page 10 2>/dev/null

# Always available (portable - no GNU date required)
git tag --sort=-creatordate 2>/dev/null | head -5
git log --oneline --since="2 weeks ago" 2>/dev/null | 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. If not, create it usin