Autopilot

Turn a natural-language request into a structured, reviewable delivery workflow — automatically.

中文说明

What is Autopilot?

Autopilot is a plugin for OpenCode that acts as an AI project manager for your coding requests.

Instead of throwing a requirement at AI and hoping for the best, Autopilot breaks every request into 5 controlled stages:

Your request → Refine → Plan → Build → Review → Test → Done
                 ↑ ask    ↑ approve   ↑ auto    ↑ check   ↑ verify

Each stage produces a document you can read, approve, or correct before moving forward. You stay in control; AI does the heavy lifting.

Why use Autopilot?

| Without Autopilot | With Autopilot | |---|---| | One-shot generation, unpredictable output | Staged pipeline, visible at every step | | AI guesses your intent and starts coding | Ambiguity is resolved before code is written | | Large code dumps are hard to review | Each stage has its own artifact you can inspect | | Regression risks are left to memory | Impact scope and risk signals are tracked explicitly | | Every session follows different patterns | Skills inject consistent team conventions |

Who is this for?

• Developers who want AI-assisted coding with quality guardrails
• Teams that need consistent patterns across AI-generated code
• Anyone who's experienced "AI wrote 500 lines and half of them are wrong"

Quick Start (3 steps)

1. Install the plugin

Add this to your OpenCode configuration (opencode.json):

{
  "plugin": ["@fkqfkq123/opencode-autopilot"]
}

Restart OpenCode. You should see:

[autopilot] Autopilot plugin loaded (... commands)

2. Start your first workflow

Just type your request in natural language. For example:

Add sorting to the product list page and make sure regression risks are reviewed.

Autopilot will take over from there, guiding you through each stage.

3. Follow along

Autopilot will prompt you at key moments:

• Refinement stage: It may ask clarifying questions about your request. Answer them to move forward.
• Plan stage: It shows you the implementation plan. Approve it when ready.
• Build / Review / Test: These run mostly automatically. You'll see results at each stage.

You typically only need 3–5 interactions per request — mostly answering questions or clicking approve.

How the workflow works

| Stage | What happens | What you do | |---|---|---| | Refine | Analyzes your request, fills in gaps, asks questions if something is unclear | Answer clarification questions (or let it infer) | | Plan | Creates a step-by-step implementation plan with file list, risks, and acceptance criteria | Review and approve the plan | | Build | Writes code according to the approved plan | Monitor progress (automatic) | | Review | Checks code quality, consistency, and regression risks | Review findings, decide if fixes needed | | Test | Runs verification and reports pass/fail with evidence | Check test results |

If Review finds issues, the workflow loops back to Build automatically (up to 3 times). If Test fails, it pauses for your decision.

If a develop/review/test session appears to finish but the current phase artifact is still unchanged from its template, Autopilot performs one extra artifact-only repair dispatch before escalating to human action. That dispatch is limited to updating the artifact only — it must not continue modifying application code.

Chat-style Autopilot directives

Autopilot supports a small set of private inline directives inside normal chat input. These are parsed by Autopilot itself; they are not OpenCode host slash commands.

Supported directives:

/ap-doc: docs/requirement.md
/ap-mode: light
/ap-mode: standard
/ap-mode: safe
/ap-start-at: develop

Examples:

1. Update the product list copy
2. Change the primary button color
/ap-doc: docs/requirement.md
/ap-start-at: develop

/ap-doc: local_docs/figma_md/page.md

Rules:

• /ap-doc: adds an explicit workflow reference document and reads it into the workflow-open request.
• /ap-mode: records a workflow preset so chat input can align with the same mode semantics exposed by public slash commands.
• /ap-start-at: develop explicitly skips refinement and plan, then starts a new workflow directly in develop.
• These directives must be written as standalone lines.
• Plain prose like startAt: develop is treated as normal text and is not interpreted as a control directive.
• A direct-develop workflow still keeps review/test guardrails and records that refinement/plan were skipped.

Public slash commands

