Multi-Agent Workflow

多視角並行工作流生態系：RESEARCH → PLAN → TASKS → IMPLEMENT → REVIEW → VERIFY

Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                      multi-agent-workflow（統一專案）                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │RESEARCH │→ │  PLAN   │→ │  TASKS  │→ │IMPLEMENT│→ │ REVIEW  │→ │ VERIFY  │ │
│  │   ✅    │  │   ✅    │  │   ✅    │  │   ✅    │  │   ✅    │  │   ✅    │ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘ │
│       ↓            ↓            ↓            ↓            ↓            ↓      │
│  research/     plans/       tasks/       code/       reviews/    verification/│
│                                                                               │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │                     🔗 ORCHESTRATE（編排器）✅                          │  │
│  │               串聯所有階段，自動流轉，智能回退                          │  │
│  └────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘

Features

6 階段完整工作流：研究 → 規劃 → 任務分解 → 實作 → 審查 → 驗證
多視角並行處理：每個階段 4 個視角同時工作
Map-Reduce 協調：並行執行 → 交叉驗證 → 智能匯總
Git Worktree 隔離：IMPLEMENT/REVIEW/VERIFY 在隔離分支中執行
Skill runtime 零外部依賴：核心 skills 使用 Claude Code 內建工具；CLI / portable tooling 可使用 Python 依賴並提供 fallback
Memory 整合：成果自動存檔，支持跨階段復用
共用模組架構：避免重複程式碼
指標收集系統：自動追蹤執行、品質、效率指標
報告系統：單次報告、週報、基準線追蹤
即時進度顯示：階段和視角狀態可視化
結構化錯誤處理：標準化錯誤碼和排除指南
CT Research Layer：以 Constraint Texture 約束研究、合規檢查、失敗挖掘與實驗設計
CT 閉環自我改善：strict/experiment 模式產生 retrospective，必要時輸出 self-upgrade proposal；runtime 變更預設 proposal-only

Installation

Via Agent Skills CLI (`npx skills`)

If you use the open Agent Skills installer, install this repository with:

npx skills add miles990/multi-agent-workflow

For a non-interactive global Codex install:

npx skills add miles990/multi-agent-workflow -g -a codex --skill '*' --copy --full-depth -y

Use --all only when you intentionally want to install every skill to every supported agent. For Codex-only global installation, prefer -g -a codex.

This installs the repository skills. Each skill carries generated portable copies of the shared framework resources under _shared/, _templates/, _scripts/, and _cli/, so /multi-research, /multi-plan, /multi-tasks, /multi-implement, /multi-review, /multi-verify, and /orchestrate can still access the common CT, quality, metrics, coordination, template, and hook assets.

Portable tools use best-effort dependency handling. They first use the existing runtime, then try to install missing Python packages or system tools, and only fall back to built-in lightweight behavior when installation is unavailable. Set MAW_DISABLE_AUTO_INSTALL=1 in locked-down environments to disable automatic dependency installation.

Version surfaces are documented in docs/versioning.md.

Component	Source	Current
Plugin distribution	`plugin.json`	2.4.2
Python CLI/tooling	`pyproject.toml`	3.1.0
Research skill	`skills/research/SKILL.md`	3.2.0

Via Claude Code Plugin - Full framework install

# 1. 添加 Marketplace
/plugin marketplace add miles990/multi-agent-workflow

# 2. 安裝 Plugin
/plugin install multi-agent-workflow@multi-agent-workflow

# 3. 重啟 Claude Code 載入新 Plugin

Direct Install

/plugin install miles990/multi-agent-workflow

Use the plugin install when you specifically need Claude Code plugin packaging: plugin cache sync, marketplace metadata, and release/version tooling.

Available Skills

Skill	Command	Description	Status
research	`/multi-research`	多視角並行研究，內建 CT 自動模式	✅ Ready
plan	`/multi-plan`	多視角規劃設計	✅ Ready
tasks	`/multi-tasks`	多視角任務分解（v2.2 新增）	✅ Ready
implement	`/multi-implement`	監督式並行實作	✅ Ready
review	`/multi-review`	多視角程式碼審查	✅ Ready
verify	`/multi-verify`	多視角驗證測試	✅ Ready
orchestrate	`/orchestrate`	端到端編排	✅ Ready

