Proposal: `maintaining-roadmap` skill for cross-session priority orchestration

[vlattko]

• I searched existing issues and this has not been proposed before

What problem does this solve?

I run Superpowers across multiple terminals and multiple tools (Claude
Code, Codex, Antigravity) working on a stealth geospatial platform. On
any given week I have 3–5 plans in flight at different stages: one mid-
execution, one specced but unplanned, one plan waiting on a collaborator,
one long-term idea I don't want to lose.

The plans themselves are durable, docs/superpowers/plans/ is exactly
the right artifact. What's not durable is everything around the plans:
which one is active, which is blocked and why, what the last session
left half-done, what the next session should pick up.

Concretely, three things keep costing me real time:

1. Session start friction. I open a fresh Claude Code in a worktree
   and it has no idea whether I'm mid-task, blocked, or starting fresh.
   I end up narrating the state back to it, or it picks a plan arbitrarily.
2. Mid-task handoff loss. I stop work to pick up a kid / switch
   machines / end the day. Next session, whoever (me or another agent)
   picks up has to reconstruct what was half-done from git log + file
   mtimes. Sometimes WIP gets lost.
3. Priority drift. A new item escalates and I ask for a plan. I get
   the plan. The previously-active plan stays marked "current focus" in
   my head but nowhere durable, and a week later I can't remember why
   I deferred it.

The pattern I've been falling back to manually is a single markdown file
at the project root that lists plans by tier, tracks their state, and
carries a session-end handoff note. It works well enough that I've been
hand-maintaining it for three weeks across the projects where I hit this
hardest. The manual overhead is the friction I'd like to solve.

Proposed solution

Add a skill (working name maintaining-roadmap) that introduces a
single durable artifact at docs/superpowers/roadmap.md, structured in
three priority tiers:

• Immediate — active, blocked, or next-up. Must link to a plan file.
• Mid-term — specced, 1–4 week horizon. Links to a spec, no plan yet.
• Long-term — backlog, idea-level. No file links required.

Each entry carries state (not-started / in-progress / blocked / review /
done), last-touched date, and a concrete handoff note for in-progress or
blocked items. The file also has a header (last-updated, current focus)
and a session-handoff block at the bottom with "next session should"
actions and open questions.

The skill handles:

1. Reading the roadmap at session start to orient
2. Updating state when plans progress
3. Writing a handoff note at session end (always — even if no state
   changed)
4. Promoting / demoting items between tiers when priorities shift
5. Reconciling the roadmap against the filesystem when they disagree

The skill is additive. It does not modify writing-plans, brainstorming,
executing-plans, or subagent-driven-development in this PR. Hooks
into those skills (e.g. offering to register a newly-written plan in the
roadmap) could follow later if the pattern proves useful, but the
initial skill stands alone.

A concrete example of the artifact is at the bottom of this issue.

What alternatives did you consider?

Per-plan status frontmatter. Each plan file carries its own state
block. Rejected because it doesn't solve cross-plan prioritization — I'd
still have to open every plan to see what's current. Also fragments the
handoff context across files.

TodoWrite as the persistence layer. TodoWrite is per-session; the
data doesn't survive across conversation resets, let alone across tools.
It's the right tool for sub-task tracking within a plan, not for
inter-plan state.

A separate plugin (superpowers-roadmap). This is the main real
alternative and I want to flag it honestly. Arguments for it being a
plugin: it's opinionated about file shape, it's orthogonal to the
spec-plan-execute pipeline, and someone could reasonably run Superpowers
without ever wanting a roadmap. Arguments for it being core: the pain
it solves (cross-session continuity) is structural to how Superpowers
works, specs and plans are durable but the connective tissue between
them isn't, and every multi-project Superpowers user will hit this
eventually. I lean slightly toward core but would accept plugin if
you'd rather keep the core surface small. Either outcome is useful to me.

Just keep hand-maintaining it. What I'm doing now. Works for me
personally but doesn't help anyone else who hits the same pattern, and
the agent doesn't know to consult or update the file without being told
every session.

Is this appropriate for core Superpowers?

Yes, with the caveat in the previous section. The core argument: the
problem isn't domain-specific (geospatial ML, web dev, anything with
multi-plan projects will feel it), isn't tool-specific (same pain in
Claude Code, Codex, Antigravity), and doesn't require any third-party
dependencies. It's a markdown file and a skill that reads and writes it.

The case for plugin-instead: if you'd rather the core skill set stay
tightly focused on "produce artifacts" rather than "orchestrate
artifacts", a separate plugin is reasonable. I'd be willing to maintain
such a plugin and would still find the work valuable.

If you accept this for core, the design decisions I'd expect to resolve
in review (not blocking issues, but shaping implementation):

• Archival: done items stay in an ## Archive section, move to
  roadmap-archive.md, or get deleted. I lean toward in-file Archive.
• Schema rigidity: three tiers fixed, or project-configurable. I
  lean fixed.
• Decoupled vs coupled: initial PR fully decoupled (existing skills
  untouched), integration hooks as follow-up. Non-negotiable from my
  side. I don't want to touch the core planning skills in the same PR.

Context

• Model: Claude Opus 4.6 / Claude Code, also used with Codex
• Workflow: Multi-project agentic development across several
  terminals and tools, daily. Plans live under docs/superpowers/plans/
  per the documented convention.
• Existing manual pattern: Hand-maintained docs/superpowers/roadmap.md
  in three projects for ~3 weeks. Happy to share a sanitized example of
  what the file looks like in practice if useful.

---

Example of the proposed artifact

# Project Roadmap

**Last updated:** 2026-04-15 by subagent-driven-development (session: dm-integration)
**Current focus:** Task 3 of digital-mapping plan

---

## Immediate (active, blocked, or next up)

### Digital mapping integration — in-progress
- Plan: `docs/superpowers/plans/2026-04-12-dm-integration.md`
- State: 🟡 in-progress (Task 3 of 7)
- Last touched: 2026-04-15
- Handoff: Tests passing through Task 2. Task 3 blocked awaiting
  model param mapping from external collaborator.

### Incremental fine-tuning pipeline
- Plan: `docs/superpowers/plans/2026-04-15-ff-incremental.md`
- State: ⚪ not-started
- Notes: Depends on DSM Task 5 outputs.

## Mid-term (specced, next 1–4 weeks)

### product integration
- Spec: `docs/superpowers/specs/2026-04-08-product-integration.md`
- State: approved
- Notes: Waiting on pricing model from economics team before planning.

## Long-term (backlog, concept level)

### Real-time ingestion pipeline
- Idea only — no spec yet
- Rationale: Current batch pipeline has 24h lag; customers want ≤6h.

## Session handoff

**Next session should:**
1. Check if collaborator replied re: params
2. If yes → resume DM Task 3
3. If no → draft incremental pipeline spec while waiting

**Open questions for human:**
- Should ensemble v2 block DM integration, or run in parallel?

I have a skeleton SKILL.md, a supporting schema reference, and three
pressure-test scenarios drafted in the format described in
skills/writing-skills/testing-skills-with-subagents.md. Happy to share
any of that here if the proposal is interesting enough to move forward.