@fkqfkq123/opencode-autopilot 0.1.3 → 0.1.6

package/GUIDE.zh-CN.md

@@ -0,0 +1,120 @@
+# Autopilot
+
+[English](./README.md) | 中文说明
+
+Autopilot 是一个 OpenCode 插件，可以把自然语言需求推进成一套完整流程：需求精炼、计划、实现、评审和测试。
+
+## 安装
+
+在 OpenCode 配置里加入插件：
+
+```json
+{
+  "plugin": ["@fkqfkq123/opencode-autopilot"]
+}
+```
+
+然后重启 `opencode`。
+
+如果加载成功，你应该看到类似日志：
+
+```txt
+[autopilot] Autopilot plugin loaded (... commands)
+```
+
+## 使用
+
+直接输入自然语言需求，例如：
+
+```txt
+给商品列表页增加排序能力，并注意回归风险。
+```
+
+Autopilot 会通过这些工具推进流程：
+
+- `workflow_open`
+- `workflow_attach`
+- `workflow_status`
+- `workflow_answer`
+- `workflow_approve`
+- `workflow_resume`
+
+通常你只需要按照 workflow 输出里提示的下一步工具继续即可。
+
+## 配置
+
+Autopilot 会在需要时自动创建：
+
+```txt
+.workflow-harness/autopilot.json
+~/.config/opencode/autopilot.json
+```
+
+如果配置保持空值，就使用默认行为。
+
+### `autopilot.json`
+
+最小示例：
+
+```json
+{
+  "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
+  "phases": {
+    "spec_refinement": { "requiredSkills": [] },
+    "plan": { "requiredSkills": [] },
+    "develop": { "requiredSkills": [] },
+    "review": { "requiredSkills": [] },
+    "test": { "requiredSkills": [] }
+  }
+}
+```
+
+字段说明：
+
+- `skillRoots`：要扫描的 skill 目录
+- `phases.<phase>.requiredSkills`：该阶段需要注入的 skill
+
+支持的 phase：
+
+- `spec_refinement`
+- `plan`
+- `develop`
+- `review`
+- `test`
+
+如果旧的 `workflow.json` 存在而新的 `autopilot.json` 不存在，Autopilot 会复用旧文件，并提示你后续迁移。
+
+## 备用安装方式
+
+如果你更想走本地文件安装：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
+```
+
+## 常见问题
+
+### OpenCode 启动失败
+
+先临时从 `opencode.json` 中移除这个插件，确认 OpenCode 能正常启动，再检查配置后重新启用。
+
+### 插件加载了，但看不到 workflow 命令
+
+通常是宿主没有正确注册导出的 workflow tools。
+
+### 某个 workflow 状态坏掉了
+
+删除当前项目的运行时目录后重新开始：
+
+```bash
+rm -rf .workflow-harness
+```
+
+## 如果你要开发这个插件
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```

package/README.md

@@ -2,223 +2,11 @@
 
 English | [中文说明](./GUIDE.zh-CN.md)
 
-Autopilot is an OpenCode-oriented **attached-session workflow harness**. It provides a workflow runtime skeleton covering refinement, planning, development, review, and testing, plus a locally loadable plugin, CLI entrypoints, and diagnostics.
+Autopilot is an OpenCode plugin that turns a natural-language request into a structured workflow: refinement, plan, implementation, review, and testing.
 
-## 1. What this project provides
+## Install
 
