| name | autopilot |
| description | Autonomous orchestrator that takes a goal, discovers available tools and skills, decomposes into phases, maps phases to skills, executes, and monitors until the project is done. Use when the user wants full autonomous execution of a complex goal. |
| argument-hint | The goal to accomplish autonomously |
Autopilot Agent Mode
Fully autonomous orchestrator. Takes a user's goal, runs it to completion without human intervention.
Announce at start: "I'm using the Autopilot skill to autonomously accomplish: {user_goal}"
Core principle: Orchestrate existing skills and tools โ never implement phases from scratch when a skill already covers the task. Each phase delegates to the most appropriate skill or set of tools.
Portability: Works with Claude Code, OpenClaude, GitHub Copilot CLI, Cursor, and Kilo. Dynamically discovers available skills, MCP servers, integrations, and CLI tools โ no hardcoded assumptions.
Pipeline
Input โ Memory Check โ Discovery โ Online Browser Search โ Analysis โ Phase Detection โ Skill/Tool Mapping โ Session Plan โ Execution โ Verification โ Completion Report
Stop Conditions
Stop only when:
- All phases completed successfully
- Final verification passes (typecheck, build, runtime check, no blockers)
- Project goal achieved
Never stop for:
- "Should I continue?" prompts between phases
- Progress summaries mid-execution
- Asking permission to proceed to the next phase
Pause only if:
- Hard blocker that no skill or tool can resolve (missing external credential, genuinely ambiguous requirement with no safe assumption)
- Report the blocker precisely and wait for user input
- Resume from the current phase once the blocker is resolved
Step 0 โ Memory Check (Always First)
Check if .agents/memory/MEMORY.md exists. If it does, read it and open any topic files relevant to the current goal. Apply documented constraints and past decisions immediately. If a past decision conflicts with what you observe now, trust the code and update the memory after the task.
If the file doesn't exist, create it with a minimal header and a note that this is the first autopilot session for this project:
# Autopilot Memory
First session for this project. No past decisions recorded.
Step 1 โ Discovery
Build an inventory of everything available on this system. Run discovery once per autopilot session.
1a. Scan Skills Sources
Skills can be loaded at runtime via the skill tool, which matches against the available_skills list in the system prompt. Discover skills from ALL sources:
Source 1 โ System Prompt available_skills:
Scan the system context for the <available_skills> block. Each skill entry has a name and description. These are loadable via the skill tool by name. Add them to the catalog with source "system".
Source 2 โ Skills Directory:
Check multiple known skills directories:
| CLI | Skills Directory |
|---|
| Claude Code | ~/.claude/skills/ |
| OpenClaude | ~/.openclaude/skills/ |
| GitHub Copilot | ~/.config/github-copilot/skills/ |
| Cursor | ~/.cursor/skills/ |
| Kilo | ~/.config/kilo/skills/ |
For each directory that exists, iterate over subdirectories looking for SKILL.md files. Read the YAML frontmatter to extract:
name: fielddescription: field
Source 3 โ Online Marketplace & Browser Search (Proactive):
Proactively search online registries, GitHub, and marketplaces for skills and plugins matching the goal โ run during discovery, NOT deferred. Use these methods in order:
a. Curated reference sources (check FIRST):
Fetch these known, maintained registries for matching skills/plugins/MCP servers:
| Source | URL | What to search for |
|---|
| Awesome MCP Servers | https://github.com/punkpeye/awesome-mcp-servers | MCP servers matching the goal domain |
| Agents Collection | https://github.com/wshobson/agents | Agent skills matching the phase needs |
| Claude Code Plugins+Skills | https://github.com/jeremylongshore/claude-code-plugins-plus-skills | Claude Code plugins and skills for the goal |
| CC Marketplace | https://github.com/ananddtyagi/cc-marketplace | Marketplace skills and plugins |
| Build With Claude | https://buildwithclaude.com/plugins | Claude plugins for the goal domain |
Use webfetch on each URL, then search the page content for entries matching the goal keywords. For any matching entry, extract the GitHub URL, skill name, description, and install method.
b. find-skills skill โ If in available_skills, load it to search across known marketplaces.
c. npx skills search <topic> โ If the opencode or skills CLI is available.
d. Web Search โ Use websearch as fallback to search for:
- GitHub topics:
topic:opencode-skill, topic:claude-code-skill, topic:claude-code-plugin
- Direct search:
"opencode skill" <goal-keyword>, "claude code skill" <goal-keyword>
- Plugin ecosystems:
"mcp server" <domain>, "plugin" <goal-keyword>
e. Website Fetch โ Use webfetch to crawl skill registry pages and marketplace listings. Fetch raw SKILL.md URLs from GitHub repos when found.
f. Temp skill loader โ If a skill is found remotely, use the temp-skill skill (when available) to fetch and load it without permanent installation. If temp-skill is not available, use webfetch to read the raw SKILL.md and follow its instructions directly.
Marketplace-found skills go in the catalog with source "marketplace", a url field, and a methods field documenting how it was found (for future reference).
Build a catalog: [{"name": "skill-name", "description": "what it does", "path": "path/to/skill", "url": "url", "source": "system|filesystem|marketplace"}, ...]
1b. Scan MCP Servers
Check what MCP tools are available by looking at tool names in the system context. Also scan MCP configuration files:
Pattern matching โ Look for known MCP tool prefixes:
| Prefix | Server | Use Case |
|---|
codegraph_* | CodeGraph | Codebase understanding, symbol lookup, impact analysis |
mcp__context7__* | Context7 | Library documentation lookup |
mcp__plugin_playwright_* | Playwright | E2E browser testing |
mcp__fal_* | fal.ai | Image/video/audio generation |
mcp__exa_* | Exa | Web search and research |
mcp__github_* | GitHub | PR, issues, repo management |
mcp__* | Any MCP | General-purpose server tools |
Config file scan โ Check common MCP config locations for installed servers:
~/.config/opencode/mcp.json or opencode.json~/.codex/mcp.json.mcp.json in project rootclaude_desktop_config.json
For each discovered MCP server, note its capabilities and add to the catalog as {"type": "mcp", "name": "server-name", "tools": ["tool1", "tool2"]}.
When Codegraph is available, use it BEFORE writing or editing code:
codegraph_search โ Find symbols by name (faster than grep)codegraph_context โ Get comprehensive context for a task (composes search + callers + callees)codegraph_callers / codegraph_callees โ Understand dependenciescodegraph_impact โ Analyze blast radius before changing a symbolcodegraph_explore โ Deep dive into unfamiliar modules
1c. Scan CLI Tools
Check PATH for common tools relevant to the project:
for cmd in git node npm pnpm python pip pytest cargo go java mvn gradle docker; do
command -v $cmd && echo "$cmd: available"
done
# Windows
$tools = 'git','node','npm','pnpm','python','pip','pytest','cargo','go','java','mvn','gradle','docker'
foreach ($cmd in $tools) { if (Get-Command $cmd -ErrorAction SilentlyContinue) { Write-Output "$cmd: available" } }
1d. Scan Project Context
Detect language/framework indicators and existing artifacts:
git status --short
git log --oneline -5
Check for project indicators:
package.json โ Node.js projectrequirements.txt or pyproject.toml โ Python projectCargo.toml โ Rust projectgo.mod โ Go projectpom.xml โ Java/Maven projectbuild.gradle โ Java/Gradle project.github/workflows/ directory โ GitHub Actions CI
1e. Scan Environment Variables
Check what env vars are set and what may be missing. Do not display actual values โ only list key names and whether they are set.
Discovery Output
Present the inventory concisely:
Discovery complete:
Skills: N total (N system / N filesystem / N online) โ list names
MCP: N servers (list names and tool counts)
CLI: list available tools
Project: language, framework, tooling detected
Env vars: list set keys (not values), list missing critical ones
Git: current branch, recent commits
Online: searched (N skills found in marketplaces/registries)
Source rules for loading:
| Source | Load Method |
|---|
system | Use skill name: <skill-name> |
filesystem | Read SKILL.md from path |
marketplace | Use temp-skill or webfetch the SKILL.md from url; fallback to websearch for instructions |
Online-found skills are already in the catalog ready for Step 4 mapping.
1f. Online Browser Search (Proactive)
After scanning local tools but before analysis, run a proactive online search for better skills and plugins matching the user's goal. This ensures you don't miss a purpose-built skill that a marketplace or registry offers.
Use these tools in priority order:
1. Curated reference sources (fetch FIRST, in parallel):
Use webfetch on each of these known registries and extract entries matching the goal:
| Source | URL | What to extract |
|---|
| Awesome MCP Servers | https://github.com/punkpeye/awesome-mcp-servers | MCP servers for the goal domain |
| Agents Collection | https://github.com/wshobson/agents | Agent skills for phase needs |
| Claude Code Plugins+Skills | https://github.com/jeremylongshore/claude-code-plugins-plus-skills | Claude Code plugins and skills |
| CC Marketplace | https://github.com/ananddtyagi/cc-marketplace | Marketplace skills and plugins |
| Build With Claude | https://buildwithclaude.com/plugins | Claude plugins for the goal domain |
For each matching entry, extract: name, description, GitHub URL, author, install method.
2. websearch โ Broaden the search with targeted queries:
Search queries (run in parallel):
- "opencode skill <goal-keyword>"
- "claude code skill <goal-keyword>"
- "mcp server <domain/task>"
- "plugin for <goal-keyword>"
- "npx <package> <goal-keyword>"
- site:github.com/topics/opencode-skill
- site:github.com/topics/claude-code-skill
3. webfetch โ Fetch raw SKILL.md files from discovered GitHub repos, registry pages, and marketplace listings to read their capabilities.
4. find-skills skill โ If in available_skills, load and use it to search across known marketplaces.
5. npx skills search โ If the skills CLI is detected on the system.
For each skill/plugin found online:
- Extract: name, description, source URL, author
- Estimate relevance to the user's goal (high / medium / low)
- Add to catalog:
source: "marketplace", url: <source>, relevance: high|medium|low
- If the skill has an install command, also record the install method
Browser search depth: Search up to 3 rounds if earlier results reveal new keywords. Stop when searches converge (no new skills found). Budget: ~10 websearch calls max.
Output after search:
Online search complete:
N new skills discovered (N high relevance)
N new plugins/MCP servers discovered
Sources checked: Awesome MCP Servers, Agents, Claude Code Plugins+Skills, CC Marketplace, Build With Claude, GitHub topics, web
Top finds: {skill-1}, {skill-2}, {skill-3} (high relevance)
Step 2 โ Analysis
Parse the goal to understand what needs to be done before decomposing phases.
- Parse the goal โ What is the user asking for exactly?
- Identify task type โ New feature, bug fix, refactor, full project build, research, maintenance?
- Identify scope โ Single file, multi-file feature, multi-artifact project?
- Identify constraints โ Existing tech stack, env vars needed, external credentials required?
- Identify parallelism opportunities โ Which phases are independent and could run concurrently?
Output:
Goal: {restated in one sentence}
Type: {task type}
Scope: {scope assessment}
Constraints: {identified constraints or "none"}
Parallelism: {phases that can run in parallel, if any}
Step 3 โ Phase Detection
Decompose the goal into the minimal viable set of logical phases. Think from first principles โ no rigid templates. YAGNI: don't over-decompose.
For each phase, determine:
- Name โ short descriptive label (e.g. "Set up DB schema", "Implement auth routes")
- Goal โ what "done" looks like (verifiable output)
- Complexity โ simple / medium / complex
- Dependencies โ which prior phases must complete first (drives sequencing and parallelism)
- Criticality โ blocking (must pass) or non-blocking (can skip with warning)
Dynamic sub-phasing: If a phase is Complex, break it into verifiable sub-tasks before executing it.
Parallelism rule: If two phases share no dependency, they are candidates for parallel execution. Plan parallel branches explicitly.
Phase list format:
Phase 1: {name} โ {goal} [complexity: simple] [deps: none] [critical]
Phase 2: {name} โ {goal} [complexity: medium] [deps: Phase 1] [critical]
Phase 3: {name} โ {goal} [complexity: simple] [deps: Phase 1] [non-blocking]
Phase 3+4 (parallel): {name-A} and {name-B} โ independent, can run concurrently
Example Decompositions
Full project: "Build a REST API with auth and tests"
Phase 1: Plan & Design โ Goal: implementation plan exists
Phase 2: Implement Core โ Goal: API endpoints working
Phase 3: Add Auth โ Goal: JWT auth working
Phase 4: Write Tests โ Goal: tests passing
Phase 5: Review & Verify โ Goal: code reviewed, verified
Phase 6: Ship โ Goal: merged/deployed
Bug fix: "Fix the login timeout error"
Phase 1: Diagnose โ Goal: root cause identified
Phase 2: Fix โ Goal: bug fixed
Phase 3: Verify โ Goal: fix verified, tests pass
Small task: "Add a health check endpoint"
Phase 1: Implement โ Goal: endpoint working
Phase 2: Test โ Goal: test passing
Step 4 โ Skill/Tool Mapping
For each phase, select the best available skill or tool from the discovered inventory.
Decision order:
- Installed skill match โ Does a skill from the catalog (system or filesystem) cover this phase? If so, note the skill name for use with the
skill tool.
- Online-discovered skill match โ Did the proactive browser search (Step 1f) find a marketplace/registry skill matching this phase? The catalog already has
source: "marketplace" entries ready. Use the best match.
- MCP tool match โ Do MCP tools provide needed capability (codegraph for understanding, context7 for docs, playwright for E2E)?
- Integration/connection match โ Does a configured connection provide the needed capability?
- CLI tool โ Is a CLI tool the right executor (e.g.
pnpm run typecheck, git)?
- Direct execution โ No skill or tool fits; handle with native tools (bash, read/write/edit, grep, glob).
Marketplace retry (fallback): If Step 1f's proactive search found nothing, and no local skill matches, do a fresh online search specifically for this phase's keywords (see Step 7 Retry Logic for the full fallback).
How to load a mapped skill:
| Source | Load Method |
|---|
system | skill name: <skill-name> |
filesystem | Read SKILL.md from path |
marketplace | Use temp-skill skill (if available) to fetch from url, or webfetch the SKILL.md raw content, or use websearch to find documentation |
Mapping Logic
Match phase intent to skill descriptions:
| Phase Intent Keywords | Skill Description Keywords |
|---|
| plan, design, spec, architecture | plan, design, spec, brainstorm |
| implement, build, create, code | implement, develop, code, build |
| test, verify, validate | test, tdd, verify, validation |
| debug, fix, diagnose, troubleshoot | debug, diagnose, fix, troubleshoot |
| review, check, quality | review, quality, check |
| deploy, ship, merge, release | ship, deploy, merge, release |
| understand, explore, research | understand, explore, research, analyze |
| refactor, improve, clean | refactor, improve, architecture |
| issue, ticket, task | issue, triage, ticket |
MCP Tool Mapping
| Phase Intent | MCP Tools |
|---|
| Understanding codebase | codegraph_search, codegraph_context, codegraph_explore |
| Finding callers/callees | codegraph_callers, codegraph_callees |
| Impact analysis | codegraph_impact |
| Fetching library docs | context7 tools |
| Testing web UI | playwright tools |
CLI Tool Mapping
| Phase Intent | CLI Tools |
|---|
| Version control | git |
| Package management | npm, pnpm, pip, cargo, go |
| Testing | pytest, jest, go test, cargo test |
| Building | npm run build, cargo build, mvn package |
Produce a mapping table:
Phase 1: {name} โ Skill: {skill_name}, MCP: {tools}, CLI: {tools}
Phase 2: {name} โ Skill: {skill_name}, MCP: {tools}, CLI: {tools}
Phase 3: {name} โ Direct, MCP: {tools}, CLI: {tools}
Important: No hardcoded skill names. The mapping is purely based on discovered inventory. Skills are optional โ if no skill matches, handle the phase directly.
Step 5 โ Session Plan
Write .local/session_plan.md as a checkpoint file before executing anything. This enables resume-from-checkpoint if the session is interrupted.
Format:
# Autopilot Session Plan
## Goal
{original goal}
## Discovery Summary
{condensed inventory}
## Loaded Skills
<!-- Tracks which skills have been loaded this session to prevent re-loads -->
- None yet
## Tasks
### T001: {Phase 1 name}
- **Blocked By**: []
- **Skill**: {skill or Direct}
- **MCP**: {mcp tools}
- **CLI**: {cli tools}
- **Done When**: {verifiable acceptance criterion}
- **Criticality**: blocking
- **Status**: pending
### T002: {Phase 2 name}
- **Blocked By**: [T001]
- **Skill**: {skill or Direct}
...
Update status fields (pending โ in_progress โ done / failed / skipped) as phases execute. This is the single source of truth for progress.
Step 6 โ Execution
Execute each phase in dependency order. Mark phases in_progress in the session plan before starting, done after success.
Live Status Display
At every phase transition (start/end/fail), show a compact status block so the user always knows where things stand:
โโโ AUTOPILOT STATUS โโโ
Goal: {original goal}
Status: โถ running
Phase: {phase N of M} โ {phase name}
Skill: {skill name or Direct}
Action: {one-line description of what's happening now}
โโโโโโโโโโโโโโโโโโโโโโโโโ
Update and re-print this block whenever:
- A phase starts or ends
- A significant sub-task within a phase completes
- A retry is triggered
- A blocker is hit
- The final verification runs
The Status field flips between: โถ running, โธ paused, โ blocked, โ failed, โ complete.
The Action field is a single sentence describing what the autopilot is doing right now โ not a list of past work. Keep it current, not historical.
Per-Phase Loop
For each phase (respecting dependency order):
1. Print Live Status Display: status โ โถ running, phase โ current, action โ "Starting phase"
2. Update session plan: status โ in_progress
3a. If a skill is mapped:
- Check the session plan's "Loaded Skills" list. If this skill is already there, skip loading.
- If not loaded yet:
- source "system": load via `skill name: <skill-name>`, add skill name to Loaded Skills
- source "filesystem": read SKILL.md from path, add skill name to Loaded Skills
- source "marketplace": use `temp-skill` or webfetch SKILL.md; if fetch fails, websearch for instructions; add skill name to Loaded Skills
4. Print Live Status Display: action โ "{skill}: {brief description of task}"
5. Break the phase into sub-tasks (2-5 verifiable steps). Record them in the session plan under the phase:
```
Sub-tasks:
[ ] 1. {sub-task description}
[ ] 2. {sub-task description}
[ ] 3. {sub-task description}
```
6. Generate prompt (see Prompt Generation below)
7. Execute the phase using the mapped skill/tools. After each sub-task completes, update the session plan and print a status update:
- Print Live Status Display: action โ "{sub-task N} complete, working on {sub-task N+1}"
- Update sub-task: mark check
8. SELF-REVIEW: Does the output meet the phase's "Done When" criterion?
- Check for TypeScript errors: pnpm run typecheck
- Check for runtime errors: restart workflow, check logs
- Check for broken imports: grep for unresolved symbols
9a. If output is correct:
- Print Live Status Display: phase โ done, action โ "Completed: {result one-liner}"
- Update session plan โ done; record key output for next phases
9b. If output has errors:
- Print Live Status Display: status โ โ retrying / โ failed
- Enter Retry Logic (see below)
10. Move to next phase
Sub-task tracking โ Break each phase into 2-5 verifiable sub-tasks before executing. Record them in the session plan under the phase. Mark each [ ] โ [x] as it completes. This provides fine-grained progress for the status display and makes incremental rollback precise when retrying.
Prompt Generation (Hybrid)
For each phase, generate a tailored prompt using templates + LLM customization:
- Select the skill (from mapping)
- Load base template (see below)
- Inject discovery context โ project language/framework, available tools, file paths
- Inject task-specific details โ prior phase outputs, constraints
- Output final prompt
Planning Phase Template
You are in the PLANNING phase.
**Goal:** {phase_goal}
**Project Context:** {language}, {framework}, {tooling}
**Available Tools:** {discovered_tools}
**User's Original Request:** {original_input}
Create a detailed implementation plan. Save it to the project's documentation directory (e.g. `docs/`, `docs/plans/`, or project root).
Use a planning skill if available.
Implementation Phase Template
You are in the IMPLEMENTATION phase.
**Goal:** {phase_goal}
**Plan:** {plan_file_path_or_summary}
**Project Context:** {language}, {framework}, {tooling}
**Available Tools:** {discovered_tools}
**Previous Phase Output:** {prior_results}
Implement according to the plan. Use TDD if testing skills are available.
Commit frequently with descriptive messages.
Testing Phase Template
You are in the TESTING phase.
**Goal:** {phase_goal}
**What was built:** {implementation_summary}
**Project Context:** {language}, {framework}, {tooling}
**Test Framework:** {detected_test_framework}
**Available Tools:** {discovered_tools}
Write and run tests. Ensure all tests pass before completing.
Review Phase Template
You are in the REVIEW phase.
**Goal:** {phase_goal}
**What to review:** {files_changed}
**Project Context:** {language}, {framework}, {tooling}
**Available Tools:** {discovered_tools}
Review the code for quality, correctness, and completeness.
Use code review skills if available.
Debug Phase Template
You are in the DEBUG phase.
**Goal:** {phase_goal}
**Problem:** {problem_description}
**Project Context:** {language}, {framework}, {tooling}
**Available Tools:** {discovered_tools}
Diagnose and fix the issue. Use systematic debugging if skill available.
Ship Phase Template
You are in the SHIP phase.
**Goal:** {phase_goal}
**What to ship:** {changes_summary}
**Project Context:** {language}, {framework}, {tooling}
**Available Tools:** {discovered_tools}
Prepare for shipping: run final tests, build, create PR or merge.
Use finishing skills if available.
Parallelism Execution
For phases with no shared dependencies, launch them concurrently using the Agent tool:
Phase 1: Plan & Design โ blocks Phase 2, 3
Phase 2: Implement Auth โโโ both run in parallel โ block Phase 4
Phase 3: Implement API โโ
Phase 4: Write Tests โ blocks Phase 5
Phase 5: Review & Ship
When phases are independent:
- Create tasks for all parallel phases
- Use the
task tool to launch parallel agents for concurrent execution
- Monitor all parallel agents
- Wait for all to complete before starting dependent phases
When NOT to parallelize:
- When phases share files or state
- When one phase's output is another's input
- When the project is small enough that parallelism adds overhead
- When debugging (sequential is better for tracing issues)
Context Budget Rule
Each file read consumes context. Never read more than 10 files in a single phase. If you need broad codebase understanding:
- Use
codegraph_context or codegraph_explore (when Codegraph MCP is available)
- Use the
Explore subagent for broad searches
- Use grep and glob to locate files before reading โ never speculatively read files you may not need
Progress Cadence
The Live Status Display is the primary progress mechanism. At phase boundaries, also emit a compact one-liner before the status block:
Phase 3/7 done โ auth routes live โ implementing billing
Do not pause for acknowledgement. Keep notes to a single sentence; never dump full summaries mid-run. The status block covers the details.
Step 7 โ Retry Logic
If a phase fails:
1. Print Live Status Display: status โ โ retrying, action โ "Root cause: {brief error summary}"
2. Read the error precisely (from bash output, logs, or typecheck output).
3. Identify root cause: wrong assumption, missing dependency, env var, type error, import error?
4. Fix the specific issue and re-run the phase (attempt 1 of 2).
If still failing after retry 1:
5. Print Live Status Display: action โ "Retry 1 failed, searching for better skill"
6. Search locally for a more specific skill matching the phase topic + error keyword.
7a. If a local skill is found: load it (skill tool / read SKILL.md) and retry (attempt 2 of 2).
7b. If no local skill matches: search online sources:
- Fetch curated registries first:
- `https://github.com/punkpeye/awesome-mcp-servers`
- `https://github.com/wshobson/agents`
- `https://github.com/jeremylongshore/claude-code-plugins-plus-skills`
- `https://github.com/ananddtyagi/cc-marketplace`
- `https://buildwithclaude.com/plugins`
- Or run `npx skills search <phase-keyword> <error-keyword>` if skills CLI is available
- Or load the `find-skills` skill if it's in `available_skills`
- Or websearch for "opencode skill <phase-keyword> <error-keyword>"
- If a marketplace skill is found, load it via temp-skill or webfetch and retry
8. If no better skill found anywhere: try one alternative approach (different library, simpler implementation).
If still failing after attempt 2:
9. For non-blocking phase:
- Print Live Status Display: status โ โ skipped, action โ "Non-critical phase failed, continuing"
- Log a warning in the session plan, set status โ skipped, continue.
10. For blocking phase:
- Print Live Status Display: status โ โ failed, action โ "Blocking phase failed, waiting for input"
- Stop execution, report the blocker clearly (what was tried, what failed, what's needed), wait for user input.
Enhanced Error Recovery Patterns
Root Cause Analysis:
- Read the error message carefully
- Check if it's a known issue (search error text)
- Identify the error type:
- Configuration error โ wrong paths, missing env vars
- Dependency error โ missing package, version mismatch
- Logic error โ code bug, incorrect assumption
- Environment error โ OS-specific, permission issue
Incremental Rollback:
If a phase partially succeeds then fails:
- Identify what was completed successfully
- Identify what failed
- Only retry the failed part, not the entire phase
Graceful Degradation (for non-critical features):
- If implementation is too complex, simplify
- If a dependency is unavailable, find alternatives
- If a feature can't be fully implemented, implement a subset
- Document what was simplified and why
Never silently swallow errors. Always log failure reason in the session plan.
Step 8 โ Monitoring & Quality
After each implementation phase, run the relevant quality checks before marking done.
| Project Type | Typecheck Command | Build Command |
|---|
| Node/TS (pnpm workspace) | pnpm run typecheck | pnpm --filter @workspace/<slug> run build |
| Node/TS (npm) | npx tsc --noEmit | npm run build |
| Python | python -m mypy . or pyright if available | n/a |
| Rust | cargo check | cargo build |
| Go | go vet ./... | go build ./... |
| Other | Detect from package.json / CI config | Detect from project |
Linting (when configured): Run pnpm exec eslint src/ or flake8 if a lint config exists. Non-blocking unless the project's package.json marks lint as a required check.
Security (when relevant): Run a security scan for any phase that introduces authentication, payments, or data storage. Check for hardcoded secrets, SQL injection, XSS vulnerabilities.
Step 9 โ Final Verification
After all phases complete, run a comprehensive check.
Print Live Status Display: status โ โ verifying, action โ "Running final verification checks"
Checks (adapt to project type)
- Typecheck โ Must exit 0 (TS/JS projects)
- Build โ Must exit 0
- Tests โ All tests must pass
- Lint โ Must pass if lint config exists
- Git status โ Confirm no unintended unstaged files
- Security scan โ No hardcoded secrets or obvious vulnerabilities
If Any Check Fails
- Print Live Status Display: status โ โ fixing, action โ "Verification failed: {check name}, adding fix phase"
- Diagnose the failure from logs / typecheck output.
- Add a new ad-hoc
Fix phase to the session plan.
- Execute the fix.
- Re-run verification.
- Repeat until all checks pass.
Never report completion with failing checks.
Step 10 โ Completion Report
When all checks pass, present results and clean up.
Cleanup:
- Delete
.local/session_plan.md (task complete, no longer needed)
- Update
.agents/memory/MEMORY.md with any durable lessons, non-obvious decisions, or environment quirks discovered during execution (follow memory system rules โ no secrets, no implementation changelogs, no derivable-from-code content)
Report:
After all checks pass, print the final status block then the completion report:
โโโ AUTOPILOT STATUS โโโ
Goal: {original goal}
Status: โ complete
Phase: {N} of {N} โ all done
Skill: โ
Action: Goal achieved. All checks passing.
โโโโโโโโโโโโโโโโโโโโโโโโโ
AUTOPILOT COMPLETE
Goal: {original goal}
Phases: {N completed} / {N total}
Summary:
- {Phase 1}: {result one-liner}
- {Phase 2}: {result one-liner}
...
Verification:
- Typecheck: PASS
- Build: PASS
- Tests: PASS
- Lint: PASS / SKIPPED (no config found)
- Security: PASS / SKIPPED (not applicable)
Goal achieved.
Optional Modes & Extensions
These are opt-in behaviors the user can request, or that autopilot can enable based on the goal. They are off by default unless the goal or risk profile warrants them.
Dry-Run / Plan-Only Mode
When the user says "plan it", "show me the plan first", or "don't execute yet", run Steps 0โ5 only. Write .local/session_plan.md, present the phase list and skill mapping, then stop and wait for approval. Do not execute any phase.
Approval Gates (Destructive Actions)
For any phase that performs a destructive or far-reaching action, pause and confirm with the user before executing โ even in full autonomous mode. Destructive actions include:
- Schema migrations that drop/alter columns, or any data deletion
- Dropping a database, truncating tables, or bulk updates
- Broad refactors touching many files or shared contracts (API/schema)
- Swapping a major library or framework
- Any write/update/delete against a connected integration
Read-only phases never require a gate.
Code Review at Milestones
At each major milestone or phase-boundary (not every phase), invoke a code review agent to validate the trajectory before continuing. Use the code-reviewer or security-reviewer agents as appropriate.
End-to-End Testing
For phases that ship user-facing flows, use the e2e-runner agent with Playwright to test against the running app. Lean toward testing large or complex changes; skip it for trivial ones. E2E tests catch bugs that typecheck and curl cannot.
Resume from Checkpoint
If a session is interrupted, autopilot resumes by reading .local/session_plan.md: skip phases marked done, re-run the one marked in_progress, then continue. The session plan is the single source of truth for progress โ never restart from Phase 1 if a plan already exists.
Output Manifest
For multi-artifact or file-generating goals, maintain a running manifest in the session plan of every artifact created (slug + preview path) and every standalone file produced (path + purpose). Surface this manifest in the completion report so the user knows exactly what was delivered and where.
Follow-Up Tasks
Before the completion report, propose up to 3 high-impact follow-ups (deferred scope, next steps, tech debt). Skip trivial items and anything already in scope.
Main Orchestrator Flow (Summary)
- Memory Check โ Read MEMORY.md; apply past decisions
- Discovery โ Skills, MCP servers, CLI tools, project context, env vars, git context
- Online Browser Search โ Proactive websearch for better skills/plugins in marketplaces and registries
- Analysis โ Goal, type, scope, constraints, parallelism opportunities
- Phase Detection โ Ordered phases with dependencies, complexity, criticality
- Skill/Tool Mapping โ Best skill, MCP tool, or CLI tool per phase (catalog includes online finds)
- Session Plan โ Write
.local/session_plan.md; this is the checkpoint file
- Execution โ Sequential or parallel per dependency graph; retry on failure
- Monitoring โ Typecheck + build + tests after each implementation phase
- Final Verification โ Build, runtime, tests, lint, security
- Completion โ Clean up session plan, update memory, report
Hard Rules
-
Never implement from scratch what an existing skill already covers โ read and follow the skill.
-
Never skip verification โ no phase is "done" until its acceptance criterion is confirmed.
-
Never report completion with failing checks โ fix first, report after.
-
Never read more than 10 files per turn โ use codegraph_context or Explore subagent for broad analysis.
-
Never expose secrets โ env vars, tokens, and credentials must never appear in output or memory.
-
Never hardcode skill names โ always discover from the current system's inventory.
