autopilot

Files (41)

• SKILL.md
• archetypes.schema.json · install_assets/openspec/schemas/
• convergence-state.schema.json · install_assets/openspec/schemas/
• flags.schema.json · install_assets/openspec/schemas/
• convergence-recovery.md · references/
• __init__.py · scripts/
• agent_lane.py · scripts/
• audit_log_validator.py · scripts/
• autopilot.py · scripts/
• complexity_gate.py · scripts/
• convergence_disposition.py · scripts/
• convergence_loop.py · scripts/
• gatekeeper_shadow.py · scripts/
• gatekeeper_shadow_report.py · scripts/
• goal_gate.py · scripts/
• handoff_builder.py · scripts/
• implementation_strategy_selector.py · scripts/
• phase_agent.py · scripts/
• phase_fixer.py · scripts/
• phase_outcome_shadow.py · scripts/
• phase_outcome_shadow_report.py · scripts/
• phase_token_meter.py · scripts/
• pi_local_provider.ts · scripts/
• provider_dispatch.py · scripts/
• queue_projection.py · scripts/
• runner.py · scripts/
• smoke_provider_dispatch.py · scripts/
• __init__.py · scripts/tests/
• test_autopilot.py · scripts/tests/
• test_complexity_gate.py · scripts/tests/
• test_convergence_loop.py · scripts/tests/
• test_gatekeeper_degraded.py · scripts/tests/
• test_gatekeeper_shadow.py · scripts/tests/
• test_implementation_strategy_selector.py · scripts/tests/
• test_phase_outcome_shadow.py · scripts/tests/
• test_phase_outcome_shadow_report.py · scripts/tests/
• test_provider_dispatch.py · scripts/tests/
• token_budget_check.py · scripts/
• __init__.py · tests/
• test_convergence_escalation.py · tests/
• test_convergence_metrics.py · tests/

SKILL.md (first lines)

# Autopilot

## 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.

Orchestrate the full plan-review-implement-validate-PR lifecycle with multi-vendor review convergence. For simple features, runs fully automatically from proposal to PR. Stops at merge for human approval.

## Arguments

`<change-id or description>` - Either an existing OpenSpec change-id or a feature description in quotes.

Optional flags:
- `--force` — Skip the GATEKEEPER judge entirely (operator override of the
  verifiability/risk gate). Also bypasses the scope-safety floor.
- `--val-review` — Force VAL_REVIEW phase even for simple features
- `--no-review` — Skip multi-vendor review phases (PLAN_REVIEW, IMPL_REVIEW); iterate phases still run

## Prerequisites

- OpenSpec CLI installed (v1.0+)
- At least 2 vendor CLIs available (claude, codex, antigravity, grok, pi) for multi-vendor convergence
- Coordinator recommended (degrades to linear workflow without it)

## Coordinator Capability Check

At skill start, run the coordinator detection script:

```bash
python3 "<skill-base-dir>/../coordination-bridge/scripts/check_coordinator.py" --json
```

If coordinator is unavailable, emit a warning and fall back to sequential skill invocation:
1. `/plan-feature` (if description provided)
2. `/iterate-on-plan` (always runs — self-review)
3. `/parallel-review-plan` (CLI only — single pass, no convergence loop)
4. `/implement-feature`
5. `/iterate-on-implementation` (always runs — self-review)
6. `/parallel-review-implementation` (CLI only — single pass, no convergence loop)
7. `/validate-feature`
8. Create PR manually

## Steps

### Coordinated phase-projection protocol

The queue mirror is enabled **only** after coordinator detection selected the
coordinated tier. The host must pass the detected coordinator URL explicitly as
`<coordinator-url>`; local-parallel and sequential hosts do not import,
construct, register, submit, reconcile, or label through the projection adapter.

For a coordinated resume, load no queue state into the loop. First repair the
queue solely from the durable file, before pending-gate handling or phase work:

```bash
python3 "<skill-base-dir>/scripts/runner.py" project-state \
  --change-id <change-id> --mode reconcile \
  --coordinator-url "<coordinator-url>"
```

The host must use `runner.py init` for initialization and `runner.py
transition --outcome <outcome>` for every ordinary phase edge; it must not
hand-edit `current_phase`. After **every successfully persisted** runner
mutation — `init`, `transition`, `apply-outcome`,
`escalate`, `record-state-only-archetype`, and `gate-answer` — immediately run
`project-state --mode submit`. A non-zero mutation exit suppresses projection. Runner mutation exit codes are
0 for a successful write or a clean gate-pending stop, 1 for operational
failure, and 2 for invalid caller input. A clean gate-pending transition writes
nothing and remains parked for `gate-answer`.
An invalid logical phase edge is different from invalid CLI input: `transition`
records `transition_failed`, enters ESCALATE with the current phase as
`previous_phase`, and exits 0 so the required projection publishes the parked
generation. If host-side phase bookkeeping fails before `transition` can run,
use the explicit durable writer:

```bash
python3 "<skill-base-dir>/scripts/runner.py" escalate \
  --change-id <change-id> \
  --reason "apply-outcome failed; retained handoff <handoff_id>"
```

After its exit-0 write, submit projection and stop the run.
For `gate-check`, exits 0, 3, and 4 all mean a decision or park was durably
recorded, so submit projection before asking, continuing, or stopping; exits 1
and 2 suppress projection. Projection failure is reported as degraded but never
reverts or rewrites `loop-state.json`. A `project-state` command that emits a
structured degraded JSON envelope exits 0 so authoritative phase work continues;
exit 1 is reserved for failures that prevent producing that envelope.

```bash
python3 "<skill-base-dir>/scripts/runner.py" project-state \
  --change-id <change-id> --mode submit \
  --coordinator-url "<coordinator-url>"
```

### Dispatched worker protocol (supervise children)

A run whose worktree carries a launch marker was dispatched by `/supervise`
(dispatch-contract). The marker is its only view of the dispatch request; it
carries no token.

- **Gates.** The supervisor is authoritative. Apply a gate decision only from the
  marker's `gate_answer`: `runner.py gate-answer <change-id> --gate <gate>
  --decision <decision> --approval-ref <gate_answer.approval_ref>`. Never answer or
  re-evaluate a pending gate yourself; `gate-check` prints it unchanged.
- **Cloud workers (no launch marker).** The supervisor relays its answer as a message
  naming `gate-decision:<id>`. Apply it only with `runner.py relayed-gate-answer
  <change-id> --gate <gate> --decision <decision> --approval-ref <ref>
  [--resume-at VALIDATE|IMPLEMENT]`. It fetches the roadmap branch and records the answer only if
  that decision is committed there for this change and gate, is the latest one, and
  its attempt is where that decision leaves it (relaunched after an approval, still
  parked after a rejection); otherwise, or when the fetch fails, it exits 2 and
  records nothing. Never use plain `gate-answer` for a relayed answer, and never push to
  `openspec/roadmap-*`.
- **Permission denials.** When the harness denies a tool call, do not retry or wait:
  `runner.py park <change-id> --kind permission_blocked --tool <tool> --rule "<matched
  rule>" --command "<command>" --reason "<classifier reason>"`, commit
  `loop-state.json`, emit the result, and stop. The command is stored redacted.
- **Probing.** Run only `execution_profile.probe_command`. Never read environment

From jankneumann/agentic-coding-tools, MIT.

More from jankneumann/agentic-coding-tools