agentflowctl 0.1.0

package/dist/roles.js

@@ -0,0 +1,79 @@
+/**
+ * 決定每個步驟由哪個 agent 執行。
+ *
+ * 規則只有三條：
+ * 1. 審查者不能是最後寫程式的 agent。
+ * 2. 開啟 tddSplit 時，同一個任務的測試與實作由不同 agent 負責。
+ * 3. 所有選擇都沿著同一個輪替順序（cycle）前進，所以不同公司的模型會輪流扮演各個角色。
+ */
+/** 從 from 的下一位開始，找第一個不在 exclude 裡的 agent；全部被排除時退回下一位（單一 agent 也能運作） */
+export function nextAfter(cycle, from, exclude = []) {
+    const n = cycle.length;
+    const start = from === undefined ? -1 : cycle.indexOf(from);
+    for (let i = 1; i <= n; i++) {
+        const candidate = cycle[(start + i + n) % n];
+        if (!exclude.includes(candidate))
+            return candidate;
+    }
+    return cycle[(start + 1 + n) % n];
+}
+export const specAgent = (cycle) => cycle[0];
+export const planAgent = (cycle) => cycle[0];
+/** 第 i 個任務的測試由輪替順序的第 i 位負責，實作交給下一位 */
+export function taskAgents(cycle, taskIndex, tddSplit) {
+    const tests = cycle[taskIndex % cycle.length];
+    return { tests, code: tddSplit ? nextAfter(cycle, tests, [tests]) : tests };
+}
+/** 從最後寫程式的 agent 之後，依序挑出 quorum 位不重複、而且不是作者的 reviewer */
+export function reviewers(cycle, lastWriter, quorum) {
+    const picked = [];
+    let cursor = lastWriter;
+    for (let i = 0; i < cycle.length && picked.length < quorum; i++) {
+        const next = nextAfter(cycle, cursor, [...(lastWriter ? [lastWriter] : []), ...picked]);
+        if (picked.includes(next) || (next === lastWriter && cycle.length > 1))
+            break;
+        picked.push(next);
+        cursor = next;
+    }
+    return picked.length ? picked : [nextAfter(cycle, lastWriter)];
+}
+/**
+ * 誰來修正：
+ * - verify 失敗（型別、lint、建置這類機械性錯誤）：交給最後寫程式的 agent
+ * - review 要求修改：ring 策略輪到 reviewer 的下一位；author 策略交回作者
+ */
+export function fixAgent(cycle, opts) {
+    if (opts.source === "verify" || opts.strategy === "author")
+        return opts.lastWriter ?? cycle[0];
+    return nextAfter(cycle, opts.lastReviewer, opts.lastReviewer ? [opts.lastReviewer] : []);
+}
+/** 計畫修正者：ring 策略輪到審查者的下一位；author 策略交回計畫作者 */
+export function planFixAgent(cycle, opts) {
+    if (opts.strategy === "author")
+        return opts.planWriter ?? cycle[0];
+    return nextAfter(cycle, opts.planReviewer, opts.planReviewer ? [opts.planReviewer] : []);
+}
+/**
+ * 仲裁小組：
+ * - 有第三方（作者與最後審查者以外的 agent）→ 由第三方單獨仲裁
+ * - 只有兩家 → 兩家各自在全新 context 中雙盲仲裁，避免讓一直反對的審查者同時當裁判
+ * - 只有一家 → 只能由它自己仲裁
+ */
+export function arbiterPanel(cycle, writer, reviewer) {
+    const involved = [writer, reviewer].filter((x) => Boolean(x));
+    const third = cycle.find((c) => !involved.includes(c));
+    if (third)
+        return [third];
+    return [...new Set(cycle)];
+}
+/**
+ * 代打人選：原本的 agent 可用就用它；額度用完時，沿輪替順序找下一位還有額度的 agent。
+ * 全部都用完時回傳 undefined。
+ */
+export function availableAgent(cycle, preferred, exhausted) {
+    if (!exhausted.includes(preferred))
+        return preferred;
+    const next = nextAfter(cycle, preferred, exhausted);
+    return exhausted.includes(next) ? undefined : next;
+}
+//# sourceMappingURL=roles.js.map

package/dist/runner.js

