@ethan.carter/autocode 0.0.0-stage → 0.0.2

package/dist/hosts/templates/en/commands/auto-fix.ejs

@@ -0,0 +1,69 @@
+---
+description: Locate the original defect report (pasted error / ticket URL / work item / file), produce the defect analysis restated in this project's business terms plus a fix plan, for review and confirmation; fixes along the plan once the knowledge base reaches the development threshold and the user agrees
+argument-hint: "<what to fix, or where the report is: pasted text / URL / work item / file>"
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep, Edit, WebFetch, mcp__*
+<% } -%>
+autocode-template: 3
+---
+
+# /auto-fix
+
+## Step 1: locate the original defect report
+`$ARGUMENTS` is what the user said, not necessarily the report itself. Decide where the source is, in this order, and stop at the first hit:
+1. The user pasted an error, log or reproduction steps → that is the source; take it verbatim, never rewrite or summarise.
+2. The user gave a ticket URL → fetch the page body with the web-fetch tool.
+3. The user refers to a work item in a project tool (Feishu Project, Jira, ...) → fetch title, description and reproduction steps with the matching MCP tool.
+4. The user refers to a file in the repo → Read it.
+5. None of the above → the user's words are the source; append the relevant symptoms, expected behaviour and known files from the conversation, each marked "from conversation".
+Put one source comment on the first line of the text: `<!-- autocode-source: conversation|url|mcp|file|prompt <reference> -->`.
+When fetching the source:
+- Feishu / Lark document links (`/wiki/`, `/docx/`) cannot be web-fetched: use lark-cli or a Feishu MCP when available to get the Markdown body, and download the images in it.
+- Pages behind a login or rendered by scripts: use a browser automation tool when available.
+- PDF: Read it directly (images and CJK PDFs included); do not use extraction tools such as pdftotext.
+- Images, interface documents and other material the source refers to are not pasted into it: put them in a scratch folder inside the repo (not under `.autocode/`) and hand it over with `--attachments` in step 2. The engine keeps a copy in the change folder; the scratch folder can go afterwards.
+
+## Step 2: run (source goes through stdin)
+    autocode fix "$ARGUMENTS" <<'AUTOCODE_ORIGINAL'
+    <source text>
+    AUTOCODE_ORIGINAL
+Bash tool, timeout of at least <%= timeoutMinutes %> minutes. The source always goes through stdin, never into the argument.
+- Material to hand over: add `--attachments <scratch folder>`.
+- The user says "no plan yet" / "just the restatement": add `--no-plan` and read only the integrate document in step 3; when the user wants the plan later, run `autocode fix --plan-only <document id>` (plans from the existing restatement, reads no stdin).
+The "Result" section gives the folder path, the source kind and the version; "Changes" lists every generated file.
+
+## Step 3: read the files in order and present them
+1. integrate.defect.md - the symptom, root cause and related business rules restated in this project's own business terms.
+2. defect.plan.md - the fix plan. If it is an overview (it has a sub-plans section), read defect.plan.01-*.md, 02-*.md ... in order.
+3. original.defect.md - the source; consult it only when the first two are ambiguous.
+Present to the user: the restated symptom, the root cause (or the candidate list when it says "not located"), how many plans and what each covers, the open questions, and this version number. When the root cause is "not located", give the user the candidates and rerun with the id once they add clues.
+
+After every generation or revision (`--no-plan` and `--plan-only` included), first give the user a **summary of this version** with four fixed items:
+1. **Version**: vn; for a revision, vold → vnew.
+2. **What changed**: for a new document, the gist of the symptom and root cause and of the plans; for a revision, go through the "restatement sections changed" listed under "Result" section by section and say what each now reads (open the file and read them, never from memory), and through the plan files the "Changes" section lists as added / updated / removed.
+3. **Questions for the developer**: every item under "New questions" (subject, severity, question file), plus the rest of the "Open questions" section of integrate.defect.md; "none" when there are none.
+4. **Can it be fixed directly**: relay the development-threshold line under "Next", and what is missing when it is not ready.
+
+## Step 4: ask for review
+Ask three things: are the symptom and root cause right, can the plan be done this way, how should the open questions be answered. Then:
+- Changes wanted: let the user edit the files, or rerun this command with the document id and the feedback (`/auto-fix <document id> <feedback>`); the engine produces a new version; back to step 3.
+- Confirmed: set `confirmation` to `confirmed` in the frontmatter of integrate.defect.md and every plan file. That is the only field you may change.
+- Undecided: change nothing; the documents stay pending.
+
+## Step 5: may the knowledge base carry the fix
+Read the development-threshold line under "Next" in step 2's output (`data.dev` with `--json`).
+- Ready (`dev.ready` is true) and the user confirmed the restatement and every plan in step 4 → ask the user whether to fix the plan now. Start only on a yes:
+  - Fix strictly along the plan steps and the code locations and anchors the restatement lists; before touching code, read the related knowledge-base documents with `autocode query <anchor> --json`, then the code.
+  - After each plan step, tell the user which files it changed.
+  - When a module, interface or data structure outside the plan has to change, stop and ask the user first.
+  - At the end, list every changed file with its plan step and ask the user to review the code.
+- Not ready (`dev.ready` is false), documents unconfirmed, or the user does not want it now → relay what the "First" list names (answer questions, confirm business terms, run /auto-wiki first); this command ends here. Do not start writing code; do not run autocode wiki.
+
+On either branch, never run autocode wiki and never change files under `.autocode/`; the knowledge base updates when the user runs /auto-wiki, from the code and the confirmed documents.
+
+## Never
+- Outside the ready branch of step 5, never fix the defect or change business code; never fix below the threshold or on unconfirmed documents.
+- Never create or edit anything under `.autocode/`; the only exception is the `confirmation` field after the user explicitly confirms.
+- Never answer the engine's questions on the user's behalf.
+- Never put the source into the command-line argument; never rewrite or summarise it.
+- Pending documents are not read by the knowledge base; never imply they already are.

