nav-roadmaps

Navigator Roadmaps

Render the open roadmaps of a Navigator project as a table. One row per roadmap document. One extra table per ticket-style roadmap with counts per section.

When to Invoke

Invoke when the user says:

• "show roadmaps", "list roadmaps", "list me all the roadmaps we have open"
• "roadmap table", "roadmap status", "which roadmaps are open"
• "what roadmaps do we have", "roadmaps across repos"

Do NOT invoke when the user asks about one named roadmap. Read that file directly.

What This Does

1. Finds roadmap documents under .agent/: files named *roadmap*, task docs whose H1 says roadmap, and program docs a roadmap names as its source plan. Markers and archives are skipped.
2. Classifies each document: live, historical (header note), stub (moved pointer), program. A live document whose newest header date is older than the threshold is flagged stale Nd.
3. Counts ticket rows (✅ 🚧 🎫 📋) per ## section for ticket-table roadmaps.
4. Prints two Markdown tables. The agent adds a one-paragraph reading.

Execution Steps

Step 1: Check Navigator Initialized

if [ ! -d ".agent" ]; then
  echo "❌ Navigator not initialized in this project (no .agent/)"
  exit 1
fi

Step 2: Run the Scanner

Add --also <path>/.agent for every sibling repo the user names or that the project CLAUDE.md names as a split-docs home (example: console sessions also scan ../pilot/.agent).

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

python3 "$PLUGIN_DIR/skills/nav-roadmaps/functions/roadmap_scan.py" --root .agent [--also ../other-repo/.agent] [--stale-days 30]

Flags: --format json for machine output · --stale-days N (default 30) · --excerpt N status width (default 110) · --today YYYY-MM-DD for reproducible runs.

Step 3: Present

1. Paste the scanner's Markdown verbatim. Do not retype the table.
2. Below it, add at most one short paragraph: which roadmap is the plan of record, which status lines are stale, and the one hygiene step that follows. No other commentary.
3. If a stub row appears, name the repo that holds the real document (the stub's header says where it moved).

Output Format

See templates/roadmap-table.md for the shape and examples/pilot-console-2026-11-08.md for a real run across two repos.

Rules

• The scanner reads headers only (first 15 lines) for title, kind, date and status. A status line that is a stacked **Status**: chain shows its first segment; the stale flag comes from the newest date anywhere in the header.
• MM-DD dates in status lines take the current year, or the previous year when that would be in the future.
• Rows in a section whose title contains "Legend" are not counted.
• The skill changes no files.