Orchestrator Skill: Roadmap Planning

Purpose

Chain the roadmap-related atomic skills in the applicable route to complete the requested roadmap work. The fixed full-planning sequence applies only when business planning is authorized; structure-only work uses the bounded route below. This skill orchestrates only; it performs no domain analysis. For a single step, call the corresponding atomic skill directly (promote-roadmap-items for promotion alone, review-roadmap for a health check alone).

Its reason to exist is satisfying the downstream halt conditions up front. A missing roadmap or strategic-goals document stops promotion; discovering that only at the final step forces a backtrack. This skill checks and fills preconditions like that before the call.

Structure-only routing

For a new blank structure-only entry under the stage contract, route directly to define-roadmap for the selected empty layout and then to review-roadmap for structure-only review. Do not run strategy creation, intake, prioritization, dependency analysis, promotion, population or external publication. Return the inspectable structure for the requested confirmation. This route uses the Spec's stage boundary, not a new planning gate. Reuse previously settled structure during later population. For populated-plan structural repair, preserve facts rather than generating blanks.

Content and continuous routing

For content on settled structure, call define-roadmap with the retained structure and authorized source-backed content scope, then review-roadmap for content acceptance. Do not run layout selection or the full planning chain merely to fill known facts. Route new prioritization, dependency, promotion or maintenance work through its existing atomic skill only when requested or necessary within already authorized scope; unresolved business choices remain proposals.

For continuous structure and content, chain structural definition and scoped review before content definition and content review. If structure is already settled, reuse it. Continue without an intermediate confirmation when both stages are authorized; stop at a reserved boundary or unresolved material choice. Aggregate separate stage results, source gaps, business options and skipped-step reasons. A review-only request calls review-roadmap directly with its requested scope and never invokes mutating planning steps. Existing-project alignment remains bounded by its preservation contract; these entries do not force a full replanning chain.

Orchestrator Role

For remote publication/authority migration, route delivery and authorized cleanup to define-roadmap, existing-plan changes to update-roadmap, and post-write review to review-roadmap. Carry the retained destination and source-system write exclusions through each call. A missing local file after migration is not a bootstrap signal. Aggregate source, read-back, rendering and cleanup results separately; unresolved delivery or recovery findings cannot become healthy or an automatic deletion.

By the naming convention, an orchestrator skill does exactly 4 things:

1. Detect the context: select the requested stage entry or review-only scope before the full chain; otherwise call step 0 and derive the mode and each step's run condition mechanically from its findings
2. Chain the calls: run the atomic skills in a fixed order
3. halt-on-failure: the tier decides the failure semantics (see below)
4. Aggregate the output: merge every step's output into a single report

Forbidden: assessing roadmap quality, deciding dependencies, setting priorities, or reimplementing the logic of any atomic skill inside this skill.

Execution order (fixed)

Resolve intent before applying this planning table. An existing-project alignment request selects the bounded align-existing branch below; the table's mandatory strategy/promotion steps apply to the full-planning route, not to alignment or the bounded stage entries above. Preserve relative order for any steps actually selected. Alignment is not implicit planning intent.

Every step carries a tier — a mandatory step runs when its condition is hit and cannot be skipped, a default step runs when its condition is hit but the user can skip it explicitly, a recommended step is only surfaced and never runs on its own.

A step whose condition does not match is skipped; the final report names which steps were skipped and why.

The tiers are not adjustable at will. The three tiers are a mechanical mapping of constraints the atomic skills already carry, not a domain judgement made here:

• Steps 1 and 2 are mandatory because a missing strategic-goals.md and a missing roadmap.md are all halt conditions promote-roadmap-items states outright; leave them unfilled and the chain never reaches the end
• The double tier on step 4 mirrors promote's two behaviors: it halts on "all unset" and merely skips those items on "some unset"
• Step 5 reuses sufficient current evidence rather than rerunning mapping by candidate count. One candidate may depend on existing items, another team or an external service; default tier permits explicit skipping, not an inferred readiness pass
• Step 8 is recommended because archive-milestone removes a directory — a destructive operation — and its own apply defaults to false (dry-run)

Step 5 must come before step 6 when triggered: promotion consumes dependency and next-step deliverable evidence. Pass the checked/unchecked distinction; a skipped check does not establish readiness. Known cycles remain unresolved and cannot become executable candidates through an orchestration downgrade.

Behavior

Step 1: detect the context

Intent precedence: first alignment. When the user requests first adoption or alignment of an existing project's requirements/roadmap without replanning, select align-existing before bootstrap/refresh/intake/maintain. Pass that intent through review and repair. Discover the actual plan, source authority and stable locations; if they cannot be found, report the location gap rather than bootstrap a new plan.

Run step 0 (review-roadmap), then route only its classified findings:

After any repair/maintenance, re-run review-roadmap and compare the preserved business facts and links. Report unresolved criteria instead of a full pass; do not loop automatically until evidence is fabricated. Repeated alignment with no new gap makes no change. This branch skips steps 1, 3–6 and 8 unless the user separately authorizes the corresponding work. Missing strategy, unset priorities, unregistered intake and unpromoted items alone do not expand alignment into those steps. Explicit mixed requests are separated into alignment and the authorized planning/maintenance actions; carry the intent and preservation boundary to every atomic call.