Quick Start

Research

# 基本用法
/multi-research AI Agent 架構設計模式

# 快速模式（2 視角）
/multi-research --quick 技術選型問題

# 深度模式（6 視角）
/multi-research --deep 重大架構決策

# 手動覆蓋 CT 模式
/multi-research --ct lite "先快速看一下這方向"
/multi-research --ct strict "幫我做深度架構分析"
/multi-research --ct experiment "幫我設計實驗"
/multi-research --no-ct "只要草稿"

/multi-research 內建 CT Escalation Router。預設使用 CT-lite；架構、風險、產品或 agent 系統設計會升級到 CT-strict；論文、實驗、benchmark、evaluation、hypothesis 類任務會升級到 CT-experiment。偵測結果會寫入 meta.yaml 的 ct_detection。

CT mode 會控制流程重量：CT-lite 只在 synthesis 加上 evidence / uncertainty / drift guard；CT-strict 才產生 ct-retrospective.md 與必要的 self-upgrade-proposal.md；CT-experiment 才跑完整 experiment harness 與 closed-loop-summary.md。Autonomous patch 預設關閉；gates / workflow scripts 的變更只提出 proposal，需人工批准。

CT-experiment 還必須產生可重跑的實驗 harness：

.claude/memory/research/{topic-id}/experiments/{topic-id}/
├── cases.yaml
├── run-config.yaml
├── rubric.yaml
├── results.jsonl
└── analysis.md

內建 scorer 位於 _shared/ct/experiment-harness/score-run.py，用來把研究 artifact 轉成可比較的分數。

Plan

# 基本用法
/multi-plan 建立用戶認證系統

# 從研究報告載入
/multi-plan --from-research user-auth

Tasks (v2.2 新增)

# 從計劃載入並分解任務
/multi-tasks user-auth

# 快速模式（2 視角）
/multi-tasks --quick user-auth

# 深度模式（6 視角）
/multi-tasks --deep user-auth

# 強制 TDD 順序
/multi-tasks --tdd user-auth

Implement

# 從計劃載入
/multi-implement --from-plan user-auth

# 快速模式（2 視角）
/multi-implement --quick --from-plan small-feature

Review

# 審查指定範圍
/multi-review src/auth/

# 審查 git diff
/multi-review --diff HEAD~3

Verify

# 驗證功能
/multi-verify user-auth

# 嚴格模式
/multi-verify --strict user-auth

Full Workflow

# 端到端編排（自動判斷起始點）
/orchestrate 新增用戶認證功能

# 從已有計劃開始
/orchestrate --from-plan user-auth

Git Worktree Mode

# 自動使用 worktree（預設）
/orchestrate 新增用戶認證功能

# 強制使用 worktree
/orchestrate --worktree 新增功能

# 禁用 worktree（直接在 main 工作）
/orchestrate --no-worktree 快速修復

# 恢復中斷的工作流
/orchestrate --resume user-auth

# 清理孤立的 worktrees
/orchestrate --cleanup-worktrees

Skill Perspectives

research

ID	Name	Focus
`architecture`	架構分析師	系統結構、設計模式、可擴展性
`cognitive`	認知科學研究員	方法論、思維模式、認知框架
`workflow`	工作流設計師	執行流程、整合策略、實作步驟
`industry`	業界實踐研究員	現有框架、案例研究、最佳實踐

plan

ID	Name	Focus
`architect`	系統架構師	技術可行性、組件設計、擴展性
`risk-analyst`	風險分析師	潛在風險、依賴問題、失敗場景
`estimator`	估算專家	工作量評估、優先順序、時程規劃
`ux-advocate`	UX 倡導者	使用者體驗、API 設計、開發者體驗

implement