-- A full workflow phase chain: `spec_refinement -> plan -> develop -> review -> test -> done`
-- OpenCode-facing workflow commands such as `workflow_open`, `workflow_attach`, `workflow_status`, `workflow_answer`, `workflow_approve`, `workflow_resume`, and `workflow_back`
-- Plugin loading and native primary workflow agent registration for OpenCode-style hosts
-- `install` and `doctor` flows for bootstrapping configuration and validating setup
-- Review/test loop-back semantics, human breakpoints, event storage, attach/re-attach support
-
-## 2. Who this is for
-
-Autopilot is a good fit if you want to:
-
-- add a workflow primary agent to an OpenCode-style host,
-- structure engineering work into explicit workflow phases,
-- validate a workflow runtime and command surface through a plugin.
-
-## 3. Prerequisites
-
-Recommended environment:
-
-- macOS / Linux / Windows
-- [Bun](https://bun.sh/) `1.3.5` or a compatible version
-- OpenCode installed if you want to actually load and verify the plugin
-
-Check Bun:
-
-```bash
-bun --version
-```
-
-If Bun is not installed yet:
-
-```bash
-curl -fsSL https://bun.sh/install | bash
-```
-
-Then restart your terminal and verify again:
-
-```bash
-bun --version
-```
-
-## 4. Installation
-
-### 4.1 Recommended: install as an npm plugin package
-
-OpenCode supports npm-based plugins directly. Once this package is published, the simplest configuration is:
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot"]
-}
-```
-
-You can also pin a version:
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot@0.1.2"]
-}
-```
-
-In this mode, OpenCode installs and caches the npm package automatically. No manual `git clone`, local `plugin.js`, or extra install script is required.
-
-### 4.2 Fallback: install from GitHub Releases
-
-If you prefer a local-file installation path or need a fallback distribution mode, use the one-line installer from GitHub Releases:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
-```
-
-Install a specific version:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash -s -- --version v0.1.2
-```
-
-The fallback installer will:
-
-- download the prebuilt release package from GitHub Releases,
-- install it into `~/.config/opencode/plugins/autopilot/`,
-- update `~/.config/opencode/opencode.json`.
-
-Release requirement:
-
-- Each GitHub Release must include `autopilot-release.tar.gz`
-- The repository includes `.github/workflows/release.yml`, which builds and uploads that file automatically on `v*` tags
-
-If you want to modify the codebase or work from source, continue with the source setup below.
-
-### 4.3 Clone the repository
-
-```bash
-git clone https://github.com/juhuaxia/Autopilot.git
-cd Autopilot
-```
-
-### 4.4 Install dependencies
-
-```bash
-bun install
-```
-
-The project uses `bun.lock`, so dependencies are expected to stay reproducible.
-
-## 5. Recommended first-run commands
-
-Run these from the project root:
-
-```bash
-bun run src/cli.ts install
-bun run src/cli.ts doctor
-bun run build
-```
-
-What they do:
-
-1. `install`
-   - creates project-level `.workflow-harness/workflow.json`
-   - tries to safely update `~/.config/opencode/opencode.json`
-   - normalizes `opencode.jsonc` into `opencode.json` when safe
-2. `doctor`
-   - checks `workflow.json`
-   - checks `skillRoots`
-   - checks phase-level `requiredSkills`
-   - reports warnings and missing pieces
-3. `build`
-   - compiles TypeScript
-   - produces `dist/plugin.js`
-
-After that, confirm:
-
-- `.workflow-harness/workflow.json` exists
-- `doctor` shows no blocking configuration issue
-- `dist/plugin.js` exists
-
-## 6. Common development commands
-
-### 6.1 Build
-
-```bash
-bun run build
-```
-
-### 6.2 Typecheck
-
-```bash
-bun run typecheck
-```
-
-### 6.3 Run tests
-
-```bash
-bun test
-```
-
-### 6.4 Run plugin smoke tests
-
-```bash
-bun run smoke:plugin
-```
-
-### 6.5 Run CLI commands directly
-
-```bash
-bun run src/cli.ts doctor
-bun run src/cli.ts install
-```
-
-Or through the script alias:
-
-```bash
-bun run cli --help
-```
-
-> The CLI mainly provides workflow initialization, attach/status flows, and install/doctor actions.
-
-## 7. CLI quick usage
-
-### 7.1 Initialize config
-
-```bash
-bun run src/cli.ts install
-```
-
-### 7.2 Run a self-check
-
-```bash
-bun run src/cli.ts doctor
-```
-
-### 7.3 Create a workflow
-
-```bash
-bun run src/cli.ts workflow-open wf-1
-```
-
-### 7.4 Check workflow status
-
-```bash
-bun run src/cli.ts workflow-status wf-1
-```
-
-### 7.5 Re-attach to the workflow channel
-
-```bash
-bun run src/cli.ts workflow-attach wf-1
-```
-
-## 8. Loading the plugin into OpenCode
-
-### 8.0 Recommended npm plugin path
-
-Recommended OpenCode config:
+Add the plugin to your OpenCode config:
 
 ```json
 {
@@ -226,237 +14,109 @@ Recommended OpenCode config:
 }
 ```
 