Requirement-body routing is a conditional alignment subflow, not backlog intake. Do not recapture existing requirements, reset their priorities, or edit frozen approved/implemented/superseded originals. A missing successor authorization or business fact remains a limitation; do not create a new draft ID or approve it merely to make alignment pass. Requirement review/repair owns that assessment.

The normal planning modes below remain unchanged for actual planning requests.

Run review-roadmap for its findings and map them mechanically to a mode with the table below. When several signatures match at once, take the one earlier in the table, because an earlier mode corresponds to a gap further upstream.

review-roadmap does not emit a mode itself — it emits findings only, and the mapping happens at this layer.

A concise roadmap is not incomplete merely because it omits stage hypotheses or metric tables. Only requirements and defects enter promotion; task-level input resolves to its parent. Keep aggregated evidence in the report, not in roadmap rows. Version groups and schedule milestones are valid selected views, not invalid requirement rows. Route scope/date changes to maintenance and view-structure changes to definition. Preserve selected views and destination; an unchanged destination does not need repeated confirmation. An explicit full-reassessment request routes to prioritize-backlog even when no priorities are unset; pass that intent through.

Unresolved phase/event findings cannot fall through to healthy. Structural findings choose refresh; existing timing/state/evidence discrepancies choose maintain. Missing occurrence evidence blocks claiming an event reached; maintenance must obtain evidence or retain/report the unresolved state, never invent a receipt. If review reports another finding not mapped above, report it as unresolved and stop for diagnosis rather than declare the roadmap healthy.

Step 2: chain the calls

Call in the order of the table above, collecting each step's output. Before a call, go through that step's preconditions and fill what can be filled, to avoid a downstream halt and a backtrack.

Archive target for step 8: for legacy directory-backed work packages resolve milestone_slug from project records, never guess it. For a phase/version/period snapshot pass the selected phase/version/period identity and its existing source references. With several candidates, obtain the user's selection; unavailable identity means skip and report the limitation.

Step 3: halt-on-failure

The tier decides the failure semantics. This is a deliberate divergence from the single halt rule in orchestrate-code-review — there the atomic skills are independent of one another, here the steps carry data dependencies, and one blanket rule would cut short a flow that could have continued:

The special halt in step 1: if the user rejects the candidate goals design-strategic-goals produces in fallback mode, this layer does not walk back level by level to fill in the vision / North Star — that is the job of plan-next's goal tree traversal. Then halt and prompt to run plan-next first to establish the strategy layer.

Step 4: aggregate the output

A single report, containing:

• A summary of each step's result
• The skipped steps and the reason for each
• The roadmap change list (added / promoted / demoted / status changed)
• The priority-ordered tier report when step 6 ran; alignment instead reports repaired structure, preserved decisions/links, and post-repair findings
• Unresolved findings (those from step 0 that this round did not handle)
• Suggestions for the next step

Input & Output

Input: an optional scope hint and any unregistered raw input; governance document paths are discovered automatically from the project norms.

Output: a single aggregated report (see above).

Restrictions

Hard Boundaries

• Do not assess roadmap quality, decide dependencies, or set priorities inside this skill
• Preserve the execution order within the selected route. The explicit structure-only and alignment routes skip unauthorized planning steps; in the full chain, step 5 must not be placed after step 6
• Do not adjust grades within a branch; alignment skips out-of-scope planning steps by the explicit intent contract, not by waiving their preconditions
• Do not confirm on the user's behalf: the item-by-item confirmation each atomic skill asks for goes ahead as usual, and the orchestration layer does not approve in bulk
• Do not call plan-next or orchestrate-governance-step in reverse, to avoid a call cycle
• Do not reimplement plan-next's goal tree traversal

Orthogonal boundary against the existing orchestration layers

In one line: plan-next answers "what the whole project does next", this skill answers "the roadmap line, from strategy through promotion, in a single pass".

Skill Boundaries

Not done inside the orchestrator skill (the atomic sub-skills carry it): roadmap assessment → review-roadmap; structure definition → define-roadmap; scoring → prioritize-backlog; dependencies → map-item-dependencies; promotion → promote-roadmap-items; status and dates → update-roadmap; archiving → archive-milestone.

Self-Check

Apply business priority, archive and downstream-planning checks only when those steps ran. A structure-only result reports its two atomic steps and excluded business work; it does not fabricate priority order or source evidence.

• Does only the 4 things: "detect the context / chain the calls / halt-on-failure / aggregate the output"
• No domain judgement logic was implemented inside this skill
• Intent selects structure-only, content-on-settled-structure, continuous, review-only, alignment or planning first; within that branch, review findings determine actions without independent roadmap assessment
• Selected planning steps retain order, with step 5 ahead of step 6; alignment additionally re-runs read-only review after repair
• Skipped steps carry their reason in the report
• Failure semantics follow the tier; when a default step fails, the report states whether the downstream guardrail is void
• The archive target for step 8 has a definite source and was not guessed
• The report carries separate applicable stage results and unresolved findings; priority order appears only when promotion ran
• Alignment intent was resolved before normal planning routes; no skipped strategy/intake/scoring/promotion/archive action ran implicitly, and post-repair review checked preservation

