pi-maestro-flow 0.2.0

package/skills/spec-add/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: spec-add
+description: "Add spec entry by category with role tagging Arguments: [--scope project|global|team|personal] [-y] <category> <content>"
+allowed-tools: Read Write Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Add `<spec-entry>` to specs by category. 4 scopes: project (default), global, team, personal.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
+
+**Options:**
+- `--description <desc>` — One-line description for search results (falls back to content[:240])
+- `--json` — Output JSON with generated `sid` (needed for supersession: `maestro spec supersede <old-sid> --by <new-sid>`)
+- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
+- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
+
+Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
+
+**Examples:**
+```bash
+# English content → English keywords
+/spec-add coding "Named exports" "Always use named exports" --keywords "exports,naming"
+
+# With description for search results
+/spec-add coding "OAuth PKCE Flow" "完整 PKCE 集成流程" --keywords "oauth,pkce" --description "OAuth 2.0 PKCE 认证流程规范"
+
+# Chinese content → Chinese keywords
+/spec-add coding "命名导出规范" "始终使用命名导出" --keywords "导出,命名,模块"
+
+# Ref mode
+/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
+```
+</context>
+
+<invariants>
+1. **Idempotent append** — duplicate entry ID MUST be rejected (E003-level check on title + category match before write)
+2. **Category validation** — category MUST be one of: coding, arch, quality, debug, test, review, learning, ui. Invalid category → E003
+3. **Scope isolation** — writes target ONLY the scope-resolved directory; project scope NEVER writes to global (~/.maestro/specs/), global scope NEVER writes to project (.workflow/specs/)
+4. **Confirmation gate** — MUST AskUserQuestion before appending entry (unless -y flag); NEVER write without user confirmation in interactive mode
+5. **Entry format invariance** — all entries MUST use `<spec-entry>` closed-tag format with id, keywords, and category attributes
+6. **Output boundary** — ALL file writes MUST target the scope-resolved specs directory (.workflow/specs/, ~/.maestro/specs/, .workflow/collab/specs/, or .workflow/collab/{uid}/specs/) and optionally .workflow/knowhow/ for --ref mode. NEVER modify source code or files outside these paths
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/specs-add.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Validate**
+- REQUIRED: Category and content both parsed from arguments.
+- REQUIRED: Category is a valid value (coding, arch, quality, debug, test, review, learning, ui).
+- REQUIRED: Scope resolved to a valid directory path.
+- BLOCKED if: E001 (missing args), E003 (invalid category), E004 (invalid scope), E005 (personal scope without uid).
+
+**GATE 2: Validate → Format**
+- REQUIRED: Specs directory exists for the resolved scope.
+- REQUIRED: No duplicate entry with identical title + category already present in target file.
+- BLOCKED if: E002 (specs not initialized).
+
+**GATE 3: Format → Write**
+- REQUIRED: `<spec-entry>` block formatted with id, keywords, category attributes.
+- REQUIRED: User confirmation via AskUserQuestion (unless -y flag).
+- BLOCKED if: user declines confirmation — abort without writing.
+
+**Confirmation gate**: Unless -y flag is passed, after formatting the `<spec-entry>` block but before appending to the target file, AskUserQuestion showing the formatted entry, target file path, and scope. Proceed only on user confirm.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Category and content are both required | parse_input |
+| E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, ui | parse_input |
+| E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
+| E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope and category parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 relevant terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format
+- [ ] Entry appended to correct target file for scope
+- [ ] Confirmation report displayed with scope, path, keywords
+- [ ] Next step routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify entry added | `maestro load --type spec --scope <scope> --keyword {keyword}` |
+| New entry replaces old one | `maestro spec supersede <old-sid> --by <new-sid>` |
+| View evolution chain | `maestro spec history <sid>` |
+| Add more entries | `/spec-add <category>` |
+| View all specs | `/spec-load --category <category>` |
+| Check knowledge health | `maestro spec health` |
+</completion>