-### 8.1 Fallback release-based path
-
-If you prefer a local installed fallback plugin, use:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
-```
-
-Default install location:
-
-```txt
-~/.config/opencode/plugins/autopilot/
-```
+Restart `opencode`.
 
-The installer will register a plugin entry similar to:
+If the plugin loads correctly, you should see a log like:
 
 ```txt
-file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js
-```
-
-### 8.2 Source-development path
-
-Run:
-
-```bash
-bun run src/cli.ts install
-bun run src/cli.ts doctor
-```
-
-If the installer can safely update the OpenCode config, you usually do not need to edit anything manually.
-
-> `install.sh` targets GitHub Releases installs. The project-local installer targets source-development setups.
-
-### 8.3 Manual plugin registration
-
-OpenCode config is usually located at:
-
-- `~/.config/opencode/opencode.json`
-- or `~/.config/opencode/opencode.jsonc`
-
-#### Option A: load the built plugin
-
-Build first:
-
-```bash
-bun run build
-```
-
-Then add this to OpenCode config:
-
-```json
-{
-  "plugin": [
-    "file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js"
-  ]
-}
-```
-
-#### Option B: load source directly during development
-
-```json
-{
-  "plugin": [
-    "file:///ABSOLUTE_PATH_TO_PROJECT/plugin.ts"
-  ]
-}
+[autopilot] Autopilot plugin loaded (... commands)
 ```
 
-### 8.4 Start OpenCode
+## Use
 
-Interactive mode:
-
-```bash
-opencode
-```
+Start with a natural-language request, for example:
 
-Server mode:
-
-```bash
-opencode serve
+```txt
+Add sorting to the product list page and make sure regression risks are reviewed.
 ```
 
-## 9. What you should see after loading
+Autopilot will guide the workflow through the available tools:
 
-The plugin exposes these tools/commands:
-
-- `workflow_channel`
 - `workflow_open`
 - `workflow_attach`
 - `workflow_status`
 - `workflow_answer`
 - `workflow_approve`
 - `workflow_resume`
-- `workflow_back`
-- `workflow_doctor`
 
-Recommended split-tool entrypoints:
+You usually only need to follow the next recommended tool shown by the workflow output.
 
-- `workflow_open`
-- `workflow_attach`
-- `workflow_status`
-- `workflow_answer`
-- `workflow_approve`
-- `workflow_resume`
-- `workflow_back`
+## Configuration
 
-Typical load log:
+Autopilot automatically creates these files when needed:
 
 ```txt
-[autopilot] Autopilot plugin loaded (... commands)
+.workflow-harness/autopilot.json
+~/.config/opencode/autopilot.json
 ```
 
-## 10. Directory layout
-
-### 10.1 Configuration layers
-
-- user default: `~/.config/opencode/workflow.json`
-- project override: `<repo>/.workflow-harness/workflow.json`
-- runtime state: `<repo>/.workflow-harness/workflows/<workflowId>/`
+If they are left empty, Autopilot uses default behavior.
 
-### 10.2 What each directory does
+### `autopilot.json`
 
-- `src/` — CLI entrypoints and top-level source files
-- `packages/runtime/` — workflow runtime implementation
-- `tests/` — tests
-- `scripts/` — auxiliary scripts
-- `.workflow-harness/` — runtime config, state, and artifacts
-- `dist/` — build output
-
-## 11. Minimal `workflow.json` example
-
-Start with a fully neutral config:
+Minimal example:
 
 ```json
 {
   "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
   "phases": {
+    "spec_refinement": { "requiredSkills": [] },
+    "plan": { "requiredSkills": [] },
     "develop": { "requiredSkills": [] },
+    "review": { "requiredSkills": [] },
     "test": { "requiredSkills": [] }
   }
 }
 ```
 
-Then add skills per project. For example, for a frontend-oriented project:
-
-```json
-{
-  "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
-  "phases": {
-    "develop": { "requiredSkills": ["frontend-design"] },
-    "test": { "requiredSkills": ["playwright"] }
-  }
-}
-```
-
-That frontend example is only an example. The workflow runtime is not frontend-bound by default.
+Field meanings:
 
-Recommendations:
+- `skillRoots`: directories to scan for skill files
+- `phases.<phase>.requiredSkills`: skills to inject into that phase
 
-- keep skill/profile config in global or project-level `workflow.json`
-- do not put skill config under `workflows/<workflowId>/`
-- run `workflow_doctor` or CLI `doctor` before using a new config
+Supported phases:
 
