roadmap

name	roadmap
description	Visual roadmap snapshot — theme progress, milestones, velocity. Zero new infra (Linear MCP + velocity.json).
argument-hint	[--update | --milestones | empty for snapshot]

Roadmap Visibility — Strategic Progress Snapshot

Display or generate STOA Platform roadmap aligned with Linear roadmap:* labels and milestones.

Target: $ARGUMENTS

Step 0: Determine Mode

Argument	Mode	Description	MCP Budget
(empty)	Snapshot	Display roadmap in terminal (read-only)	7-8 reads
--update	Update	Regenerate ROADMAP.md at repo root	7-8 reads + 1 file write
--milestones	Milestones	Show milestone timeline with days remaining	1 MCP read

Step 1: Fetch Theme Progress (5 queries)

Query each roadmap:* label to count Done vs Total issues:

For each theme in [gateway, platform, dx, security, community, observability]:
  linear.list_issues(
    team: "<LINEAR_TEAM_ID>",
    labels: ["roadmap:<theme>"],
    first: 250
  )
  Count: total issues, done issues (status = "Done" or "Canceled")

Label IDs (cached)

Theme	Label	ID
Gateway	roadmap:gateway	<LABEL_ID_ROADMAP_GATEWAY>
Platform	roadmap:platform	<LABEL_ID_ROADMAP_PLATFORM>
DX	roadmap:dx	<LABEL_ID_ROADMAP_DX>
Security	roadmap:security	<LABEL_ID_ROADMAP_SECURITY>
Community	roadmap:community	<LABEL_ID_ROADMAP_COMMUNITY>
Observability	roadmap:observability	<LABEL_ID_ROADMAP_OBSERVABILITY>

Important: Theme percentages depend on roadmap:* labels being applied to issues. If a theme shows 0/0, it means no issues have been tagged with that label yet. Run a backfill session to tag historical issues.

Step 2: Fetch Milestones (1 query)

linear.list_milestones(project: "<LINEAR_PROJECT_ID>")

Milestone IDs (cached)

Milestone	ID	Target Date
Demo MVP Ready	<MILESTONE_DEMO_MVP>	2026-02-17
Demo Day	<MILESTONE_DEMO_DAY>	2026-03-17
Private Beta	<MILESTONE_PRIVATE_BETA>	2026-04-30
RC1 Public Beta	<MILESTONE_RC1>	2026-06-30
v1.0 GA	<MILESTONE_V1_GA>	2026-07-31

For each milestone, compute:

• Status: Done (target date < today AND progress 100%), Active (target date > today), Overdue (target date < today AND progress < 100%)
• Days remaining: (target_date - today).days (negative = overdue)

Step 3: Read Velocity (file read)

Read .claude/state/velocity.json

Extract:

• rolling_avg_3.pts_per_day
• rolling_avg_3.issues_per_day
• rolling_avg_3.completion_pct
• Last cycle data for "Current Cycle" section

Step 4: Fetch Current Cycle (1 query)

linear.list_cycles(teamId: "<LINEAR_TEAM_ID>", type: "current")

Extract: cycle name, scope (total pts), done (pts), issue count.

Step 5: Render Output

Snapshot Mode (default) — Terminal Display

STOA Roadmap — YYYY-MM-DD
══════════════════════════
Vision: European Agent Gateway — v1.0 Jul 31, 2026

MILESTONES
  ✅ Feb 17  Demo MVP Ready
  🔄 Mar 17  Demo Day ..................... NN days
  ⬜ Apr 30  Private Beta (3 partners) .... NN days
  ⬜ Jun 30  RC1 (public beta) ............ NN days
  ⬜ Jul 31  v1.0 GA ...................... NN days

THEMES                                    Done/Total  Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Gateway       [████████████████░░░░]  XX%   NN/NN
Platform      [██████████████░░░░░░]  XX%   NN/NN
DX            [████████████░░░░░░░░]  XX%   NN/NN
Security      [████████████████░░░░]  XX%   NN/NN
Community     [██████████░░░░░░░░░░]  XX%   NN/NN
Observability [██████████████░░░░░░]  XX%   NN/NN

VELOCITY (rolling 3-cycle avg)
  XX.X pts/day | X.X issues/day | XXX% completion
  Capacity (7d): XXX pts target

CURRENT CYCLE — Cycle NN
  Committed: XX pts | Done: YY pts | ZZ%

Progress Bar Generation

For each theme, generate a 20-char bar:

filled = round(percentage / 100 * 20)
bar = "█" * filled + "░" * (20 - filled)
output = f"[{bar}]  {percentage}%"

Update Mode (--update) — Write ROADMAP.md

Generate the same content as snapshot but write to ROADMAP.md at repo root.

Add header:

<!-- Auto-generated by /roadmap --update. Do not edit manually. -->
<!-- Last updated: YYYY-MM-DD -->

Milestones Mode (--milestones) — Timeline Only

Display only the milestones section with more detail:

STOA Platform — Milestone Timeline
═══════════════════════════════════

  ✅ 2026-02-17  Demo MVP Ready          DONE
  🔄 2026-03-17  Demo Day                NN days remaining
  ⬜ 2026-04-30  Private Beta            NN days remaining
  ⬜ 2026-06-30  RC1 Public Beta         NN days remaining
  ⬜ 2026-07-31  v1.0 GA                 NN days remaining

Total progress: N/5 milestones complete
Next milestone: <name> in NN days

Rules

• Read-only by default — snapshot mode makes zero writes (Linear or files)
• MCP budget: max 8 calls per snapshot (5 theme queries + 1 milestones + 1 cycles + 1 velocity file)
• No --push-metrics in v1 — Pushgateway integration deferred to follow-up
• Theme percentages are label-dependent — if labels aren't applied, percentages will be 0/0
• velocity.json is the source of truth for velocity data (maintained by /sync-plan)
• ROADMAP.md is generated — never edit manually (overwritten by --update)
• Milestones are managed on Linear — use Linear UI or MCP to update dates/status
• No auto-commit — show output to user, let them decide whether to commit