Autopilot also registers discoverable OpenCode slash commands so users can see available workflow modes while typing /a in the chat box.

Available commands:

• /ap-light: full workflow mode; routes to the workflow agent and expands to preset light plus direct-develop start
• /ap-standard: full workflow mode; routes to the workflow agent and expands to preset standard
• /ap-safe: full workflow mode; routes to the workflow agent and expands to preset safe
• /ap-debug: full workflow mode; routes to the workflow agent and expands to preset debug
• /ap-review-heavy: node review mode; on completed workflow context it creates a review node run, otherwise it expands to preset review-heavy
• /ap-develop: node develop mode; creates a develop node run against an existing workflow context
• /ap-verify: node verify mode; creates a verify node run against an existing workflow context

These commands are thin entrypoints. They autocomplete in OpenCode, run on the workflow agent, and expand into Autopilot directive lines that the workflow runtime parses reliably.

Current preset / node behavior:

• light: direct-develop path for small clear tasks
• standard: default phase order with balanced review/test guidance
• safe: default phase order with stricter review/test guidance and deeper understanding during review/test
• debug: default phase order with reproduce/isolate/fix/verify guidance for bug work
• review-heavy: default phase order with extra review scrutiny and regression discovery bias
• verify: default phase order with validation-first guidance and concise review
• review-heavy node runs: review -> done
• develop node runs: develop -> done
• verify node runs: test -> done

Node run metadata:

• runKind: full, review-heavy, develop, or verify
• parentWorkflowId: the immediate parent workflow/run
• sourceWorkflowId: the original root workflow that supplied the artifacts

Node runs are intended for follow-up review, test, develop, or verify work on top of an existing completed workflow. They reuse the source workflow artifacts for context, but they do not overwrite the original workflow history.

See docs/ap-command-presets.md for the recorded preset design and docs/review-orchestration-overview.md for the end-to-end review orchestration and consolidation flow.

Workflow recovery

When you change code outside the workflow while it is paused in review or test, use workflow_resync to realign workflow state with the current worktree.

Behavior:

• workflow_resync is a dedicated recovery command/tool.
• It currently supports workflows paused in review or test only.
• It resets the current phase artifact to a fresh rerun baseline and re-dispatches that same phase.
• The default behavior is to rerun the current phase, not to continue from the old conclusion.

Example recovery flow:

1. Workflow pauses in review or test.
2. You manually fix code outside the workflow.
3. Re-attach or inspect status if needed.
4. Run workflow_resync for the same workflowId.
5. Autopilot rebuilds the current phase baseline and reruns that phase.

Typical use:

workflow_status -> workflow_resync -> workflow_attach

Configuration

Autopilot creates/uses two configuration files:

| Scope | Path | Purpose | |---|---|---| | Global (all projects) | ~/.config/opencode/autopilot.json | Your personal defaults | | Project-specific | <your-project>/.workflow-harness/autopilot.json | Per-project overrides |

When both exist, they merge — project settings are added on top of global ones. If neither file exists, Autopilot creates autopilot.json with sensible defaults on first run. You don't need to configure anything to get started.

Explicit @read(...) sources

Autopilot supports explicit read targets inside workflow-open requests.

Examples:

Please use @read(docs/acceptance.md) for the acceptance criteria.
Add the content from @read(local_docs/figma_md/17786586547155.png) under the "video generate" section.

Rules:

• @read(...) is only consumed during refinement and plan.
• Plain file paths without @read(...) are not automatically read.
• Text targets (.md, .txt, .rst, .adoc) are read directly and injected into the workflow input.
• Image targets (.png, .jpg, .jpeg, .webp) go through the image summary service.

Image summary service behavior

Image @read(...) targets only produce summaries when an OpenAI-compatible vision service is configured through environment variables:

export AUTOPILOT_IMAGE_SUMMARY_BASE_URL="https://your-openai-compatible-endpoint"
export AUTOPILOT_IMAGE_SUMMARY_API_KEY="your-api-key"
export AUTOPILOT_IMAGE_SUMMARY_MODEL="your-vision-model"

