agentflowctl 0.1.2 → 0.2.0

package/README.md

@@ -93,7 +93,6 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `--base` | 基底分支，預設為目前分支 |
 | `--cycle` | 這次 run 的輪替順序，例如 `claude,codex,gemini`；建立後就固定，`resume` 沿用 |
 | `--max-agent-runs` | 這次 run 的 agent 執行次數上限 |
-| `--budget` | 估計花費上限（美元）；使用 API 計費時才需要 |
 | `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
 
 `status` 會列出任務。進行中的任務會標出正在寫測試還是正在寫實作。
@@ -109,7 +108,7 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
   "tddSplit": true,
   "tieBreak": "proceed",
   "agents": {
-    "codex": { "adapter": "codex", "model": "你要用的模型", "pricing": { "inputPerMTok": 1.25, "outputPerMTok": 10 } },
+    "codex": { "adapter": "codex", "model": "你要用的模型" },
     "aider": { "adapter": "command", "command": ["aider", "--yes-always", "--no-auto-commits", "--message", "{prompt}"] }
   }
 }
@@ -124,13 +123,34 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者都 `approve` |
 | `planArbiter` | `true` | 計畫審查僵持時交付仲裁。關掉之後，僵持會直接讓 run 失敗 |
 | `tieBreak` | `proceed` | 兩家仲裁意見分歧時：`proceed` 繼續並記錄爭議；`stop` 停下 |
-| `auth` | `subscription` | `subscription` 移除子程序裡的 API key；`api` 保留，給 CI 用 |
 | `maxAgentRuns` | `60` | 單一 run 最多執行幾次 agent |
 | `install` / `test` / `checks` | 見 `src/schemas.ts` | verify 階段實際執行的指令 |
 | `agents` | 內建 claude、codex、gemini | 覆寫內建 agent，或用 `command` adapter 接上其他 CLI |
 
 verify 失敗（型別、lint、建置）一律交回最後作者。審查意見才依 `fixStrategy` 決定修正者。
 
+### 用指令管理 agent
+
+`agents` 與 `cycle` 也可以用 `agent` 指令修改，不必手動編輯 JSON。每次寫入前都會先驗證整份設定：
+
+```bash
+agentflowctl agent list                                   # 內建與自訂 agent、是否已安裝、輪替位置
+agentflowctl agent add claude-strong --adapter claude --model opus
+agentflowctl agent add aider --adapter command -- aider --yes-always --message {prompt}
+agentflowctl agent set codex --model 你要用的模型 --extra-arg=--search
+agentflowctl agent set aider --adapter gemini             # 換 adapter
+agentflowctl agent remove aider
+agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯示目前的順序
+```
+
+修改會連帶更新相關設定，並在終端機列出：
+
+- `set --adapter` 換 adapter 時，會清掉舊 adapter 的 `model`、`extraArgs`、`command`，這次有重新指定的除外。
+- `remove` 刪除自訂 agent 時，會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回自動偵測。對內建 agent 用 `remove`，只會刪掉覆寫設定。
+- `--extra-arg` 可以重複指定，會整個取代原本的 `extraArgs`。參數以 `-` 開頭時，寫成 `--extra-arg=--sandbox`。
+
+已建立的 run 會沿用建立時的輪替順序，不受這些修改影響。
+
 ## 計畫怎麼在沒有人的情況下通過
 
 人工確認計畫是為了擋住方向錯了還一路做下去。預設用三層機制取代它；加上 `--manual-plan` 時，三層都過了仍會停下來等你。
@@ -169,6 +189,23 @@ verify 失敗（型別、lint、建置）一律交回最後作者。審查意見
 
 驗收條件寫在 `.flow/acceptance.json`（`AC-1`…），任務寫在 `.flow/tasks.json`（`T-1`…）。
 
+## Prompt 結構
+
+每個階段的 prompt 都有專屬角色：需求分析師、軟體架構師、計畫審查者、計畫修訂者、中立仲裁者、測試工程師、實作工程師、除錯工程師、程式碼審查者。內容用 XML 標籤分段：`<role>`、`<context>`、`<inputs>`、`<steps>`、`<constraints>`、`<output_format>`、`<reply_format>`。
+
+Agent 的最後回覆要附上 XML 中繼資料：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>做了什麼</summary>
+  <files_changed><file>src/form.ts</file></files_changed>
+  <concerns>對規格或測試的疑慮</concerns>
+</result>
+```
+
+`blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
+
 ## Adapter
 
 | adapter | 執行方式 | 權限 |
@@ -184,11 +221,11 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 
 ## 登入、額度與代打
 
-預設 `auth: "subscription"`，只用各家 CLI 的訂閱登入。
+只支援各家 CLI 的訂閱登入。
 
-執行 agent 時，會從子程序環境移除 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CODEX_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`GOOGLE_API_KEY`，避免環境裡的 key 蓋過訂閱登入。`doctor` 發現這些變數時會提醒。專案指令（install、test、build）不受影響。
+執行 agent 時，一律從子程序環境移除 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CODEX_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`GOOGLE_API_KEY`，避免環境裡的 key 蓋過訂閱登入。`doctor` 發現這些變數時會提醒。專案指令（install、test、build）不受影響。
 
-上限是執行次數（`maxAgentRuns`，預設 60），不是金額。Claude Code 回報的美元金額是 API 價格的估計值。
+上限是執行次數（`maxAgentRuns`，預設 60），不是金額。`status` 會列出各 agent 的執行次數與 token 數。
 
 額度用完時：
 
@@ -204,8 +241,6 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 
 額度錯誤靠錯誤訊息辨識（usage limit、rate limit、quota、429 等），只在 agent 執行失敗時判斷。辨識不到時，會當成一般失敗重試。
 
-CI 無法使用訂閱登入時，設 `"auth": "api"` 保留 API key，並用 `--budget` 設估計花費上限。Codex、Gemini 只回報 token，要在 `agents.<name>.pricing` 設定價格才會算進預算。GitHub Actions 範例見 `examples/github-actions.yml`。
-
 ## 在哪裡跑
 
 agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell 執行。
@@ -213,7 +248,7 @@ agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell
 | 環境 | 適合的用法 |
 |---|---|
 | 自己的電腦 | 自己的專案、自己寫的需求。剛開始可以加 `--manual-plan`，確認審查品質後再拿掉 |
-| CI、容器、遠端開發機 | 無人值守。見 `examples/github-actions.yml`：issue 加上標籤就跑完並開 PR |
+| 容器、遠端開發機 | 無人值守。先在該環境內完成各家 CLI 的訂閱登入 |
 | Claude Code、Codex 裡面 | 讓它們用 shell 執行 `npx agentflowctl` |
 
 沒有容器隔離時，verify 會在你的電腦上執行 agent 寫出來的程式碼。Gemini 在無人值守時是 yolo 模式。處理外部 issue，或需求文字不是你自己寫的，放到可丟棄的環境。AI 審查計畫擋不住夾在需求裡的指示。
@@ -228,7 +263,7 @@ src/
   runner.ts         執行 agent、正規化結果、執行專案指令
   agents/           claude、codex、gemini、command
   git.ts            worktree 與 git 操作
-  store.ts          狀態、花費、代打紀錄
+  store.ts          狀態、用量、代打紀錄
   tasks.ts          任務 DAG
   schemas.ts        zod schema
 prompts/            各階段 prompt

package/dist/agentConfig.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+import { DEFAULT_CYCLE } from "./agents/index.js";
+import { AgentDef, RepoConfig } from "./schemas.js";
+/** 這些欄位的意義取決於 adapter，換 adapter 時要清掉 */
+const ADAPTER_FIELDS = ["model", "extraArgs", "command"];
+const isBuiltin = (name) => DEFAULT_CYCLE.includes(name);
+const agentsOf = (cfg) => ({ ...(cfg.agents ?? {}) });
+const isDefined = (cfg, name) => isBuiltin(name) || name in agentsOf(cfg);
+/** 只留下有值的欄位，驗證後回傳 */
+function buildAgent(base, patch) {
+    const next = { ...base };
+    for (const [k, v] of Object.entries(patch))
+        if (v !== undefined)
+            next[k] = v;
+    const parsed = AgentDef.safeParse(next);
+    if (!parsed.success)
+        throw new Error(`agent 設定不合法：\n${z.prettifyError(parsed.error)}`);
+    if (parsed.data.adapter === "command" && !parsed.data.command?.length) {
+        throw new Error("command adapter 需要指令，請寫在 -- 後面，例如：-- aider --message {prompt}");
+    }
+    if (parsed.data.adapter !== "command" && parsed.data.command)
+        throw new Error("只有 command adapter 可以設定 command");
+    return next;
+}
+export function addAgent(cfg, name, def) {
+    if (!/^[\w-]+$/.test(name))
+        throw new Error(`agent 名稱只能用英數字、底線與連字號：${name}`);
+    if (isDefined(cfg, name))
+        throw new Error(`agent ${name} 已存在，要修改請用 agent set`);
+    const { adapter, ...patch } = def;
+    return { cfg: { ...cfg, agents: { ...agentsOf(cfg), [name]: buildAgent({ adapter }, patch) } }, changes: [] };
+}
+export function setAgent(cfg, name, patch) {
+    if (!isDefined(cfg, name))
+        throw new Error(`未定義的 agent：${name}`);
+    if (Object.values(patch).every((v) => v === undefined)) {
+        throw new Error("沒有要修改的欄位（--adapter、--model、--extra-arg 或 -- <command>）");
+    }
+    const agents = agentsOf(cfg);
+    // 內建 agent 第一次修改時，新增一筆覆寫設定
+    const base = { ...(agents[name] ?? { adapter: name }) };
+    const changes = [];
+    if (patch.adapter !== undefined && patch.adapter !== base.adapter) {
+        const cleared = ADAPTER_FIELDS.filter((f) => base[f] !== undefined && patch[f] === undefined);
+        for (const f of cleared)
+            delete base[f];
+        if (cleared.length)
+            changes.push(`adapter 從 ${String(base.adapter)} 換成 ${patch.adapter}，已清掉舊的 ${cleared.join("、")}`);
+    }
+    return { cfg: { ...cfg, agents: { ...agents, [name]: buildAgent(base, patch) } }, changes };
+}
+export function removeAgent(cfg, name) {
+    const agents = agentsOf(cfg);
+    if (!(name in agents)) {
+        throw new Error(isBuiltin(name) ? `${name} 是內建 agent，沒有覆寫設定可以刪除` : `未定義的 agent：${name}`);
+    }
+    delete agents[name];
+    const next = { ...cfg, agents };
+    const changes = [];
+    const cycle = cfg.cycle;
+    // 自訂 agent 刪掉後就不存在了，一併從輪替順序移除；內建 agent 只是恢復預設，仍可留在輪替裡
+    if (cycle?.includes(name) && !isBuiltin(name)) {
+        const rest = cycle.filter((n) => n !== name);
+        if (rest.length) {
+            next.cycle = rest;
+            changes.push(`已從輪替順序移除，現在是 ${rest.join(" → ")}`);
+        }
+        else {
+            delete next.cycle;
+            changes.push("輪替順序因此變空，已刪除 cycle，改回自動偵測已安裝的 CLI");
+        }
+    }
+    return { cfg: next, changes };
+}
+export function setCycle(cfg, names) {
+    if (!names.length)
+        throw new Error("輪替順序至少要有一個 agent");
+    const dup = names.find((n, i) => names.indexOf(n) !== i);
+    if (dup)
+        throw new Error(`輪替順序裡 ${dup} 重複了`);
+    const missing = names.filter((n) => !isDefined(cfg, n));
+    if (missing.length)
+        throw new Error(`未定義的 agent：${missing.join("、")}（先用 agent add 新增）`);
+    return { cfg: { ...cfg, cycle: names }, changes: [] };
+}
+export function readRawConfig(path) {
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** 先用 RepoConfig 驗證整份設定，通過才寫入 */
+export function writeRawConfig(path, cfg) {
+    const parsed = RepoConfig.safeParse(cfg);
+    if (!parsed.success)
+        throw new Error(`設定不合法，未寫入：\n${z.prettifyError(parsed.error)}`);
+    writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
+}
+//# sourceMappingURL=agentConfig.js.map

package/dist/agents/claude.js

@@ -55,7 +55,6 @@ export const claude = {
                 kind: "usage",
                 inputTokens: num(usage.input_tokens),
                 outputTokens: num(usage.output_tokens),
-                costUsd: num(ev.total_cost_usd),
             });
             out.push({ kind: "done", ok: ev.is_error !== true, summary: str(ev.result) });
         }

package/dist/cli.js

@@ -8,8 +8,9 @@ import { API_KEY_VARS, probeAgent, resolveAgent, runCommand } from "./runner.js"
 import { addWorktree, git, removeWorktree } from "./git.js";
 import { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.js";
 import { TaskList } from "./schemas.js";
-import { agentRuns, costByAgent, getCost, getRun, listRuns, listSubstitutions, saveRun } from "./store.js";
+import { agentRuns, getRun, listRuns, listSubstitutions, saveRun, usageByAgent } from "./store.js";
 import { readJsonFile } from "./util.js";
+import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfig } from "./agentConfig.js";
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -28,7 +29,7 @@ function printSummary(run) {
     console.log("");
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
-    console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次（估計花費 $${getCost(run.id).toFixed(2)}${run.budgetUsd ? ` / $${run.budgetUsd}` : "，訂閱登入時僅供參考"}）`);
+    console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次`);
     console.log(`agent    ${run.cycle.join(" → ")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
     console.log(`分支     ${run.branch}`);
     console.log(`worktree ${worktreeDir(run.id)}`);
@@ -78,7 +79,6 @@ program
     .option("--req-file <file>", "從檔案讀取需求")
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
-    .option("--budget <usd>", "選用：估計花費上限（美元），使用 API 計費時才需要")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
     .option("--cycle <agents>", "agent 輪替順序，例如 claude,codex,gemini")
     .action(async (opts) => {
@@ -108,7 +108,6 @@ program
         requirement: requirement.trim(),
         stage: "spec",
         autopilot: !opts.manualPlan,
-        budgetUsd: opts.budget ? Number(opts.budget) : undefined,
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
         cycle,
         attempts: {},
@@ -132,11 +131,8 @@ program
     .command("resume <id>")
     .description("從暫停、中斷或失敗的階段接續")
     .option("--max-agent-runs <n>", "調整 agent 執行次數上限")
-    .option("--budget <usd>", "調整估計花費上限（美元）")
     .action(async (id, opts) => {
     let run = mustGetRun(id);
-    if (opts.budget)
-        run = { ...run, budgetUsd: Number(opts.budget) };
     if (opts.maxAgentRuns)
         run = { ...run, maxAgentRuns: Number(opts.maxAgentRuns) };
     if (run.stage === "paused") {
@@ -171,11 +167,11 @@ program
     .action((id) => {
     const run = mustGetRun(id);
     printSummary(run);
-    const byAgent = costByAgent(id);
+    const byAgent = usageByAgent(id);
     if (Object.keys(byAgent).length) {
         console.log("\n各 agent 用量");
         for (const [agent, c] of Object.entries(byAgent)) {
-            console.log(`  ${agent.padEnd(10)} ${String(c.runs).padStart(3)} 次  ${String(c.tokens).padStart(9)} tokens  $${c.usd.toFixed(2)}`);
+            console.log(`  ${agent.padEnd(10)} ${String(c.runs).padStart(3)} 次  ${String(c.tokens).padStart(9)} tokens`);
         }
     }
     const subs = listSubstitutions(id);
@@ -194,6 +190,83 @@ program
         console.log(`  ${mark} ${t.id} ${t.title}`);
     });
 });
+// ───────────── agent 管理：讀寫 flow.config.json 的 agents 與 cycle ─────────────
+const configPath = () => join(projectRoot(), "flow.config.json");
+const collect = (value, prev = []) => [...prev, value];
+function applyEdit(edit, done) {
+    const before = readRawConfig(configPath());
+    const { cfg, changes } = edit(before);
+    writeRawConfig(configPath(), cfg);
+    console.log(`✅ ${done}（${configPath()}）`);
+    for (const c of changes)
+        console.log(`   ↳ ${c}`);
+    if (JSON.stringify(before.cycle) !== JSON.stringify(cfg.cycle)) {
+        console.log("   已建立的 run 會沿用建立時的輪替順序，不受影響");
+    }
+}
+const agent = program.command("agent").description("管理 agent 與 adapter 設定（寫入 flow.config.json）");
+agent
+    .command("list")
+    .description("列出內建與自訂 agent、是否已安裝、在輪替中的位置")
+    .action(async () => {
+    const cfg = loadRepoConfig();
+    const cycle = await resolveCycle().catch(() => cfg.cycle ?? []);
+    const names = [...new Set([...DEFAULT_CYCLE, ...Object.keys(cfg.agents)])];
+    for (const name of names) {
+        const def = resolveAgent(cfg, name);
+        const ok = await probeAgent(def);
+        const pos = cycle.indexOf(name);
+        const kind = DEFAULT_CYCLE.includes(name) ? (name in cfg.agents ? "內建（已覆寫）" : "內建") : "自訂";
+        const detail = [
+            `adapter=${def.adapter}`,
+            def.model && `model=${def.model}`,
+            def.extraArgs.length && `extraArgs=${def.extraArgs.join(" ")}`,
+            def.command && `command=${def.command.join(" ")}`,
+        ].filter(Boolean);
+        console.log(`${ok ? "✅" : "❌"} ${name.padEnd(14)} ${kind.padEnd(8)} ${pos >= 0 ? `輪替 #${pos + 1}` : "不在輪替"}  ${detail.join(" ")}`);
+    }
+    console.log(`
+輪替順序：${cycle.length ? cycle.join(" → ") : "（沒有可用的 agent）"}${cfg.cycle ? "" : "（自動偵測）"}`);
+});
+agent
+    .command("add <name> [command...]")
+    .description("新增 agent；command adapter 的指令寫在 -- 後面")
+    .requiredOption("--adapter <adapter>", "claude、codex、gemini 或 command")
+    .option("--model <model>", "模型名稱")
+    .option("--extra-arg <arg>", "額外參數，可重複；以 - 開頭時寫成 --extra-arg=--sandbox", collect)
+    .action((name, command, opts) => {
+    applyEdit((cfg) => addAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, command: command.length ? command : undefined }), `已新增 ${name}；要加進輪替請用 agent cycle`);
+});
+agent
+    .command("set <name> [command...]")
+    .description("修改 agent；更換 adapter 時會清掉舊 adapter 的 model、extraArgs、command")
+    .option("--adapter <adapter>", "claude、codex、gemini 或 command")
+    .option("--model <model>", "模型名稱")
+    .option("--extra-arg <arg>", "額外參數，可重複，會整個取代原本的設定", collect)
+    .action((name, command, opts) => {
+    applyEdit((cfg) => setAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, command: command.length ? command : undefined }), `已更新 ${name}`);
+});
+agent
+    .command("remove <name>")
+    .description("刪除自訂 agent（一併從輪替移除），或刪除內建 agent 的覆寫設定")
+    .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已刪除 ${name} 的設定`));
+agent
+    .command("cycle [names]")
+    .description("顯示輪替順序，或用逗號分隔設定新的順序")
+    .action(async (names) => {
+    if (!names) {
+        const cfg = loadRepoConfig();
+        console.log(`${(await resolveCycle()).join(" → ")}${cfg.cycle ? "" : "（自動偵測）"}`);
+        return;
+    }
+    const list = names.split(",").map((s) => s.trim()).filter(Boolean);
+    applyEdit((cfg) => setCycle(cfg, list), `輪替順序設為 ${list.join(" → ")}`);
+    const cfg = loadRepoConfig();
+    for (const n of list) {
+        if (!(await probeAgent(resolveAgent(cfg, n))))
+            console.log(`⚠️  ${n} 目前找不到可執行的 CLI，run 會失敗，請先安裝或用 agent set 修正`);
+    }
+});
 program
     .command("doctor")
     .description("檢查可用的 agent CLI 與目前的輪替設定")
@@ -212,11 +285,9 @@ program
         console.log(`\n${e.message}`);
     }
     const leaked = API_KEY_VARS.filter((k) => process.env[k]);
-    console.log(`\n登入方式：${cfg.auth === "subscription" ? "訂閱登入（執行 agent 時會移除 API key）" : "API key"}`);
+    console.log("\n登入方式：訂閱登入（執行 agent 時會移除 API key）");
     if (leaked.length) {
-        console.log(cfg.auth === "subscription"
-            ? `⚠️  環境中有 ${leaked.join("、")}，agentflowctl 執行 agent 時會移除，但你自己直接執行 CLI 時仍可能改走 API 計費`
-            : `使用中的 API key：${leaked.join("、")}`);
+        console.log(`⚠️  環境中有 ${leaked.join("、")}，agentflowctl 執行 agent 時會移除，但你自己直接執行 CLI 時仍可能改走 API 計費`);
     }
     console.log(`單一 run 的 agent 執行上限：${cfg.maxAgentRuns} 次`);
     console.log(`修正策略：${cfg.fixStrategy}　測試與實作分開：${cfg.tddSplit ? "是" : "否"}`);
@@ -228,7 +299,7 @@ program
     .action(() => {
     for (const r of listRuns()) {
         const req = r.requirement.split("\n")[0].slice(0, 40);
-        console.log(`${r.id}  ${r.stage.padEnd(17)}  $${getCost(r.id).toFixed(2).padStart(6)}  ${r.updatedAt.slice(0, 16)}  ${req}`);
+        console.log(`${r.id}  ${r.stage.padEnd(17)}  ${String(agentRuns(r.id)).padStart(3)} 次  ${r.updatedAt.slice(0, 16)}  ${req}`);
     }
 });
 program

package/dist/engine.js

@@ -7,7 +7,7 @@ import { exec } from "./proc.js";
 import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, reviewers, specAgent, taskAgents } from "./roles.js";
 import { resolveAgent, runAgent, runCommand } from "./runner.js";
 import { AcceptanceList, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
-import { addCost, addSubstitution, agentRuns, getCost, saveRun } from "./store.js";
+import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
 import { orderTasks } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
@@ -43,18 +43,27 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
-        const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, `${step}-${agent}`), prompt, {
-            stripApiKeys: cfg.auth === "subscription",
-        });
-        addCost(run.id, { stage: step, agent, usd: r.costUsd, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
-        if (!r.quotaExhausted)
+        const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, `${step}-${agent}`), prompt);
+        addUsage(run.id, { stage: step, agent, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
+        if (!r.quotaExhausted) {
+            reportMeta(run, agent, r);
             return { r, agent };
+        }
         info(run, `⛽ ${agent} 的額度已用完`);
         exhausted.add(agent);
         await reset();
         // 迴圈回到開頭：review 會停下，write 會找代打
     }
 }
+/** 印出回覆裡的 XML 中繼資料；只供人檢視，關卡仍由程式檢查決定 */
+function reportMeta(run, agent, r) {
+    if (!r.meta)
+        return;
+    if (r.meta.status === "blocked")
+        info(run, `   🚧 ${agent} 回報卡住：${r.meta.summary}`);
+    if (r.meta.concerns)
+        info(run, `   💭 ${agent} 的疑慮：${r.meta.concerns}`);
+}
 function readFeedback(run) {
     const p = flowFile(run, "feedback.md");
     return existsSync(p) ? readFileSync(p, "utf8") : "";
@@ -481,7 +490,7 @@ async function prStage(run) {
     const title = run.requirement.split("\n")[0].slice(0, 72);
     const spec = existsSync(flowFile(run, "spec.md")) ? readFileSync(flowFile(run, "spec.md"), "utf8") : "";
     const bodyPath = join(runDir(run.id), "pr-body.md");
-    writeFileSync(bodyPath, `> 由 agentflowctl 自動產生（run: ${run.id}，參與的 agent：${run.cycle.join("、")}，花費約 $${getCost(run.id).toFixed(2)}）\n\n${spec}`);
+    writeFileSync(bodyPath, `> 由 agentflowctl 自動產生（run: ${run.id}，參與的 agent：${run.cycle.join("、")}，執行 agent ${agentRuns(run.id)} 次）\n\n${spec}`);
     const r = await exec("gh", ["pr", "create", "--head", run.branch, "--base", run.baseBranch, "--title", title, "--body-file", bodyPath], { cwd: repo });
     if (r.code !== 0) {
         info(run, `⚠️  gh pr create 失敗，分支已推送，請手動建立 PR：${r.stderr.trim()}`);
@@ -516,15 +525,6 @@ export async function advance(initial) {
                 failureReason: `已執行 agent ${runs} 次，達到上限 ${run.maxAgentRuns}（可用 resume --max-agent-runs 調高）`,
             });
         }
-        const cost = getCost(run.id);
-        if (run.budgetUsd !== undefined && cost >= run.budgetUsd) {
-            return saveRun({
-                ...run,
-                stage: "failed",
-                failedStage: stage,
-                failureReason: `估計花費 $${cost.toFixed(2)}，超過預算 $${run.budgetUsd}`,
-            });
-        }
         try {
             run = saveRun(await STAGES[stage](run));
         }

package/dist/runner.js

@@ -1,11 +1,12 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
+import { z } from "zod";
 import { ADAPTERS, DEFAULT_CYCLE } from "./agents/index.js";
 import { AgentDef } from "./schemas.js";
 import { projectRoot, runDir } from "./paths.js";
 import { exec, execShell } from "./proc.js";
 import { tail } from "./util.js";
-/** 會讓各家 CLI 改走 API 計費的環境變數；訂閱登入模式下執行 agent 時會移除 */
+/** 會讓各家 CLI 改走 API 計費的環境變數；只用訂閱登入，執行 agent 時一律移除 */
 export const API_KEY_VARS = [
     "ANTHROPIC_API_KEY",
     "ANTHROPIC_AUTH_TOKEN",
@@ -29,6 +30,28 @@ const QUOTA_PATTERNS = [
     /\b429\b/,
 ];
 export const isQuotaError = (text) => QUOTA_PATTERNS.some((p) => p.test(text));
+/** Agent 回覆結尾的 <result> 中繼資料（格式定義在各 prompt 的 <reply_format>） */
+export const ResultMeta = z.object({
+    status: z.enum(["done", "blocked"]),
+    summary: z.string().default(""),
+    filesChanged: z.array(z.string()).default([]),
+    concerns: z.string().default(""),
+});
+const tagText = (xml, tag) => xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1]?.trim();
+/** 取回覆中最後一個 <result> 區塊；沒有或格式不合時回傳 undefined，不影響關卡判斷 */
+export function parseResultMeta(text) {
+    const block = [...text.matchAll(/<result>([\s\S]*?)<\/result>/g)].at(-1)?.[1];
+    if (block === undefined)
+        return undefined;
+    const files = tagText(block, "files_changed") ?? "";
+    const parsed = ResultMeta.safeParse({
+        status: tagText(block, "status"),
+        summary: tagText(block, "summary"),
+        filesChanged: [...files.matchAll(/<file>([\s\S]*?)<\/file>/g)].map((m) => m[1].trim()).filter(Boolean),
+        concerns: tagText(block, "concerns"),
+    });
+    return parsed.success ? parsed.data : undefined;
+}
 function appendLog(file, text) {
     mkdirSync(dirname(file), { recursive: true });
     appendFileSync(file, text.endsWith("\n") ? text : `${text}\n`);
@@ -54,7 +77,7 @@ export async function probeAgent(def) {
     }
 }
 /** 執行任一家的 agent CLI，把輸出正規化成同一種結果 */
-export async function runAgent(name, def, t, prompt, opts) {
+export async function runAgent(name, def, t, prompt) {
     const adapter = ADAPTERS[def.adapter];
     const inv = adapter.invoke({
         prompt,
@@ -68,13 +91,12 @@ export async function runAgent(name, def, t, prompt, opts) {
     appendLog(t.logFile, `# agent=${name} adapter=${def.adapter} cmd=${inv.cmd}`);
     let done;
     let lastText = "";
-    let costUsd;
     let inputTokens = 0;
     let outputTokens = 0;
     const r = await exec(inv.cmd, inv.args, {
         cwd: t.cwd,
         env: inv.env,
-        unsetEnv: opts.stripApiKeys ? API_KEY_VARS : [],
+        unsetEnv: API_KEY_VARS,
         input: inv.input,
         onStdoutLine: (line) => {
             if (!line.trim())
@@ -91,8 +113,6 @@ export async function runAgent(name, def, t, prompt, opts) {
                 else if (ev.kind === "usage") {
                     inputTokens += ev.inputTokens ?? 0;
                     outputTokens += ev.outputTokens ?? 0;
-                    if (ev.costUsd !== undefined)
-                        costUsd = (costUsd ?? 0) + ev.costUsd;
                 }
                 else if (ev.kind === "done") {
                     done = { ok: ev.ok, summary: ev.summary };
@@ -102,14 +122,11 @@ export async function runAgent(name, def, t, prompt, opts) {
     });
     if (r.stderr.trim())
         appendLog(t.logFile, `[stderr]\n${r.stderr}`);
-    // CLI 沒回報花費時，用設定的價格從 token 數估算
-    if (costUsd === undefined && def.pricing) {
-        costUsd = (inputTokens * def.pricing.inputPerMTok + outputTokens * def.pricing.outputPerMTok) / 1_000_000;
-    }
     const ok = r.code === 0 && (done?.ok ?? true);
     const summary = done?.summary || lastText || tail(r.stdout, 2000) || tail(r.stderr, 2000);
     const quotaExhausted = !ok && isQuotaError(`${summary}\n${done?.summary ?? ""}\n${r.stderr}\n${tail(r.stdout, 4000)}`);
-    return { ok, quotaExhausted, summary, costUsd: costUsd ?? 0, inputTokens, outputTokens };
+    const meta = parseResultMeta(summary) ?? parseResultMeta(lastText);
+    return { ok, quotaExhausted, summary, meta, inputTokens, outputTokens };
 }
 /**
  * 在 worktree 內執行專案指令（安裝、測試、建置）。

package/dist/schemas.js

@@ -46,8 +46,6 @@ export const AgentDef = z.object({
     extraArgs: z.array(z.string()).default([]),
     /** 只有 command adapter 使用，`{prompt}` 會被替換成 prompt */
     command: z.array(z.string()).optional(),
-    /** CLI 沒有回報花費時，用 token 數估算（每百萬 token 美元） */
-    pricing: z.object({ inputPerMTok: z.number(), outputPerMTok: z.number() }).optional(),
 });
 /** 目標專案可選的 flow.config.json，預設值對應 Vite + TypeScript + Vitest 專案 */
 export const RepoConfig = z.object({
@@ -70,12 +68,7 @@ export const RepoConfig = z.object({
      * proceed＝繼續實作，爭議記錄在計畫裡，後面還有測試、驗證與程式碼審查把關；stop＝停下來等人
      */
     tieBreak: z.enum(["proceed", "stop"]).default("proceed"),
-    /**
-     * subscription：使用各家 CLI 的訂閱登入，執行 agent 時會移除環境中的 API key，避免意外改走 API 計費；
-     * api：保留 API key（例如在 CI 中）
-     */
-    auth: z.enum(["subscription", "api"]).default("subscription"),
-    /** 單一 run 最多執行幾次 agent；訂閱制下用這個取代金額預算 */
+    /** 單一 run 最多執行幾次 agent */
     maxAgentRuns: z.number().int().positive().default(60),
     install: z.string().default("npm install --no-audit --no-fund"),
     test: z.string().default("npx vitest run"),
@@ -96,8 +89,6 @@ export const FlowRun = z.object({
     requirement: z.string(),
     stage: Stage,
     autopilot: z.boolean(),
-    /** 選用：以估計花費（美元）為上限；訂閱登入時通常不設定 */
-    budgetUsd: z.number().positive().optional(),
     /** 單一 run 最多執行幾次 agent */
     maxAgentRuns: z.number().int().positive(),
     /** 暫停前所在的階段與原因（額度用完時） */

package/dist/store.js

@@ -3,7 +3,8 @@ import { dirname, join } from "node:path";
 import { agentflowctlDir, runDir } from "./paths.js";
 import { FlowRun } from "./schemas.js";
 const statePath = (id) => join(runDir(id), "state.json");
-const costPath = (id) => join(runDir(id), "costs.jsonl");
+/** 檔名沿用舊版的 costs.jsonl，進行中的 run 升級後執行次數不會歸零 */
+const usagePath = (id) => join(runDir(id), "costs.jsonl");
 /** 先寫暫存檔再 rename，確保 state.json 不會因中斷而只寫一半 */
 function writeAtomic(path, content) {
     mkdirSync(dirname(path), { recursive: true });
@@ -29,38 +30,28 @@ export function listRuns() {
         .filter((r) => r !== undefined)
         .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
-export function addCost(id, entry) {
+export function addUsage(id, entry) {
     mkdirSync(runDir(id), { recursive: true });
-    appendFileSync(costPath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
+    appendFileSync(usagePath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
 }
-/** 依 agent 加總花費與 token，方便比較各家模型 */
-export function costByAgent(id) {
-    const p = costPath(id);
+/** 依 agent 加總 token 與執行次數，方便比較各家模型 */
+export function usageByAgent(id) {
+    const p = usagePath(id);
     const out = {};
     if (!existsSync(p))
         return out;
     for (const line of readFileSync(p, "utf8").split("\n").filter(Boolean)) {
         const e = JSON.parse(line);
         const key = e.agent ?? "?";
-        const acc = (out[key] ??= { usd: 0, tokens: 0, runs: 0 });
-        acc.usd += e.usd ?? 0;
+        const acc = (out[key] ??= { tokens: 0, runs: 0 });
         acc.tokens += (e.inputTokens ?? 0) + (e.outputTokens ?? 0);
         acc.runs += 1;
     }
     return out;
 }
-export function getCost(id) {
-    const p = costPath(id);
-    if (!existsSync(p))
-        return 0;
-    return readFileSync(p, "utf8")
-        .split("\n")
-        .filter(Boolean)
-        .reduce((sum, line) => sum + (JSON.parse(line).usd ?? 0), 0);
-}
-/** 這個 run 已執行 agent 的次數（每次執行都會記一筆花費，即使是 0） */
+/** 這個 run 已執行 agent 的次數（每次執行都會記一筆用量） */
 export function agentRuns(id) {
-    const p = costPath(id);
+    const p = usagePath(id);
     return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).length : 0;
 }
 const subPath = (id) => join(runDir(id), "substitutions.jsonl");

package/examples/flow.config.json

@@ -6,14 +6,10 @@
   "planReviewQuorum": 1,
   "planArbiter": true,
   "tieBreak": "proceed",
-  "auth": "subscription",
   "maxAgentRuns": 60,
   "agents": {
     "claude": { "adapter": "claude" },
-    "codex": {
-      "adapter": "codex",
-      "pricing": { "inputPerMTok": 1.25, "outputPerMTok": 10 }
-    }
+    "codex": { "adapter": "codex" }
   },
   "install": "pnpm ci",
   "test": "npx vitest run",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",

package/prompts/fix.md

@@ -1,17 +1,38 @@
-你是資深工程師，這個階段負責修正驗證或程式碼審查發現的問題。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是除錯工程師，負責修正驗證失敗或程式碼審查指出的問題。你要找出每個問題的根本原因，而不是只讓症狀消失。
+</role>
 
-## 要修正的問題
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
-請先閱讀 .flow/feedback.md，裡面列出了失敗的檢查（型別、lint、測試、建置）或審查意見。
-規格請參考 .flow/spec.md 與 .flow/acceptance.json。
-
-## 工作步驟
+<inputs>
+- .flow/feedback.md：失敗的檢查（型別、lint、測試、建置）或審查意見
+- .flow/spec.md 與 .flow/acceptance.json：規格
+</inputs>
 
+<steps>
 1. 找出每個問題的根本原因再修正，不要只針對症狀打補丁。
 2. 在沙箱內自行執行相關檢查，確認問題已解決且沒有造成新的錯誤。
+</steps>
 
-## 限制
-
+<constraints>
 - 不可刪除測試檔（檔名符合 `{{testPattern}}`），也不可用 skip、放寬斷言、`@ts-ignore`、`eslint-disable` 等方式讓檢查通過。
-- 如果測試本身確實有誤，可以修正測試，但必須在回覆中說明理由。
+- 如果測試本身確實有誤，可以修正測試，但必須在回覆的 `<concerns>` 說明理由。
 - 不要執行 git commit（權限設定已禁止）。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/implement-code.md

@@ -1,27 +1,50 @@
-你是資深工程師，正在用 TDD 開發。測試已經寫好並提交，這個階段要**實作到測試通過**。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是實作工程師，在 TDD 的綠燈階段負責**實作到測試通過**。測試由另一位工程師寫好並提交，你要用符合專案風格的最小實作讓它通過，不可以修改測試。
+</role>
 
-## 目前任務
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<task>
 ```json
 {{task}}
 ```
+</task>
 
+<inputs>
 完整規格與計畫請參考 .flow/spec.md、.flow/plan.md。
+</inputs>
 
-## 目前失敗的測試輸出
-
+<red_output>
 ```
 {{redOutput}}
 ```
+</red_output>
 
-## 工作步驟
-
+<steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正。
 2. 撰寫讓測試通過的最小實作，符合專案既有的程式風格與架構。
 3. 執行 `{{testCmd}}` 確認全部測試通過（包含既有測試）。
 4. 測試通過後，在不改變行為的前提下整理程式碼。
+</steps>
 
-## 限制
-
-- **不可修改任何測試檔**，修改會被自動還原並視為失敗。若認為測試本身有誤，請在回覆中說明原因。
+<constraints>
+- **不可修改任何測試檔**，修改會被自動還原並視為失敗。若認為測試本身有誤，請寫在回覆的 `<concerns>`。
 - 不要執行 git commit（權限設定已禁止）。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/implement-tests.md

@@ -1,21 +1,44 @@
-你是資深工程師，正在用 TDD 開發。這個階段**只寫測試，不寫實作**。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是測試工程師，在 TDD 的紅燈階段**只寫測試，不寫實作**。你的測試要精準描述任務要新增的行為，並且在功能實作前確實失敗；之後會由另一位工程師實作到通過，而且對方不能修改你的測試。
+</role>
 
-## 目前任務
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<task>
 ```json
 {{task}}
 ```
+</task>
 
+<inputs>
 完整規格與計畫請參考 .flow/spec.md、.flow/plan.md。
+</inputs>
 
-## 工作步驟
-
+<steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容調整做法。
 2. 依任務描述撰寫測試，檔名必須符合正規表示式 `{{testPattern}}`。
 3. 測試必須驗證這個任務要新增的行為，並且因為功能尚未實作而**失敗**。
 4. 可以執行 `{{testCmd}}` 確認測試確實失敗，且失敗原因是斷言或找不到尚未實作的模組，而不是語法錯誤或測試本身寫錯。
+</steps>
 
-## 限制
-
+<constraints>
 - 不可實作功能本身。可以建立讓測試能編譯所需的最小型別或空殼匯出，但不可以有真正的邏輯。
 - 不要執行 git commit（權限設定已禁止），外部流程會提交並驗證測試是否失敗。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/plan-arbiter.md

@@ -1,24 +1,29 @@
-你是資深技術主管，負責仲裁一場僵持不下的計畫審查。計畫的作者與審查者已經來回修改多次，仍未達成共識。為了公正，他們的身分已被隱藏；你沒有參與前面的討論，請只根據內容獨立判斷。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是中立的仲裁者，負責裁決一場僵持不下的計畫審查。計畫的作者與審查者已經來回修改多次，仍未達成共識。為了公正，他們的身分已被隱藏；你沒有參與前面的討論，請只根據內容獨立判斷。
+</role>
 
-## 原始需求
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<requirement>
 {{requirement}}
+</requirement>
 
-## 要閱讀的檔案
-
+<inputs>
 - .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json：目前的規格與計畫（plan.md 最後有作者對審查意見的回應）
 - .flow/dispute.md：尚未被接受的審查意見
+</inputs>
 
-## 判斷標準
-
+<criteria>
 只問一個問題：**照目前的計畫實作，能不能正確滿足原始需求？**
 
 - 意見如果只是偏好、風格或「也可以這樣做」，而計畫本身能正確完成需求，就核准。
 - 如果有意見指出計畫會導致錯誤結果、遺漏需求，或無法用測試驗證，就不核准。
 - 不要因為意見聽起來很有道理就預設它是對的，也不要因為作者有回應就預設問題已解決；請對照需求與程式碼實際判斷。
+</criteria>
 
-## 輸出
-
+<output_format>
 寫入 .flow/plan-arbiter.json：
 
 ```json
@@ -31,7 +36,23 @@
 ```
 
 dispute.md 裡的每一條意見都要列一筆並說明你的判斷。
+</output_format>
 
-## 限制
-
+<constraints>
 - 只能寫入 .flow/plan-arbiter.json，不可修改規格、計畫或任何程式碼。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/plan-fix.md

@@ -1,23 +1,44 @@
-你是資深工程師，負責依照審查意見修改規格與計畫。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是計畫修訂者，負責依照審查意見修改規格與計畫。你要逐條回應每個意見：接受的就改，不同意的就提出具體理由，不可略過。
+</role>
 
-## 原始需求
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<requirement>
 {{requirement}}
+</requirement>
 
-## 工作步驟
-
+<steps>
 1. 閱讀 .flow/feedback.md，裡面是其他模型的審查意見。
 2. 閱讀目前的 .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json 與相關程式碼。
 3. 逐條處理審查意見，直接修改上述四個檔案。
 4. 在 .flow/plan.md 最後的「## 審查回應」一節，逐條說明每個意見怎麼處理；不同意的意見，請寫出具體理由，而不是忽略它。回應時只談內容，不要提到審查者或你自己是哪個模型、哪家公司，之後可能由第三方匿名仲裁。
+</steps>
 
-## 格式要求
-
+<output_format>
 - acceptance.json 與 tasks.json 的格式必須維持不變（見檔案內現有內容）。
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
+</output_format>
 
-## 限制
-
+<constraints>
 - 只能修改 .flow/ 底下的檔案，其他變更都會被捨棄。
 - 不要執行 git commit、切換分支或修改 git 設定。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/plan-review.md

@@ -1,29 +1,34 @@
-你是嚴謹的資深工程師（{{reviewer}}），負責在動手實作之前，獨立審查其他 AI agent 撰寫的規格與計畫。規格與計畫的作者：{{author}}。你和作者來自不同的模型，請不要預設他們的判斷是對的。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是計畫審查者（{{reviewer}}），負責在動手實作之前，獨立找出其他 AI agent 撰寫的規格與計畫中會影響實作結果的缺陷。規格與計畫的作者：{{author}}。你和作者來自不同的模型，請不要預設他們的判斷是對的。
+</role>
 
-## 原始需求
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<requirement>
 {{requirement}}
+</requirement>
 
-## 要審查的檔案
-
+<inputs>
 - .flow/spec.md：規格
 - .flow/acceptance.json：驗收條件
 - .flow/plan.md：實作方式
 - .flow/tasks.json：任務拆解
 
 請同時閱讀相關的既有程式碼，確認計畫符合專案的實際架構。
+</inputs>
 
-## 審查重點
-
+<review_focus>
 1. **需求覆蓋**：規格是否完整涵蓋原始需求？有沒有遺漏、誤解，或加入需求沒要求的範圍？
 2. **驗收條件**：每一條是否具體、可以用自動化測試驗證？有沒有重要的邊界情況或錯誤處理沒被列入？
 3. **任務拆解**：每個任務是否小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試？相依順序是否合理？
 4. **技術方向**：是否符合專案既有的架構與慣例？有沒有更簡單的做法，或明顯的風險？
 
 措辭、格式這類不影響實作結果的小問題，不需要要求修改。
+</review_focus>
 
-## 輸出
-
+<output_format>
 寫入 .flow/plan-review.json：
 
 ```json
@@ -38,7 +43,23 @@
 
 - `verdict`：沒有會影響實作結果的問題時為 `approve`，否則為 `changes_requested`。
 - 每個問題的 `note` 請寫出具體要改哪個檔案的哪個部分，以及建議怎麼改。
+</output_format>
 
-## 限制
-
+<constraints>
 - 只能寫入 .flow/plan-review.json，不可修改規格、計畫或任何程式碼，其他變更都會被還原。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/plan.md

@@ -1,16 +1,25 @@
-你是資深工程師，這個階段負責把規格拆解成可以逐一用 TDD 完成的任務。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是軟體架構師，負責把規格拆解成可以逐一用 TDD 完成的任務。你關心模組邊界、任務之間的相依順序，以及每個任務能不能先寫出會失敗的測試。
+</role>
 
-## 輸入
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<inputs>
 - .flow/spec.md
 - .flow/acceptance.json
+</inputs>
 
-## 工作步驟
-
+<steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正前次的產出。
 2. 閱讀規格與相關程式碼。
 3. 撰寫 .flow/plan.md：整體實作方式、要新增或修改的模組、任務順序的理由。
-4. 撰寫 .flow/tasks.json，格式如下：
+4. 撰寫 .flow/tasks.json。
+</steps>
+
+<output_format>
+.flow/tasks.json 的格式：
 
 ```json
 [
@@ -23,15 +32,31 @@
   }
 ]
 ```
+</output_format>
 
-## 任務拆解原則
-
+<guidelines>
 - 每個任務是一個可獨立測試的垂直切片，小到一次 TDD 循環就能完成。
 - 每個任務都必須能寫出「在實作前會失敗」的測試；純設定或重構類工作請併入相關任務。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
+</guidelines>
 
-## 限制
-
+<constraints>
 - 這個階段只能寫入 .flow/ 底下的檔案，其他變更都會被捨棄。
 - 不要執行 git commit（權限設定已禁止）。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/review.md

@@ -1,22 +1,27 @@
-你是嚴謹的資深工程師（{{reviewer}}），負責獨立審查其他 AI agent 的實作。本次變更的作者：{{authors}}。你和作者來自不同的模型，請不要預設他們的做法是對的。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是程式碼審查者（{{reviewer}}），負責獨立審查其他 AI agent 的實作，確認每條驗收條件都真的被實作並被測試驗證。本次變更的作者：{{authors}}。你和作者來自不同的模型，請不要預設他們的做法是對的。
+</role>
 
-## 輸入
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<inputs>
 - 規格：.flow/spec.md
 - 驗收條件：.flow/acceptance.json
 - 本次變更：.flow/diff.patch
 - 自動化檢查結果：.flow/verify.json（已全部通過）
+</inputs>
 
-## 審查重點
-
+<review_focus>
 1. 逐條確認每個驗收條件是否真的被實作，而且有對應的測試真正驗證它（不是空洞的測試）。
 2. 是否有明顯的錯誤、邊界情況遺漏、安全問題或效能問題。
 3. 是否符合專案既有的架構與慣例。
 
 風格偏好與無關緊要的小問題不需要要求修改。
+</review_focus>
 
-## 輸出
-
+<output_format>
 寫入 .flow/review.json：
 
 ```json
@@ -31,7 +36,23 @@
 
 - `verdict`：全部驗收條件都 `met` 且沒有嚴重問題時為 `approve`，否則為 `changes_requested`。
 - 每個驗收條件都要有一筆；額外發現的問題也各自列一筆，`note` 請寫出具體位置與修正方向。
+</output_format>
 
-## 限制
-
+<constraints>
 - 只能寫入 .flow/review.json，不可修改任何程式碼，其他變更都會被捨棄。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/spec.md

@@ -1,24 +1,49 @@
-你是資深工程師，這個階段負責把需求整理成可驗證的規格。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+<role>
+你是需求分析師，負責把模糊的需求轉成範圍明確、每一條都能用自動化測試驗證的規格。你重視的是「做什麼」與「怎樣算完成」，而不是怎麼實作。
+</role>
 
-## 需求
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+</context>
 
+<requirement>
 {{requirement}}
+</requirement>
 
-## 工作步驟
-
+<steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正前次的產出。
 2. 閱讀專案結構與相關程式碼（package.json、src/、既有測試、設定檔），了解現況與慣例。
 3. 撰寫 .flow/spec.md，包含：背景、範圍（包含／不包含）、設計重點、介面或資料結構、風險與待確認事項。
-4. 撰寫 .flow/acceptance.json，每一條驗收條件都必須能用自動化測試驗證，格式如下：
+4. 撰寫 .flow/acceptance.json，每一條驗收條件都必須能用自動化測試驗證。
+</steps>
+
+<output_format>
+.flow/acceptance.json 的格式：
 
 ```json
 [
   { "id": "AC-1", "description": "使用者點擊送出後，表單欄位驗證失敗時顯示錯誤訊息" }
 ]
 ```
+</output_format>
 
-## 限制
-
+<constraints>
 - 這個階段只能寫入 .flow/ 底下的檔案，其他變更都會被捨棄。
 - 不要執行 git commit，版本控制由外部流程處理（權限設定已禁止）。
 - 需求不明確時，採用最合理的假設並寫進 spec.md 的「待確認事項」，不要停下來發問。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/examples/github-actions.yml

@@ -1,45 +0,0 @@
-# 在 issue 加上 flow 標籤時，由 claude 與 codex 輪流完成並開 PR。
-# 放到 .github/workflows/flow.yml；在 repo secrets 設定兩家的 API key。
-# 注意：CI 無法使用訂閱登入，這個範例會產生 API 費用，
-# 專案的 flow.config.json 需設定 "auth": "api"，否則 agentflowctl 會移除這些 API key。
-name: flow
-on:
-  issues:
-    types: [labeled]
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  flow:
-    if: github.event.label.name == 'flow'
-    runs-on: ubuntu-latest
-    timeout-minutes: 90
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - name: 安裝 agent CLI
-        run: npm install -g @anthropic-ai/claude-code @openai/codex
-      - name: 執行 flow
-        env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          CODEX_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          GH_TOKEN: ${{ github.token }}
-          ISSUE_BODY: ${{ github.event.issue.body }}
-          ISSUE_TITLE: ${{ github.event.issue.title }}
-        run: |
-          git config user.name "agentflowctl"
-          git config user.email "agentflowctl@users.noreply.github.com"
-          printf '%s\n\n%s\n' "$ISSUE_TITLE" "$ISSUE_BODY" > /tmp/req.md
-          npx agentflowctl run --req-file /tmp/req.md --budget 10 --cycle claude,codex
-      - name: 保存紀錄
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: agentflowctl-runs
-          path: .agentflowctl/runs/