package/dist/hosts/templates/en/commands/auto-init.ejs

@@ -0,0 +1,22 @@
+---
+description: Initialise or refresh autocode - skeleton, code graph, host integration (zero AI)
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep
+<% } -%>
+autocode-template: 1
+---
+
+# /auto-init
+
+## Run
+From the project root, with the Bash tool and a timeout of at least <%= timeoutMinutes %> minutes; never use inline `!` execution:
+    autocode init
+
+## Relay
+The output is sectioned Markdown. Relay it section by section, verbatim in substance; do not embellish or add conclusions the engine did not state.
+- An empty "Changes" section means the repo was already initialised and this was a refresh; say so.
+- "no usable provider" means Claude Code or the Codex CLI is missing; it does not affect initialisation itself.
+
+## Never
+- Never create or edit anything under `.autocode/`; it is generated.
+- Never decompose the work yourself or bypass the command to edit documents; the workflow lives in the engine.

package/dist/hosts/templates/en/commands/auto-wiki.ejs

@@ -0,0 +1,42 @@
+---
+description: Generate or update the business knowledge base; accepts a natural-language instruction
+argument-hint: "[instruction, e.g. only one module / preview / rewrite everything]"
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep, Edit
+<% } -%>
+autocode-template: 2
+---
+
+# /auto-wiki
+
+## Run
+From the project root, with the Bash tool and a timeout of at least <%= timeoutMinutes %> minutes; never use inline `!` execution:
+    autocode wiki "$ARGUMENTS"
+(Pass no quotes when there is no argument.)
+If the user states how the business actually works (business facts), pass them in the instruction as they are: the engine records their words as human-confirmed answers and edits the related documents accordingly; do not look for a file to write them into.
+If the instruction means rewriting every document ("rewrite everything", "full"), it is expensive and irreversible: confirm with the user first.
+
+## Relay
+The output is sectioned Markdown. Relay it section by section; do not embellish or add conclusions the engine did not state.
+- A "preview" instruction only prints the affected list; relay it as is.
+- "Nothing to update" is a valid outcome; relay the reason.
+- "cannot resolve the instruction" → relay the reason, then use `autocode query <keyword>` to find the related unit documents and domains (the document file names and domain ids it reports) and list them for the user to confirm; once they agree, run `autocode wiki --scope unit:<file>,domain:<domain id>` (no instruction) to rewrite only those.
+- "No document relates to the request" → handle it like the previous item: find the related documents with `autocode query`, and run with `--scope` once the user confirms.
+- "Review unmet" under next steps → relay each one (the requirement as quoted + what is missing) and ask whether to rephrase and run again, or leave it.
+- "not initialised" → suggest /auto-init; "no usable provider" → suggest installing Claude Code or the Codex CLI.
+
+## Questions
+The engine never stops to ask: where it was unsure it wrote the documents on an assumption and left the question in the output. Now you ask.
+<% if (host === "claude") { -%>
+1. For every item under "Answer first", ask the user with the question tool (AskUserQuestion): title = the subject, description = the current-behaviour line from the output, options = the options from the output plus "Other" and "Later". Never invent options; never choose for the user.
+<% } else { -%>
+1. For every item under "Answer first", list the subject, current behaviour and options in the conversation and ask the user to answer. Never invent options; never choose for the user.
+<% } -%>
+2. When the user answers (an answer of "accept" is written as is: the engine then adopts the document's assumption), open that question file and write the answer verbatim under `## 回答 / Answer` (no summary, no additions); set three frontmatter fields: `status: answered`, `answered_at: <ISO time now>`, `answered_via: host-agent`. Touch nothing else. Leave "Later" items untouched.
+3. If at least one answer was written, run `autocode wiki` once more without an instruction (incremental) and relay the result; the affected documents are updated from the answers in that pass.
+4. "New questions" are listed only; say they can be answered now, or later by writing directly under `## 回答 / Answer` in the question file (`.autocode/questions/`), which takes effect on the next `autocode wiki`. Handle any the user wants to answer now with step 2.
+
+## Never
+- Never create or edit anything under `.autocode/`; the only exception is writing the user's answer in Questions step 2.
+- Never answer the engine's questions on the user's behalf; never rephrase the user's answer.
+- Never decompose the work yourself or bypass the command to edit documents; the workflow lives in the engine.

package/dist/hosts/templates/en/marker-block.ejs

@@ -0,0 +1,6 @@
+## autocode business knowledge base (maintained by autocode install; do not edit this block)
+This repository keeps a business knowledge base in `.autocode/`: code says "how", the knowledge base says "why and under which rules". Query before coding: `autocode query <keyword or anchor> --json` (documents, business terms, entries, anchors; a document's frontmatter `up` / `down` point to the next layer), `autocode graph <anchor> --json` (call relations), question files with `status: open` under `.autocode/questions/` (open questions).
+Business-term discipline: reuse the names from the business terms verbatim; never coin synonyms; a term whose status is confirmed is the settled wording.
+Only two things may be written into `.autocode/`: the user's answer to a question (verbatim, into the question file's answer section) and the user's confirmation of a requirement / defect document (the `confirmation` field); nothing else.
+Do not go back and change requirement / defect documents when changing code; they record the intent at the time. The knowledge base follows the code; divergences become questions at the next wiki update for a human to settle.
+Slash commands and their CLI (Codex users call the CLI on the right directly): /auto-init → `autocode init`; /auto-wiki → `autocode wiki "<instruction>"`; /auto-check → `autocode check`; /auto-feat → `autocode feat "<the user's words>" < source`; /auto-fix → `autocode fix "<the user's words>" < source`.

package/dist/hosts/templates/en/skill-graph.ejs

@@ -0,0 +1,30 @@
+---
+name: autocode-graph
+description: Query this repository's code-graph call chains - give an anchor (a function, method or type name; a shared name written file::qualifiedName) or a keyword and get the multi-hop chain of who calls it and what it calls (the graph engine's own call graph), plus the symbols in its file; list every entry (routes, pages, jobs, consumers). Query before walking a call chain or locating code instead of grepping file by file. For the business meaning use autocode-query; for the tools see autocode.
+autocode-template: 2
+---
+
+# autocode code graph
+
+autocode builds the code graph from the source; it is the bottom layer of the knowledge base, and the anchors in documents are its node names. `autocode graph` calls the graph engine's own call graph and search directly: read-only, no AI, usable while a wiki runs.
+
+## Query
+| Need | Command |
+|---|---|
+| an anchor's call chain (2 hops each way by default) | `autocode graph <anchor>` (call trees to read) / `autocode graph <anchor> --json` (machine-readable) |
+| look further or closer | `--depth <1-5>` |
+| only part of the name is known | `autocode graph <keyword>` (the graph engine's full-text / fuzzy search) |
+| which entries exist and which unit document covers each | `.autocode/entries.md` (entry catalog by module, with node names, files and lines) |
+
+## Reading the result
+- Without `--json`: the first line is the resolved symbol with its file and line, then two trees — "callers" (`←`, what reaches it) and "callees" (`→`, where it goes); one indent is one hop more; `(↺)` marks a node already shown (recursion or a join), `… +N` a level cut for width.
+- `--json`: `symbol`; `chain.nodes` (each node's `anchor`, `kind`, file and line), `chain.edges` (`from` → `to`, with the call-site line), `chain.tree` (the same two trees as text); `callers` / `callees` are the one-hop short lists, `siblings` the symbols of the same file.
+- "N symbols share that name" / `candidates.reason = ambiguous`: nothing is guessed; pick one and query again with its `file::qualifiedName`.
+- "no symbol has that name; the search found" / `candidates.reason = keyword`: pick a hit and query again; a single hit is already explored. `truncated` true means there are more; use a more specific keyword.
+- "nothing in the graph": it may be a variable or a constant (use Grep), or refresh the graph by running /auto-wiki first.
+
+## With the knowledge base
+- From business words: find the documents with `autocode query` first; the `anchors` and `entries` in their frontmatter are names to query the graph with.
+- From code: with an anchor in hand, `autocode query <anchor> --json` tells which unit document and domain it belongs to.
+
+This file is maintained by `autocode install`; manual edits are overwritten on the next install.

package/dist/hosts/templates/en/skill-query.ejs

@@ -0,0 +1,34 @@
+---
+name: autocode-query
+description: Query the documents of this repository's business knowledge base (.autocode/) - find documents by anchor or by business words, read what a piece of code means for the business, its rules, which business a change affects, the exact wording of a business term. Query before coding instead of guessing from source. For call relations and code structure use autocode-graph; for updating documents and the other tools see autocode.
+autocode-template: 2
+---
+
+# autocode knowledge-base query
+
+Code answers "how"; the knowledge base answers "why, for whom, under which rules".
+
+## Query (before coding)
+| Need | Command |
+|---|---|
+| an anchor (function, method or type name) or business words → related documents, business-term definitions, entries, related requirement documents | `autocode query <anchor or keyword> --json` |
+| call relations, what a name is in the code | see the autocode-graph skill |
+| open business questions | question files with `status: open` under `.autocode/questions/` |
+
+## Layers and how to read them
+The knowledge base has four layers, bottom to top; each document's frontmatter `layer` says which, and `up` / `down` point one layer up and down (paths relative to `.autocode/`):
+1. code graph: query it with `autocode graph` (autocode-graph skill)
+2. entries: `.autocode/entries.md`, one line per entry with its node name, file and line, and the unit document covering it
+3. units: one document per business capability; `down` points at its entries
+4. domains: one document per module, the end-to-end journey; `down` lists its units
+
+- Holding an anchor (a function, method or type name) or an entry (a route, a page path): `autocode query <anchor> --json`; documents naming that anchor come first (`anchorHit`) and `entries` gives its place in the entry catalog; follow `up` to the domain and `down` to the entries; read the implementation with `autocode graph <anchor>`.
+- Holding business words: query the business term first, read the documents it hits, and walk `up` / `down` the same way.
+- A document's `confidence` is computed by code (the generation's own assessment, open questions, stale anchors, pending business terms); its closing "Development entry" section says whether it is ready for automated development and what is missing.
+
+Every turn already injects where the knowledge base lives, the domain catalog, and the business terms and document clues picked from the current message and the recent turns (with why each was picked); the clues are not complete — never guess content from a title, read the document or fetch it with query.
+
+## Business-term discipline
+In identifiers, comments, documents and PR descriptions, reuse the names from the business terms verbatim, a confirmed term being the settled wording; query when unsure; ask the user in the conversation when nothing is found.
+
+This file is maintained by `autocode install`; manual edits are overwritten on the next install.

package/dist/hosts/templates/en/skill.ejs

@@ -0,0 +1,54 @@
+---
+name: autocode
+description: How to use the tools that maintain this repository's business knowledge base (.autocode/) - onboarding (init), generating and updating documents (wiki), the health check (check), restating requirements (feat) and defects (fix), host installation (install / uninstall), their extra flags, and what people maintain by hand. Read it to update documents, write requirement or defect documents, or look into a knowledge-base problem; to read documents use autocode-query, for code structure autocode-graph.
+autocode-template: 4
+---
+
+# autocode knowledge-base tools
+
+The engine generates and maintains the knowledge base `.autocode/`: you run the commands and relay their results faithfully; you never edit documents by hand. The slash commands are these commands' entry points in the host (Codex calls the CLI on the right directly). The Claude Code / Codex the engine starts sees what a developer starting it in this directory sees — the skills, plugins, slash commands and MCP servers here — under the developer's own permission settings.
+
+## Commands
+| Command | Slash command | What it does | AI |
+|---|---|---|---|
+| `autocode init` | /auto-init | onboard a repository: skeleton, code graph, reference index, available models | no |
+| `autocode wiki ["instruction"]` | /auto-wiki | generate / update the knowledge-base documents | yes |
+| `autocode check` | /auto-check | health check: stale anchors, coverage blind spots, pending business terms, documents below the development threshold… | no |
+| `autocode feat "<user's words>" < original` | /auto-feat | restate a requirement in this project's business terms and plan it | yes |
+| `autocode fix "<user's words>" < original` | /auto-fix | restate a defect, locate its cause and plan the fix | yes |
+| `autocode install [claude\|codex\|all]` | — | install / refresh the host files (slash commands, skills, marker blocks, hooks) | no |
+| `autocode uninstall [claude\|codex\|all]` | — | remove the host files; the knowledge base stays | no |
+
+Every command takes `--json` for the machine-readable envelope; the default output is sectioned Markdown (result / changes / questions / next), relayed section by section.
+
+## wiki
+- Without an instruction: incremental. Code changes, answered questions, changed business terms and entries without a document decide which documents change, one call per document; when nothing changed it calls no AI and only refreshes the layer links, the confidence and the development-entry section.
+- With an instruction (natural language): "update only module X", "add to the entry Y", "preview", "rewrite everything". Unit titles, entries, anchors and domain names the instruction names are matched by code; business facts it states are recorded as human-confirmed answers. "Rewrite everything" is expensive: ask the user first.
+- `--scope unit:<file name>,domain:<domain id>`: rewrite exactly these documents (no instruction).
+- `--check`: run check first and rewrite only the documents its report names (same as `autocode check --fix`).
+- Only one wiki / init / `check --fix` runs at a time (they rewrite the knowledge base); query, graph, check, feat and fix may run alongside. On "another … is running", wait for it to end and retry; do not rebuild the code graph.
+- Handle the questions in the output as the /auto-wiki "Questions" section says; after writing answers back, run wiki once more without an instruction.
+
+## check
+- Zero AI; findings grouped by severity. `--fix`: after the report, rewrite the documents with stale anchors or broken rules.
+- Usual findings: `stale-anchor` · `anchor-loose` (an older anchor that breaks the rule; fixed at the next rewrite) · `term-pending` (business terms awaiting a human) · `dev-below-threshold` (below the development threshold, with what holds it back) · `layer-link-dangling` (fixed by the next wiki) · `host-outdated` (run `autocode install`).
+
+## feat / fix
+- The original always goes through stdin (heredoc); the argument carries only the user's words. Rerunning with the document id revises it into a new version.
+- `--no-plan`: write the original and the restatement only; once settled, `--plan-only <document id>` plans from the restatement.
+- `--attachments <folder inside the repo>`: images, PDFs, interface documents; the engine keeps a copy in the change folder.
+- `dev` in the result: whether every document involved reaches the development threshold, with what holds it back otherwise; only when ready and confirmed by the user may the plan be implemented (step 5 of /auto-feat and /auto-fix).
+
+## What people maintain by hand (extended use)
+- Answers: the `## Answer` section of a question file under `.autocode/questions/`, taken up by the next wiki.
+- Confirming business terms: set the leading "Status" column of a business-term row to confirmed; the AI never changes it again, the documents using it are updated and their confidence rises.
+- Project brief `.autocode/project.md`: facts and the module split written by the project owner; it outranks anything inferred from code.
+- Configuration `.autocode/config.yaml`: `wiki.devThreshold` (development threshold, 0.8 by default), `wiki.reviewRounds`, `budget`, `concurrency`, `entries.exclude`.
+- Requirement / defect documents: people may edit the restatement and the plans; set `confirmation` to `confirmed` when settled; unconfirmed ones are not read by the knowledge base.
+
+## The only two things you may write
+- The user's answer to a question: verbatim, into the question file's answer section.
+- The user's confirmation of a requirement / defect document: the `confirmation` field.
+Nothing else. After code changes the user runs /auto-wiki to update the knowledge base. Do not go back and change requirement / defect documents when changing code: they record the intent at the time and divergence from the code is normal; the knowledge base follows the code, and divergences become questions at the next wiki update for a human to settle.
+
+This file is maintained by `autocode install`; manual edits are overwritten on the next install.

package/dist/hosts/templates/zh/commands/auto-check.ejs

@@ -0,0 +1,25 @@
+---
+description: 知识库体检:失效、孤儿、frontmatter、宿主文件版本、技术债(零 AI)
+argument-hint: "[范围]"
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep
+<% } -%>
+autocode-template: 1
+---
+
+# /auto-check
+
+## 调用
+在项目根目录用 Bash 工具执行,超时不少于 <%= timeoutMinutes %> 分钟,不要用内联 `!` 执行:
+    autocode check "$ARGUMENTS"
+(无参数时不传引号对。)
+
+## 转述
+命令输出是分节 Markdown,按「高 / 中 / 低」如实转述给用户;不美化、不补写引擎没说的结论。
+- `host-outdated` 表示宿主侧文件缺失或版本落后,建议用户运行 `autocode install`。
+- 报错「未初始化」→ 提示先运行 /auto-init。
+
+## 禁止
+- 不要创建或编辑 `.autocode/` 下的任何文件,那是生成物。
+- 不要替用户回答引擎提出的问题。
+- 不要自行拆解步骤或绕过命令直接改文档;工作流全部在引擎内。

