agentflowctl 0.1.2 → 0.3.0

package/dist/runner.js

@@ -1,11 +1,12 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { ADAPTERS, DEFAULT_CYCLE } from "./agents/index.js";
+import { z } from "zod";
+import { ADAPTERS, builtinAgents } 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,18 +30,48 @@ 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`);
 }
+/** 一行工具事件的畫面輸出：完整顯示指令或參數，多行時後續行縮排對齊 */
+export function formatToolLine(agent, tool) {
+    const head = `    🔧 [${agent}] ${tool.name}`;
+    const detail = tool.detail?.trim();
+    return detail ? `${head}: ${detail.split("\n").join("\n       ")}` : head;
+}
 /** 內建的 claude、codex、gemini 定義，可在 flow.config.json 覆寫或新增其他 agent */
 export function resolveAgent(cfg, name) {
     const custom = cfg.agents[name];
     if (custom)
         return custom;
-    if (DEFAULT_CYCLE.includes(name)) {
+    if (builtinAgents(cfg.removedAgents).includes(name)) {
         return AgentDef.parse({ adapter: name });
     }
+    if (cfg.removedAgents.includes(name))
+        throw new Error(`${name} 已從設定移除（removedAgents），要使用請先 agent add ${name} --adapter ${name}`);
     throw new Error(`未定義的 agent：${name}（請在 flow.config.json 的 agents 裡設定）`);
 }
 /** 確認某個 agent 的 CLI 是否可以執行 */
@@ -54,7 +85,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 +99,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())
@@ -86,13 +116,11 @@ export async function runAgent(name, def, t, prompt, opts) {
                     console.log(`    💬 [${name}] ${ev.text.trim().split("\n")[0]?.slice(0, 110)}`);
                 }
                 else if (ev.kind === "tool") {
-                    console.log(`    🔧 [${name}] ${ev.name}`);
+                    console.log(formatToolLine(name, ev));
                 }
                 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 +130,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 內執行專案指令（安裝、測試、建置）。
@@ -117,6 +142,7 @@ export async function runAgent(name, def, t, prompt, opts) {
  */
 export async function runCommand(t, cmd) {
     appendLog(t.logFile, `$ ${cmd}`);
+    console.log(`    $ ${cmd.trim().split("\n").join("\n      ")}`);
     const r = await execShell(cmd, { cwd: t.cwd });
     const output = `${r.stdout}\n${r.stderr}`.trim();
     appendLog(t.logFile, output);

package/dist/schemas.js

@@ -46,13 +46,13 @@ 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({
     /** 自訂或覆寫 agent；claude、codex、gemini 三個名稱內建 */
     agents: z.record(z.string(), AgentDef).default({}),
+    /** 移除的內建 agent：不再自動偵測，也不能放進輪替；用 agent add 加回 */
+    removedAgents: z.array(z.string()).default([]),
     /** 輪替順序；未設定時自動偵測已安裝的 CLI */
     cycle: z.array(z.string()).min(1).optional(),
     /** review 後的修正由誰做：ring＝輪到下一位；author＝最後寫程式的 agent */
@@ -70,12 +70,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 +91,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.3.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>