Gemini Phase Roadmap Builder

Gemini Phase Roadmap Builder

Builds a multi-phase roadmap that downstream gemini-plan-phase can turn into implementation lanes. This is the Gemini port of the Claude-oriented roadmap builder; do not edit or depend on the original skill at runtime.

Core Rules

• Preserve Plan Mode boundaries. In Plan Mode, inspect files and produce a <proposed_plan> roadmap only; do not create or edit repo-tracked files.
• In Default mode, write the roadmap artifact only after enough context is available.
• During planning-only roadmap creation, do not execute test suites, builds, formatters, generators, or migrations. Capture end-to-end verification commands in the roadmap without running them.
• Use local truth first: read named specs, AGENTS.md, and repo docs the user explicitly points at. Do not invent phases from vague context.
• Use PMCP for external capability research when current docs or third-party tooling facts affect the roadmap. Prefer gateway_catalog_search, then gateway_describe, then gateway_invoke; use Context7 for library/product docs. Use Bright Data only if PMCP exposes it in the current environment.
• Use request_user_input only when available; in Default mode ask one concise plain-text question only if a missing decision would make the roadmap wrong.
• Prefer fewer serial phases and more parallel work inside each phase. A phase boundary exists only when a contract must freeze before downstream work starts.
• Do not spawn subagents unless the user explicitly asks for agents, subagents, delegation, or parallel agent work.

Inputs

• Optional spec path: markdown file to fold into the roadmap.
• Optional output path: default specs/phase-plans-v<N>.md, choosing the highest existing version or v1 if none exists.
• Append mode: if the output roadmap exists, add phases without rewriting prior phases unless the user explicitly requests a replacement.

Workflow

1. Resolve repo root with git rev-parse --show-toplevel, then inspect:
   • the named spec, if any;
   • AGENTS.md and CLAUDE.md, if present;
   • existing specs/phase-plans-v*.md;
   • markdown files the user named.
2. Choose create or append mode:
   • Create mode writes a full roadmap.
   • Append mode reads existing aliases, phase numbers, dependencies, and interface gates, then appends only new phases.
3. Write top-level context:
   • Context
   • Architecture North Star when structural
   • Assumptions
   • Non-Goals
   • Cross-Cutting Principles
4. Decompose into phases:
   • serial phases only at interface-freeze boundaries;
   • sibling phases for independent subtrees;
   • at least two likely lanes per implementation phase unless it is a preamble or interface-only phase;
   • explicit Depends on and Produces entries.
5. Add:
   • Top Interface-Freeze Gates;
   • Phase Dependency DAG;
   • Execution Notes that name which phases can be planned or executed concurrently;
   • end-to-end Verification commands.
6. Validate manually:
   • stable headings are present;
   • aliases are unique;
   • dependency graph is acyclic;
   • every produced gate has a producing phase;
   • append mode did not silently rewrite old phases.

Artifact Contract

Use this shape so gemini-plan-phase can parse it:

# Phase roadmap v<N>

## Context

## Architecture North Star

## Assumptions

## Non-Goals

## Cross-Cutting Principles

## Top Interface-Freeze Gates
- IF-0-<ALIAS>-<N> — <frozen contract>

## Phases

### Phase N — <Name> (<ALIAS>)
**Objective**

**Exit criteria**
- [ ] <testable criterion>

**Scope notes**

**Non-goals**

**Key files**

**Depends on**
- (none)

**Produces**
- IF-0-<ALIAS>-<N> — <contract>

## Phase Dependency DAG

## Execution Notes

## Verification

Closeout

In Default mode, write the roadmap with the active session's file-editing tool, then run git status --short -- <artifact>. If the artifact is untracked or modified and the user did not explicitly forbid staging, run git add <artifact> and include the _reviews.md sibling if one was produced. Rerun git status --short -- <artifact> and report Artifact state: staged|tracked|modified|unstaged|blocked. Do not commit unless the user asked for a commit.

Before final response and handoff, choose the next phase to plan from the roadmap DAG. If at least one phase is ready, report Next phase: <alias> - <phase name> and Next command: gemini-plan-phase <artifact> <alias>. If no phase should be planned next, report Next phase: none - <reason> and Next command: none - <reason>.

If writing self-improvement state, follow gemini-config/shared/runtime-state.md and use Gemini paths only:

• Reflection: ~/.gemini/skills/gemini-phase-roadmap-builder/reflections/<repo_hash>/<branch_slug>/<run_id>.md
• Handoff: ~/.gemini/skills/gemini-phase-roadmap-builder/handoffs/<repo_hash>/<branch_slug>/<run_id>.md
• Latest handoff pointer: ~/.gemini/skills/gemini-phase-roadmap-builder/handoffs/<repo_hash>/<branch_slug>/latest.md

Handoff frontmatter must include from: gemini-phase-roadmap-builder, timestamp:, repo:, repo_root:, branch:, branch_slug:, commit:, run_id:, artifact:, artifact_state:, next_skill:, next_command:, and next_phase:. Update latest.md with the same handoff content.