-## 12. FAQ
+- `spec_refinement`
+- `plan`
+- `develop`
+- `review`
+- `test`
 
-### Q1: What if `install` cannot update my OpenCode config?
+If an old `workflow.json` exists and `autopilot.json` does not, Autopilot can reuse the legacy file and warn you to migrate.
 
-Edit OpenCode config manually and add either the release plugin path or the local build path to the `plugin` array. Example:
+## Fallback Install
 
-```json
-{
-  "plugin": [
-    "file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js"
-  ]
-}
-```
-
-For source development, you can also point to your local `dist/plugin.js`.
+If you prefer a local file install instead of the npm package:
 
-If you are using the npm plugin mode, you can simply configure:
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot"]
-}
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
 ```
 
-### Q2: Why can’t I see workflow commands after building?
-
-That usually means the host integration layer has not actually registered the exported `workflowCommands` onto the host command/tool surface.
-
-### Q3: What should I validate first?
-
-Validate this order first:
+## Troubleshooting
 
-1. the host can import the plugin file
-2. the host can call the default export
-3. the host receives a plugin-like object
+### OpenCode fails to start
 
-Do not start by validating UI behavior first.
+Temporarily remove the plugin from `opencode.json`, restart OpenCode, then re-enable it after checking the config.
 
-### Q4: Any important rule for the plugin root entry?
+### The plugin loads but workflow commands do not appear
 
-The root `plugin.ts` entry should only expose a single host-callable default export. Do not expose extra internal classes or helper functions from the root entry.
+This usually means the host did not register the exported workflow tools correctly.
 
-## 13. Recommended reading
+### A workflow seems broken
 
-| Document | Purpose |
-|---|---|
-| `README.md` | Main entry for installation, release, and usage |
-| `WORKFLOW_SKILL_PROFILE_ARCHITECTURE_CN.md` | Skill/profile configuration design |
-| `OPENCODE_WORKFLOW_AGENT_GUIDE.md` | Agent/tool calling loop |
-| `REQUIREMENT_TEMPLATE.md` | Requirement input template |
+Delete the project runtime folder and start again:
 
-Internal planning notes, acceptance drafts, and status scratch docs can be kept locally under `docs_internal/`, which is ignored by default.
+```bash
+rm -rf .workflow-harness
+```
 
-## 14. Fastest path to a working setup
+## For source development
 
-If you just want the fastest local source setup:
+If you want to work on the plugin itself:
 
 ```bash
 bun install
-bun run src/cli.ts install
-bun run src/cli.ts doctor
+bun run typecheck
+bun test
 bun run build