ID	Name	Focus
`tdd-enforcer`	TDD 守護者	測試先行、覆蓋率、邊界案例
`performance-optimizer`	效能優化師	時間複雜度、記憶體、快取
`security-auditor`	安全審計員	OWASP、輸入驗證、授權
`maintainer`	維護性專家	可讀性、文檔、重構友善

review

ID	Name	Focus
`code-quality`	程式碼品質審查員	風格一致性、重複程式碼、設計模式
`test-coverage`	測試覆蓋審查員	測試品質、邊界案例、Mock 適當性
`documentation`	文檔審查員	API 文檔、註解、README
`integration`	整合審查員	向後相容、API 契約、依賴影響

tasks (v2.2 新增)

ID	Name	Focus
`dependency-analyst`	依賴分析師	依賴關係、執行順序、並行機會
`task-decomposer`	任務分解師	實作任務、估算、驗收標準
`test-planner`	測試規劃師	測試任務、TDD 案例、邊界條件
`risk-preventor`	風險預防師	風險任務、回退點、監控任務

verify

ID	Name	Focus
`functional-tester`	功能測試員	核心功能、Happy Path、使用者流程
`edge-case-hunter`	邊界獵人	極端輸入、錯誤處理、容錯
`regression-checker`	回歸檢查員	現有功能、API 相容、向後相容
`acceptance-validator`	驗收驗證員	需求符合度、Definition of Done

Memory Structure

This is the common memory layout. The research tree below is intentionally a compact view; complete mode-specific artifacts are defined in skills/research/SKILL.md.

.claude/memory/
├── research/           # research skill 產出
│   └── [topic-id]/
│       ├── meta.yaml
│       ├── ct-stack.yaml       # CT-strict / experiment
│       ├── ct-compliance.md    # CT-strict / experiment
│       ├── hypotheses.yaml     # CT-experiment
│       ├── experiment-plan.md  # CT-experiment
│       ├── overview.md
│       ├── perspectives/
│       └── synthesis.md
├── plans/              # plan skill 產出
│   └── [feature-id]/
│       ├── meta.yaml
│       ├── perspectives/
│       └── implementation-plan.md
├── tasks/              # tasks skill 產出
│   └── [feature-id]/
│       ├── meta.yaml
│       ├── perspectives/
│       ├── tasks.yaml
│       └── dependency-graph.md
├── implementations/    # implement skill 產出
├── reviews/            # review skill 產出
└── verifications/      # verify skill 產出

Project Structure

multi-agent-workflow/
├── skills/
│   ├── research/                 # ✅ Ready
│   │   ├── SKILL.md
│   │   ├── 00-quickstart/
│   │   ├── 01-perspectives/
│   │   ├── 02-ct-mode/
│   │   ├── _shared/              # generated portable copy of shared/
│   │   ├── _scripts/             # generated portable scripts
│   │   ├── _templates/           # generated portable templates
│   │   └── _cli/                 # generated portable Python CLI modules
│   ├── plan/                     # ✅ Ready
│   ├── tasks/                    # ✅ Ready (v2.2 新增)
│   ├── implement/                # ✅ Ready
│   ├── review/                   # ✅ Ready
│   ├── verify/                   # ✅ Ready
│   └── orchestrate/              # ✅ Ready
├── scripts/                      # 開發工具
│   ├── create-skill.sh           # Skill 腳手架工具
│   ├── validate-skills.sh        # Skill 結構驗證
│   └── portable/
│       └── sync-skill-resources.sh # 同步 generated portable resources
├── shared/                       # 共用模組
│   ├── ct/                       # CT schema、compiler、checker、templates
│   │   ├── taxonomy.yaml
│   │   ├── ct-schema.yaml
│   │   ├── escalation-router.md
│   │   ├── escalation-rules.yaml
│   │   ├── compiler.md
│   │   ├── compliance-checker.md
│   │   ├── drift-detector.md
│   │   ├── failure-miner.md
│   │   └── templates/
│   ├── skill-structure/          # Skill 結構規範 (v2.3 新增)
│   │   ├── STANDARD.md           # 結構規範文件
│   │   ├── CLAUDE.md             # AI 自動載入說明
│   │   └── templates/            # 模板檔案
│   ├── coordination/
│   │   ├── map-phase.md          # 並行執行
│   │   └── reduce-phase.md       # 整合匯總
│   ├── synthesis/
│   │   ├── cross-validation.md   # 交叉驗證
│   │   └── conflict-resolution.md # 矛盾解決
│   ├── perspectives/
│   │   └── base-perspective.md   # 視角基礎結構
│   ├── isolation/                # Git Worktree 隔離
│   │   ├── worktree-setup.md     # Worktree 創建
│   │   ├── worktree-completion.md # Worktree 完成
│   │   └── path-resolution.md    # 路徑解析
│   ├── integration/
│   │   ├── evolve-checkpoints.md # CP 對應
│   │   └── memory-system.md      # Memory 寫入
│   ├── metrics/                  # 指標收集
│   │   ├── schema.yaml           # 指標定義
│   │   ├── collector.md          # 收集器
│   │   └── memory-structure.md   # Memory 結構
│   ├── reporting/                # 報告系統
│   │   ├── single-report.md      # 單次報告
│   │   ├── weekly-report.md      # 週報
│   │   └── baseline.md           # 基準線
│   ├── progress/                 # 進度顯示
│   │   └── display.md            # 進度模組
│   └── errors/                   # 錯誤處理
│       ├── error-codes.md        # 錯誤碼定義
│       └── formatter.md          # 錯誤格式化
├── docs/
│   └── troubleshooting/          # 錯誤排除指南
├── templates/                    # 共用模板
├── plugin.json                   # Plugin manifest
├── .claude-plugin/marketplace.json
├── LICENSE
└── README.md

