flow-orchestration

All-in-One Flow 編排知識

Pipeline 架構

All-in-One Flow 是一個 YAML 驅動的多代理開發工作流：

JIRA 需求擷取 → 文件掃描 → Codebase 分析 → Proposal 生成
    → Proposal Review Loop → TDD 規劃 → 程式碼實作 → 最終審查

YAML Flow 定義

工作流由 YAML 檔案定義（flows/default.yaml 或專案根目錄的 .flow.yaml）。

Step 類型

1. prompt — 單次執行：一個 prompt → 一個 output
2. review-loop — 審查迭代：reviewer ↔ author，直到通過或達上限

Model 選項（Claude 模型）

• haiku — 輕量任務（擷取、掃描），最便宜
• sonnet — 中等任務（分析、規劃、實作），最佳 CP 值
• opus — 深度推理（Proposal 生成），最強

當 cli: codex 時，model 欄位設為 codex，表示使用 OpenAI Codex 作為執行引擎，非 Claude 模型。

CLI 選項

• claude — 直接由 Claude 執行（你自己）
• codex — 委派給 Codex CLI
• copilot — 委派給 GitHub Copilot CLI

CLI 委派具體指令

cli: claude（你自己）

直接執行 prompt 內容，不需要 bash 呼叫。model 欄位（haiku/sonnet/opus）僅作為 prompt 設計的參考，Claude Code 會用當前 session 的 model 執行。

cli: codex

codex --task "<prompt_content>" --write --cwd "$PWD"

• --write：允許 Codex 修改檔案
• 若只需審查（如 review 步驟），省略 --write：

codex --task "<prompt_content>" --cwd "$PWD"

cli: copilot

gh copilot suggest "<prompt_summary>"

• Copilot CLI 適合程式碼生成建議
• 實際實作仍需 Claude 整合 Copilot 的輸出

Fallback 規則

當指定的 CLI 不可用時（load 輸出標記 ✗），自動切換：

主要 CLI	Fallback	說明
codex	claude	Codex 不可用時用 Claude 審查
copilot	claude	Copilot 不可用時用 Claude 實作

當 fallback 觸發時，model 也會相應調整（使用 fallback_model）。

Step 間 Output 傳遞

每個步驟的產出寫入 .flow-output/<output>。後續步驟需要讀取前置步驟的產出：

1. 執行 Step N，結果寫入 .flow-output/<step_N_output>
2. 執行 Step N+1 時：
   a. 取得 prompt 模板（flow-companion.mjs prompt）
   b. 讀取 prompt 中提及的前置步驟 output 檔案
   c. 將檔案內容作為上下文注入 prompt 執行

範例：Step 4 (Proposal) 依賴 Step 1-3

# prompt 中會指示讀取：
.flow-output/step-01-jira.md      ← Step 1 產出
.flow-output/step-02-docs.md      ← Step 2 產出
.flow-output/step-03-codebase.md  ← Step 3 產出

Agent 應先用 Read 工具讀取這些檔案，再結合 prompt 一起執行。

Review Loop 執行邏輯

round = 1
while round <= max_rounds:
  1. 用 reviewer 的 model/cli 執行 reviewer.prompt
     → 產出審查意見
  2. 檢查意見是否包含 exit_on（例如 "APPROVE"）
  3. 若包含 → 標記完成，退出 loop
  4. 用 author 的 model/cli 執行 author.prompt
     → 根據審查意見修改 proposal
  5. round += 1
若 round > max_rounds → 標記完成（最大輪次已達），通知使用者

Prompt 變數慣例

Prompt 模板中使用 {VARIABLE} 語法，常見變數：

變數	說明
{TICKET_ID}	JIRA ticket ID
{PROJECT_ROOT}	專案根目錄
{OUTPUT_DIR}	輸出目錄（通常 .flow-output）

狀態管理

執行狀態儲存在 .flow-output/state.json：

• pending — 尚未開始
• running — 執行中
• completed — 已完成
• failed — 失敗
• skipped — 已跳過

自訂 Flow

使用者可複製 flows/default.yaml 到專案根目錄命名為 .flow.yaml，自由調整：

• 增刪步驟
• 更換 model/cli
• 調整 review loop 次數（max_rounds）
• 修改 prompt 路徑
• 設定步驟依賴