package/dist/hosts/templates/zh/commands/auto-feat.ejs

@@ -0,0 +1,69 @@
+---
+description: 找到原始需求文档(对话粘贴 / URL / 工作项 / 文件),生成用本项目业务术语整合重述的需求与实现计划,供审阅与确认;知识库达到开发阈值且用户同意时按计划实现
+argument-hint: "<要做什么,或原文在哪:粘贴的内容 / URL / 工作项 / 文件>"
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep, Edit, WebFetch, mcp__*
+<% } -%>
+autocode-template: 3
+---
+
+# /auto-feat
+
+## 第一步:找到原始需求文档
+`$ARGUMENTS` 是用户的话,不一定是需求本身。按下面顺序判断原文在哪,取到即止:
+1. 用户在对话里粘贴了需求原文 → 原文就是它,逐字取用,不改写、不概括。
+2. 用户给了 URL → 用网页抓取工具取回正文。
+3. 用户指的是项目管理工具里的工作项(飞书项目、Jira 等)→ 用对应 MCP 工具取回标题、描述、验收标准。
+4. 用户指的是仓库里的文件 → Read。
+5. 都不是 → 用户的话本身就是原文;再把对话里相关的背景、目标、已知文件、约束逐条补在后面,标明「来自对话」。
+取回的原文第一行写一条来源注释:`<!-- autocode-source: conversation|url|mcp|file|prompt <引用> -->`。
+取原文时还要注意:
+- 飞书 / Lark 文档链接(`/wiki/`、`/docx/`)用网页抓取拿不到:有 lark-cli 或飞书 MCP 就用它取 Markdown 正文,正文里的图片一并下载。
+- 要登录或靠脚本渲染的网页:有浏览器自动化工具就用它取正文。
+- PDF:直接用 Read 读(图片和中文 PDF 都能读),不要用 pdftotext 一类的抽取工具。
+- 原文引用的图片、接口文档等材料不要拼进原文:放进仓库里的一个临时文件夹(不放在 `.autocode/` 下),第二步用 `--attachments` 交给引擎。引擎会复制一份到变更文件夹,之后临时文件夹可以删掉。
+
+## 第二步:调用(原文走 stdin)
+    autocode feat "$ARGUMENTS" <<'AUTOCODE_ORIGINAL'
+    <原文>
+    AUTOCODE_ORIGINAL
+Bash 工具,超时不少于 <%= timeoutMinutes %> 分钟。原文一律用 stdin,不塞进参数。
+- 有附件:加 `--attachments <临时文件夹>`。
+- 用户说「先不出计划」「只要重述」这类意思:加 `--no-plan`,第三步只读整合文档;之后用户要计划时运行 `autocode feat --plan-only <文档id>`(按已有重述只生成计划,不读 stdin)。
+输出的「结果」给出文件夹路径、原文来源与版本号,「变更」列出生成的每份文件。
+
+## 第三步:按顺序读文件,呈现给用户
+1. integrate.prd.md —— 用这个项目自己的业务术语、业务单元和代码位置整合重述的需求。
+2. prd.plan.md —— 实现计划。若它是总览(有「子计划」一节),再按编号依次读 prd.plan.01-*.md、02-*.md……;每份子计划标了依赖。
+3. original.prd.md —— 原文,只在前两份有歧义时回看。
+向用户呈现:需求重述的要点、涉及的业务单元与代码、计划份数与每份范围、未决问题、本次版本号。
+
+每次生成或改版之后(包括 `--no-plan`、`--plan-only`),先给用户一段**本次版本小结**,固定四项:
+1. **版本**:v版本号;改版时写 v旧 → v新。
+2. **本次修改**:新建时概括需求重述与计划要点;改版时按输出「结果」里的「整合文档改动段落」逐段读这些段落的新内容,说明这一版改成了什么(打开文件读,不凭印象),计划按「变更」里新增 / 更新 / 移除的文件逐份说明。
+3. **需要开发回答的问题**:输出「新增问题」逐条列出(主题、级别、问题文件路径),加上integrate.prd.md「未决问题」一节里的其余问题;没有就写「无」。
+4. **能否直接实现**:转述「后续」里关于开发阈值的那一行,未达标时说明还差什么。
+
+## 第四步:请用户审阅
+问用户三件事:需求重述对不对、计划能不能这样做、未决问题怎么答。按回答处理:
+- 要改:让用户直接编辑文件,或把修改意见带上文档 id 重跑本命令(`/auto-feat <文档id> <修改意见>`),引擎会生成新版本,再回到第三步。
+- 确认:把 integrate.prd.md 与每份计划文件 frontmatter 的 `confirmation` 改为 `confirmed`。这是你唯一可以改动的字段。
+- 还没想好:什么都不改,文档保持 pending。
+
+## 第五步:能否据知识库直接实现
+看第二步输出「后续」里关于开发阈值的那一行(`--json` 时是 `data.dev`)。
+- 达标(`dev.ready` 为真),且用户在第四步确认了整合文档与全部计划 → 问用户「要现在按计划实现吗」。用户同意才开始:
+  - 严格按计划步骤和整合文档列出的代码位置、锚点实现;动手前先用 `autocode query <锚点> --json` 读相关知识库文档,再读代码。
+  - 每完成一个计划步骤,告诉用户这一步改了哪些文件。
+  - 需要动计划之外的模块、接口或数据结构时,先停下来问用户。
+  - 结束时列出全部改动文件和对应的计划步骤,请用户审代码。
+- 未达标(`dev.ready` 为假)、文档未确认、或用户不想现在实现 → 把「先处理」列出的内容转述给用户(回答问题、确认业务术语、先运行 /auto-wiki),本命令到此结束。不要开始写代码,不要运行 autocode wiki。
+
+无论哪个分支,都不要运行 autocode wiki、不要改 `.autocode/` 下的文件;知识库会在用户运行 /auto-wiki 时,根据代码与已确认文档的变化更新。
+
+## 禁止
+- 除第五步的达标分支外,不要实现需求、改业务代码;未达标或文档未确认时一律不实现。
+- 不要创建或编辑 `.autocode/` 下的任何内容;唯一例外是用户明确确认后改 `confirmation` 字段。
+- 不要替用户回答引擎提出的问题。
+- 不要把原文塞进命令行参数;不要改写或概括原文。
+- 未确认(pending)的文档不会被知识库读取,不要向用户暗示「已经进知识库」。

