autopilot-roadmap

Files (5)

• SKILL.md
• __init__.py · scripts/
• orchestrator.py · scripts/
• policy.py · scripts/
• replanner.py · scripts/

SKILL.md (first lines)

# Autopilot Roadmap

## Durable state artifact authority

Shared holder, writer, authority, fallback, and rehydration semantics live in `docs/guides/state-artifacts.md`. The procedures below retain this skill's phase-specific commands and gates.

Execute roadmap items iteratively with policy-aware vendor routing and adaptive reprioritization. Manages the full lifecycle of each roadmap item from planning through completion, writing learning entries and adjusting priorities based on accumulated experience.

## Arguments

`<workspace-path>` - Path to a roadmap workspace directory containing `roadmap.yaml` (produced by `/plan-roadmap`).

Optional flags:
- `--repo-root <path>` - Repository root for schema validation (defaults to auto-detect)
- `--dry-run` - Report what would be executed without making changes

## Prerequisites

- A roadmap workspace with `roadmap.yaml` (from `/plan-roadmap`)
- Shared runtime at `<skill-base-dir>/../roadmap-runtime/scripts/` (models, checkpoint, learning, context)
- At least one vendor CLI available for `/implement-feature` invocation

## Local CLI Mutation Boundary

`autopilot-roadmap` writes checkpoint, roadmap status, learning entries, and may
invoke implementation/validation skills for roadmap items. In local CLI
execution, every mutating run MUST start from a managed worktree unless
`--dry-run` is set.

Before loading or updating the roadmap workspace, run:

```bash
CHANGE_ID="roadmap-<workspace-name>"
eval "$(python3 "<skill-base-dir>/../worktree/scripts/worktree.py" setup "$CHANGE_ID")"
cd "$WORKTREE_PATH"
python3 "<skill-base-dir>/../shared/checkout_policy.py" require-mutation
```

`--dry-run` remains read-only and may run from the shared checkout.

## Approval gate

A direct `/autopilot-roadmap` invocation is itself the operator's approval — there is
no separate `/supervise cycle` session to have asked first. Before execution starts,
record that approval as a `roadmap_approval` gate decision (mirroring `/supervise`'s
own gate router) and pass the resulting reference through, rather than letting
`ExecutionAdapter.prepare` refuse for want of one (`route-supervise-gates-through-the-
approval-gate-service`, D2/D5):

```bash
python3 "<skill-base-dir>/../supervise/scripts/cycle_state.py" --repo-root . \
  gate-answer --roadmap "$ROADMAP_ID" --gate roadmap_approval \
  --decision approved --note "direct invocation"
```

The command prints the recorded decision, including a `roadmap_approval_ref` of the
form `gate-decision:<decision_id>` — pass that value to `ExecutionAdapter.prepare`
(and to any dispatched `execute` call) for this run.

## Input

A roadmap workspace path containing:
- `roadmap.yaml` - The roadmap with items, dependencies, policy, and status
- `checkpoint.json` (optional) - Existing execution state for resume
- `learnings/` (optional) - Previously written learning entries

## Steps

### 1. Load or Resume from Checkpoint

```python
from orchestrator import execute_roadmap
result = execute_roadmap(workspace=Path(workspace_path), repo_root=Path(repo_root))
```

If `checkpoint.json` exists, the orchestrator resumes from the saved position, skipping already-completed items. Otherwise, it creates a fresh checkpoint targeting the first ready item.

### 2. Select Next Ready Item

The orchestrator queries `roadmap.ready_items()` to find items whose dependencies are all completed and whose status is `approved`. Items are processed in priority order (lower number = higher priority).

### 3. Execute via /implement-feature

**Refine the item's plan before implementing it.** `/plan-roadmap` already scaffolded every item into `openspec/changes/<change-id>/` with a proposal, tasks, and a spec delta sketched from its acceptance outcomes. That sketch validates, but its `WHEN` clauses are generic — the roadmap could not know each item's trigger at decomposition time.

So the first dispatch for a ready item is refinement, not implementation: run `/plan-feature` (and `/iterate-on-plan` where the item warrants it) against the existing change, seeded with what the item's completed dependencies taught. This is where the roadmap's central advantage is realised — an item planned after its dependencies land is planned against reality rather than against a forecast. Then dispatch `/implement-feature`.

**Pass the item's `change_id` explicitly — never let the planner choose its own slug.** `roadmap.yaml` records a `change_id` per item, and resume detection, dependency tracking and the learning log all key off it. If `/plan-feature` derives a different slug, it creates a second directory alongside the scaffolded one and the roadmap cannot find the work.

Roadmaps generated before `change_id` was persisted may omit it. In that case call `populate_change_ids(roadmap)` from `<skill-base-dir>/../plan-roadmap/scripts/scaffolder.py` on load and save the roadmap back, so the ids are fixed once rather than re-derived differently by each consumer.

For each ready item, the SKILL.md prompt layer invokes the existing skill workflow. The orchestrator provides a `dispatch_fn` callback interface:

```python
result = execute_roadmap(
    workspace=workspace,
    repo_root=repo_root,
    dispatch_fn=my_dispatch,  # Called for each item needing implementation
)
```

The `dispatch_fn` receives `(item_id, phase, context)` and returns an outcome string. The SKILL.md layer implements this by invoking `/implement-feature`, `/validate-feature`, etc.

#### Opt-in delegated lifecycle

Supervised execution uses the additive two-stage API; ordinary `execute_roadmap()` callers retain the four historical phases exactly. `prepare_delegated_batch(workspace, repo_root=..., isolation_resolver=..., context=...)` selects the deterministic scope-safe ready batch, resolves each item's isolation envelope, and persists every `prepared` generation before returning any request. It never invokes `dispatch_fn`. Invalid exact change IDs are returned as non-dispatched failures without failing the roadmap item.

The host owns child launch and the acknowledgement/go protocol. After it has advanced the persisted attempts to `launched` and collected schema-valid results, it calls `apply_delegated_batch(workspace, batch_id, results, dispatch_fn, repo_root=...)`. Apply rejects incomplete, duplicate, stale, or mismatched result sets before invoking the callback. Each unresolved generation is then presented exactly once as `dispatch_fn(item_id, "autopilot", context)`, where `context["dispatch_result"]` is the exact correlated result and the remaining context preserves router-owned keys plus dispatch, scope, and isolation identity. Success reuses the existing checkpoint and learning seam; a gate or policy `parked` result remains nonterminal and does not unblock dependents.

### 4. Handle Success

On item completion:
- Write a learning entry via `<skill-base-dir>/../roadmap-runtime/scripts/learning.py`
- Mark the item completed in the checkpoint
- Run adaptive reprioritization (`replanner.replan()`) to adjust pending items
- Advance to the next ready item

### 5. Handle Failure

From jankneumann/agentic-coding-tools, MIT.

More from jankneumann/agentic-coding-tools