package/skills/spec-load/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: spec-load
+description: "Load specs and lessons for current context Arguments: [--scope <scope>] [--category <category>] [--keyword <word>]"
+allowed-tools: Read Bash Glob Grep
+---
+
+<purpose>
+Load relevant specs filtered by scope, category (file-level) and/or keyword (entry-level).
+Category-based loading: loads the category's primary doc in full + matching entries from other files.
+By default, loads from both global (~/.maestro/specs/) and project (.workflow/specs/) layers.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-load.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags and keyword
+
+**Flags:**
+- `--scope <scope>` — Load scope (default: global + project merged):
+  - `project`: project baseline only (.workflow/specs/)
+  - `global`: global + project merged (~/.maestro/specs/ + .workflow/specs/)
+  - `team`: project + team shared (.workflow/collab/specs/)
+  - `personal`: project + team + personal (requires uid)
+- `--category <category>` — Load by category: primary category doc (full) + cross-file entries with matching category attr. Categories: coding, arch, quality, test, review, debug, learning, ui.
+- `--keyword <word>` — Filter by keyword within entries
+
+**File → Primary Category mapping:**
+| File | Category |
+|------|----------|
+| coding-conventions.md | coding |
+| architecture-constraints.md | arch |
+| test-conventions.md | test |
+| review-standards.md | review |
+| debug-notes.md | debug |
+| ui-conventions.md | ui |
+| quality-rules.md | review |
+| learnings.md | learning |
+
+**Examples:**
+```
+/spec-load --category coding            # coding全文 + 跨文件coding条目 (global + project)
+/spec-load --scope global --category arch  # 明确包含全局 arch 规范
+/spec-load --category review            # review-standards + quality-rules + 跨文件review条目
+/spec-load --category coding --keyword auth
+/spec-load --keyword auth
+```
+
+**Ref entries:**
+When loading entries with `ref` attribute, only the summary is shown with a load command:
+  → Detail: maestro load --type knowhow --id <knowhow-id>
+Use the load command to read the full referenced document.
+</context>
+
+<invariants>
+1. **Read-only** — NEVER modify, create, or delete any spec files during load. This command is purely a read operation
+2. **Output to context only** — loaded specs are injected into the conversation context; NEVER write loaded content to new files or modify existing files
+3. **Scope layering** — global scope MUST merge both ~/.maestro/specs/ and .workflow/specs/; project scope loads .workflow/specs/ only; team adds .workflow/collab/specs/; personal adds .workflow/collab/{uid}/specs/
+4. **Category primary doc** — when --category is specified, the primary category doc MUST be loaded in full before cross-file matching
+5. **Entry-level filtering** — --keyword filtering operates at `<spec-entry>` level via keywords attribute, NOT at file level; unmatched entries in a matching file are excluded
+6. **Output boundary** — this command produces NO file writes. All output is conversation-context injection only
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/specs-load.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Discover**
+- REQUIRED: Arguments parsed — at least one of --category or --keyword is provided, or empty args triggers full load.
+- REQUIRED: Scope resolved (default: global+project merged).
+- BLOCKED if: invalid scope value or invalid category value.
+
+**GATE 2: Discover → Load**
+- REQUIRED: At least one spec directory exists in the resolved scope chain.
+- BLOCKED if: E001 — .workflow/specs/ not initialized AND no global specs available. Warn and abort.
+
+**GATE 3: Load → Display**
+- REQUIRED: Spec files read and entries parsed.
+- REQUIRED: Keyword filtering applied if --keyword was provided.
+- BLOCKED if: no readable spec files found in any scope layer.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | warning | `.workflow/specs/` not initialized -- run `/spec-setup` first (global specs still available) | detect_context |
+| W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
+</error_codes>
+
+<success_criteria>
+- [ ] Category and/or keyword parsed from arguments
+- [ ] Spec files loaded per category mapping
+- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords attribute)
+- [ ] Legacy entries filtered by text grep fallback
+- [ ] Results displayed with file:category references
+</success_criteria>