package/dist/hosts/templates/zh/commands/auto-fix.ejs

@@ -0,0 +1,69 @@
+---
+description: 找到原始缺陷描述(粘贴的报错 / 缺陷单 URL / 工作项 / 文件),生成用本项目业务术语整合重述的缺陷分析与修复计划,供审阅与确认;知识库达到开发阈值且用户同意时按计划修复
+argument-hint: "<要修什么,或缺陷描述在哪:粘贴的内容 / URL / 工作项 / 文件>"
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep, Edit, WebFetch, mcp__*
+<% } -%>
+autocode-template: 3
+---
+
+# /auto-fix
+
+## 第一步:找到原始缺陷描述
+`$ARGUMENTS` 是用户的话,不一定是缺陷描述本身。按下面顺序判断原文在哪,取到即止:
+1. 用户在对话里粘贴了报错、日志或复现步骤 → 原文就是它,逐字取用,不改写、不概括。
+2. 用户给了缺陷单 URL → 用网页抓取工具取回正文。
+3. 用户指的是项目管理工具里的工作项(飞书项目、Jira 等)→ 用对应 MCP 工具取回标题、描述、复现步骤。
+4. 用户指的是仓库里的文件 → Read。
+5. 都不是 → 用户的话本身就是原文;再把对话里相关的现象、预期行为、已知文件逐条补在后面,标明「来自对话」。
+取回的原文第一行写一条来源注释:`<!-- autocode-source: conversation|url|mcp|file|prompt <引用> -->`。
+取原文时还要注意:
+- 飞书 / Lark 文档链接(`/wiki/`、`/docx/`)用网页抓取拿不到:有 lark-cli 或飞书 MCP 就用它取 Markdown 正文,正文里的图片一并下载。
+- 要登录或靠脚本渲染的网页:有浏览器自动化工具就用它取正文。
+- PDF:直接用 Read 读(图片和中文 PDF 都能读),不要用 pdftotext 一类的抽取工具。
+- 原文引用的图片、接口文档等材料不要拼进原文:放进仓库里的一个临时文件夹(不放在 `.autocode/` 下),第二步用 `--attachments` 交给引擎。引擎会复制一份到变更文件夹,之后临时文件夹可以删掉。
+
+## 第二步:调用(原文走 stdin)
+    autocode fix "$ARGUMENTS" <<'AUTOCODE_ORIGINAL'
+    <原文>
+    AUTOCODE_ORIGINAL
+Bash 工具,超时不少于 <%= timeoutMinutes %> 分钟。原文一律用 stdin,不塞进参数。
+- 有附件:加 `--attachments <临时文件夹>`。
+- 用户说「先不出计划」「只要重述」这类意思:加 `--no-plan`,第三步只读整合文档;之后用户要计划时运行 `autocode fix --plan-only <文档id>`(按已有重述只生成计划,不读 stdin)。
+输出的「结果」给出文件夹路径、原文来源与版本号,「变更」列出生成的每份文件。
+
+## 第三步:按顺序读文件,呈现给用户
+1. integrate.defect.md —— 用这个项目自己的业务术语重述的现象、根因定位与相关业务规则。
+2. defect.plan.md —— 修复计划。若它是总览(有「子计划」一节),再按编号依次读 defect.plan.01-*.md、02-*.md……。
+3. original.defect.md —— 原文,只在前两份有歧义时回看。
+向用户呈现:现象重述、根因定位(或「未定位」时的候选清单)、计划份数与每份范围、未决问题、本次版本号。根因写「未定位」时,把候选列给用户,由用户补充线索后带 id 重跑。
+
+每次生成或改版之后(包括 `--no-plan`、`--plan-only`),先给用户一段**本次版本小结**,固定四项:
+1. **版本**:v版本号;改版时写 v旧 → v新。
+2. **本次修改**:新建时概括现象与根因与计划要点;改版时按输出「结果」里的「整合文档改动段落」逐段读这些段落的新内容,说明这一版改成了什么(打开文件读,不凭印象),计划按「变更」里新增 / 更新 / 移除的文件逐份说明。
+3. **需要开发回答的问题**:输出「新增问题」逐条列出(主题、级别、问题文件路径),加上integrate.defect.md「未决问题」一节里的其余问题;没有就写「无」。
+4. **能否直接修复**:转述「后续」里关于开发阈值的那一行,未达标时说明还差什么。
+
+## 第四步:请用户审阅
+问用户三件事:现象与根因对不对、计划能不能这样做、未决问题怎么答。按回答处理:
+- 要改:让用户直接编辑文件,或把修改意见带上文档 id 重跑本命令(`/auto-fix <文档id> <修改意见>`),引擎会生成新版本,再回到第三步。
+- 确认:把 integrate.defect.md 与每份计划文件 frontmatter 的 `confirmation` 改为 `confirmed`。这是你唯一可以改动的字段。
+- 还没想好:什么都不改,文档保持 pending。
+
+## 第五步:能否据知识库直接修复
+看第二步输出「后续」里关于开发阈值的那一行(`--json` 时是 `data.dev`)。
+- 达标(`dev.ready` 为真),且用户在第四步确认了整合文档与全部计划 → 问用户「要现在按计划修复吗」。用户同意才开始:
+  - 严格按计划步骤和整合文档列出的代码位置、锚点修复;动手前先用 `autocode query <锚点> --json` 读相关知识库文档,再读代码。
+  - 每完成一个计划步骤,告诉用户这一步改了哪些文件。
+  - 需要动计划之外的模块、接口或数据结构时,先停下来问用户。
+  - 结束时列出全部改动文件和对应的计划步骤,请用户审代码。
+- 未达标(`dev.ready` 为假)、文档未确认、或用户不想现在修复 → 把「先处理」列出的内容转述给用户(回答问题、确认业务术语、先运行 /auto-wiki),本命令到此结束。不要开始写代码,不要运行 autocode wiki。
+
+无论哪个分支,都不要运行 autocode wiki、不要改 `.autocode/` 下的文件;知识库会在用户运行 /auto-wiki 时,根据代码与已确认文档的变化更新。
+
+## 禁止
+- 除第五步的达标分支外,不要修复缺陷、改业务代码;未达标或文档未确认时一律不修复。
+- 不要创建或编辑 `.autocode/` 下的任何内容;唯一例外是用户明确确认后改 `confirmation` 字段。
+- 不要替用户回答引擎提出的问题。
+- 不要把原文塞进命令行参数;不要改写或概括原文。
+- 未确认(pending)的文档不会被知识库读取,不要向用户暗示「已经进知识库」。