Documentation

Module	Description	Link
research	多視角研究，內建 CT 模式	→
CT Layer	Constraint Texture 共用層	→
orchestrate	端到端編排	→
Skill Structure	Skill 結構規範	→
Map Phase	並行執行	→
Reduce Phase	整合匯總	→
Cross Validation	交叉驗證	→
Conflict Resolution	矛盾解決	→
Perspectives	視角配置	→
Git Worktree	Worktree 隔離	→
Memory System	存儲系統	→
Checkpoints	evolve 整合	→
Metrics Schema	指標定義	→
Metrics Collector	指標收集	→
Single Report	單次報告	→
Weekly Report	週報/趨勢	→
Baseline	基準線機制	→
Progress Display	進度顯示	→
Error Codes	錯誤碼定義	→
Troubleshooting	錯誤排除指南	→

Development Tools

建立新 Skill

使用腳手架工具快速建立符合規範的 Skill 結構：

# 互動模式（引導式）
./scripts/create-skill.sh

# 非互動模式（CI/自動化）
./scripts/create-skill.sh --non-interactive \
  --name my-skill \
  --desc "Skill 描述" \
  --version 1.0.0

產生的結構：

skills/my-skill/
├── SKILL.md                    # 主要定義檔（frontmatter）
├── 00-quickstart/
│   └── _base/usage.md          # 快速開始指南
└── 01-perspectives/
    └── _base/default-perspectives.md  # 視角定義

驗證 Skill 結構

使用驗證工具確保所有 Skills 符合標準：

# 驗證所有 Skills
./scripts/validate-skills.sh

# 驗證單一 Skill
./scripts/validate-skills.sh research

# CI 模式（嚴格，有退出碼）
./scripts/validate-skills.sh --ci

驗證項目：

SKILL.md 存在且 frontmatter 完整（name, description, version）
00-quickstart/_base/usage.md 存在
01-perspectives/_base/default-perspectives.md 存在

詳細規範請參考 Skill 結構標準。

同步 npx portable resources

Repo-level shared/、templates/、scripts/hooks/ 是 source of truth。修改這些共用資源後，執行：

./scripts/portable/sync-skill-resources.sh

這會更新每個 skill 內的 generated _shared/、_templates/、_scripts/、_cli/，讓 npx skills add miles990/multi-agent-workflow 安裝單一 skill 目錄時仍保留完整能力。