-opencode
 ```
-
-Then:
-
-1. confirm `.workflow-harness/workflow.json` exists
-2. confirm `dist/plugin.js` exists
-3. if OpenCode does not auto-load the plugin, add `file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js` manually to config
-4. verify `workflow_open`, `workflow_attach`, and `workflow_status` are visible in the host

package/dist/packages/runtime/src/bootstrap/create-harness.d.ts

@@ -14,6 +14,7 @@ export interface CreateHarnessOptions {
     sessionClient?: OpencodeSessionClient;
     opencodeBaseUrl?: string;
     opencodePassword?: string;
+    homeDir?: string;
 }
 export declare function createHarness(baseDir: string, options?: CreateHarnessOptions): Promise<{
     stateStore: FileSystemWorkflowStateStore;

package/dist/packages/runtime/src/bootstrap/create-harness.js

@@ -1,11 +1,12 @@
 import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { HttpOpencodeSessionClient, InMemoryOpencodeSessionClient, } from "../../../adapters/opencode/src/opencode-session-client";
 import { DefaultPhaseTransition } from "../../../core/src/transitions/default-phase-transition";
 import { FileSystemArtifactEvaluator } from "../artifacts/file-system-artifact-evaluator";
 import { DefaultAttachService } from "../attach/attach-service";
 import { buildSkillRegistryWithWarnings } from "../config/skill-registry";
-import { resolveWorkflowConfig } from "../config/workflow-config";
+import { ensureAutopilotConfigFile, resolveWorkflowConfig, AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
 import { DefaultWorkflowEngine } from "../engine/default-workflow-engine";
 import { FileSystemWorkflowEventStore } from "../events/file-system-workflow-event-store";
 import { BasicRecoveryClassifier } from "../recovery/basic-recovery-classifier";
@@ -20,8 +21,11 @@ import { DefaultWorkflowWorkspace } from "../workspace/workflow-workspace";
 export async function createHarness(baseDir, options = {}) {
     await mkdir(join(baseDir, "workflows"), { recursive: true });
     const workspace = new DefaultWorkflowWorkspace(baseDir);
+    await ensureAutopilotConfigFile(workspace.workflowConfigFile());
+    await ensureAutopilotConfigFile(join(options.homeDir ?? homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME));
     const resolvedConfig = await resolveWorkflowConfig({
         projectConfigFile: workspace.workflowConfigFile(),
+        ...(options.homeDir ? { homeDir: options.homeDir } : {}),
     });
     const skillRegistryResult = await buildSkillRegistryWithWarnings(resolvedConfig.skillRoots);
     const skillRegistry = skillRegistryResult.registry;

package/dist/packages/runtime/src/config/workflow-config.d.ts

@@ -1,3 +1,6 @@
+export declare const AUTOPILOT_CONFIG_FILENAME = "autopilot.json";
+export declare const LEGACY_WORKFLOW_CONFIG_FILENAME = "workflow.json";
+export declare const DEFAULT_SKILL_ROOTS: string[];
 export type WorkflowConfigPhase = "spec_refinement" | "plan" | "develop" | "review" | "test";
 export type WorkflowPhaseConfig = {
     requiredSkills?: string[];
@@ -11,7 +14,9 @@ export type ResolvedWorkflowConfig = {
     phases: Partial<Record<WorkflowConfigPhase, WorkflowPhaseConfig>>;
     warnings: string[];
 };
+export declare const DEFAULT_AUTOPILOT_CONFIG: WorkflowConfigFile;
 export declare function resolveWorkflowConfig(args: {
     projectConfigFile: string;
     homeDir?: string;
 }): Promise<ResolvedWorkflowConfig>;
+export declare function ensureAutopilotConfigFile(filePath: string): Promise<void>;

package/dist/packages/runtime/src/config/workflow-config.js

@@ -1,6 +1,20 @@
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { readJsonFile } from "../shared/json-file";
+import { dirname, join } from "node:path";
+import { fileExists, readJsonFile, writeJsonFile } from "../shared/json-file";
+export const AUTOPILOT_CONFIG_FILENAME = "autopilot.json";
+export const LEGACY_WORKFLOW_CONFIG_FILENAME = "workflow.json";
+export const DEFAULT_SKILL_ROOTS = ["~/.claude/skills", "~/.config/opencode/skills"];
+export const DEFAULT_AUTOPILOT_CONFIG = {
+    skillRoots: DEFAULT_SKILL_ROOTS,
+    phases: {
+        spec_refinement: { requiredSkills: [] },
+        plan: { requiredSkills: [] },
+        develop: { requiredSkills: [] },
+        review: { requiredSkills: [] },
+        test: { requiredSkills: [] },
+    },
+};
 const EMPTY_CONFIG = {
     skillRoots: [],
     phases: {},
@@ -43,9 +57,84 @@ function mergeConfigs(base, incoming) {
     }
     return next;
 }
+async function readConfigFileWithWarnings(filePath, label) {
+    if (!(await fileExists(filePath))) {
+        return { config: null, warnings: [] };
+    }
+    try {
+        const raw = await readFile(filePath, "utf8");
+        if (!raw.trim()) {
+            return {
+                config: null,
+                warnings: [`${label} is empty and will be treated as defaults: ${filePath}`],
+            };
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                config: null,
+                warnings: [`${label} is not a JSON object and will be ignored: ${filePath}`],
+            };
+        }
+        return {
+            config: parsed,
+            warnings: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return {
+                config: null,
+                warnings: [`${label} contains invalid JSON and will be ignored: ${filePath}`],
+            };
+        }
+        throw error;
+    }
+}
+async function loadConfigWithLegacy(args) {
+    const preferred = await readConfigFileWithWarnings(args.preferredFile, args.label);
+    if (preferred.config || preferred.warnings.length > 0 || await fileExists(args.preferredFile)) {
+        return preferred;
+    }
+    const legacy = await readConfigFileWithWarnings(args.legacyFile, `Legacy ${args.label}`);
+    if (!legacy.config && legacy.warnings.length === 0) {
+        return legacy;
+    }
+    return {
+        config: legacy.config,
+        warnings: [
+            `Using legacy ${LEGACY_WORKFLOW_CONFIG_FILENAME}; migrate to ${AUTOPILOT_CONFIG_FILENAME}: ${args.legacyFile}`,
+            ...legacy.warnings,
+        ],
+    };
+}
 export async function resolveWorkflowConfig(args) {
-    const globalConfigFile = join(args.homeDir ?? homedir(), ".config", "opencode", "workflow.json");
-    const globalConfig = await readJsonFile(globalConfigFile);
-    const projectConfig = await readJsonFile(args.projectConfigFile);
-    return mergeConfigs(mergeConfigs(EMPTY_CONFIG, globalConfig), projectConfig);
+    const globalConfigFile = join(args.homeDir ?? homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME);
+    const globalLegacyFile = join(args.homeDir ?? homedir(), ".config", "opencode", LEGACY_WORKFLOW_CONFIG_FILENAME);
+    const projectLegacyFile = join(dirname(args.projectConfigFile), LEGACY_WORKFLOW_CONFIG_FILENAME);
+    const globalConfig = await loadConfigWithLegacy({
+        preferredFile: globalConfigFile,
+        legacyFile: globalLegacyFile,
+        label: `Global ${AUTOPILOT_CONFIG_FILENAME}`,
+    });
+    const projectConfig = await loadConfigWithLegacy({
+        preferredFile: args.projectConfigFile,
+        legacyFile: projectLegacyFile,
+        label: `Project ${AUTOPILOT_CONFIG_FILENAME}`,
+    });
+    const merged = mergeConfigs(mergeConfigs(EMPTY_CONFIG, globalConfig.config), projectConfig.config);
+    merged.warnings.push(...globalConfig.warnings, ...projectConfig.warnings);
+    return merged;
+}
+export async function ensureAutopilotConfigFile(filePath) {
+    if (await fileExists(filePath)) {
+        return;
+    }
+    const legacyFilePath = join(dirname(filePath), LEGACY_WORKFLOW_CONFIG_FILENAME);
+    const legacyConfig = await readJsonFile(legacyFilePath);
+    if (legacyConfig) {
+        await writeJsonFile(filePath, legacyConfig);
+        return;
+    }
+    await writeJsonFile(filePath, DEFAULT_AUTOPILOT_CONFIG);
 }

package/dist/packages/runtime/src/diagnostics/workflow-diagnostics-format.js

@@ -1,3 +1,4 @@
+import { AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
 const divider = "=".repeat(64);
 export function formatWorkflowDoctorResult(result) {
     const lines = [
@@ -50,7 +51,7 @@ export function formatWorkflowInstallResult(result) {
     const lines = [
         divider,
         `Workflow Install: ${result.ok ? "OK" : "ATTENTION"}`,
-        `Project workflow.json: ${result.projectWorkflowConfigFile}`,
+        `Project ${AUTOPILOT_CONFIG_FILENAME}: ${result.projectWorkflowConfigFile}`,
         `OpenCode config: ${result.opencodeConfigFile}`,
         `Plugin entry: ${result.pluginEntry}`,
     ];

package/dist/packages/runtime/src/diagnostics/workflow-doctor.d.ts

@@ -20,4 +20,6 @@ export type WorkflowDoctorResult = {
     nextSteps: string[];
     warnings: string[];
 };
-export declare function runWorkflowDoctor(workspace: WorkflowWorkspace): Promise<WorkflowDoctorResult>;
+export declare function runWorkflowDoctor(workspace: WorkflowWorkspace, options?: {
+    homeDir?: string;
+}): Promise<WorkflowDoctorResult>;

package/dist/packages/runtime/src/diagnostics/workflow-doctor.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { buildSkillRegistryWithWarnings } from "../config/skill-registry";
-import { resolveWorkflowConfig } from "../config/workflow-config";
+import { AUTOPILOT_CONFIG_FILENAME, resolveWorkflowConfig } from "../config/workflow-config";
 async function fileExists(filePath) {
     try {
         await access(filePath);
@@ -27,11 +27,12 @@ function gitignoreHasWorkflowHarness(content) {
         return normalized.includes(".workflow-harness/");
     });
 }
-export async function runWorkflowDoctor(workspace) {
+export async function runWorkflowDoctor(workspace, options = {}) {
     const projectConfigFile = workspace.workflowConfigFile();
-    const globalConfigFile = join(homedir(), ".config", "opencode", "workflow.json");
+    const globalConfigFile = join(options.homeDir ?? homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME);
     const resolvedConfig = await resolveWorkflowConfig({
         projectConfigFile,
+        ...(options.homeDir ? { homeDir: options.homeDir } : {}),
     });
     const registryResult = await buildSkillRegistryWithWarnings(resolvedConfig.skillRoots);
     const checks = [];
@@ -52,7 +53,7 @@ export async function runWorkflowDoctor(workspace) {
     }
     const hasGlobalConfig = await fileExists(globalConfigFile);
     if (!hasGlobalConfig) {
-        warnings.push(`Global workflow.json not found: ${globalConfigFile}`);
+        warnings.push(`Global ${AUTOPILOT_CONFIG_FILENAME} not found: ${globalConfigFile}`);
     }
     const workspaceRoot = workspace.baseDir().endsWith(".workflow-harness")
         ? dirname(workspace.baseDir())
@@ -91,10 +92,10 @@ export async function runWorkflowDoctor(workspace) {
     });
     const nextSteps = [];
     if (!(await fileExists(projectConfigFile))) {
-        nextSteps.push(`Run installer to generate project workflow.json: ${projectConfigFile}`);
+        nextSteps.push(`Run installer to generate project ${AUTOPILOT_CONFIG_FILENAME}: ${projectConfigFile}`);
     }
     if (resolvedConfig.skillRoots.length === 0) {
-        nextSteps.push("Add skillRoots to workflow.json if you want phase skill injection");
+        nextSteps.push(`Add skillRoots to ${AUTOPILOT_CONFIG_FILENAME} if you want phase skill injection`);
     }
     if (missingSkills.length > 0) {
         nextSteps.push("Fix missing requiredSkills or add corresponding skill files under configured skillRoots");

package/dist/packages/runtime/src/install/workflow-installer.js

@@ -1,23 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { access } from "node:fs/promises";
-import { writeJsonFile } from "../shared/json-file";
-const DEFAULT_WORKFLOW_CONFIG = {
-    skillRoots: ["~/.claude/skills", "~/.config/opencode/skills"],
-    phases: {
-        develop: { requiredSkills: [] },
-        test: { requiredSkills: [] },
-    },
-};
-async function fileExists(filePath) {
-    try {
-        await access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+import { ensureAutopilotConfigFile, AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
+import { fileExists, writeJsonFile } from "../shared/json-file";
 function stripJsonComments(input) {
     return input
         .replace(/^\s*\/\/.*$/gm, "")
@@ -44,18 +28,18 @@ async function resolveOpencodeConfigFile(opencodeConfigDir) {
 export async function runWorkflowInstall(args) {
     const repoRoot = resolve(args.cwd);
     const harnessDir = join(repoRoot, ".workflow-harness");
-    const projectWorkflowConfigFile = join(harnessDir, "workflow.json");
+    const projectWorkflowConfigFile = join(harnessDir, AUTOPILOT_CONFIG_FILENAME);
     const opencodeConfigDir = join(args.homeDir, ".config", "opencode");
+    const globalAutopilotConfigFile = join(opencodeConfigDir, AUTOPILOT_CONFIG_FILENAME);
     const pluginEntryFile = args.options?.pluginEntryFile ?? "dist/plugin.js";
     const pluginEntry = `file://${join(repoRoot, pluginEntryFile)}`;
     const configResolution = await resolveOpencodeConfigFile(opencodeConfigDir);
     const opencodeConfigFile = join(opencodeConfigDir, "opencode.json");
     const warnings = [...configResolution.warnings];
     await mkdir(harnessDir, { recursive: true });