package/dist/hosts/templates/zh/commands/auto-init.ejs

@@ -0,0 +1,22 @@
+---
+description: 初始化或刷新 autocode:骨架、代码图、宿主集成(零 AI)
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep
+<% } -%>
+autocode-template: 1
+---
+
+# /auto-init
+
+## 调用
+在项目根目录用 Bash 工具执行,超时不少于 <%= timeoutMinutes %> 分钟,不要用内联 `!` 执行:
+    autocode init
+
+## 转述
+命令输出是分节 Markdown,逐节如实转述给用户;不美化、不补写引擎没说的结论。
+- 「变更」为空表示已初始化过,本次只是刷新,照实说。
+- 报错「无可用 provider」→ 提示安装 Claude Code 或 Codex CLI;这不影响初始化本身。
+
+## 禁止
+- 不要创建或编辑 `.autocode/` 下的任何文件,那是生成物。
+- 不要自行拆解步骤或绕过命令直接改文档;工作流全部在引擎内。

package/dist/hosts/templates/zh/commands/auto-wiki.ejs

@@ -0,0 +1,42 @@
+---
+description: 生成或更新业务知识库;可带自然语言指令
+argument-hint: "[指令,如:只生成某个模块 / 预览 / 全部重写]"
+<% if (host === "claude") { -%>
+allowed-tools: Bash(autocode:*), Read, Glob, Grep, Edit
+<% } -%>
+autocode-template: 2
+---
+
+# /auto-wiki
+
+## 调用
+在项目根目录用 Bash 工具执行,超时不少于 <%= timeoutMinutes %> 分钟,不要用内联 `!` 执行:
+    autocode wiki "$ARGUMENTS"
+(无参数时不传引号对。)
+用户在指令里讲了业务实际怎么运作(业务事实),原样放进指令即可:引擎会把原话记为人工确认答案,并据此修改相关文档;不要另找文件去写。
+指令含「全部重写」「全量」这类重写全部文档的意思时,费用高且不可逆:先向用户确认,得到同意再调用。
+
+## 转述
+命令输出是分节 Markdown,逐节如实转述给用户;不美化、不补写引擎没说的结论。
+- 「预览」类指令只输出影响清单,原样转述。
+- 「本次无需更新」是合法结论,直接转述原因。
+- 「无法解析指令」→ 转述原因后,用 `autocode query <关键词>` 找出相关的单元文档与领域(取结果里文档的文件名、领域 id),列给用户确认;用户同意后执行 `autocode wiki --scope unit:<文件名>,domain:<领域 id>`(不带指令),只重写这几篇。
+- 「没有与要求相关的文档」→ 按上一条同样处理:用 `autocode query` 找出相关文档,让用户确认后用 `--scope` 运行。
+- 「后续」里有「复核未满足」→ 逐条转述给用户(要求原话 + 还缺什么),问用户是换个说法再运行,还是先这样。
+- 报错「未初始化」→ 提示先运行 /auto-init;报错「无可用 provider」→ 提示安装 Claude Code 或 Codex CLI。
+
+## 问题
+引擎运行时不会停下来提问:拿不准的地方已按「暂按推断」写进文档,问题留在输出里;现在轮到你问。
+<% if (host === "claude") { -%>
+1. 「待优先回答的问题」每一条,用提问工具(AskUserQuestion)问用户:标题用问题主题,说明用输出里的现状一句,选项用输出里的可选答案,再加「其他」和「稍后再答」。不要自己补选项,不要替用户选。
+<% } else { -%>
+1. 「待优先回答的问题」每一条,在对话里逐条列出主题、现状与可选答案,请用户回答。不要自己补选项,不要替用户选。
+<% } -%>
+2. 用户答了 → 打开该问题文件(用户说「按推断」也照写,引擎会直接采纳文档里的推断),把回答逐字写进 `## 回答` 段(不概括、不补充),frontmatter 改三项:`status: answered`、`answered_at: <现在的 ISO 时间>`、`answered_via: host-agent`。其它内容不动。「稍后再答」的不动。
+3. 至少写回一条 → 再运行一次不带指令的 `autocode wiki`(增量),转述结果;相关文档会在这一趟按答案更新。
+4. 「新增问题」只列出,说明可以现在答,也可以之后直接在问题文件(`.autocode/questions/`)的 `## 回答` 段作答,下次运行 `autocode wiki` 时生效;用户要现在答的按第 2 步处理。
+
+## 禁止
+- 不要创建或编辑 `.autocode/` 下的任何文件;唯一例外是「问题」第 2 步写回用户的回答。
+- 不要替用户回答引擎提出的问题;不要改写用户的回答。
+- 不要自行拆解步骤或绕过命令直接改文档;工作流全部在引擎内。