package/skills/spec-remove/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: spec-remove
+description: "Remove spec entry by ID Arguments: <entry-id> [--cascade] [-y]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
+
+**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
+</context>
+
+<invariants>
+1. **Confirmation required** — MUST AskUserQuestion before deletion (unless -y flag); NEVER remove entries silently
+2. **Referential integrity** — before removing, check if other spec entries reference the target entry; warn user if references exist
+3. **Cascade explicit** — ref-type entries MUST NOT cascade-delete the linked knowhow file unless --cascade is explicitly passed; default leaves orphan knowhow intact
+4. **Atomic removal** — use `maestro wiki remove-entry` for atomic operation; NEVER manually edit spec files to remove entries
+5. **Index consistency** — wiki index MUST be auto-updated after removal; stale index entries are a hard failure
+6. **Output boundary** — file modifications MUST target ONLY the spec container file (.workflow/specs/*.md) and optionally the referenced knowhow file (.workflow/knowhow/*) when --cascade is used. NEVER modify source code or files outside these paths
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/specs-remove.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Lookup**
+- REQUIRED: Entry ID parsed from arguments.
+- BLOCKED if: E001 — no entry ID provided.
+
+**GATE 2: Lookup → Confirm**
+- REQUIRED: .workflow/specs/ directory exists.
+- REQUIRED: Entry found in wiki index as a spec sub-node.
+- REQUIRED: Entry content loaded for user preview.
+- BLOCKED if: E002 (specs not initialized), E003 (entry not found), E004 (wrong type).
+
+**GATE 3: Confirm → Remove**
+- REQUIRED: User confirmed removal via AskUserQuestion (unless -y flag).
+- REQUIRED: If --cascade and entry has ref attribute, user additionally confirmed knowhow file deletion.
+- BLOCKED if: user declines — abort without modification.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
+| E003 | fatal | Entry ID not found in wiki index | lookup |
+| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, is sub-node)
+- [ ] User confirmed removal (unless -y flag)
+- [ ] Entry removed from container file via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
+</success_criteria>

package/skills/spec-setup/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: spec-setup
+description: "Initialize specs from project structure Arguments: "
+allowed-tools: Read Write Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-setup.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments expected)
+
+**Preconditions:**
+- `.workflow/` directory must exist (created by `/maestro-init`)  # (see code: E001)
+- Project must contain source files to scan  # (see code: E002)
+</context>
+
+<invariants>
+1. **Non-destructive** — NEVER overwrite existing spec files; if a file already exists, skip it and report as already-initialized
+2. **Idempotent** — safe to re-run on an initialized project; re-running MUST NOT duplicate entries or corrupt existing content
+3. **Confirmation gate** — MUST AskUserQuestion showing all files to be created before writing; NEVER write without user confirmation
+4. **Output boundary** — ALL file writes MUST target .workflow/specs/ (spec files) and .workflow/knowhow/ (recipe knowhow) only. NEVER modify source code, .workflow/state.json, or files outside these paths
+5. **Core files mandatory** — coding-conventions.md, architecture-constraints.md, and learnings.md MUST always be created (unless they already exist)
+6. **Signal-driven optionals** — optional spec files (quality-rules.md, test-conventions.md, ui-conventions.md) MUST only be created when corresponding framework/tool signals are detected in the codebase; NEVER create optional files without evidence
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/specs-setup.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Precondition → Scan**
+- REQUIRED: .workflow/ directory exists.
+- REQUIRED: Project contains source files to scan.
+- BLOCKED if: E001 (.workflow/ not initialized), E002 (no source files).
+
+**GATE 2: Scan → Plan**
+- REQUIRED: Codebase scan completed — framework, language, and tooling signals collected.
+- REQUIRED: Core spec file list determined (always 3: coding-conventions, architecture-constraints, learnings).
+- REQUIRED: Optional spec files determined by detected signals only.
+
+**GATE 3: Plan → Write**
+- REQUIRED: User confirmed the full list of files to create via AskUserQuestion (showing core specs, optional specs, recipe knowhow, and detected signals).
+- BLOCKED if: user declines — abort without writing.
+
+**GATE 4: Write → Report**
+- REQUIRED: All confirmed files written to .workflow/specs/ and .workflow/knowhow/.
+- REQUIRED: Existing files skipped (not overwritten).
+- REQUIRED: .proposed.md files created when slug collision detected (W003).
+
+**Confirmation gate**: After scanning codebase and determining which files/directories will be created (core specs, optional specs, recipe knowhow), AskUserQuestion showing the full list of files to create with their categories and detected signals. Proceed only on user confirm.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
+| E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
+| W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
+| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
+| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory created
+- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
+- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
+- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
+</success_criteria>

package/skills/team-adversarial-swarm/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: team-adversarial-swarm
+description: "ACO swarm intelligence with modular Workflow composition and adversarial decision gates. Coordinator drives iteration loop; 4 composable Workflow scripts handle exploration, scoring, convergence, and synthesis — each with built-in adversarial patterns."
+allowed-tools: Read Write Edit Bash Glob Grep Workflow AskUserQuestion Agent
+---
+
+# Team Adversarial Swarm
+
+ACO 蚁群优化 + 模块化 Workflow 编排 + 对抗决策。
+
+继承 `team-swarm` 的蚁群算法核心（Python ACO 脚本），用 4 个可组合的 Workflow 脚本
+替代 team-worker 架构，在每个决策节点注入对抗性 agent 模式。
+
+## Architecture
+
+```
+SKILL.md (Coordinator — this file)
+  │
+  │  Phase 1: Config Generation (inline)
+  │  Phase 2: ACO Init (Bash: aco.py init)
+  │
+  │  Phase 3: Iteration Loop ×K
+  │  ┌──────────────────────────────────────────────────┐
+  │  │ 3a. Bash: aco.py select → assignments            │
+  │  │ 3b. Workflow(wf-swarm-explore)   ← 模块1         │
+  │  │     N ants parallel → ant_results                │
+  │  │ 3c. Workflow(wf-swarm-score)     ← 模块2         │
+  │  │     3-vote adversarial scoring → verified_scores │
+  │  │ 3d. Write scores → Bash: aco.py update           │
+  │  │ 3e. Workflow(wf-swarm-converge)  ← 模块3         │
+  │  │     prosecutor/defender/judge → converged?       │
+  │  │ 3f. if converged: break                          │
+  │  └──────────────────────────────────────────────────┘
+  │
+  │  Phase 4: Bash: aco.py report
+  │  Workflow(wf-swarm-synthesize)      ← 模块4
+  │  3-perspective analysis + arbitration → best-solution.md
+```
+
+## Workflow Module Registry
+
+| Module | Script | Args Interface | Adversarial Pattern | Returns |
+|--------|--------|---------------|--------------------|---------| 
+| **Explore** | `workflows/wf-swarm-explore.js` | `{ iteration, assignments[], objective, session, config }` | N ants parallel | `{ ant_results[] }` |
+| **Score** | `workflows/wf-swarm-score.js` | `{ iteration, ant_results[], objective, rubric? }` | 3-vote per ant (prosecutor/defender/judge) | `{ scores{}, calibration }` |
+| **Converge** | `workflows/wf-swarm-converge.js` | `{ iteration, best, history[], config }` | prosecutor(continue)/defender(stop)/judge | `{ converged, reason, confidence }` |
+| **Synthesize** | `workflows/wf-swarm-synthesize.js` | `{ best, top_k[], convergence_story, objective }` | 3-perspective + arbitrator | `{ report, caveats }` |
+
+每个模块独立可用，也可由 Coordinator 组合编排。
+
+## Shared Dependencies
+
+**所有依赖均在本 skill 内部，无外部引用。**
+
+- **Python ACO 脚本**: `<this-skill>/scripts/aco.py`
+  - 运行时解析: `Glob(".claude/skills/team-adversarial-swarm/scripts/aco.py")`
+  - 依赖模块: `pheromone.py`, `scoring.py`（同目录）
+  - 命令: `init` / `select` / `update` / `converged` / `report`
+  - 协议: [specs/swarm-protocol.md](specs/swarm-protocol.md)
+- **Workflow 脚本**: `<this-skill>/workflows/wf-swarm-*.js`
+  - 运行时解析: `Glob(".claude/skills/team-adversarial-swarm/workflows/wf-swarm-*.js")`
+
+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/swarm-protocol.md](specs/swarm-protocol.md) | Coordinator ↔ Script ↔ Workflow 三方协议 |
+| [specs/pheromone-schema.md](specs/pheromone-schema.md) | 信息素矩阵结构、更新公式、蒸发规则 |
+| [specs/ant-output-schema.md](specs/ant-output-schema.md) | 蚁输出 JSON 合约（三层评分） |
+| [specs/convergence-criteria.md](specs/convergence-criteria.md) | 双层收敛：Python 信号 + 对抗辩论 |
+| [specs/swarm-config-template.json](specs/swarm-config-template.json) | 用户配置模板 |
+
+## Session Directory
+
+```
+.workflow/.team/TAS-<slug>-<date>/
+├── swarm-config.json       # Phase 1 output
+├── pheromone/              # ACO state (managed by aco.py)
+│   ├── current.json
+│   └── history/
+├── trails/                 # Per-iteration trails (managed by aco.py)
+├── scores/                 # Adversarial scoring results
+│   └── iter-<k>-scores.json
+├── artifacts/
+│   ├── ant-<k>-<id>.json   # Ant outputs
+│   └── best-solution.md    # Final synthesis
+├── workflows/              # Workflow run artifacts
+│   ├── explore-<k>.json    # Per-iteration explore results
+│   ├── score-<k>.json      # Per-iteration score results
+│   └── converge-<k>.json   # Per-iteration convergence decision
+└── best.json               # Canonical best (managed by aco.py)
+```
+
+---
+
+## Coordinator Execution Flow
+
+### Phase 0: Resume Check
+
+1. `Glob(".workflow/.team/TAS-*/swarm-config.json")` → 查找活跃 session
+2. 若存在且有 `workflows/converge-*.json` 未标记 converged → 恢复到对应迭代
+3. 若无活跃 session → Phase 1
+
+### Phase 1: Config Generation
+
+解析用户 intent，生成 `swarm-config.json`。
+
+若 intent 不够明确，用 AskUserQuestion 澄清：
+- 搜索空间是什么？（文件 glob / 节点列表 / 抽象决策集）
+- 目标是什么？（最优方案 / 发现问题 / 优化路径）
+- 如何评分？（测试通过率 / lint / 自定义规则 / LLM 对抗评分）
+- 预算？（最大迭代 / 每轮蚁数 / token 预算）
+
+生成 config 字段：
+```json
+{
+  "task": { "objective": "...", "evidence_requirements": "..." },
+  "swarm": { "n_ants": 5, "max_iterations": 5 },
+  "aco": { "alpha": 1.0, "beta": 2.0, "rho": 0.1, "q": 1.0 },
+  "task_space": { "nodes": [...], "auto_discover_from": "..." },
+  "scoring": { "mode": "adversarial", "rubric": "..." },
+  "convergence": { "patience": 2, "min_improvement": 0.01, "max_iterations": 5 }
+}
+```
+
+Write 到 `<session>/swarm-config.json`。
+
+### Phase 2: ACO Init
+
+1. 创建 session 目录: `TAS-<slug>-<date>`
+2. 解析 aco.py 路径（从 team-swarm skill 继承）
+3. `Bash: python <aco.py> --session <session> init`
+4. 解析输出: `{ n_nodes, n_edges, pheromone_path }`
+
+### Phase 3: Iteration Loop
+
+```python
+for k in range(1, max_iterations + 1):
+    # 3a. ACO selection
+    assignments = Bash("python aco.py --session <session> select --iter k")
+    
+    # 3b. Parallel exploration (Workflow Module 1)
+    explore_result = Workflow({
+        scriptPath: "<skill>/workflows/wf-swarm-explore.js",
+        args: { iteration: k, assignments, objective, session, config }
+    })
+    
+    # 3c. Adversarial scoring (Workflow Module 2)
+    score_result = Workflow({
+        scriptPath: "<skill>/workflows/wf-swarm-score.js",
+        args: { iteration: k, ant_results: explore_result.ant_results, objective, rubric }
+    })
+    
+    # 3d. Write scores + pheromone update
+    Write("<session>/scores/iter-k-scores.json", score_result)
+    Bash("python aco.py --session <session> update --iter k")
+    
+    # 3e. Adversarial convergence check (Workflow Module 3)
+    converge_result = Workflow({
+        scriptPath: "<skill>/workflows/wf-swarm-converge.js",
+        args: { iteration: k, best: aco_best, history: iter_history, config }
+    })
+    
+    # 3f. Save + check
+    Write("<session>/workflows/converge-k.json", converge_result)
+    if converge_result.converged: break
+```
+
+**注意**：每次 Workflow 调用是独立的，数据通过 args 传入、返回值传出。
+Coordinator 负责 Workflow 间的数据桥接和 Python 脚本调用。
+
+### Phase 4: Synthesis
+
+1. `Bash: python aco.py --session <session> report` → 获取 best + top_k + curve
+2. 调用 Workflow Module 4:
+   ```
+   Workflow({
+     scriptPath: "<skill>/workflows/wf-swarm-synthesize.js",
+     args: { best, top_k, convergence_story, objective }
+   })
+   ```
+3. 将 synthesis 结果写入 `<session>/artifacts/best-solution.md`
+4. 展示完成摘要 + AskUserQuestion（归档 / 保留 / 导出 / 再跑一轮）
+
+---
+
+## Module Composition Patterns
+
+### 完整流水线（默认）
+```
+explore → score → update → converge → [loop] → synthesize
+```
+
+### 仅探索（跳过评分，用 self_score）
+```
+explore → update(self_score) → converge → synthesize
+```
+
+### 单次迭代调试
+```
+explore(k=1) → score(k=1)  // 不循环，只看一轮
+```
+
+### 独立评分（已有 ant artifacts）
+```
+score(ant_results from files) → 输出 verified_scores
+```
+
+### 独立综合（已有 best + trails）
+```
+synthesize(best, top_k) → best-solution.md
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| aco.py 未找到 | Glob team-swarm skill 路径；提示安装 |
+| Python < 3.10 | 尝试 python3；报告依赖 |
+| Workflow 执行失败 | 记录错误，提供 --resume 恢复点 |
+| 所有蚁全部失败 | 暂停，AskUserQuestion（重试/终止/调整config） |
+| 收敛从不触发 | max_iterations 安全网总会触发 |
+| 幻觉集群 (>50% 蚁被降分) | 暂停，AskUserQuestion（继续/调整评分规则） |
+
+## Completion
+
+展示最终结果 + 交互选择:
+- **归档**: 保存 session，展示 best-solution.md
+- **继续**: 保持 session，可追加迭代
+- **导出**: 复制 best-solution.md 到目标位置
+- **再跑**: 重置收敛，继续 K 轮