@@ -0,0 +1,125 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+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 時會移除 */
+export const API_KEY_VARS = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CODEX_API_KEY",
+    "OPENAI_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+];
+/**
+ * 判斷 agent 失敗是否因為方案額度或速率限制。
+ * 各家的錯誤訊息會隨版本變動，這裡用寬鬆的樣式比對，且只在執行失敗時才檢查，避免誤判正常輸出。
+ */
+const QUOTA_PATTERNS = [
+    /usage limit/i,
+    /rate[ _-]?limit/i,
+    /quota/i,
+    /resource[_ ]exhausted/i,
+    /limit reached/i,
+    /too many requests/i,
+    /hit your (usage )?limit/i,
+    /\b429\b/,
+];
+export const isQuotaError = (text) => QUOTA_PATTERNS.some((p) => p.test(text));
+function appendLog(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, text.endsWith("\n") ? text : `${text}\n`);
+}
+/** 內建的 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)) {
+        return AgentDef.parse({ adapter: name });
+    }
+    throw new Error(`未定義的 agent：${name}（請在 flow.config.json 的 agents 裡設定）`);
+}
+/** 確認某個 agent 的 CLI 是否可以執行 */
+export async function probeAgent(def) {
+    const { cmd, args } = ADAPTERS[def.adapter].probe(def.command);
+    try {
+        return (await exec(cmd, args)).code === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** 執行任一家的 agent CLI，把輸出正規化成同一種結果 */
+export async function runAgent(name, def, t, prompt, opts) {
+    const adapter = ADAPTERS[def.adapter];
+    const inv = adapter.invoke({
+        prompt,
+        cwd: t.cwd,
+        model: def.model,
+        extraArgs: def.extraArgs,
+        runDir: runDir(t.runId),
+        projectRoot: projectRoot(),
+        command: def.command,
+    });
+    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 : [],
+        input: inv.input,
+        onStdoutLine: (line) => {
+            if (!line.trim())
+                return;
+            appendLog(t.logFile, line);
+            for (const ev of adapter.parse(line)) {
+                if (ev.kind === "text") {
+                    lastText = ev.text;
+                    console.log(`    💬 [${name}] ${ev.text.trim().split("\n")[0]?.slice(0, 110)}`);
+                }
+                else if (ev.kind === "tool") {
+                    console.log(`    🔧 [${name}] ${ev.name}`);
+                }
+                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 };
+                }
+            }
+        },
+    });
+    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 };
+}
+/**
+ * 在 worktree 內執行專案指令（安裝、測試、建置）。
+ * 注意：這些指令會執行 agent 寫出來的程式碼，而且不在任何沙箱內。
+ */
+export async function runCommand(t, cmd) {
+    appendLog(t.logFile, `$ ${cmd}`);
+    const r = await execShell(cmd, { cwd: t.cwd });
+    const output = `${r.stdout}\n${r.stderr}`.trim();
+    appendLog(t.logFile, output);
+    return { ok: r.code === 0, output };
+}
+//# sourceMappingURL=runner.js.map

