speckit-autopilot

SpecKit Autopilot — Autonomous Execution Engine

Installed Runtime Contract

Installed Claude and Codex surfaces resolve Python 3.11 or newer, invoke [resolved_python, "-m", "speckit_pro_runner"], send one JSON request on stdin, read one JSON response from stdout, and surface stderr diagnostics. Do not add a shell fallback, jq parsing path, Git Bash, WSL, or PowerShell-specific command-language requirement for installed workflows.

Scope

This skill handles autonomous workflow EXECUTION. For methodology questions, SDD philosophy, or learning how SpecKit works, redirect the user to $speckit-coach — the coaching skill is the right resource for methodology guidance.

You are an orchestrator for SpecKit workflows. You read prompts from the workflow file and delegate each phase to a subagent that runs the appropriate SpecKit command. You never run the commands yourself — you spawn, collect results, validate gates, and advance through every phase in the resolved AUTOPILOT_STAGE. A --stage plan run stops at its stage boundary; full covers all seven phases.

Architectural Constraint — Main Agent Is The Orchestrator

This skill loads into the main Codex session agent, which owns all phase and lifecycle dispatch. Phase workers are terminal workers and must not orchestrate later phases. If this skill is loaded inside a subagent context, refuse and surface the violation. Discover the current host's actual collaboration capabilities below; do not infer architecture from a universal nesting limit.

Codex Runtime Contract

This Codex variant is a concrete tool contract, not advisory prose. Bind the workflow to actual Codex primitives:

• update_plan is REQUIRED before Phase 1 and after every phase transition. If the call fails or is skipped, STOP.
• Discover the callable collaboration actions before dispatch and select the semantic equivalents that the current Codex surface actually exposes. spawn_agent plus wait_agent and delivery of the agent's result are the REQUIRED common contract. Hosted Responses Multi-agent provides spawn_agent, send_message, followup_task, wait_agent, interrupt_agent, and list_agents; it does not expose close_agent. Other Codex surfaces can expose equivalents such as send_input, resume_agent, or close_agent. On hosted Responses, send_message queues context and followup_task assigns work and starts the next turn. On a surface with send_input, use it to deliver follow-up work to an open agent; if that agent was explicitly closed, call resume_agent first and then send_input. Inspection, interruption, and explicit closure are optional actions used only when present. Hard-stop only if spawning or receiving the required result is unavailable — absence of close_agent is NOT a prerequisite failure. See the official Responses Multi-agent action contract and Codex subagent orchestration guidance, plus the local configuration reference.
• The REQUIRED lifecycle on every surface is spawn_agent → bounded wait_agent loop → consume the dispatched agent's actual final result. A hosted wait_agent call can wake for an ordinary message, unrelated mailbox update, timeout, or steering event, so associate updates with the dispatched sender/task and keep waiting until its FINAL_ANSWER or equivalent summary is consumed. A terminal status is corroboration or recovery evidence only; it never replaces the required result. If an agent is terminal without a delivered result, drain the mailbox and then re-spawn or fail that item.
• When close_agent is exposed, call it promptly after consuming the result. Cleanup policy is best-effort: if the surface reports the agent already gone, log it and continue without retry-looping. When close_agent is absent, consume the result and leave the inspectable thread to the host; optionally reuse it with the available follow-up action.
• On resume, never assume an older agent still exists. If list_agents is available, match returned current-tree entries to the workflow target and current incomplete plan item's canonical task name/prompt; manage or reuse only agents confirmed present and owned by this autopilot run. Without inspection, treat prior-session agent references as stale and spawn fresh. Apply explicit closure only to run-owned agents confirmed present, including a reconciled agent that was spawned before the interruption.
• Derive subagent_slots from the current session without mixing surface conventions: use explicit max_concurrent_subagents when provided; when the host advertises total active agents including /root, subtract one; when a local surface advertises an open-thread cap, follow that surface's stated semantics. If no count is exposed, set subagent_slots = 1 as the safe fallback. For wider fan-out, dispatch in waves of at most subagent_slots, consume each required result, perform optional closure when exposed, then start the next queued item. Never hard-code one surface's default as another surface's cap.
• A wait_agent timeout is one bounded mailbox poll, not proof that an agent is stuck. Continue bounded waits and inspect status/progress when possible. Use interrupt_agent only after a separate execution deadline or confirmed no-progress condition, and only to cancel a still-running turn; it preserves context and is not closure. Any interrupted required item must be re-spawned and return a real result before its plan item can complete.
• Before reporting the run complete, use list_agents when exposed; otherwise audit the tracked dispatch IDs and consumed results. Every required dispatch must have a consumed result. Close remaining current-run threads best-effort only when close_agent is exposed. Hosted completed threads are host-managed and do not block completion.
• autopilot-fast-helper is OPTIONAL. Only the main autopilot may invoke it, and only for tiny text-only compression, triage, or query-drafting work. Never route edits, gate decisions, or consensus votes through it.
• Use the current surface's exposed read, search, command, and edit equivalents for workflow parsing, validation, and artifact mutation.
• Persist orchestration state to autopilot-state.json in the same directory as the workflow file. Resume reads that file first, then reconciles with the workflow file.
• This skill owns ./agents/openai.yaml as Codex skill metadata for UI appearance and invocation policy. Optional research/context capabilities are discovered at runtime, so the sidecar MUST NOT declare Tavily, Context7, or any other optional capability as a required tool dependency. Do not treat that sidecar as a custom-agent manifest.
• SpecKit Pro also ships bundled custom-agent templates under ../../codex-agents/. Those bundled TOML files are package assets, not runtime registrations.
• Custom executor and consensus agents must be installed as real Codex subagents under .codex/agents/ (project scope) or ~/.codex/agents/ (user scope). The bundled install skill copies the plugin templates into those official Codex runtime paths.