package/dist/hosts/templates/zh/marker-block.ejs

@@ -0,0 +1,6 @@
+## autocode 业务知识库(由 autocode install 维护,勿手改此块)
+本仓库用 autocode 维护业务知识库 `.autocode/`:代码说「怎么做」,知识库说「为什么、有什么规则」。编码前先查:`autocode query <关键词或锚点> --json`(文档、业务术语、入口、锚点;文档 frontmatter 的 `up` / `down` 指向上下层)、`autocode graph <锚点> --json`(调用关系)、`.autocode/questions/` 下 `status: open` 的问题文件(待答问题)。
+业务术语纪律:业务概念逐字复用业务术语里的名字,不另造同义词;状态为「已确认」的口径以它为准。
+只有两件事可以写进 `.autocode/`:用户对问题的回答(逐字写进问题文件「回答」段),用户对需求 / 缺陷文档的确认(改 `confirmation` 字段);其余一律不写。
+改代码时不要回头去改需求 / 缺陷文档,它们是当时的意图记录;知识库以代码为准,出入会在下次 wiki 更新时变成问题由人裁决。
+斜杠命令与 CLI 对照(Codex 用户直接调用右侧 CLI):/auto-init → `autocode init`;/auto-wiki → `autocode wiki "<指令>"`;/auto-check → `autocode check`;/auto-feat → `autocode feat "<用户的话>" < 原文`;/auto-fix → `autocode fix "<用户的话>" < 原文`。