查詢視角定義

查詢集中管理的視角定義：

# 列出所有視角
./scripts/list-perspectives.sh

# 按類別過濾
./scripts/list-perspectives.sh --category plan

# 按 skill 過濾
./scripts/list-perspectives.sh --skill implement

# 顯示視角詳細資訊
./scripts/list-perspectives.sh --show tdd-enforcer

# 顯示預設組合
./scripts/list-perspectives.sh --preset standard

查詢配置索引

查詢集中管理的配置索引：

# 列出所有配置類別
./scripts/get-config.sh --list-categories

# 列出某類別的配置
./scripts/get-config.sh --category skill-config

# 搜尋配置
./scripts/get-config.sh --search "tdd"

# 顯示配置詳情
./scripts/get-config.sh --show skills/implement/SKILL.md

# 顯示配置間的引用關係
./scripts/get-config.sh --relations

For Plugin Developers

The user-facing /plugin-dev skill has been removed. Plugin maintenance remains available through the underlying Python CLI and shell scripts.

Development Setup

# Clone repository
git clone https://github.com/miles990/multi-agent-workflow.git
cd multi-agent-workflow

# Validate plugin structure
./scripts/plugin/validate-plugin.sh

# Sync to Claude Code cache when testing plugin packaging
./scripts/plugin/sync-to-cache.sh

# Optional hot-reload workflow
./scripts/plugin/dev-watch.sh

Python CLI

python -m cli.plugin validate
python -m cli.plugin sync
python -m cli.plugin status
python -m cli.plugin version check
python -m cli.plugin release patch --dry-run

Shell Scripts

./scripts/plugin/sync-to-cache.sh
./scripts/plugin/dev-watch.sh
./scripts/plugin/validate-plugin.sh
./scripts/plugin/bump-version.sh patch
./scripts/plugin/publish.sh patch

Testing

python -m pytest tests/plugin/ -v
python -m pytest tests/plugin/ --cov=cli/plugin

Project Structure

cli/plugin/           # Python CLI modules
├── __main__.py       # CLI entry point
├── cache.py          # CacheManager
├── version.py        # VersionManager
├── dev.py            # DevCommands
└── release.py        # ReleaseCommands

scripts/plugin/       # Shell scripts
├── sync-to-cache.sh
├── dev-watch.sh
├── validate-plugin.sh
├── bump-version.sh
├── generate-changelog.sh
└── publish.sh

shared/plugin/        # Configuration
├── config.yaml
├── cache-policy.yaml
└── version-strategy.yaml

tests/plugin/         # Plugin tooling tests

Core Design Principles

Principle	Description
Skill Runtime Zero Dependencies	skill 執行層使用 Task API + 內建工具；CLI/tooling 依賴具 fallback
Multi-Perspective	Map-Reduce 模式，4 視角同時工作
Cross Validation	共識識別 + 矛盾解決
Git Worktree Isolation	main 穩定，feature 在隔離分支開發
Memory Integration	與 evolve Checkpoint 對應
Shared Modules	shared/ 避免重複程式碼
Unified Entry	單一 plugin，7 個 user-facing workflow skills；plugin tooling 改為 maintainer-only CLI/scripts
Standard Structure	所有 Skill 遵循統一結構規範

Related Projects

self-evolving-agent — 自我進化 Agent 框架

Changelog

Unreleased

Plugin tooling CLI
- 新增 python -m cli.plugin <command>：sync, watch, validate, status, version, release
- 保留 shell fallback scripts
- /plugin-dev skill 已移除，plugin tooling 改為 maintainer-only CLI/scripts

v2.4.0 (2026-02-01)

Plugin 開發工作流系統
- 新增 cli/plugin/ 模組：CacheManager, VersionManager, DevCommands, ReleaseCommands
- 新增 scripts/plugin/ 腳本：sync-to-cache, dev-watch, validate, bump-version, changelog, publish
- 新增 shared/plugin/ 配置：config.yaml, cache-policy.yaml, version-strategy.yaml
- 熱載入開發模式（fswatch/inotifywait/polling）
- 增量同步（Hash-based）
- 語義化版本管理
- 自動變更日誌生成
- 一鍵發布流程
- 73 個測試覆蓋

