Swain Roadmap

Roadmap

Before proceeding with any state-changing operation, check for an active session:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null

If the JSON output has "status" other than "active", inform the operator: "No active session — start one with /swain-init?" Proceed if they dismiss.

Regenerates ROADMAP.md from the artifact graph and opens it. The heavy lifting is done by chart.sh roadmap in swain-design — this skill is the user-facing entry point.

When invoked

1. Locate chart.sh

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
CHART_SH="$REPO_ROOT/.agents/bin/chart.sh"

If chart.sh is not found, tell the user swain-design is not installed and stop.

2. Regenerate roadmap

Parse the argument: if the user provided an artifact ID (e.g., swain-roadmap VISION-001), set SCOPE_ID to that ID. Otherwise, SCOPE_ID is empty.

If SCOPE_ID is set:

bash "$CHART_SH" roadmap --scope "$SCOPE_ID"

This writes a roadmap.md to the scoped artifact's folder.

If SCOPE_ID is empty:

bash "$CHART_SH" roadmap

This writes ROADMAP.md to the project root AND regenerates all per-Vision and per-Initiative roadmap.md slices in their respective artifact folders.

The project-wide ROADMAP.md contains:

• Quadrant chart — priority matrix as PNG (falls back to inline Mermaid if mmdc is unavailable)
• Legend — epics grouped by quadrant with short IDs
• Eisenhower tables — Do First / Schedule / In Progress / Backlog with progress, unblock counts, and operator decision needs
• Gantt timeline — priority-staggered schedule with dependency links
• Dependency graph — blocking relationships across priority boundaries (only if dependencies exist)

Each per-artifact slice contains: intent summary, child artifact table with links and progress, aggregate progress bar, recent git commits, and an Eisenhower priority subset.

2.5. Post-process intent placeholders

After chart.sh completes, scan the output file(s) for {{INTENT: <ID>}} placeholders. For each:

1. Read the source artifact markdown.
2. Extract the first sentence of ## Value Proposition (for Visions) or ## Goal / Objective (for Initiatives).
3. Replace the {{INTENT: <ID>}} marker with the extracted sentence.
4. Write the file back.

If the section cannot be found, leave the placeholder as-is (the operator can fill it in manually or wait for brief-description frontmatter to be populated via SPEC-144).

3. Open the roadmap

If SCOPE_ID was set, open the scoped slice. Look up the artifact's file path from the graph cache to find its folder:

ARTIFACT_FILE="$(bash "$CHART_SH" show "$SCOPE_ID" 2>/dev/null | grep -oE 'docs/[^ ]+' | head -1)"
if [ -n "$ARTIFACT_FILE" ]; then
    open "$REPO_ROOT/$(dirname "$ARTIFACT_FILE")/roadmap.md"
fi

If no scope, open the project-wide roadmap:

open "$REPO_ROOT/ROADMAP.md"

Always open the rendered file so the operator gets the full view with charts and diagrams. Never tell the operator to open it themselves — just do it.

4. Show CLI summary

ROADMAP.md contains tables, Mermaid diagrams, and image references that do not render in a terminal. Use the --cli flag to get a pre-formatted plain text summary:

bash "$CHART_SH" roadmap --cli

This outputs a deterministic, aligned summary grouped by Eisenhower quadrant (Do First, Schedule, In Progress, Backlog), with all first-degree children (EPICs, SPECs, SPIKEs) nested under their parent initiative. Show this output directly — do not reformat or filter it.

Say "ROADMAP.md refreshed and opened." before the CLI output. For scoped runs, say "Roadmap slice for {SCOPE_ID} refreshed and opened." instead.

Context-rich display

When listing roadmap items (Eisenhower quadrants, Gantt timeline), present each artifact as a context line instead of a bare ID:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/artifact-context.sh" <ID> 2>/dev/null

Fall back to <ID> — <title> if the utility is unavailable.

6. Focus lane context

If a focus lane is set in .agents/session.json, mention it at the end.

FOCUS="$(bash "$REPO_ROOT/.agents/bin/swain-focus.sh" 2>/dev/null)"

If focus is set, note: "Focus: {FOCUS}. Recommendations are scoped to this lane."

Freshness check (for other skills)

Other skills can call chart.sh directly for staleness-based regeneration. This skill always regenerates unconditionally — it is the "force refresh" path.

Status Dashboard (ADR-023, formerly SPEC-122)

When the operator says "status", "what's next", "dashboard", "overview", "where are we", or "what should I work on", run the status script:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
STATUS_SCRIPT="$REPO_ROOT/.agents/bin/swain-status.sh"
[ -f "$STATUS_SCRIPT" ] && bash "$STATUS_SCRIPT" --refresh || echo "status dashboard script not found"

For compact mode (MOTD): bash "$STATUS_SCRIPT" --compact

Cache

Status writes to .agents/status-cache.json with 120-second TTL. Use --refresh to bypass, --json for raw output.

Recommendation

Read .priority.recommendations[0] from the JSON cache. When a focus lane is set, recommendations scope to that vision/initiative.

Mode Inference

1. Both specs in review AND strategic decisions pending -> ask operator
2. Specs awaiting review -> detail mode
3. Focus lane + pending decisions -> vision mode
4. Nothing actionable -> vision mode (master plan mirror)

Decisions Needed (roadmap integration)

Uses chart.sh roadmap --json for Eisenhower classification. Show top 5 items from "Do First" and "Schedule" quadrants that need operator decisions.

Error handling

• If chart.sh fails, show the error output and suggest running swain-doctor
• If ROADMAP.md exists but chart.sh is unavailable, show the existing (possibly stale) file with a staleness warning
• Never fail hard — show whatever is available