package/dist/hosts/templates/zh/skill-graph.ejs

@@ -0,0 +1,30 @@
+---
+name: autocode-graph
+description: 查询本仓库的代码图调用链:输入锚点(函数、方法、类型名,重名写成 文件::全名)或关键字,返回它向上被谁调用、向下调用了谁的多层调用链(代码图引擎原生的调用图),以及同文件的符号;列出全部入口(路由、页面、任务、消费者)。读调用链、定位代码时先查,不要逐个文件 grep。业务含义用 autocode-query,工具用法见 autocode。
+autocode-template: 2
+---
+
+# autocode 代码图
+
+代码图由 autocode 从源码建出,是知识库的最底层;文档里的锚点就是图里的节点名。`autocode graph` 直接调用代码图引擎原生的调用图与搜索,只读、不调 AI,wiki 运行时也能用。
+
+## 查
+| 需求 | 命令 |
+|---|---|
+| 一个锚点的调用链(默认上下各 2 层) | `autocode graph <锚点>`(读调用树)/ `autocode graph <锚点> --json`(机读) |
+| 看得更远或更近 | `--depth <1~5>` |
+| 只记得名字的一部分 | `autocode graph <关键字>`(代码图引擎的全文 / 模糊搜索) |
+| 有哪些入口、各归哪篇单元文档 | `.autocode/entries.md`(入口目录,按模块分组,带节点名与文件行号) |
+
+## 读结果
+- 不带 `--json`:第一行是解析到的符号与文件行号,下面两棵树——「调用方」(`←`,谁会走到这里)与「被调用」(`→`,这里会走到哪),缩进一层即多一跳;`(↺)` 表示前面已出现过(递归或汇合),`… +N` 表示这一层太宽被截断。
+- `--json`:`symbol`;`chain.nodes`(每个节点的 `anchor`、`kind`、文件行号)、`chain.edges`(`from` → `to`,带调用所在行)、`chain.tree`(同上两棵树的文本);`callers` / `callees` 是一跳的简表,`siblings` 是同文件符号。
+- 「有 N 个同名符号」/ `candidates.reason = ambiguous`:不会替你猜;挑一个,用它的 `文件::全名` 再查。
+- 「没有叫这个名字的符号,搜索到」/ `candidates.reason = keyword`:按搜索结果挑一个再查;只命中一个时已直接展开。`truncated` 为真说明还有更多,换个更具体的关键字。
+- 「图里没有」:可能是变量或常量,用 Grep 查;或先运行 /auto-wiki 刷新代码图。
+
+## 和知识库一起用
+- 从业务说法出发:先 `autocode query` 找到文档,文档 frontmatter 的 `anchors`、`entries` 就是可以拿来查图的名字。
+- 从代码出发:拿到锚点后 `autocode query <锚点> --json`,看它属于哪篇单元文档、哪个领域。
+
+本文件由 `autocode install` 维护,人工改动会在下次安装时被覆盖。