-    if (!(await fileExists(projectWorkflowConfigFile))) {
-        await writeJsonFile(projectWorkflowConfigFile, DEFAULT_WORKFLOW_CONFIG);
-    }
+    await ensureAutopilotConfigFile(projectWorkflowConfigFile);
     await mkdir(opencodeConfigDir, { recursive: true });
+    await ensureAutopilotConfigFile(globalAutopilotConfigFile);
     if (!(await fileExists(configResolution.filePath))) {
         await writeJsonFile(opencodeConfigFile, {
             plugin: [pluginEntry],

package/dist/packages/runtime/src/plugin/workflow-plugin-entry.js

@@ -5,10 +5,11 @@ import { createHarness } from "../bootstrap/create-harness";
 import { runWorkflowDoctor } from "../diagnostics/workflow-doctor";
 import { runWorkflowInstall } from "../install/workflow-installer";
 import { SdkOpencodeSessionClient, } from "../../../adapters/opencode/src/opencode-session-client";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
 import { z } from "zod";
+import { readJsonFile } from "../shared/json-file";
+import { DefaultWorkflowWorkspace } from "../workspace/workflow-workspace";
 const workflowIdSchema = z.string().min(1).describe("Workflow identifier");
 const WORKFLOW_PRIMARY_AGENT_PROMPT = `You are the workflow execution agent.
 
@@ -29,7 +30,7 @@ Hard rules:
 - If the user provides natural language only, keep it as-is and let the workflow runtime + downstream AI refinement handle understanding and document selection.
 `;
 const WORKFLOW_PRIMARY_AGENT_DESCRIPTION = "Primary workflow agent that drives refine->plan->develop->review->test via workflow tools";
-const WORKFLOW_PRIMARY_AGENT_MODEL = "ppchat-codex/gpt-5.4";
+const WORKFLOW_PRIMARY_AGENT_MODEL = "openai/gpt-5.5";
 function buildPrimaryAgentMetadata(baseDir) {
     return {
         name: "workflow",
@@ -77,14 +78,8 @@ async function syncHostTodos(args) {
     if (!todoClient?.list || !todoClient.create || !todoClient.update) {
         return;
     }
-    const stateFile = join(args.baseDir, "workflows", args.workflowId, "workflow-state.json");
-    let workflow = null;
-    try {
-        workflow = JSON.parse(await readFile(stateFile, "utf8"));
-    }
-    catch {
-        return;
-    }
+    const workspace = new DefaultWorkflowWorkspace(args.baseDir);
+    const workflow = await readJsonFile(workspace.workflowStateFile(args.workflowId));
     if (!workflow?.activeSessionId || !workflow.phase || !workflow.status) {
         return;
     }
@@ -320,7 +315,7 @@ export async function workflowPlugin(input) {
                 },
             },
             workflow_install: {
-                description: "Generate workflow.json and safely register the plugin in OpenCode config.",
+                description: "Generate autopilot.json and safely register the plugin in OpenCode config.",
                 args: {},
                 execute: async () => {
                     return JSON.stringify(await runWorkflowInstall({

package/dist/packages/runtime/src/shared/json-file.d.ts

@@ -1,2 +1,3 @@
+export declare function fileExists(filePath: string): Promise<boolean>;
 export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
 export declare function writeJsonFile(filePath: string, value: unknown): Promise<void>;

package/dist/packages/runtime/src/shared/json-file.js

@@ -1,5 +1,14 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+export async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function readJsonFile(filePath) {
     try {
         const raw = await readFile(filePath, "utf8");

package/dist/packages/runtime/src/workspace/workflow-workspace.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
 export class DefaultWorkflowWorkspace {
     root;
     constructor(root) {
@@ -9,6 +10,9 @@ export class DefaultWorkflowWorkspace {
         if (!normalized) {
             throw new Error("workflowId must be a non-empty string");
         }
+        if (normalized.includes("..") || normalized.includes("/") || normalized.includes("\\")) {
+            throw new Error("workflowId must not contain path separators or traversal sequences");
+        }
         return normalized;
     }
     baseDir() {
@@ -18,7 +22,7 @@ export class DefaultWorkflowWorkspace {
         return join(this.root, "workflows");
     }
     workflowConfigFile() {
-        return join(this.root, "workflow.json");
+        return join(this.root, AUTOPILOT_CONFIG_FILENAME);
     }
     workflowDir(workflowId) {
         return join(this.workflowsRoot(), this.normalizeWorkflowId(workflowId));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fkqfkq123/opencode-autopilot",
   "private": false,
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "An OpenCode plugin for attached-session workflow execution with refinement, planning, development, review, and test phases.",
   "type": "module",
   "packageManager": "bun@1.3.5",
@@ -24,7 +24,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "GUIDE.zh-CN.md"
   ],
   "publishConfig": {
     "access": "public"