maestro-flow 0.4.18 → 0.4.20

package/.agy/skills/maestro-swarm-workflow/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: maestro-swarm-workflow
+description: Parallel workflow accelerator — route intent to fixed Workflow scripts for multi-agent concurrent execution
+argument-hint: <intent> [--script <name>] [--dims <d1,d2>] [--roles <r1,r2>] [--count N] [--tier quick|standard] [--resume <runId>]
+allowed-tools:
+  - Workflow
+  - ask_question
+  - grep_search
+  - replace_file_content
+  - run_command
+  - view_file
+  - write_to_file
+---
+<purpose>
+Parallel accelerator layer for maestro commands. Routes user intent to pre-built Workflow scripts
+that leverage `parallel()` / `pipeline()` for multi-agent concurrent execution.
+
+Complements maestro-ralph (sequential decision chain) — ralph manages state + decisions,
+swarm-workflow provides parallel compute bursts within individual steps.
+
+Scripts: `~/.maestro/workflows/swarm/wf-*.js`
+
+| Script | Accelerates | Pattern |
+|--------|-------------|---------|
+| `wf-analyze` | maestro-analyze | cli-explore-agent → 6-dimension parallel scoring → synthesis |
+| `wf-brainstorm` | maestro-brainstorm | multi-role parallel analysis → cross-role-reviewer → guidance |
+| `wf-review` | quality-review | 6-dimension workflow-reviewer → adversarial verify → report |
+| `wf-verify` | maestro-verify | 3-layer workflow-verifier + convergence + antipattern → aggregate |
+| `wf-grill` | maestro-grill | cli-explore-agent → parallel branch stress-testing → contradiction synthesis |
+| `wf-plan` | maestro-plan | parallel context exploration → workflow-planner → plan-checker |
+| `wf-execute` | maestro-execute | wave-based parallel workflow-executor (worktree isolation) |
+| `wf-milestone-audit` | maestro-milestone-audit | parallel coverage + execution + integration-checker |
+
+Integration modes:
+- **Standalone**: `/maestro-swarm-workflow "analyze auth module"` — direct invocation
+- **Ralph step**: ralph chain 中某个 step 可指定 `swarm-workflow` 作为加速执行器
+- **Chained**: 输出 JSON 可被下游命令通过 `--from` 消费
+</purpose>
+
+<context>
+$ARGUMENTS — intent text with optional flags.
+
+**Parse:**
+```
+--script <name>  → 强制指定脚本（wf-analyze, wf-brainstorm, wf-review, wf-verify）
+--dims <d1,d2>   → 限定分析维度（analyze: architecture,complexity,patterns,risk,testability,performance）
+--roles <r1,r2>  → 限定角色（brainstorm: system-architect,product-manager,test-strategist,ux-expert,security-analyst,data-architect）
+--count N        → 角色数量（brainstorm 默认 3）
+--tier <level>   → review 层级（quick=2 维度, standard=4 维度）
+--resume <runId> → 从之前的 workflow 运行恢复（增量重跑）
+Remaining        → intent
+```
+
+**Script inventory** (`~/.maestro/workflows/swarm/`):
+
+| Script | args 接口 |
+|--------|-----------|
+| `wf-analyze` | `{ target, scope, context, phase?, dimensions? }` |
+| `wf-brainstorm` | `{ topic, context, count?, roles? }` |
+| `wf-review` | `{ target, scope, specs?, tier?, dimensions? }` |
+| `wf-verify` | `{ goals, plan_dir?, scope?, task_files?, must_haves?, skip_antipattern? }` |
+| `wf-grill` | `{ topic, context?, depth?: "shallow"\|"standard"\|"deep" }` |
+| `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
+| `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
+| `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE        — 解析参数和意图                    PERSIST: —
+S_ROUTE        — 路由到目标脚本                    PERSIST: —
+S_CONTEXT      — 组装 context payload             PERSIST: —
+S_DISPATCH     — 调用 Workflow 工具                PERSIST: —
+S_INGEST       — 处理返回结果                      PERSIST: —
+S_FALLBACK     — 无法路由                         PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_ROUTE     WHEN: intent parsed                DO: A_PARSE_ARGS
+  → S_FALLBACK  WHEN: no intent
+
+S_ROUTE:
+  → S_CONTEXT   WHEN: script resolved              DO: A_ROUTE_SCRIPT
+  → S_FALLBACK  WHEN: ambiguous intent              DO: ask_question
+
+S_CONTEXT:
+  → S_DISPATCH  DO: A_ASSEMBLE_CONTEXT
+
+S_DISPATCH:
+  → S_INGEST    WHEN: workflow completed            DO: A_DISPATCH_WORKFLOW
+  → S_FALLBACK  WHEN: workflow failed
+
+S_INGEST:
+  → END         DO: A_INGEST_RESULTS
+
+S_FALLBACK:
+  → S_PARSE     WHEN: user provides input
+  → END         WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_PARSE_ARGS
+
+1. 提取 flags（--script, --dims, --roles, --count, --tier, --resume）
+2. 剩余文本作为 intent
+3. 若有 --resume，记录 resumeRunId
+
+### A_ROUTE_SCRIPT
+
+Intent-to-script routing（按关键词匹配，--script 优先级最高）：
+
+| Keywords | Script |
+|----------|--------|
+| 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
+| 头脑风暴 / brainstorm / 方案 / 设计 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
+| 审查 / review / 代码审查 / code review / 质量 / quality | `wf-review` |
+| 验证 / verify / 检查 / check / 反模式 / antipattern | `wf-verify` |
+| 拷问 / grill / 压力测试 / stress-test / 挑战 / challenge | `wf-grill` |
+| 规划 / plan / 任务分解 / decompose / 分波 / wave | `wf-plan` |
+| 执行 / execute / 实现 / implement / 开发 / develop | `wf-execute` |
+| 里程碑审计 / milestone-audit / 集成检查 / integration | `wf-milestone-audit` |
+
+多命中 → ask_question 让用户选择。
+
+### A_ASSEMBLE_CONTEXT
+
+根据目标脚本组装 args payload：
+
+**wf-analyze:**
+1. Read `.workflow/state.json` 获取当前 phase/milestone 信息
+2. `target` = intent 中的目标描述
+3. `scope` = 从 intent 推断文件范围，或读 roadmap 获取 phase scope
+4. `context` = 拼接相关上下文（上游 artifact 摘要、specs）
+5. `dimensions` = --dims 解析结果（可选）
+
+**wf-brainstorm:**
+1. `topic` = intent 文本
+2. `context` = 读取相关代码文件摘要 + 已有 specs
+3. `count` = --count 或默认 3
+4. `roles` = --roles 解析结果（可选）
+
+**wf-review:**
+1. `target` = 读 git diff 描述变更范围
+2. `scope` = 变更文件列表
+3. `tier` = --tier 或 "standard"
+4. `dimensions` = --dims 解析结果（可选）
+
+**wf-verify:**
+1. `goals` = 读最近的 plan artifact 提取目标列表
+2. `plan_dir` = 定位最近的 plan scratch 目录
+3. `scope` = plan 涉及的文件范围
+4. `skip_tests` / `skip_antipattern` = 从 flags 提取
+
+### A_DISPATCH_WORKFLOW
+
+1. 确定 scriptPath = `~/.maestro/workflows/swarm/{script}.js`（展开为绝对路径）
+2. 构建 Workflow 调用：
+   ```
+   Workflow({
+     scriptPath: absoluteScriptPath,
+     args: assembledArgs,
+     resumeFromRunId: resumeRunId  // 若有
+   })
+   ```
+3. 等待 Workflow 返回结果
+4. 记录 runId 用于潜在的后续 resume
+
+### A_INGEST_RESULTS
+
+Workflow 返回 JSON 后：
+
+1. **摘要输出**：按脚本类型格式化关键指标
+   - analyze: overall_score, scope_verdict, go_no_go, critical findings count
+   - brainstorm: role count, conflict/synergy count, top guidance items
+   - review: verdict (APPROVE/REQUEST_CHANGES/BLOCK), confirmed vs false-positive count
+   - verify: overall_passed, confidence, gap count, antipattern blocker count
+
+2. **Artifact 写入**（可选）：
+   - 若当前在 ralph session 中（检测 `.workflow/.maestro/ralph-*/status.json` 状态为 running）：
+     将结果写入对应 step 的 scratch 目录，格式兼容命令产出
+   - 否则写入 `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/results.json`
+
+3. **Ralph 兼容产出**：
+   - analyze → `analysis.md` + `context.md`（decisions）+ `conclusions.json`
+   - brainstorm → `guidance-specification.md`
+   - review → `review.json`
+   - verify → `verification.json`
+
+4. **RunId 提示**：显示 `Resume: /maestro-swarm-workflow --resume {runId}` 用于增量重跑
+
+</actions>
+
+</state_machine>
+
+<invariants>
+1. **只做并行加速，不做状态决策** — 不修改 ralph status.json，不推进 step
+2. **args 预编译** — 所有 FS 读取在 A_ASSEMBLE_CONTEXT 完成，脚本内 agent 通过工具自行读取补充
+3. **产出格式兼容** — 写入的 artifact 格式必须与对应命令（analyze/brainstorm/review/verify）的产出一致
+4. **resume 透传** — resumeFromRunId 直接透传给 Workflow 工具，利用内置缓存机制
+5. **脚本只读** — 路由命令不修改 `~/.maestro/workflows/swarm/wf-*.js` 脚本文件
+6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
+</invariants>
+
+<appendix>
+
+### 与 Ralph 集成
+
+Ralph 可以在 A_BUILD_STEPS 中将某些 step 的执行方式标记为 `swarm-workflow`：
+
+```json
+{
+  "index": 2,
+  "skill": "maestro-swarm-workflow",
+  "args": "--script wf-analyze {phase}",
+  "stage": "analyze",
+  "command_scope": "project",
+  "command_path": "<resolved by maestro ralph skills>"
+}
+```
+
+ralph-execute 正常通过 `maestro ralph next` 加载并执行，swarm-workflow 内部再调 Workflow 工具。
+
+### 输出示例
+
+```
+┌─ wf-analyze ──────────────────────────────────────┐
+│  Explore  [████████████████████] 6/6 dimensions    │
+│  Synthesize  [████████████████] done               │
+├────────────────────────────────────────────────────┤
+│  Score: 7.2/10  Scope: medium  Verdict: go         │
+│  Findings: 23 total (2 critical, 5 high)           │
+│  Cross-cutting: 3 themes                           │
+│  Decisions: 4 locked, 2 free, 1 deferred           │
+├────────────────────────────────────────────────────┤
+│  Output: .workflow/scratch/20260530-swarm-analyze/  │
+│  Resume: /maestro-swarm-workflow --resume wf_abc123 │
+└────────────────────────────────────────────────────┘
+```
+
+### Error Codes
+
+| Code | Description | Recovery |
+|------|-------------|----------|
+| E001 | No intent and no --script | Prompt for intent |
+| E002 | Ambiguous routing | ask_question |
+| E003 | Script file not found | Check .claude/workflows/ |
+| E004 | Workflow execution failed | Show error, suggest --resume |
+| E005 | Result ingestion failed | Write raw JSON to scratch |
+
+</appendix>

package/.agy/skills/manage-codebase-rebuild/SKILL.md

@@ -37,7 +37,7 @@ $ARGUMENTS -- optional flags.
 | Agent | Focus | Output file |
 |-------|-------|-------------|
 | Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
-| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 2 | **Architecture** -- produced by KG pipeline Step 14 (UA architecture-analyzer delegate); layers, module boundaries, data flow, entry points | `architecture.md` |
 | Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
 | Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
 
@@ -45,6 +45,9 @@ $ARGUMENTS -- optional flags.
 - `.workflow/` -- must be initialized (project.md, state.json exist)
 - `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
 - `.workflow/codebase/doc-index.json` -- generated documentation index
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by KG pipeline Steps 10–17 if UA vendor is installed)
+
+**UA vendor requirement:** The KG pipeline (Steps 10–17) requires the UA vendor at `~/.maestro/vendor/ua/understand-anything-plugin/`. If not installed, these steps are skipped automatically. Run `scripts/ua-vendor-setup.sh` to install.
 </context>
 
 <execution>