package/dist/hosts/templates/zh/skill-query.ejs

@@ -0,0 +1,34 @@
+---
+name: autocode-query
+description: 查询本仓库的业务知识库文档(.autocode/):按锚点或业务说法找到文档,读某段代码的业务含义、业务规则、改动影响哪些业务、业务术语的准确口径。编码前先查,不要通读源码猜。调用关系与代码结构用 autocode-graph,更新文档等工具用法见 autocode。
+autocode-template: 2
+---
+
+# autocode 知识库查询
+
+代码回答「怎么做」,知识库回答「为什么、给谁用、有什么规则」。
+
+## 查(编码前)
+| 需求 | 命令 |
+|---|---|
+| 锚点(函数、方法、类型名)或业务说法 → 关联文档、业务术语释义、入口、相关需求文档 | `autocode query <锚点或关键词> --json` |
+| 调用关系、某个名字在代码里是什么 | 见 autocode-graph skill |
+| 待答业务问题 | `.autocode/questions/` 下 `status: open` 的问题文件 |
+
+## 分层与查法
+知识库从下到上四层,每篇文档 frontmatter 的 `layer` 说明它在哪层,`up` / `down` 指向上一层和下一层(路径相对 `.autocode/`):
+1. 代码图层:代码图,用 `autocode graph` 查(autocode-graph skill)
+2. 入口层:`.autocode/entries.md`,每个入口一行,带节点名、文件行号和所属单元文档
+3. 单元层:一个业务能力一篇,`down` 指向它的入口
+4. 领域层:一个模块一篇,端到端旅程,`down` 列出本领域的单元
+
+- 手里有锚点(函数、方法、类型名)或入口(路由、页面路径):`autocode query <锚点> --json`,锚点命中的文档排在最前(`anchorHit`),结果里的 `entries` 给出它在入口目录的位置;顺着 `up` 读领域、顺着 `down` 读入口;要看实现再 `autocode graph <锚点>`。
+- 手里是业务说法:先 query 业务术语,再读命中的文档,同样顺着 `up` / `down` 读。
+- 文档的 `confidence` 由代码计算(生成时自评、待答问题、失效锚点、待确认业务术语);文档末尾「开发入口」段写明能否据它自动开发、还差什么。
+
+每轮对话开始时已注入知识库的位置、领域目录,以及按本轮输入和最近对话挑出的相关业务术语与文档线索(含挑中原因);线索不保证完整,看到标题不要猜内容,直接读文档或用 query 取详情。
+
+## 业务术语纪律
+写标识符、注释、文档、PR 描述时,业务概念逐字复用业务术语里的名字,状态为「已确认」的口径以它为准;拿不准先 query;查不到就在对话里向用户确认。
+
+本文件由 `autocode install` 维护,人工改动会在下次安装时被覆盖。