agentic-coding-roadmap

name	agentic-coding-roadmap
description	Use before writing or revising Superpowers specs when work may need roadmap-level phase decomposition, or when creating/updating/selecting project roadmaps.
argument-hint	[optional: scope or roadmap path]

Agentic Coding Roadmap

Use this skill before writing or revising a Superpowers design spec when the request may be too large for one implementation phase, when the repository has no spec/roadmap baseline, or when the user asks to create, update, review, or choose a roadmap.

Purpose

Keep roadmap decisions explicit before spec writing starts. Decide whether the current request fits one scoped spec, belongs to an existing roadmap phase, or needs a new roadmap with multiple phases and dependencies.

Scan Scope

Scan the user-requested scope first:

1. If the user names a repository, directory, sibling project, product lane, file set, or roadmap path, scan that scope.
2. If the user does not specify scope, scan only the current CLI repository.
3. Do not scan sibling repositories unless the request is explicitly cross-repo or lane-level.

Roadmap Discovery

Look for roadmap candidates in this order:

1. User-specified roadmap path.
2. docs/solutions/l1/roadmap/**/*.md
3. docs/superpowers/specs/*roadmap*.md
4. Other repository-local *-roadmap.md or roadmap.md files.

Also inspect relevant plan/spec references and recent git history before choosing a primary roadmap.

Primary Roadmap Selection

Multiple roadmaps are allowed. Infer the primary roadmap from evidence:

• Current plan or spec references.
• Recent commits touching roadmap files.
• Roadmap phase artifacts that point at the current spec, plan, module, or branch.
• File location, preferring docs/solutions/l1/roadmap/ as the long-term roadmap location.
• Roadmap title and scope matching the user's requested scope.

If evidence is ambiguous, ask the user to choose among likely roadmap candidates before writing.

When A Roadmap Is Required

Create or update a roadmap when:

• The repo has no relevant spec/roadmap baseline and the request is broader than one small feature.
• The request spans multiple phases, modules, repositories, workflows, acceptance loops, or risk areas.
• Spec review finds the work should be split into phases.
• A user explicitly asks for roadmap creation or roadmap maintenance.

Do not force roadmap creation for small direct changes or a narrowly scoped one-spec feature.

New Roadmap Path

When a new roadmap is required and the user does not override the path, create:

docs/solutions/l1/roadmap/<topic>-roadmap.md

Use a stable kebab-case topic slug. Do not include the date by default.

Roadmap Content

A roadmap should include:

• Purpose and scope.
• Current baseline or known existing artifacts.
• Phase overview table.
• Status meanings.
• Per-phase goals, scope, non-goals, acceptance criteria, and primary artifacts.
• Dependency map.
• Parallelization notes.
• Roadmap maintenance rules.

When updating an existing roadmap, follow its current status vocabulary. For a new roadmap, use a small status set such as Future, Planned, Ready, In Progress, and Done.

Phase Decomposition

For each phase, record:

• Goal: the outcome the phase must deliver.
• Scope: what changes in this phase.
• Non-goals: what remains outside this phase.
• Acceptance criteria: what proves the phase is done.
• Primary artifacts: expected specs, plans, code areas, or docs.
• Dependencies: phases or external work that must precede it.
• Parallelization notes: phases that can proceed independently.

Prefer phases that can become one design spec and one implementation plan. If a phase still looks too large for one plan, split it again before writing the spec.

Relationship To Spec Review

After a roadmap-tracked design spec is approved, update the relevant roadmap phase status and artifact references. Do not treat draft brainstorming notes as completed phase evidence.

Use repository-relative paths for roadmap references. Do not write personal absolute paths into durable roadmap artifacts.

Agentic Memory Recording

After writing or materially updating a roadmap-tracked Superpowers spec, record design memory through the global wrapper when it is available:

agentic-memory record-design --phase design

Treat recording as best-effort. If the wrapper is missing or recording warns, report the warning and continue the roadmap/spec work.

Builder Workspace Roadmap Mode

When operating inside a Builder workspace, load docs/solutions/l1/roadmap/builder-workspace-baseline-rules.md and skills/agentic-coding-roadmap/rules/workspace-roadmap.md.

Use agentic-spec roadmap init --workspace <path> only to create deterministic baseline files. Write semantic phase title, depends_on, spec_ref, and status decisions as Agent-authored file edits, then run agentic-spec doctor --workspace <path> to verify the projection.