v2.3.2 (2026-02-01)

Git 操作統一模組
- 新增 scripts/git_lib/ 模組，統一所有 Git 操作
- 消除重複代碼（_get_current_workflow_id() 等 65 行重複）
- 實作 Facade Pattern，簡化 Hook 開發
- 55 個單元測試，覆蓋率 80%+
- Hook 代碼減少 54%

v2.3.0 (2026-02-01)

Skill 結構規範化
- 新增 shared/skill-structure/STANDARD.md 定義標準結構
- 新增 scripts/create-skill.sh 腳手架工具（互動/非互動模式）
- 新增 scripts/validate-skills.sh 驗證工具（含 CI 模式）
- 統一所有 Skill 目錄結構

v2.2.0 (2026-01-25)

新增 TASKS 階段（在 PLAN 和 IMPLEMENT 之間）
- 4 視角任務分解：dependency-analyst, task-decomposer, test-planner, risk-preventor
- tasks.yaml 結構化任務輸出
- DAG 依賴分析和 Wave 分組
- TDD 順序支持
更新 ORCHESTRATE 支持 TASKS 階段
工作流更新為 6 階段：RESEARCH → PLAN → TASKS → IMPLEMENT → REVIEW → VERIFY

v2.1.0 (2026-01-24)

新增指標收集系統（Phase 1）
- metrics schema 定義執行、品質、效率指標
- metrics collector 標準化收集 API
- 各 SKILL.md 嵌入指標收集點
新增報告系統（Phase 2）
- 單次執行報告：詳細分析和改善建議
- 週報/趨勢報告：長期追蹤和趨勢分析
- 基準線機制：滾動平均和目標管理
新增進度和錯誤處理（Phase 3）
- 即時進度顯示：階段和視角狀態可視化
- 標準化錯誤碼：E-AGT, E-WKF, E-MEM, E-USR, E-GIT, E-ENV
- 結構化錯誤訊息：可能原因 + 建議步驟
- Troubleshooting 文檔：詳細錯誤排除指南

v2.0.0 (2025-01-24)

重組專案為 multi-agent-workflow
提取共用模組到 shared/
更新 research skill 至 v2.0.0
新增 plan skill：多視角規劃設計
新增 implement skill：監督式並行實作（獨特設計）
新增 review skill：多視角程式碼審查
新增 verify skill：多視角驗證測試 + pass@k 機制
新增 orchestrate skill：端到端編排 + 智能回退

v1.0.0 (2025-01-23)

初始版本：multi-agent-research-skill

License

MIT

Author

miles990 — GitHub

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.claude		.claude
.plugin-dev		.plugin-dev
agents		agents
cli		cli
docs		docs
scripts		scripts
shared		shared
skills		skills
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
README.md		README.md
plugin.json		plugin.json
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

Multi-Agent Workflow

Architecture

Features

Installation

Via Agent Skills CLI (npx skills)

Via Claude Code Plugin - Full framework install

Direct Install

Available Skills

Quick Start

Research

Plan

Tasks (v2.2 新增)

Implement

Review

Verify

Full Workflow

Git Worktree Mode

Skill Perspectives

research

plan

implement

review

tasks (v2.2 新增)

verify

Memory Structure

Project Structure

Documentation

Development Tools

建立新 Skill

驗證 Skill 結構

同步 npx portable resources

查詢視角定義

查詢配置索引

For Plugin Developers

Development Setup

Python CLI

Shell Scripts

Testing

Project Structure

Core Design Principles

Related Projects

Changelog

Unreleased

v2.4.0 (2026-02-01)

v2.3.2 (2026-02-01)

v2.3.0 (2026-02-01)

v2.2.0 (2026-01-25)

v2.1.0 (2026-01-24)

v2.0.0 (2025-01-24)

v1.0.0 (2025-01-23)

License

Author

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Via Agent Skills CLI (`npx skills`)