@@ -55,6 +58,9 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 **Next-step routing on completion:**
 - View updated project state → `/manage-status`
 - Incremental updates later → `/manage-codebase-refresh`
+- Verify KG stats → `maestro kg stats`
+- Verify wiki integration → `maestro wiki list --keyword kg`
+- Future change impact → `maestro kg diff-wiki`
 </execution>
 
 <error_codes>
@@ -63,6 +69,8 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 | E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
 | W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
 | W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
+| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
 </error_codes>
 
 <success_criteria>
@@ -73,5 +81,9 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 - [ ] All documentation files regenerated
 - [ ] state.json updated with rebuild timestamp
 - [ ] project.md Tech Stack section updated if changes detected
+- [ ] KG pipeline executed (if UA vendor installed)
+- [ ] knowledge-graph.json generated in .workflow/codebase/ (if UA vendor installed)
+- [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
 - [ ] Next step routing: `/manage-status` or `/manage-codebase-refresh` for incremental updates later
+- [ ] KG impact check available: `maestro kg diff-wiki` for future change impact analysis
 </success_criteria>

package/.agy/skills/manage-codebase-refresh/SKILL.md

@@ -34,6 +34,7 @@ $ARGUMENTS -- optional flags.
 - `.workflow/` -- must be initialized
 - `.workflow/codebase/` -- must contain existing docs (from prior rebuild)
 - `.workflow/codebase/doc-index.json` -- documentation index with timestamps
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph (optional, for KG impact analysis)
 - `.workflow/state.json` -- contains `codebase_last_rebuilt` timestamp
 </context>
 
@@ -52,6 +53,8 @@ Follow '~/.maestro/workflows/codebase-refresh.md' completely.
 <success_criteria>
 - [ ] Changed files detected via git diff since last refresh
 - [ ] Affected documentation entries identified from doc-index.json
+- [ ] KG impact analysis run (if knowledge-graph.json exists): `maestro kg diff-wiki --json`
+- [ ] Affected wiki entries flagged with warnings (if any)
 - [ ] Only affected docs refreshed (selective mapper re-run)
 - [ ] doc-index.json timestamps updated per affected entry
 - [ ] state.json updated with codebase_last_refreshed timestamp

package/.agy/skills/spec-setup/SKILL.md

@@ -10,8 +10,9 @@ allowed-tools:
 ---
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Core files (coding, arch, knowhow) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
-All output lands in `.workflow/specs/`.
+Core files (coding, arch, learnings) are always created. Optional spec files (quality, test, ui) are created only when relevant signals are detected.
+Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro wiki search`.
+Spec output lands in `.workflow/specs/`; recipe output lands in `.workflow/knowhow/`.
 </purpose>
 
 <required_reading>
@@ -36,12 +37,15 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 | 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 files always created: `coding-conventions.md`, `architecture-constraints.md`, `knowhow.md`
-- [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
-- [ ] Report displayed with summary and next steps
+- [ ] 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>
 </output>

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

@@ -0,0 +1,176 @@
+---
+name: team-swarm
+description: Swarm intelligence team skill — ACO-driven multi-agent exploration with hybrid LLM coordinator + Python optimization controller. Coordinator generates swarm-config from user task, then runs K iterations of N parallel ants guided by pheromone state. Universal task space via config (nodes + scoring rule). Triggers on "team swarm", "swarm intelligence", "蚁群".
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+agy-subagents:
+  - team-worker
+---
+
+## Sub-Agent Registration (Antigravity)
+
+Before any `invoke_subagent` call below, register each sub-agent type once per session by reading the system_prompt from `<agy-agents-dir>/<name>.md` and passing it to `define_subagent`. The `<agy-agents-dir>` is:
+- global install: `~/.gemini/antigravity-cli/agents/`
+- workspace install: `<project>/.agents/agents/`
+
+- `define_subagent(name="team-worker", description="<from agents/team-worker.md frontmatter>", system_prompt=<contents of agents/team-worker.md body>, enable_write_tools=true, enable_mcp_tools=true, enable_subagent_tools=false)`
+
+**ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
+
+---
+
+# Team Swarm
+
+Orchestrate ant-colony-style exploration over a user-defined task space. **Hybrid coordinator**: LLM handles task translation + worker spawning; Python script owns all numeric decisions (selection / pheromone update / convergence). Universal — task space and scoring rule come from `swarm-config.json`.
+
+## Architecture
+
+```
+view_file(AbsolutePath="<agy-skills-dir>/team-swarm/SKILL.md") + execute inline (args: "task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- Phase 1: gen swarm-config
+     +-- Phase 2: init  --> Bash: scripts/aco.py init
+     +-- Phase 3: iterate (K rounds, each = spawn-and-stop)
+     |   |
+     |   +-- Bash: aco.py select --iter k  -> N assignments
+     |   +-- Spawn N x team-worker(ant)
+     |   +-- [callback when all ants done]
+     |   +-- (optional) Spawn team-worker(scorer)
+     |   +-- Bash: aco.py update --iter k
+     |   +-- Bash: aco.py converged
+     |   +-- branch: loop k+1 OR Phase 4
+     |
+     +-- Phase 4: converge --> Bash: aco.py report -> Spawn team-worker(analyst)
+                                                    -> best-solution.md
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| ant | [roles/ant/role.md](roles/ant/role.md) | ANT-* | false |
+| scorer | [roles/scorer/role.md](roles/scorer/role.md) | SCORE-* | false |
+| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYST-* | false |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `TS`
+- **Session path**: `.workflow/.team/TS-<slug>-<date>/`
+- **Team name**: `swarm`
+- **Script root**: `<skill_root>/scripts/aco.py` (Python 3.10+)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View iteration progress + convergence curve |
+| `resume` / `continue` | Resume interrupted iteration |
+| `feedback <text>` | Inject feedback into wisdom; applies at next iteration |
+| `revise <ITER>` | Re-run a specific iteration (rare) |
+
+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/swarm-protocol.md](specs/swarm-protocol.md) | Master protocol: script <-> coordinator interface, data flow |
+| [specs/pheromone-schema.md](specs/pheromone-schema.md) | Pheromone JSON structure, update formula, evaporation |
+| [specs/ant-output-schema.md](specs/ant-output-schema.md) | Critical contract for ant JSON artifacts |
+| [specs/convergence-criteria.md](specs/convergence-criteria.md) | Stop conditions, multi-criterion logic |
+| [specs/swarm-config-template.json](specs/swarm-config-template.json) | User-facing config template with all knobs |
+
+## Scripts
+
+| Script | Purpose | Invocation |
+|--------|---------|------------|
+| `scripts/aco.py` | Main CLI: init / select / update / converged / report | `python aco.py --session <path> <cmd>` |
+| `scripts/pheromone.py` | Pheromone matrix module (imported by aco.py) | — |
+| `scripts/scoring.py` | Pluggable scorer (script + fallback modes) | — |
+
+## Session Directory
+
+```
+.workflow/.team/TS-<slug>-<date>/
+├── team-session.json           # Session state
+├── swarm-config.json           # User-facing config (Phase 1 output)
+├── role-binding.json           # Worker role_spec path map
+├── task-space.json             # Resolved nodes list
+├── pheromone/
+│   ├── current.json            # Latest pheromone (each iter overwrites)
+│   ├── init.json               # Frozen initial state
+│   └── history/<iter>.json     # Per-iter snapshot
+├── trails/<iter>.jsonl         # Per-iter all-ant paths + scores
+├── scores/iter-<iter>-scores.json  # Scorer output (if mode == llm)
+├── artifacts/
+│   ├── ant-<iter>-<id>.json    # Per-ant schema-locked output
+│   ├── swarm-report.json       # Phase 4 full report dump
+│   └── best-solution.md        # Analyst final synthesis
+├── best.json                   # Canonical best solution
+├── wisdom/                     # learnings / decisions / issues
+└── .msg/                       # Message bus
+```
+
+## Completion Action
+
+When swarm converges, coordinator presents:
+
+```
+ask_question({
+  questions: [{
+    question: "Swarm pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, delete team" },
+      { label: "Keep Active", description: "Preserve for follow-up" },
+      { label: "Export Best Solution", description: "Copy best-solution.md to target" },
+      { label: "Run Another Round", description: "Reset convergence, K more iterations" }
+    ]
+  }]
+})
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| `aco.py` not found | Verify `<skill_root>/scripts/aco.py`; check Python install |
+| Python version < 3.10 | Use `python3` or report dependency error |
+| Config validation fails | ask_question to fix, regenerate, retry |
+| All ants fail in iteration | Halt, ask_question (retry / abort / refine config) |
+| Hallucination cluster (>50%) | Pause, ask_question (continue / refine scoring) |
+| Convergence never trips | `max_iterations` safety net always fires |
+| Session corruption | Phase 0 reconciliation; archive if irrecoverable |