Examples

Example 1: pulling in newly prioritized items (mainstream case)

• Context: review-roadmap findings show a complete structure, but 3 scored items are unpromoted → mode = intake
• Schedule: step 0 → skip 1 and 2 (governance documents complete) → skip 3 (no unregistered input) → skip 4 (no unset items) → step 5 (dependency evidence needs checking) → step 6 → skip 7 and 8
• Step 5 output: 1 candidate has an unresolved prerequisite and is marked as not admissible to Now
• Step 6: the other 2 are promoted to Now; the blocked one goes to Next
• Aggregation: priority-ordered tier report + change list + a suggestion to run capture-work-items on the newly promoted Now items

Example 2: cold start on a new project (edge case)

• Context: docs/ holds nothing but README → findings show roadmap.md and strategic-goals.md are both missing → mode = bootstrap
• Schedule: step 0 → step 1 (design-strategic-goals detects missing upstream context and derives fallback goals from repository evidence) → step 2 → step 3 → step 4 → step 5 if dependency evidence is missing or stale, otherwise reuse it → step 6
• Key point: the orchestration layer does not call define-vision just because the vision is missing. Whether the upstream is complete, and whether to run in normal or fallback mode, is design-strategic-goals's own call
• If the user rejects the fallback candidates: halt, prompt to run plan-next first to establish the strategy layer, and emit the completed step 0 health-check report

Example 3: downgrade after the dependency step fails (edge case)

• Context: mode = intake, 5 promotion candidates
• Step 5 fails: map-item-dependencies detects a dependency cycle and halts
• Handling: step 5 sits at the default tier, so the orchestration is not terminated; record the failure and carry on
• Step 6 downgraded: report the missing verified dependency result before any recommended comparison. Known cyclic candidates remain unresolved; downgrading never authorizes them into Now. Independently verified candidates may still be compared under the atomic skill's rules.
• Aggregated report: retain the cycle #12 → #19 → #25 → #12, affected candidates and the limitation. Suggest resolving the cycle before reconsidering those candidates; do not describe them as unchecked but executable.

Phase and milestone contract

Apply the Roadmap Spec across component outputs. Creation of phase/event objects belongs to define-roadmap; existing dates and source-backed event states belong to update-roadmap; structural/evidence findings belong to review-roadmap. Scoring and promotion operate on requirements/defects. Archive completed work packages or snapshots without deleting event evidence; legacy milestone directories do not define a mandatory roadmap hierarchy.

Self-check: concepts, selected views and linked evidence agree with the source records.

Revision history maintenance

Carry the selected durable history source and decision identity across definition, promotion and maintenance under the revision contract. A known post-adoption material change with missing/dropped revision evidence routes to maintain; an unknown pre-adoption history does not force reconstruction. Do not let unresolved history findings fall through to healthy. One coherent decision shared across component skills is recorded once, not once per step. Archive verification includes retained history links.

Self-check: material changes are traceable, retained links resolve, and repeated execution adds no duplicate revision.

Iteration and layout routing

Pass established cadence, selected views, single/split layout, source ownership and related document paths to atomic skills. Review findings about iteration identity, missing structural fields or unreadable main/detail layout select refresh; existing iteration scope/timebox/cadence and projection drift select maintain. Unmapped findings remain unresolved. The orchestrator does not design iterations, expand layout or infer release from an iteration boundary. Period archives retain carry-over through step 8.

Self-check: atomic findings determine layout/iteration routing and no unresolved cross-document drift falls through to healthy.

Scenario handoff

Pass known context, selection source, primary perspective, enabled views, layout and destination to atomic skills. Bootstrap/refresh delegates information gathering and recommendation to define-roadmap; do not run another interview here. Existing choices win during ordinary maintenance. Route review findings about invalid choice structure or primary/view conflicts to refresh; changed context with a consistent existing choice is an unresolved reconsideration suggestion, never automatic replacement. A recipe mismatch alone is not a finding and new features do not force migration.

Self-check: selection evidence survives every handoff and no proposed default silently replaces a team choice; unmapped findings remain explicit.

Deliverable language

Before writing roadmap-chain deliverables, apply the language contract. Read the user instruction, consuming-project policy and existing artifact first; retain a settled choice across handoffs. For a new artifact infer only from consistent reader/document evidence; ask only unresolved gaps or winning-level conflicts. Conversation language and English templates alone do not select artifact language. Record the choice and source in existing norms/planning decisions; no new mandatory configuration. Localize all new prose and display labels consistently while preserving IDs, machine fields, canonical enums, source links and historical originals.

Pass locale, basis and source to every atomic step alongside view choices. Delegate resolution to the writing skill; run no duplicate interview here. Unresolved language findings cannot fall through to healthy; report or route them to the appropriate writer without translating source evidence in the orchestrator.

Self-check: language evidence and retained choice are explicit; all new display prose is consistent, machine contracts are unchanged, and unavailable checks are reported.