When configured:

• Autopilot reads at most 5 explicit image targets per request
• processes them with concurrency 2
• uses a per-image timeout of 5 minutes
• injects READ_TARGET_IMAGE_SUMMARY blocks into refinement/plan input

When not configured:

• Autopilot falls back to NoopImageSummaryService
• injects READ_TARGET_IMAGE_ERROR instead of a summary
• does not block the workflow
• does not invent image content

The autopilot.json file

Here's what a complete configuration looks like, with explanations inline:

{
  // ---- Skill directories ----
  // These folders are scanned for skill files (.md files or directories containing SKILL.md).
  // Use "~" for your home directory. Non-existent paths are silently skipped.
  "skillRoots": [
    "~/.claude/skills",
    "~/.config/opencode/skills"
  ],

  // ---- Stage settings ----
  // Each stage can have:
  //   requiredSkills: which skills to load during this stage
  //   understandingDepth: how deeply AI should analyze your codebase (lightweight / standard / deep)
  "phases": {
    "refinement": {
      "requiredSkills": [],
      "understandingDepth": "lightweight"
    },
    "plan": {
      "requiredSkills": [],
      "understandingDepth": "standard"
    },
    "develop": {
      "requiredSkills": [],
      "understandingDepth": "deep"
    },
    "review": {
      "requiredSkills": [],
      "understandingDepth": "deep"
    },
    "test": {
      "requiredSkills": [],
      "understandingDepth": "standard"
    }
  },

  // ---- Risk signals ----
  // When these patterns are detected in your request, understanding depth is
  // automatically upgraded. Signals with "triggersDeep: true" force deep mode.
  "riskSignals": [
    { "id": "cross_module", "description": "Change spans multiple modules or packages", "triggersDeep": true },
    { "id": "public_component", "description": "Change affects shared components used by other features", "triggersDeep": true },
    { "id": "state_route_permission", "description": "Change touches state management, routing, or permissions" },
    { "id": "dependency_chain", "description": "Requires tracing parent components or import chains" },
    { "id": "history_complexity", "description": "Area has history of complexity, bugs, or regressions", "triggersDeep": true }
  ]
}

Understanding depth — what do the levels mean?

| Depth | Behavior | When it's used by default | |---|---|---| | lightweight | Extracts core intent only. No deep dependency tracing unless ambiguity is detected. Keeps analysis fast and focused. | Refinement stage — you're still defining what to build | | standard | Traces direct dependencies, parent components, and immediate impact scope. Good balance of thoroughness and speed. | Plan & Test stages — enough context to plan and verify | | deep | Comprehensive tracing: parent components, routes, stores, services, shared modules, API contracts, state flow, cross-module impacts. Full picture before touching code. | Build & Review stages — maximum safety when writing/changing code |

The depth can be auto-upgraded: if your request triggers a risk signal (e.g., "cross_module"), even a lightweight stage gets bumped up. This means simple requests stay fast, complex requests get thorough treatment — automatically.

What are Skills?

A Skill is a Markdown file that contains guidelines, rules, or reference material you want AI to follow during a specific workflow stage.

Think of it as a memo for AI — like "always use our Button component," "follow these naming conventions," or "run Playwright tests for UI changes."

Where to put skill files

Skills live in directories listed under skillRoots. Two formats are supported:

| Format | Example | Use when | |---|---|---| | Single file | ~/.config/opencode/skills/my-rule.md | Short guidelines, one file is enough | | Folder + SKILL.md | ~/.config/opencode/skills/playwright/SKILL.md | Longer skills with accompanying reference files |

The filename (without .md) becomes the skill name. For the folder format, the folder name is used.

Creating your first skill

Let's say you want AI to follow your team's frontend conventions during the build stage:

Step 1: Create the skill directory (if it doesn't exist):

mkdir -p ~/.config/opencode/skills

Step 2: Create a skill file:

# Frontend Design Rules

## Component usage
- Always use existing components from src/components/ before creating new ones.
- Import Button from "@/components/Button/Button.tsx".
- Import Table from "@/components/Table/Table.tsx".

## Styling
- Use Tailwind CSS utility classes. Do not create new CSS files.
- Follow the existing design tokens in src/styles/tokens.ts.

## Accessibility
- All interactive elements must have aria-label.
- Support keyboard navigation for all custom components.

Save this as ~/.config/opencode/skills/frontend-design.md.

Step 3: Enable it in your config:

{
  "phases": {
    "develop": {
      "requiredSkills": ["frontend-design"]
    }
  }
}

From now on, every time the workflow reaches the Build stage, AI receives your design rules as context and follows them while writing code.

Practical skill examples

| Skill name | Best for stage | What it does | |---|---|---| | frontend-design | develop | Inject component library and styling conventions | | code-review-checklist | review | Ensures consistent review criteria across sessions | | playwright | test | Guides AI to write browser-based E2E tests | | clarity-guide | refinement | Encourages AI to resolve ambiguity early | | i18n-rules | develop | Enforces internationalization patterns |

What if a skill is missing?

If you reference a skill name in requiredSkills but the file doesn't exist in any skillRoots, Autopilot notes it as [MISSING_SKILLS] in the workflow prompt but continues running normally. It won't break your workflow.

Updating Autopilot

There are two supported update entrypoints:

Option 1: CLI update

Use this when you want to refresh the installed plugin outside the OpenCode chat flow:

bun run src/cli.ts update

Alias also supported:

bun run src/cli.ts autopilot-update

Option 2: OpenCode tool update

Inside OpenCode, use the standalone maintenance tool autopilot_update.

• It is not a workflow_* command.
• It is not part of workflow_channel.
• It does not enter any workflow lifecycle or workflow state machine.

If you are chatting with an agent, asking it to call autopilot_update is more reliable than only sending the literal text autopilot_update.

What the updater does

• Local source install (file://<repo>/dist/plugin.js): checks the repo version and only rebuilds when it is behind the latest release.
• Release file install (file://~/.config/opencode/plugins/autopilot/plugin.js): downloads the latest GitHub release bundle and replaces the installed plugin safely.
• npm package install (@fkqfkq123/opencode-autopilot): reports the installed package version and tells you to run npm update @fkqfkq123/opencode-autopilot when needed.

After updating

• After any real update, restart OpenCode so its in-memory plugin cache reloads the new plugin code.
• If the updater reports that you are already current, no restart is required.

Publishing to npm

This package is configured for public scoped publishing.

Local pre-publish verification

bun run typecheck
bun test
bun run build
npm pack --dry-run

Manual publish

npm publish --access public

GitHub Actions release publish

Tagging v* runs .github/workflows/release.yml, which:

• typechecks
• builds
• runs smoke tests
• uploads the GitHub release tarball
• publishes to npm when NPM_TOKEN is configured in repository secrets

Important: keep the GitHub Release version aligned with the npm package version. If npm is published to a newer version but the latest GitHub Release is still older, file/release installs will see outdated latest-version information.

Remaining requirement

Before calling the package fully public-ready, add an explicit open-source license choice to both:

• package.json → license
• repo root → LICENSE

Without those, npm will still treat the package as proprietary metadata-wise.

Troubleshooting

OpenCode won't start after adding the plugin

Temporarily remove the plugin line from opencode.json, restart OpenCode, then re-add it after checking for typos.

Workflow seems stuck or broken

Delete the runtime folder and start fresh:

rm -rf .workflow-harness

Then re-run your request.

Plugin loads but commands aren't available

Make sure your OpenCode version supports plugin commands. Try updating both OpenCode and the plugin:

npm update @fkqfkq123/opencode-autopilot

Fallback install

If you prefer installing from source instead of npm:

curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash