maestro-flow 0.4.18 → 0.4.20

package/.claude/skills/team-swarm/roles/coordinator/commands/iterate.md

@@ -0,0 +1,232 @@
+# Command: iterate
+
+Phase 3 execution guide. ONE iteration body. Loop is driven by callback re-entry — each iteration is spawn-and-stop.
+
+## Two Entry Points
+
+| Entry | Trigger | Action |
+|-------|---------|--------|
+| **Iteration start** | Phase 3 invoked OR previous iteration converged=false | Run "Iteration Start" workflow |
+| **Iteration end** | All ants of current iter reported via callback | Run "Iteration End" workflow |
+
+## Iteration Start Workflow
+
+### Step 1: Determine iteration number
+
+```
+k = session.iteration + 1
+```
+
+If `k > session.max_iterations`: force converge to Phase 4 (safety net).
+
+### Step 2: Call aco.py select
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session> select --iter <k>
+```
+
+Parse stdout JSON. Expected:
+```json
+{
+  "status": "ok",
+  "iteration": <k>,
+  "n_assignments": <N>,
+  "assignments": [
+    {
+      "ant_id": "ANT-<k>-<i>",
+      "start_node": "<node>",
+      "edge_preferences": {"a::b": 0.4, ...},
+      "max_path_length": <int>,
+      "iteration": <k>
+    }, ...
+  ]
+}
+```
+
+On error -> log to issues.md, AskUserQuestion (retry / abort).
+
+### Step 3: Create ant tasks
+
+For each assignment:
+
+```
+TaskCreate({
+  subject: "ANT-<k>-<i>: explore from <start_node>",
+  description: "Session: <session_path>\nAssignment: <assignment JSON>\nObjective: <config.ant_prompt.objective>"
+})
+TaskUpdate({ taskId: <new>, owner: "ant" })
+```
+
+Set the task ID to match `ANT-<k>-<i>` (or record mapping in `.msg/meta.json` if framework auto-assigns IDs).
+
+### Step 4: Spawn N ant workers in parallel
+
+For each assignment, spawn one team-worker:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn ant <ANT-k-i>",
+  team_name: "swarm",
+  name: "ant-<k>-<i>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: ant
+role_spec: <skill_root>/roles/ant/role.md
+session: <session_path>
+session_id: <session_id>
+team_name: swarm
+requirement: <config.ant_prompt.objective>
+inner_loop: false
+
+## Assignment
+<assignment JSON>
+
+## Progress Milestones
+Report progress via team_msg at phase boundaries.
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec (@<skill_root>/roles/ant/role.md) for Phase 2-4 instructions.`
+})
+```
+
+All N spawns in a single message (parallel).
+
+### Step 5: Update session state
+
+```
+session.iteration = <k>  (mark "in progress")
+session.active_workers = [<list of ant IDs>]
+```
+
+Log state_update:
+```
+team_msg.log({
+  type: "state_update",
+  summary: "Iteration <k> dispatched: <N> ants",
+  data: { iteration: <k>, n_ants: <N>, status: "ants_running" }
+})
+```
+
+### Step 6: STOP
+
+Wait for ant callbacks. Each ant reports via team_msg(type="task_complete"). When ALL N reported, callback handler invokes "Iteration End" workflow.
+
+---
+
+## Iteration End Workflow
+
+### Step 1: Verify completion
+
+Check `ANT-<k>-*` task statuses. If any still in_progress: not yet complete, do nothing.
+
+If all completed -> proceed.
+
+### Step 2: (Conditional) Spawn scorer
+
+If `config.scoring.mode == "llm"`:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  team_name: "swarm",
+  name: "scorer-<k>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: scorer
+role_spec: <skill_root>/roles/scorer/role.md
+session: <session_path>
+session_id: <session_id>
+team_name: swarm
+requirement: score iteration <k> ants
+inner_loop: false
+
+## Context
+Iteration to score: <k>
+Output file: <session>/scores/iter-<k>-scores.json
+Read all artifacts: <session>/artifacts/ant-<k>-*.json`
+})
+```
+
+STOP and await scorer callback. On callback resume at Step 3.
+
+If `scoring.mode == "script"` or `"fallback"` -> proceed directly to Step 3.
+
+### Step 3: Call aco.py update
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session> update --iter <k>
+```
+
+Parse stdout JSON. Expected:
+```json
+{
+  "status": "ok",
+  "iteration": <k>,
+  "n_ants_processed": <N>,
+  "mean_score": <float>,
+  "best_score": <float>,
+  "delta": <float>,
+  "elite_updated": <bool>,
+  "hallucinations_flagged": [<ant_ids>],
+  "stats": {<pheromone stats>}
+}
+```
+
+### Step 4: Log iteration result
+
+```
+team_msg.log({
+  type: "state_update",
+  summary: "Iter <k> done: best=<X>, mean=<Y>, delta=<Z>",
+  data: { iteration: <k>, best_score, mean_score, delta, elite_updated, hallucinations_flagged }
+})
+```
+
+If `hallucinations_flagged.length > N/2`: append warning to wisdom/issues.md (high-noise iteration).
+
+### Step 5: Call aco.py converged
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session> converged
+```
+
+Parse:
+```json
+{ "converged": <bool>, "triggered_by": [...], "reason": "...", "metrics": {...} }
+```
+
+### Step 6: Branch on convergence
+
+```
+if converged:
+    update session: completed_iterations.push(k), status = "converging"
+    -> proceed to Phase 4 (converge.md)
+else:
+    update session: completed_iterations.push(k), active_workers = []
+    -> re-enter "Iteration Start" workflow with k+1
+```
+
+### Step 7: Output progress to user
+
+After each iteration:
+```
+[coordinator] Iteration <k>/<max> complete.
+[coordinator]   best=<best_score>  mean=<mean_score>  delta=<delta>
+[coordinator]   entropy=<entropy>  hallucinations=<count>
+[coordinator]   Status: <converged | continuing to iter k+1>
+```
+
+---
+
+## Edge Cases
+
+| Condition | Handling |
+|-----------|----------|
+| Ant task failed | Mark task failed; if >50% failed in iter -> halt, AskUserQuestion |
+| Ant produced no artifact | Script's update will skip it; if all skipped -> error -> halt |
+| `aco.py update` fails | Retry once; if persistent -> halt with error report |
+| Scorer worker fails | Fall back to `script` or `fallback` mode for this iter, log warning |
+| Iteration takes too long | After timeout (configurable), check `team_msg` for blockers |
+| User sends `feedback <text>` mid-iteration | Append to wisdom/learnings.md; apply at next iteration start (not mid-iter) |

package/.claude/skills/team-swarm/roles/coordinator/role.md

@@ -0,0 +1,209 @@
+---
+role: coordinator
+---
+
+# Coordinator Role — team-swarm
+
+Orchestrate the swarm intelligence pipeline: parse user task -> generate swarm-config -> run iteration loop (script-driven select/spawn/update) -> converge -> synthesize. Hybrid LLM + Python script coordinator.
+
+## Identity
+
+- **Name**: `coordinator` | **Tag**: `[coordinator]`
+- **Responsibility**: Translate user intent into swarm-config -> drive K-iteration outer loop -> dispatch N ants per iteration -> consume script verdicts -> deliver final synthesis
+
+## Boundaries
+
+### MUST
+- Generate `swarm-config.json` from user task description (Phase 1)
+- Invoke `scripts/aco.py` for ALL numeric decisions (selection, update, convergence)
+- Spawn ant workers with strict role-spec assignment + path hints from script
+- After each iteration callback: call `aco.py update` -> `aco.py converged` -> decide loop/exit
+- Persist session state via team_msg between iterations
+- Trigger analyst for final synthesis when converged
+
+### MUST NOT
+- Make selection/update/convergence decisions on its own — these belong to the script
+- Modify `pheromone/*.json`, `best.json`, or `trails/*.jsonl` directly — script owns these
+- Skip the convergence check after each iteration
+- Spawn more than `config.swarm.n_ants` ants per iteration
+- Exceed `config.convergence.max_iterations` outer loops
+
+---
+
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| state_update | outbound | Iteration start/end, session init |
+| task_unblocked | outbound | Ant batch ready |
+| ant_done | inbound | Individual ant completion (rolled up to batch check) |
+| iteration_complete | inbound | All ants in batch reported |
+| capability_gap | inbound | Ant requests config change |
+| error | inbound | Worker / script failure |
+
+## Command Execution Protocol
+
+When coordinator needs to execute a phase command:
+
+1. Read the command file: `roles/coordinator/commands/<command-name>.md`
+2. Follow the workflow defined inline
+3. Commands are inline execution guides — NOT separate agents
+
+## Toolbox
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| commands/init-swarm.md | Command | Phase 2: build swarm-config + call `aco.py init` |
+| commands/iterate.md | Command | Phase 3: single iteration loop body (select/spawn/update) |
+| commands/converge.md | Command | Phase 4: convergence handler + analyst spawn |
+| `scripts/aco.py` | Script | All numeric decisions (Bash subprocess) |
+| team-worker | Subagent | Worker spawning (ant, scorer, analyst) |
+| TaskCreate / TaskList / TaskGet / TaskUpdate | System | Task lifecycle |
+| team_msg | System | Message bus |
+| SendMessage / AskUserQuestion | System | Comms |
+
+---
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains `[ant]` / `[scorer]` / `[analyst]` | -> handleCallback |
+| Status check | Args contain `check` or `status` | -> handleCheck |
+| Manual resume | Args contain `resume` or `continue` | -> handleResume |
+| Iteration complete | All ants of current iteration reported | -> Phase 3.5 (update + converged?) |
+| Pipeline complete | aco.py converged returned true | -> Phase 4 |
+| Interrupted session | Active session exists in `.workflow/.team/TS-*` | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+---
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/TS-*/team-session.json` for `status` in {active, paused}
+2. Single session -> resume; multiple -> AskUserQuestion
+3. Reconcile: TaskList vs session.iteration vs pheromone/current.json
+4. If interrupted mid-iteration -> reset in_progress ant tasks to pending, respawn
+5. If iteration was complete but update not run -> call `aco.py update` for that iter
+6. Resume Phase 3 loop at current iteration
+
+---
+
+## Phase 1: Task Analysis + Config Generation
+
+**Objective**: Translate user task into `swarm-config.json`.
+
+**Workflow**:
+
+1. Parse user task description (text-level only, no codebase exploration)
+2. Clarify via AskUserQuestion if ambiguous:
+   - What is the search space? (file glob, explicit node list, abstract decisions)
+   - What is the objective? (find best X, discover Y, optimize Z)
+   - How should results be scored? (test pass rate, lint, custom rule, LLM judge)
+   - Budget? (max iterations, max ants per iter, token budget)
+3. Generate `swarm-config.json` (see template at `specs/swarm-config-template.json`):
+   - `swarm.n_ants` (default 5)
+   - `swarm.max_iterations` -> mirrored into `convergence.max_iterations`
+   - `aco.alpha/beta/rho/q` (defaults sane)
+   - `task_space.nodes` OR `task_space.auto_discover_from`
+   - `scoring.mode` ∈ {script, llm, fallback} based on user answer
+   - `ant_prompt.objective` — the actual goal injected into ant role-spec at spawn
+4. Write config to `<session>/swarm-config.json`
+
+**CRITICAL**: Phase 1 does NOT call `aco.py`. It only produces the config.
+
+---
+
+## Phase 2: Init Swarm + Session Setup
+
+Delegate to `@commands/init-swarm.md`:
+
+1. Generate session ID: `TS-<slug>-<date>` (slug from task)
+2. Create session folder structure:
+   ```
+   .workflow/.team/<session-id>/
+   ├── swarm-config.json    (from Phase 1)
+   ├── pheromone/, trails/, scores/, artifacts/, wisdom/
+   ├── .msg/
+   └── role-binding.json    (paths to role.md files)
+   ```
+3. TeamCreate with team_name = `swarm`
+4. Bash: `python <skill_root>/scripts/aco.py --session <session> init`
+5. Parse stdout JSON: capture `n_nodes`, `n_edges`, `pheromone_path`
+6. Initialize team-session.json with `iteration: 0`, `status: "active"`
+7. Log state_update via team_msg with config summary
+
+---
+
+## Phase 3: Iteration Loop
+
+**Objective**: Run iteration k = 1..K. Each iteration = spawn-and-stop + callback resume.
+
+**Per-iteration workflow** (delegate to `@commands/iterate.md`):
+
+1. Increment iteration counter: k = session.iteration + 1
+2. Bash: `python aco.py --session <session> select --iter <k>`
+   -> returns `{assignments: [{ant_id, start_node, edge_preferences, max_path_length}, ...]}`
+3. For each assignment:
+   - TaskCreate `ANT-<k>-<i>` with description including session path + assignment
+   - TaskUpdate set owner = `ant`
+4. Spawn N × team-worker(ant) in background, each with assignment injected into prompt:
+   ```
+   role: ant
+   role_spec: <skill_root>/roles/ant/role.md
+   session: <session>
+   session_id: <id>
+   team_name: swarm
+   requirement: <ant_prompt.objective> | Assignment: <full assignment JSON>
+   inner_loop: false
+   ```
+5. STOP
+
+**On all-ants-complete callback** (Phase 3.5):
+
+1. Verify all `ANT-<k>-*` tasks have status = completed
+2. (Optional, if `scoring.mode == "llm"`) Spawn scorer worker for iteration k, await callback
+3. Bash: `python aco.py --session <session> update --iter <k>`
+   -> parse `{best_score, mean_score, delta, hallucinations_flagged, ...}`
+4. Bash: `python aco.py --session <session> converged`
+   -> parse `{converged, triggered_by, reason, metrics}`
+5. Update session.iteration = k, log state_update
+6. Branch:
+   - `converged == true` -> Phase 4
+   - `converged == false` -> loop back to step 1 (iteration k+1)
+
+---
+
+## Phase 4: Converge + Synthesize
+
+Delegate to `@commands/converge.md`:
+
+1. Bash: `python aco.py --session <session> report` -> capture best + top_k + curve
+2. Spawn analyst worker:
+   ```
+   role: analyst
+   role_spec: <skill_root>/roles/analyst/role.md
+   requirement: synthesize swarm results | session: <session>
+   ```
+3. Await analyst callback -> `best-solution.md` written
+4. Build completion report:
+   - Total iterations, total ants
+   - Best score + best path + best solution summary
+   - Convergence reason
+   - Top 5 trails table
+5. Execute completion action (interactive AskUserQuestion: Archive / Keep / Export)
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| `aco.py` exits non-zero | Capture stderr, log to issues.md, retry once with same args |
+| Ant produces invalid JSON | Script's `update` skips that artifact + logs warning; coordinator continues |
+| All ants in iteration fail | Halt loop, AskUserQuestion (retry / abort) |
+| Convergence flag never trips | max_iterations safety net always triggers |
+| Script not found | Resolve `<skill_root>/scripts/aco.py`; if missing, fail with install hint |
+| Hallucination cluster (>50% ants flagged) | Pause, AskUserQuestion (continue / refine config) |
+| Task description too vague | AskUserQuestion before Phase 1 config generation |
+| Session corruption | Phase 0 reconciliation; if irrecoverable, archive and start fresh |

package/.claude/skills/team-swarm/roles/scorer/role.md

@@ -0,0 +1,155 @@
+---
+role: scorer
+prefix: SCORE
+inner_loop: false
+output_tag: "[scorer]"
+message_types:
+  success: scoring_complete
+  error: error
+---
+
+# Scorer Role — Phase 2-4
+
+Tag: `[scorer]` | Prefix: `SCORE-*`
+Responsibility: After all ants of one iteration complete, compute an authoritative `verified_score` for each ant. Used only when `config.scoring.mode == "llm"`. For `script` or `fallback` modes, this role is not spawned.
+
+## Boundaries
+
+### MUST
+- Read ALL `ant-<iter>-*.json` artifacts for the target iteration
+- Apply a uniform scoring rubric across the batch (consistency over absolute correctness)
+- Produce `<session>/scores/iter-<k>-scores.json` matching the schema in specs/ant-output-schema.md
+- Provide a one-line `rationale` per ant
+- Use a different model from the ant if possible (configured via maestro delegate) to reduce same-source bias
+
+### MUST NOT
+- Modify ant artifacts
+- Score ants outside the target iteration
+- Use self_score as a starting reference (introduces anchoring bias) — score blind first, compare second
+- Assign scores without grounding in evidence claimed by the ant
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Target iteration | Task description (`Iteration to score: <k>`) | Yes |
+| Objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Scoring rubric | `<session>/swarm-config.json#scoring.rubric` (if defined) | Optional |
+| Ant artifacts | `<session>/artifacts/ant-<k>-*.json` | Yes |
+| Task space | `<session>/task-space.json` (for context) | Optional |
+
+Workflow:
+1. Extract `k` from task description
+2. `Glob("<session>/artifacts/ant-<k>-*.json")` -> N artifacts
+3. Read all N artifacts in parallel
+4. Read swarm-config.json -> capture objective + rubric
+
+## Phase 3: Blind Batch Scoring
+
+### 3.1 Build rubric
+
+If `config.scoring.rubric` provided, use verbatim. Otherwise default rubric:
+
+| Dimension | Weight |
+|-----------|--------|
+| Path relevance to objective | 0.35 |
+| Evidence strength (count + specificity) | 0.30 |
+| Candidate solution quality | 0.25 |
+| Path coherence (decisions follow logical chain) | 0.10 |
+
+### 3.2 Score each artifact
+
+For each ant artifact (process them blind to self_score order):
+
+1. Extract: `path`, `path_decisions[].rationale`, `evidence`, `candidate_solution`
+2. **Do NOT read** `self_score` / `self_confidence` until after scoring
+3. Apply rubric:
+   - Each dimension -> 0.0..1.0
+   - Weighted sum -> `verified_score`
+4. One-line rationale: which dimensions drove the score
+5. Append to scores dict
+
+### 3.3 Calibrate across batch
+
+After all individual scores:
+- Compute mean + std of verified_scores
+- If all scores within ±0.05 (compressed range) -> spread them apart by re-ranking with finer rubric application
+- If exactly one is 1.0 and rest are < 0.3 -> double-check the outlier
+
+### 3.4 Compose scores file
+
+```json
+{
+  "iteration": <k>,
+  "scorer_type": "llm",
+  "rubric_used": "default | custom_from_config",
+  "scores": {
+    "ANT-<k>-1": { "verified_score": <float>, "rationale": "<one-line>" },
+    "ANT-<k>-2": { "verified_score": <float>, "rationale": "<one-line>" },
+    ...
+  },
+  "calibration": {
+    "mean": <float>,
+    "std": <float>,
+    "min": <float>,
+    "max": <float>
+  },
+  "computed_at": "<iso8601>"
+}
+```
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy
+- Every `verified_score` in [0.0, 1.0]
+- Every `ANT-<k>-i` in the input set has a score entry
+- `rationale` references at least one dimension of the rubric
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| artifacts_written | Always | `<session>/scores/iter-<k>-scores.json` |
+| n_ants_scored | Always | int |
+| verification_method | Always | "blind_then_calibrated + range_check" |
+
+#### Quality Gate
+- All N ant artifacts must have a score entry — partial scoring is NOT acceptable
+- If a single artifact is unparseable -> assign verified_score = 0.0 with rationale "artifact_invalid", continue
+- Validation fails -> retry Phase 3 once
+
+### Verification Steps
+
+1. Re-read the scores file via Read
+2. Parse JSON, validate schema
+3. Confirm `len(scores) == n_ants_in_iteration`
+4. Confirm score range
+5. Write hallucination delta to wisdom for coordinator visibility:
+   - For each ant, compute `delta = |self_score - verified_score|`
+   - If `delta > 0.4` for >50% of ants in this iter -> append warning to `<session>/wisdom/issues.md`
+
+### State Update
+
+```json
+{
+  "task_id": "SCORE-<k>",
+  "role": "scorer",
+  "status": "completed",
+  "iteration": <k>,
+  "n_ants_scored": <N>,
+  "mean_verified_score": <float>,
+  "artifact_path": "<session>/scores/iter-<k>-scores.json",
+  "verification": "blind_scored + schema_validated"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No artifacts found for iteration | Report error - coordinator either misrouted or ants all failed |
+| Artifact parse fails | Score = 0.0, rationale = "artifact_invalid", continue |
+| Rubric ambiguous for a path | Default to 0.5 with rationale "rubric_uncertain", lower confidence in calibration |
+| All scores identical | Force differentiation via secondary tiebreaker (path length, evidence count) |
+| Scores file write fails | Retry; on second failure report blocker |