[exploration] 探索 IDD workflow 如何搭配 agent teams (verify ensemble / orchestration)

[kiki830621]

Problem

Original text:
「我之後要看怎麼搭配agent teams」
— Source: pasted text, /idd-issue invocation 2026-05-29

Plain-language interpretation: 一條 parking-lot 探索種子 — 之後要研究 IDD workflow 如何與 agent teams（多 agent 協作編排）搭配。現階段是 capture-the-thought,scope 尚未定形,留待 pick-up 時細化。

Type

feature / exploration（種子,非具體需求）

Priority

P3 —「之後要看」明確是低優先 someday/maybe。不阻擋當前 critical-path（#155 idd-edit alt-layer）。

Background / 為什麼值得記

IDD 已經在跑 multi-agent,但沒有 first-class 的「agent teams」整合策略:

• /idd-verify spawn 5 個 parallel Agent(subagent_type=general-purpose) + 1 Codex = 6-AI ensemble。 但這是手動 fan-out,不是 team 抽象。
• #52 把 idd-verify 從 TeamCreate model 遷出(改成 standalone Agent calls),因為 TeamCreate 的 wait_for_idle 在 idle/wake cycle 後 context 流失 + teammate 需顯式列 Write tool。
• #70 是 TeamCreate cleanup gap(TeamDelete fails on idle-but-active reviewers)— 遷出 team model 後 structurally 消解。
• /idd-all / /idd-all-chain 是 sequential orchestration,沒有 team-parallel。

所以「搭配 agent teams」這個探索有真實的張力:IDD 剛離開 TeamCreate,但 ensemble verify 本質上就是一個 team。 問題是:正確的 team 抽象長什麼樣?

候選探索線索（給未來的自己,非結論）

開工時這些是起點,不是已選方向:

1. Verify ensemble 形式化 — 目前 6-AI 是每次手刻 prompt + file-based output + polling。 是否值得抽成可重用的「review team」primitive？（但要避開 feature: idd-verify orchestration playbook (subagent_type guidance + recovery protocol) #52 遷出的 TeamCreate 痛點）
2. idd-all-chain × team-parallel — chain 目前 sequential 解 root + spawn。 多個 independent spawn 能否 team-parallel 跑？
3. Claude Code 原生 agent teams — 平台若有 agent-teams 機制（vs 手動 Agent fan-out），IDD 該不該採用？這需要先確認平台現況。
4. 跨 skill 的 reviewer pool — verify 的 5 reviewer 角色（requirements/logic/security/regression/DA）能否被其他 skill（如 spectra-verify、code-review）共用？

Out of scope（明確不在此 issue）

• 不重啟 TeamCreate（feature: idd-verify orchestration playbook (subagent_type guidance + recovery protocol) #52 已有充分理由遷出;除非探索發現新證據）
• 不改當前 idd-verify 行為（這是探索,不是 refactor proposal）

Next（when picked up）

先 /idd-clarify #THIS resolve「agent teams 指什麼」的 referent 歧義（見下方 Clarity Surface），再 /idd-diagnose 評 complexity。 探索性質大概率 /spectra-discuss（多個 valid 方向 + 影響 published skill 編排契約）。

---

Clarity Surface