package/dist/schemas.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+export const Stage = z.enum([
+    "spec",
+    "plan",
+    "plan_review",
+    "plan_fix",
+    "awaiting_approval",
+    "implement",
+    "verify",
+    "fix",
+    "review",
+    "pr",
+    "paused",
+    "done",
+    "failed",
+]);
+/** Agent 在 spec 階段產出的 .flow/acceptance.json */
+export const AcceptanceList = z
+    .array(z.object({
+    id: z.string().regex(/^AC-\d+$/, "id 格式必須是 AC-<數字>"),
+    description: z.string().min(1),
+}))
+    .min(1);
+export const TaskItem = z.object({
+    id: z.string().regex(/^T-\d+$/, "id 格式必須是 T-<數字>"),
+    title: z.string().min(1),
+    description: z.string().min(1),
+    dependsOn: z.array(z.string()).default([]),
+    acceptance: z.array(z.string()).min(1, "每個任務至少要對應一條驗收條件"),
+});
+/** Agent 在 plan 階段產出的 .flow/tasks.json */
+export const TaskList = z.array(TaskItem).min(1);
+/** Agent 在 review 階段產出的 .flow/review.json */
+export const ReviewResult = z.object({
+    verdict: z.enum(["approve", "changes_requested"]),
+    items: z.array(z.object({
+        criterion: z.string(),
+        status: z.enum(["met", "not_met", "partial"]),
+        note: z.string().default(""),
+    })),
+});
+/** 一個 agent 的定義；名稱（agents 的 key）用在輪替順序裡 */
+export const AgentDef = z.object({
+    adapter: z.enum(["claude", "codex", "gemini", "command"]),
+    model: z.string().optional(),
+    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({}),
+    /** 輪替順序；未設定時自動偵測已安裝的 CLI */
+    cycle: z.array(z.string()).min(1).optional(),
+    /** review 後的修正由誰做：ring＝輪到下一位；author＝最後寫程式的 agent */
+    fixStrategy: z.enum(["ring", "author"]).default("ring"),
+    /** TDD 的測試與實作交給不同的 agent */
+    tddSplit: z.boolean().default(true),
+    /** 需要幾位不同的 reviewer 都核准 */
+    reviewQuorum: z.number().int().min(1).default(1),
+    /** 計畫需要幾位不同的 reviewer 都核准 */
+    planReviewQuorum: z.number().int().min(1).default(1),
+    /** 計畫審查僵持不下（達到重試上限或意見不再變化）時，交給第三方 agent 仲裁，而不是停下來等人 */
+    planArbiter: z.boolean().default(true),
+    /**
+     * 仲裁意見分歧時怎麼辦（只有兩家時由雙方各自仲裁，才可能分歧）：
+     * 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；訂閱制下用這個取代金額預算 */
+    maxAgentRuns: z.number().int().positive().default(60),
+    install: z.string().default("npm install --no-audit --no-fund"),
+    test: z.string().default("npx vitest run"),
+    testPattern: z.string().default("\\.(test|spec)\\.[cm]?[jt]sx?$"),
+    checks: z
+        .array(z.object({ name: z.string(), cmd: z.string() }))
+        .default([
+        { name: "typecheck", cmd: "npx tsc --noEmit" },
+        { name: "lint", cmd: "npx eslint ." },
+        { name: "test", cmd: "npx vitest run" },
+        { name: "build", cmd: "npx vite build" },
+    ]),
+});
+export const FlowRun = z.object({
+    id: z.string(),
+    baseBranch: z.string(),
+    branch: z.string(),
+    requirement: z.string(),
+    stage: Stage,
+    autopilot: z.boolean(),
+    /** 選用：以估計花費（美元）為上限；訂閱登入時通常不設定 */
+    budgetUsd: z.number().positive().optional(),
+    /** 單一 run 最多執行幾次 agent */
+    maxAgentRuns: z.number().int().positive(),
+    /** 暫停前所在的階段與原因（額度用完時） */
+    pausedStage: Stage.optional(),
+    pauseReason: z.string().optional(),
+    /** 這個 run 的 agent 輪替順序（建立時決定，resume 時沿用） */
+    cycle: z.array(z.string()).min(1),
+    /** 最後一個寫程式的 agent，reviewer 不可以是它 */
+    lastWriter: z.string().optional(),
+    /** 最後一個要求修改的 reviewer */
+    lastReviewer: z.string().optional(),
+    /** 最後一個撰寫或修改規格與計畫的 agent */
+    planWriter: z.string().optional(),
+    /** 最後一個對計畫要求修改的 reviewer */
+    planReviewer: z.string().optional(),
+    /** 目前的 fix 是因為 verify 失敗還是 review 要求修改 */
+    fixSource: z.enum(["verify", "review"]).optional(),
+    /** 各關卡的連續失敗次數 */
+    attempts: z.record(z.string(), z.number()),
+    taskIndex: z.number().int().nonnegative(),
+    taskPhase: z.enum(["tests", "code"]),
+    testsCommit: z.string().optional(),
+    /** 目前任務的測試實際由誰撰寫（可能是代打） */
+    lastTestsAuthor: z.string().optional(),
+    failedStage: Stage.optional(),
+    failureReason: z.string().optional(),
+    prUrl: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/store.js

@@ -0,0 +1,77 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+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");
+/** 先寫暫存檔再 rename，確保 state.json 不會因中斷而只寫一半 */
+function writeAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
+export function saveRun(run) {
+    const next = FlowRun.parse({ ...run, updatedAt: new Date().toISOString() });
+    writeAtomic(statePath(next.id), JSON.stringify(next, null, 2));
+    return next;
+}
+export function getRun(id) {
+    const p = statePath(id);
+    return existsSync(p) ? FlowRun.parse(JSON.parse(readFileSync(p, "utf8"))) : undefined;
+}
+export function listRuns() {
+    const dir = join(agentflowctlDir(), "runs");
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .map(getRun)
+        .filter((r) => r !== undefined)
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export function addCost(id, entry) {
+    mkdirSync(runDir(id), { recursive: true });
+    appendFileSync(costPath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
+}
+/** 依 agent 加總花費與 token，方便比較各家模型 */
+export function costByAgent(id) {
+    const p = costPath(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;
+        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） */
+export function agentRuns(id) {
+    const p = costPath(id);
+    return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).length : 0;
+}
+const subPath = (id) => join(runDir(id), "substitutions.jsonl");
+export function addSubstitution(id, s) {
+    mkdirSync(runDir(id), { recursive: true });
+    appendFileSync(subPath(id), `${JSON.stringify({ at: new Date().toISOString(), ...s })}\n`);
+}
+export function listSubstitutions(id) {
+    const p = subPath(id);
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+//# sourceMappingURL=store.js.map

package/dist/tasks.js

@@ -0,0 +1,51 @@
+/**
+ * 檢查任務清單並依相依關係排序（Kahn 演算法）。
+ * 回傳排序後的任務，或回傳一段可以直接回饋給 Agent 的錯誤說明。
+ */
+export function orderTasks(tasks, acceptanceIds) {
+    const errors = [];
+    const ids = new Set();
+    for (const t of tasks) {
+        if (ids.has(t.id))
+            errors.push(`任務 id 重複：${t.id}`);
+        ids.add(t.id);
+    }
+    const covered = new Set();
+    for (const t of tasks) {
+        for (const d of t.dependsOn)
+            if (!ids.has(d))
+                errors.push(`${t.id} 相依的 ${d} 不存在`);
+        for (const a of t.acceptance) {
+            if (!acceptanceIds.has(a))
+                errors.push(`${t.id} 對應的驗收條件 ${a} 不存在`);
+            covered.add(a);
+        }
+    }
+    for (const a of acceptanceIds)
+        if (!covered.has(a))
+            errors.push(`驗收條件 ${a} 沒有任何任務負責`);
+    if (errors.length)
+        return errors.join("\n");
+    const indegree = new Map(tasks.map((t) => [t.id, t.dependsOn.length]));
+    const byId = new Map(tasks.map((t) => [t.id, t]));
+    const queue = tasks.filter((t) => t.dependsOn.length === 0).map((t) => t.id);
+    const ordered = [];
+    while (queue.length) {
+        const id = queue.shift();
+        ordered.push(byId.get(id));
+        for (const t of tasks) {
+            if (!t.dependsOn.includes(id))
+                continue;
+            const n = (indegree.get(t.id) ?? 0) - 1;
+            indegree.set(t.id, n);
+            if (n === 0)
+                queue.push(t.id);
+        }
+    }
+    if (ordered.length !== tasks.length) {
+        const stuck = tasks.filter((t) => !ordered.includes(t)).map((t) => t.id);
+        return `任務之間有循環相依：${stuck.join(", ")}`;
+    }
+    return ordered;
+}
+//# sourceMappingURL=tasks.js.map

package/dist/util.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+export function tail(s, max = 4000) {
+    return s.length <= max ? s : `…（前略）\n${s.slice(-max)}`;
+}
+const PROMPTS_DIR = new URL("../prompts/", import.meta.url);
+/** 讀取 prompts/<name>.md 並代入 {{變數}} */
+export function renderPrompt(name, vars = {}) {
+    const tpl = readFileSync(new URL(`${name}.md`, PROMPTS_DIR), "utf8");
+    return tpl.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+        const value = vars[key];
+        if (value === undefined)
+            throw new Error(`prompt「${name}」缺少變數 ${key}`);
+        return value;
+    });
+}
+/** 讀取 Agent 產出的 JSON 檔並用 zod 驗證，錯誤訊息會直接回饋給 Agent */
+export function readJsonFile(path, schema) {
+    if (!existsSync(path))
+        return { ok: false, error: `找不到 ${path}` };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        return { ok: false, error: `${path} 不是合法的 JSON：${e.message}` };
+    }
+    const parsed = schema.safeParse(raw);
+    return parsed.success
+        ? { ok: true, data: parsed.data }
+        : { ok: false, error: `${path} 格式錯誤：\n${z.prettifyError(parsed.error)}` };
+}
+//# sourceMappingURL=util.js.map

package/examples/flow.config.json

@@ -0,0 +1,26 @@
+{
+  "cycle": ["claude", "codex"],
+  "fixStrategy": "ring",
+  "tddSplit": true,
+  "reviewQuorum": 1,
+  "planReviewQuorum": 1,
+  "planArbiter": true,
+  "tieBreak": "proceed",
+  "auth": "subscription",
+  "maxAgentRuns": 60,
+  "agents": {
+    "claude": { "adapter": "claude" },
+    "codex": {
+      "adapter": "codex",
+      "pricing": { "inputPerMTok": 1.25, "outputPerMTok": 10 }
+    }
+  },
+  "install": "pnpm ci",
+  "test": "npx vitest run",
+  "checks": [
+    { "name": "typecheck", "cmd": "npx tsc --noEmit" },
+    { "name": "lint", "cmd": "npx eslint ." },
+    { "name": "test", "cmd": "npx vitest run" },
+    { "name": "build", "cmd": "npx vite build" }
+  ]
+}

package/examples/github-actions.yml

@@ -0,0 +1,47 @@
+# 在 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 與 agentflowctl
+        run: |
+          npm install -g @anthropic-ai/claude-code @openai/codex
+          npm install -g agentflowctl
+      - 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
+          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/

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "agentflowctl",
+  "license": "MIT",
+  "version": "0.1.0",
+  "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
+  "keywords": [
+    "ai",
+    "agent",
+    "claude-code",
+    "codex",
+    "gemini",
+    "code-review",
+    "tdd",
+    "cli"
+  ],
+  "author": "Jin-Ze Huang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gogogohuang/agentflowctl.git"
+  },
+  "homepage": "https://github.com/gogogohuang/agentflowctl#readme",
+  "bugs": {
+    "url": "https://github.com/gogogohuang/agentflowctl/issues"
+  },
+  "type": "module",
+  "bin": {
+    "agentflowctl": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "prompts",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@9.11.0",
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run typecheck && pnpm test && pnpm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/prompts/fix.md

@@ -0,0 +1,17 @@
+你是資深工程師，這個階段負責修正驗證或程式碼審查發現的問題。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+
+## 要修正的問題
+
+請先閱讀 .flow/feedback.md，裡面列出了失敗的檢查（型別、lint、測試、建置）或審查意見。
+規格請參考 .flow/spec.md 與 .flow/acceptance.json。
+
+## 工作步驟
+
+1. 找出每個問題的根本原因再修正，不要只針對症狀打補丁。
+2. 在沙箱內自行執行相關檢查，確認問題已解決且沒有造成新的錯誤。
+
+## 限制
+
+- 不可刪除測試檔（檔名符合 `{{testPattern}}`），也不可用 skip、放寬斷言、`@ts-ignore`、`eslint-disable` 等方式讓檢查通過。
+- 如果測試本身確實有誤，可以修正測試，但必須在回覆中說明理由。
+- 不要執行 git commit（權限設定已禁止）。

package/prompts/implement-code.md

@@ -0,0 +1,27 @@
+你是資深工程師，正在用 TDD 開發。測試已經寫好並提交，這個階段要**實作到測試通過**。目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+
+## 目前任務
+
+```json
+{{task}}
+```
+
+完整規格與計畫請參考 .flow/spec.md、.flow/plan.md。
+
+## 目前失敗的測試輸出
+
+```
+{{redOutput}}
+```
+
+## 工作步驟
+
+1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正。
+2. 撰寫讓測試通過的最小實作，符合專案既有的程式風格與架構。
+3. 執行 `{{testCmd}}` 確認全部測試通過（包含既有測試）。
+4. 測試通過後，在不改變行為的前提下整理程式碼。
+
+## 限制
+
+- **不可修改任何測試檔**，修改會被自動還原並視為失敗。若認為測試本身有誤，請在回覆中說明原因。
+- 不要執行 git commit（權限設定已禁止）。