Authored inline at creation (proportionate to a terse exploration seed; run full /idd-clarify #164 when picked up for the complete three-class scan).

Type	Source phrase	Suggested canonical	Status
terminology / missing-context	「agent teams」	Resolved: within-window parallel sub-agent / orchestration primitives (per comment 2, 2026-05-30, citing #167) — concretely the Agent tool fan-out, the experimental Agent Teams (TeamCreate), and (newly available as of 2026-06) the Workflow tool (dynamic workflows). NOT generic multi-agent. Candidates (a)/(b)/(c) collapse into this family; (d) cross-skill reviewer pool is an orthogonal downstream question, not the referent.	resolved

Gate note (resolved 2026-06-01): per /idd-diagnose Step 0.5, this row was surfaced and would have refused diagnose. Referent was pinned in comment 2 (2026-05-30) and re-confirmed during /idd-diagnose 2026-06-01: "agent teams" = within-window orchestration primitive family. The 2026-06 arrival of the Workflow tool (dynamic workflows) is a new member of that same family, fully compatible with comment 2's definition — it does not re-open the referent, it expands the option set the diagnosis must weigh. Row flipped surfaced → resolved to keep the audit trail consistent with the already-existing clarification.

Linked-Context Siblings Filed

(none surfaced — clean single-seed invocation, no linked attachments / no orphan session mentions beyond the #155 alt-layer work already tracked)

---

Current Status

Phase: diagnosed
Last updated: 2026-06-01 by idd-diagnose → /spectra-discuss（discuss converged）

Key Decisions

• Complexity = Spectra (Layer 2 published skill 編排契約 + Layer 3 architectural；影響 idd-verify + idd-all-chain)
• 釘定 referent：「agent teams」= within-window orchestration primitive family，2026-06 新增成員 Workflow tool (dynamic workflows)
• 推薦 hybrid split：workflow 擁有 deterministic「fan-out → DA verify → merge」core；skill 保留 gates + GitHub 發文 + triage + verify-fix loop
• workflows.md canonical use case 逐字 = IDD verify ensemble（adversarial cross-review）；候選線索①「reusable review-team primitive」答案 = saved workflow
• Routing → spectra-discuss DONE（2026-06-01 converged）→ next /spectra-propose。Conclusion 落定：scope 含 verify ensemble + idd-all-chain（兩 site，分期 verify-first）；Codex 包進 workflow + Phase 0 spike；新 spec idd-verify（inaugural，reference idd-pr-hitl-modes，名字 reject 掉 redundant -ensemble / mechanism-leaking -workflow）

Scope Changes

• Clarity Surface row「agent teams」referent：surfaced → resolved（回寫 comment 2 釘定 + 新成員 Workflow tool）
• (side-product) naming/Purpose lesson 落地：rename idd-orchestrator-modes → idd-pr-hitl-modes + 填 Purpose（b6fd718, v2.76.1）；4 個同類 TBD-stub spec backlog → [chore] 4 specs still carry the TBD Purpose archive-stub (idd-all-chain, idd-ic-r011-checkpoint, idd-spawn-manifest, idd-worktree-isolation) #180；Spectra 上游缺口（no capability-rename + Purpose stub）以 inquiry 問上游 → 請教：spec delta 是否支援 capability 改名、填 Purpose，以及偵測未填的 TBD Purpose？ kaochenlong/spectra-app#100（注：spectra feedback CLI 是 local echo + 死 URL，真 repo 是 kaochenlong/spectra-app）

Blocking

• (none) — discuss 收斂完，等 user 自行執行 /spectra-propose（P3 parking-lot，user 主導 pacing）

Commits

• (none yet — 探索階段，無 commit 引用 [exploration] 探索 IDD workflow 如何搭配 agent teams (verify ensemble / orchestration) #164)

[kiki830621]

Spun-out sub-concern

切出一個具體工程約束作為獨立 issue：#167 — 平行執行多個 IDD 的隔離機制（worktree vs branch 防衝突）。

#164 是「IDD × agent teams」的大方向探索；#167 是其中最硬的前置 blocker —— agent teams 要平行，但 IDD 的 stateful 操作（working-tree checkout / commit / .claude/.idd/ staging）預設單序列執行者，平行會互相覆蓋。沒有隔離機制，本 issue 的 orchestration 探索無從落地。

兩者都維持 parking-lot，等 trigger 一起 pick up。

[kiki830621]

Terminology clarification (from #167)

「agent teams」在 #167 已被釐清為單一 Claude Code 視窗內呼叫的平行 sub-agent 原語（Agent tool / superpowers:dispatching-parallel-agents / TeamCreate），而非泛指多 agent。

對應 #167 的執行拓樸兩分法：

• Case A — 一個視窗呼叫 agent teams（within-window 平行 sub-agents）
• Case B — 多個視窗各跑一個 IDD（across-window）

本 issue（#164）若日後 diagnose verify ensemble / orchestration，沿用同一定義。

[kiki830621]

Diagnosis (2026-06-01 — re: dynamic workflows)

Type

feature / exploration → architecture decision. The seed asked "how does IDD combine with agent teams." As of 2026-06 it has a concrete trigger that did not exist when it was filed: the Workflow tool / dynamic workflows (Claude Code research preview, v2.1.154+). That reframes the whole question — see below.

Clarity Surface resolution: the body's surfaced row ("which agent teams?") was pinned in comment 2 (2026-05-30, citing #167) as within-window orchestration primitives, and re-confirmed during this diagnose. The 2026-06 Workflow tool is a new member of that same family, fully compatible with comment 2's definition — it does not re-open the referent, it expands the option set. Row flipped surfaced → resolved for a consistent audit trail.

---

官方 taxonomy — 「幾種 agents 的方式要分別考慮」(the part you asked to pin)

Claude Code 官方 (/en/agents) 把平行 agent 編排分成 4 種，決策軸 = 誰持有計畫 + worker 之間要不要對話 + 結果落在哪：

Approach	一句話	誰持有計畫	結果落在哪	用在
Subagents (Agent tool)	一個 session 內委派的 worker，自有 context，回傳 summary	Claude，turn-by-turn	Claude 的 context window	side task 會淹沒主對話（search/log/檔案內容）
Agent view (claude agents, research preview)	一個畫面 dispatch + 監看背景 sessions	你（hand off，事後查）	只回報給你	多個獨立任務，丟出去事後看狀態
Agent teams (TeamCreate, experimental, 預設關)	多個協作 session，shared task list + 互發訊息，由 lead 統籌	Claude lead + teammate 自協調	各自獨立 context + mailbox	要 worker 彼此對話、互相挑戰、自己協調
Dynamic workflows (Workflow tool, research preview)	一支 JS script 跑大量 subagent 並交叉驗證結果	script	script 變數（不進 Claude context）	任務大到一輪 turn 編不動，或 findings 要互相驗證：codebase audit、500-file migration、cross-checked research、多角度起草計畫

workflows.md 的「who holds the plan」補充表（subagent/skill vs workflow）：

	Subagents	Skills	Workflows
是什麼	Claude spawn 的 worker	Claude 遵循的指令	runtime 執行的 script
誰決定下一步	Claude，turn by turn	Claude，依 prompt	script
中間結果在哪	Claude context	Claude context	script 變數
可重複的是	worker 定義	指令	編排本身
規模	每輪幾個	同 subagent	數十～數百 / run
中斷	重啟該 turn	重啟該 turn	同 session 內可 resume

官方對 subagent vs team 的分界（逐字）：「Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.」

官方對 workflow 的定位（逐字，這句是關鍵）：「Moving the plan into code also lets a workflow apply a repeatable quality pattern... it can have independent agents adversarially review each other's findings before they're reported, or draft a plan from several angles and weigh them against each other.」

---

Analysis — 對 IDD 的意義（為什麼這個 feature 改變 agent 規劃方式）

1. IDD 的歷史正好是這條軸上的一次遷移。 #52 把 idd-verify 從 TeamCreate model 遷出，改成手動 parallel Agent(general-purpose) fan-out + file-based output + DA polling，因為 agent teams 的痛點（idle/wake context 流失、teammate 要顯式列 Write tool、experimental limitations、#70 cleanup gap）對 verify ensemble 是錯的形狀。這個判斷是對的 —— 但落點（manual fan-out + /tmp file IPC + 手刻 DA polling barrier + 背景 Codex subprocess）本身也是 workaround。

2. Workflow 是 #52 當時不存在的「正確第三選項」。 官方 dynamic-workflow 的 canonical use case 逐字就是 IDD 的 verify ensemble：5 reviewers 各持 lens（requirements/logic/security/regression）→ DA 對抗驗證 → Codex 跨模型盲驗 → merge → master report。/deep-research bundled workflow 做的「cross-check sources、vote on each claim、把沒通過交叉檢查的 claim filter 掉」就是同一個 adversarial-verify 形狀。

3. 手動 fan-out 的每個 workaround 都對應 workflow 的一個原生能力：

現在 idd-verify 手刻的	為什麼存在	Workflow 原生對應
5 findings 寫 /tmp/verify_*.md 檔	Agent 結果進 Claude context，但要讓 DA 讀+merge → 只能走檔案	parallel()/pipeline() + schema 回傳驗證過的結構化物件，活在 script 變數
DA polling 等其他 4 檔產生	手刻 barrier	pipeline(reviewers, review→verify)：每個 review 一完成就被 DA 對抗驗證
背景 Codex subprocess（本 session 掛了 2 次，exit 144 → #147）	跨模型盲驗只能 shell-out gpt-5.5	workflow agent() 可 bound timeout/abort，把 Codex 的失控 deterministically kill
Claude 燒 context 重讀 6 檔做 merge	結果在 Claude context 才能 merge	merge + dedup 是純 JS，不佔 context

4. 候選線索 ①（verify ensemble 形式化成可重用 primitive）現在有直接答案。 workflows.md：「When Claude writes a workflow for a task you'll repeat, you can save that run's script as a command」→ saved workflow 就是那個「review team primitive」（/workflows → s 存成 .claude/workflows/ 或 plugin-bundled /<name>），完全繞開 TeamCreate 的痛點。候選線索 ④（跨 skill reviewer pool）順勢成立：spectra-verify / code-review 可共用同一支 saved workflow。

---

Impact

• 主要：idd-verify 的編排引擎（Step 2 launch_parallel_reviewers / wait / Step 2.5 recovery / merge_findings）。
• 次要：idd-all-chain（候選線索 ② — sequential orchestration，"discover sites → transform → verify" 正是 workflow 的 migrate pattern）。
• 契約面：idd-verify 是 published plugin skill，多 repo 多使用者。硬依賴 research-preview feature 會在舊 CLI（< v2.1.154）/ free tier 直接壞 → 必須保留 manual fan-out 當 fallback（capability-gated）。這是 backward-compat 契約決定。

---

Strategy — hybrid split（不是 full rewrite）

官方對 workflow 的兩條硬限制決定了架構縫在哪：

• 「No mid-run user input. Only agent permission prompts can pause a run. For sign-off between stages, run each stage as its own workflow.」
• 「No direct filesystem or shell access from the workflow itself. Agents read, write, and run commands.」

idd-verify 有 human-in-the-loop（Step 0.7 PR scope AskUser、Step 5b triage AskUser、verify-fix loop）+ stateful side-effects（gh issue comment master+pointer、Step 0.8 auto-close 偵測、git checkout/restore）。這些不能進 workflow。所以切法：

idd-verify SKILL 保留：                      Workflow 擁有：
- Step 0.5/0.7/0.8 gates (gh + AskUser)      - parallel(5 reviewers) → 結構化 findings
- git checkout PR / restore                  - pipeline: 每個 review → DA 對抗 verify
- gh issue comment (master + pointers)       - Codex 跨模型 agent()（bounded timeout）
- Step 5b triage (AskUser: 開 follow-up?)    - merge + dedup（純 JS）
- verify-fix loop (human-in-loop)            - 回傳 validated findings array

skill 呼叫 workflow 拿到合併 findings，再做 GitHub 發文 + human gate。deterministic orchestration → workflow；stateful side-effect + human gate → skill。

• Codex placement sub-decision（2 valid approaches）：(a) 包進 workflow 當 Bash-shelling agent()，讓 script 的 abort/budget deterministically kill（直接回應 [refactor] idd-verify Codex invocation: migrate codex exec subprocess → codex-call HTTP wrapper #147 的 2 次 hang）；(b) 留在 skill 外當背景 Bash。傾向 (a)，但要驗證 workflow agent 能否 shell-out codex exec。
• 最小路徑（per Che 慣例，先標出來）：不必一次 rewrite。最小可交付 = capability-gated 採用 workflow 當 verify 的 deterministic core + 保留 manual fan-out fallback。再更小 = 先把這份官方 taxonomy + 決策規則 codify 進 IDD orchestration reference doc，idd-verify 標「pending workflow migration when capability available」，把 refactor 延後。discuss 時定哪一檔。

---

Complexity

Spectra（Layer 2 + Layer 3 皆命中）：

• Layer 2：改動 idd-verify 這個 published skill 的編排契約 + 引入 workflow 依賴 + fallback 契約，future callers/maintainers 繼承。
• Layer 3：architectural decision，long-term maintenance；且影響 2+ skills（idd-verify + idd-all-chain）需 consistency-checking。

也命中 Layer P（decision-heavy、2+ valid approaches），但 Spectra 蓋過。與 issue body 自己的預測一致（「探索性質大概率 /spectra-discuss（多個 valid 方向 + 影響 published skill 編排契約）」）。

Layer V（vagueness pre-check）：未觸發。釘定 referent 後 V1=3（mostly clear — 探索本質有開放方向，但候選具體、trigger 明確）、V4=3（acceptance = discuss 對齊方向，exploration tier 夠清楚）。max=3 < 4。真正的歧義（referent）已在 comment 2 解決，routing 軟度交給 Spectra-discuss 處理，不重複 score。

---

Risks

• Research-preview 依賴 / version floor / free-tier：硬依賴會壞掉一票使用者 → fallback 必須存在，不可省。
• Async UX 改變：workflow 跑背景、回 task ID、完成才 notify。idd-verify 現在是 blocking。chain（verify → close）pacing 會變，要在 discuss 決定。
• Resume 只限同 session：「If you exit Claude Code while a workflow is running, the next session starts fresh.」長 IDD chain 跨 session 會丟 resume 紅利。
• Opt-in 契約：Workflow 要 explicit opt-in；skill 指令觸發是官方允許的合法路徑之一，但 skill-invoked workflow 的 UX（背景跑、要不要每次問 approval）要釐清。
• [bug] /idd-verify Devil's Advocate Agent role socket crash — 2x consecutive timeouts in #119 round 2 (closing follow-up from #119) #130 可能被結構性消解（正面）：bug: /idd-verify 結束沒確認 teams 被關掉 — TeamDelete fails on idle-but-active reviewers + no cleanup SOP #70 TeamCreate cleanup gap 在離開 team model 後消失；同理 DA Agent socket crash（[bug] /idd-verify Devil's Advocate Agent role socket crash — 2x consecutive timeouts in #119 round 2 (closing follow-up from #119) #130）若改由 workflow runtime 管 agent lifecycle，手刻 polling/socket 那層可能整個不見。discuss 時驗證。

---

Residue

#164 是 parking-lot exploration seed，它的 horizon 比 verify-ensemble 大：「IDD 整體編排哲學（sequential idd-all-chain、處處 manual fan-out）是不是該重想一遍。」本次 diagnose operationalize 的是最銳利、最具體的那個 instance（verify ensemble）+ 標 idd-all-chain 為 adjacent；但「跨所有 IDD skill 的統一編排策略」這個 purpose 接不進單次 diagnose——它得透過 spectra-discuss + 實際用 workflow 跑過才會浮現。誠實標記，不假裝這份診斷把整個探索 horizon 收完了。

---

Sister Concerns Filed (mid-diagnose, Step 3.6)

none new — 相鄰 concern 都已有 issue，cross-link 即可：#147（Codex subprocess fragility，本 session 2 次 hang，直接被 Codex-placement 子決定觸及）、#130（DA Agent socket crash，可能被 workflow lifecycle 結構性消解）、#169（worktree convention，對應 workflow isolation:'worktree' + Case B across-window）、#172（membership semantics）。無新增 actionable + un-tracked 項目。

Source: surfaced during /idd-diagnose #164 sister concern surfacing (Step 3.6)

[kiki830621]

Discuss Conclusion (2026-06-01, /spectra-discuss)

Direction consensus reached — this converges the #164 exploration.

Decision

Adopt the dynamic-workflow primitive for IDD's multi-agent orchestration at two sites, capability-gated with a manual fallback (research-preview + free-tier safety):

Site	Workflow canonical pattern	Workflow owns	Skill keeps
verify ensemble	adversarial cross-review	5 reviewers fan-out → DA verify → merge	gates (Step 0.5/0.7/0.8) + gh posting + triage + verify-fix loop
idd-all-chain (Phase 2)	migrate pipeline	root-solve → auto-emergent spawn pipeline	cluster branch/PR + idd-pr-hitl-modes interaction alignment

Both are textbook cases of a workflows.md canonical pattern (官方逐字: a workflow "can have independent agents adversarially review each other's findings before they're reported"). The current manual fan-out (#52) + sequential chain (#44) are hand-rolled workarounds from before the primitive existed.

Hybrid split rationale

Workflow's two hard constraints — "no mid-run user input" + "no direct FS/shell from the workflow itself" — draw the seam: deterministic fan-out / pipeline + cross-check + merge → workflow; gates + GitHub side-effects + human-in-loop + verify-fix → skill. The skill awaits the workflow result, so from the user's view verify is still "run → get findings."

Codex

Wrapped inside the workflow as a bounded-timeout Bash agent — directly addressing the 2 hangs this session (exit 144, #147). Phase 0 spike gates it: confirm a workflow agent can clean-kill a hung codex exec child; if it cannot, fallback = Codex external with a skill-level timeout.

New spec: idd-verify (inaugural)

There is no idd-verify spec today — this change creates its inaugural capability spec. Name settled by rejecting the redundant idd-verify-ensemble (the ensemble is inherent to idd-verify) and the mechanism-leaking idd-verify-workflow (the spec must outlive the manual→workflow swap). Purpose:

Defines the /idd-verify capability: an ensemble of independent agents (distinct-lens reviewers + an adversarial devil's-advocate + a cross-model blind verifier) that cross-check an implementation and merge their findings before reporting. Specifies the ensemble-execution contract — fan-out → cross-check → merge — and its graceful degradation across execution backends (dynamic-workflow primitive when available, manual fan-out otherwise), with an identical findings contract either way.

It references idd-pr-hitl-modes for the interaction axis (a background workflow is inherently unattended). idd-all-chain Phase 2 → MODIFY the existing idd-all-chain spec. Two sites → two specs, no god-spec (avoids the idd-orchestrator-modes "too broad → Purpose=TBD" failure).

Implementation phasing

「一起想，分期出」: design covers both sites + the shared seam, but ship Phase 1 = verify ensemble first (sharpest, most-proven pattern); idd-all-chain = Phase 2.

Side-products of this discuss

• Naming lesson codified + applied: intent-named + Purpose-first (avoid mechanism-named and redundant suffix). First application: renamed idd-orchestrator-modes → idd-pr-hitl-modes + filled its TBD Purpose (commit b6fd718, v2.76.1).
• Spectra systemic gap raised upstream as an inquiry (no capability-rename primitive + Purpose=TBD stub-and-pray) → 請教：spec delta 是否支援 capability 改名、填 Purpose，以及偵測未填的 TBD Purpose？ kaochenlong/spectra-app#100 — framed as questions (Spectra is a closed app; observed against spectra 2.3.1, unverified against source). Note: the in-app spectra feedback CLI is a local echo pointing to a dead URL; the live repo is kaochenlong/spectra-app, not the kaochenlong/Spectra the binary prints.
• Purpose-audit backlog filed: 4 more specs carry the same TBD-stub → [chore] 4 specs still carry the TBD Purpose archive-stub (idd-all-chain, idd-ic-r011-checkpoint, idd-spawn-manifest, idd-worktree-isolation) #180 (paired with the upstream lint as prevention).

Next step

/spectra-propose when picked up (P3 — parking-lot pacing). Complexity remains Spectra.

---

Discuss driven turn-by-turn; conclusion captured per /spectra-discuss convention.

[kiki830621]

Propose → parked change created (2026-06-01)

#164 Phase 1 (verify ensemble) is now formalized as the Spectra change formalize-idd-verify-ensemble (parked).

Artifacts: proposal (Feature) + design (D1 hybrid split / D2 workflow bundled-vs-inline / D3 Codex-in-workflow + Phase 0 spike / D4 capability detection / D5 interaction-axis alignment with idd-pr-hitl-modes) + the inaugural idd-verify spec (5 requirements, with a real Purpose — not a TBD stub) + 9 tasks. spectra validate ✓; analyze had 5 residual heuristic warnings (design-topic title text-match false positives — tasks carry explicit [Requirement] / [D#] traceability).

The change is parked in Spectra's local state (the gitignored .spectra/ DB); it materializes into git on /spectra-apply (→ active) or on archive.

Next: /spectra-apply formalize-idd-verify-ensemble when picked up (P3 pacing). Phase 2 (idd-all-chain workflow adoption) remains a separate future change that will MODIFY the existing idd-all-chain spec.

The naming side-product (idd-orchestrator-modes → idd-pr-hitl-modes + filled Purpose, commit b6fd718, v2.76.1) is pushed to main.