maestro-flow 0.4.17 → 0.4.19

package/.agents/skills/team-swarm/roles/ant/role.md

@@ -0,0 +1,169 @@
+---
+role: ant
+prefix: ANT
+inner_loop: false
+output_tag: "[ant]"
+message_types:
+  success: ant_complete
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Ant Role — Phase 2-4
+
+Tag: `[ant]` | Prefix: `ANT-*`
+Responsibility: Receive path-hints from ACO controller, explore the task space starting from assigned node, produce schema-locked JSON artifact with self-evaluation.
+
+## Boundaries
+
+### MUST
+- Read assignment JSON from task description (start_node, edge_preferences, max_path_length)
+- Load swarm-config.json to understand objective + task semantics
+- Build a path of length 1..max_path_length starting from start_node
+- Bias choices using `edge_preferences` (pheromone-derived) BUT may deviate when evidence supports it
+- Output strict-schema JSON to `<session>/artifacts/ant-<iter>-<id>.json` (see specs/ant-output-schema.md)
+- Self-validate output before reporting (JSON parses + required fields + node validity)
+- Provide ≥ 1 evidence anchor per path
+
+### MUST NOT
+- Modify pheromone state, best.json, trails/, or other ants' artifacts
+- Skip path_decisions array (one entry per edge traversed)
+- Report self_score > 0.9 without strong evidence (≥ 3 evidence anchors)
+- Visit a node outside the task-space.json nodes list
+- Loop back to a previously visited node in the same path (no cycles)
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Assignment | Task description (parse JSON block) | Yes |
+| Objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Task semantics | `<session>/swarm-config.json#ant_prompt` (full block) | Yes |
+| Task space | `<session>/task-space.json` (valid nodes list) | Yes |
+| Pheromone hints | `assignment.edge_preferences` (already passed in) | Yes |
+| Wisdom from prior iters | `<session>/wisdom/learnings.md` (if exists) | Optional |
+
+Workflow:
+1. Extract session path from task description
+2. Parse assignment JSON block from task description
+3. Read swarm-config.json -> capture `ant_prompt.objective`, `ant_prompt.evidence_requirements`, `task_space.max_path_length`
+4. Read task-space.json -> build valid_nodes set
+5. If `<session>/wisdom/learnings.md` exists -> read for prior-iteration insights
+
+## Phase 3: Exploration
+
+**Goal**: Build a path of nodes that maximizes likelihood of achieving the objective. The objective is task-defined (find buggy code, find best refactor target, etc.); ant is task-agnostic infrastructure.
+
+Workflow:
+
+### 3.1 Initialize path
+- `path = [assignment.start_node]`
+- `path_decisions = []`
+- `visited = {start_node}`
+- `current = start_node`
+
+### 3.2 Per-step exploration loop (until len(path) reaches max_path_length OR ant decides to stop early)
+
+For each step:
+
+1. **Compute candidate neighbors**: all nodes in task_space NOT in `visited`
+2. **Build choice weights**:
+   - For each candidate c: `weight = edge_preferences.get("<current>::<c>", baseline) * heuristic(c)`
+   - `heuristic(c)` = ant's own evidence-based judgment (1.0 if no opinion)
+3. **Investigate top candidates** using available tools:
+   - Tool selection: Read, Grep, Glob for code-based task spaces; or CLI delegate `--mode analysis` for richer analysis
+   - Gather evidence about each top candidate before committing
+4. **Choose next node**: weighted-random OR argmax (when high confidence)
+5. **Record decision**:
+   ```json
+   {
+     "from": "<current>",
+     "to": "<chosen>",
+     "rationale": "<one-line>",
+     "guided_by": "pheromone | heuristic | evidence",
+     "pheromone_weight": <edge_preferences value>,
+     "deviation_from_hint": <bool — true if chosen != argmax(edge_preferences)>
+   }
+   ```
+6. **Append to path**, update `visited`, `current = chosen`
+7. **Early-stop check**: if evidence shows objective achieved OR no productive next step exists -> stop
+
+### 3.3 Self-evaluate
+
+After path is built:
+
+1. **self_score** (0..1): how well does this path satisfy the objective?
+   - Use `ant_prompt.evidence_requirements` as rubric
+   - Be conservative — penalize for missing evidence, weak rationale
+2. **self_confidence** (0..1): how sure of the self_score?
+   - Low confidence if evidence is sparse or contradictory
+3. **candidate_solution**: extract the actual deliverable along the path
+   - `type` ∈ {string, object, file_ref}
+   - `summary` — one-line
+   - `content` — actual artifact OR a path to a file written by the ant
+
+### 3.4 Compose artifact JSON
+
+Build the full artifact matching specs/ant-output-schema.md. All required fields populated.
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy — outputs must be verifiable
+- Every node in `path` MUST exist in task-space.json
+- Every `path_decisions[i].from` MUST equal `path[i]` and `to` MUST equal `path[i+1]`
+- Evidence references (e.g., `file:line`) MUST be valid (Read to confirm if file_ref)
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| files_produced | If ant wrote any | `[artifact_path]` at minimum |
+| artifacts_written | Always | `<session>/artifacts/ant-<iter>-<id>.json` |
+| verification_method | Always | "schema_validated + node_validity_checked" |
+
+#### Quality Gate
+- Schema validation pass = REQUIRED before reporting completed
+- Fails -> retry Phase 3 once (max 1 retry to bound cost)
+- Still fails -> report `partial_completion` with `validation_errors` in state data
+
+### Verification Steps
+
+1. **Schema validation**:
+   - Parse the JSON via Read
+   - Confirm all required fields from specs/ant-output-schema.md
+   - Confirm numeric ranges (self_score, self_confidence ∈ [0,1])
+   - Confirm `len(path_decisions) == len(path) - 1`
+2. **Node validity**: every node in path ∈ task_space.json#nodes
+3. **Evidence check**: at least 1 evidence anchor present; if file_ref, Read to confirm existence
+4. **Write artifact**: `write_file(<session>/artifacts/ant-<iter>-<id>.json, <json_string>)`
+5. **Re-read to confirm write**: Read it back, parse, sanity check
+
+### State Update
+
+Set Phase 5 `team_msg.log` data:
+```json
+{
+  "task_id": "ANT-<k>-<i>",
+  "role": "ant",
+  "status": "completed",
+  "iteration": <k>,
+  "self_score": <float>,
+  "self_confidence": <float>,
+  "path_length": <int>,
+  "artifact_path": "<session>/artifacts/ant-<k>-<i>.json",
+  "verification": "schema_pass + node_valid + evidence_present"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Assignment JSON malformed | Report error to coordinator via send_message, STOP |
+| start_node not in task_space | Report error (config mismatch), STOP |
+| No valid neighbors at step 1 | Build single-node path, self_score = 0, report |
+| Schema validation fails twice | Report `partial_completion` with errors list |
+| Evidence requirements unsatisfiable | Lower self_score; document blocker in artifact `notes` field |
+| Tool calls fail (Read/Grep) | Note in artifact `notes`; reduce self_confidence; proceed with available info |

package/.agents/skills/team-swarm/roles/coordinator/commands/converge.md

@@ -0,0 +1,146 @@
+# Command: converge
+
+Phase 4 execution guide. Run after `aco.py converged` returns `true`.
+
+## Workflow
+
+### Step 1: Call aco.py report
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session> report
+```
+
+Parse stdout JSON. Expected:
+```json
+{
+  "status": "ok",
+  "best": { ant_id, iteration, path, score, candidate_solution, evidence, ... },
+  "top_k": [<top 5 trails>],
+  "convergence_curve": [{iteration, entropy, tau_max, tau_mean}, ...],
+  "final_pheromone_stats": {...},
+  "iterations_completed": <int>
+}
+```
+
+Save full report to `<session>/artifacts/swarm-report.json` (raw data for analyst).
+
+### Step 2: Spawn analyst worker
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn analyst for swarm synthesis",
+  team_name: "swarm",
+  name: "analyst",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: analyst
+role_spec: <skill_root>/roles/analyst/role.md
+session: <session_path>
+session_id: <session_id>
+team_name: swarm
+requirement: synthesize swarm results into human-readable best-solution.md
+inner_loop: false
+
+## Context
+Report data: <session>/artifacts/swarm-report.json
+Best solution: <session>/best.json
+All trails: <session>/trails/*.jsonl
+Original objective: <config.ant_prompt.objective>
+
+## Progress Milestones
+Report via team_msg at: report loaded -> synthesis done -> verification done.
+Report completion via team_msg type="task_complete" after final send_message.`
+})
+```
+
+STOP. Resume on analyst callback.
+
+### Step 3: On analyst callback
+
+Verify `<session>/artifacts/best-solution.md` exists.
+
+If missing -> ask_user (skip synthesis / retry analyst).
+
+### Step 4: Build completion summary
+
+```
+[coordinator] ============================================
+[coordinator] SWARM CONVERGED
+[coordinator]
+[coordinator] Iterations: <iterations_completed> / <max_iterations>
+[coordinator] Trigger: <triggered_by[0]>
+[coordinator] Total ants spawned: <iterations * n_ants>
+[coordinator]
+[coordinator] Best Solution:
+[coordinator]   ant_id: <best.ant_id>
+[coordinator]   iteration: <best.iteration>
+[coordinator]   path: <best.path joined with " -> ">
+[coordinator]   verified_score: <best.score>
+[coordinator]   summary: <best.candidate_solution.summary>
+[coordinator]
+[coordinator] Convergence curve (entropy):
+[coordinator]   iter 1: <e1>  iter 2: <e2>  iter 3: <e3>  ...
+[coordinator]
+[coordinator] Deliverables:
+[coordinator]   - artifacts/best-solution.md (analyst synthesis)
+[coordinator]   - artifacts/swarm-report.json (raw data)
+[coordinator]   - best.json (canonical best)
+[coordinator]   - trails/*.jsonl (full exploration log)
+[coordinator]
+[coordinator] Session: <session_path>
+[coordinator] ============================================
+```
+
+### Step 5: Update session state
+
+```
+session.status = "completed"
+session.converged_at = <iso8601>
+session.convergence_reason = <triggered_by>
+```
+
+Log state_update:
+```
+team_msg.log({
+  type: "state_update",
+  summary: "Swarm pipeline complete: <iterations_completed> iters, best=<score>",
+  data: { ... }
+})
+```
+
+### Step 6: Completion action (interactive)
+
+```
+ask_user({
+  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 iteration" },
+      { label: "Export Best Solution", description: "Copy best-solution.md to target path" },
+      { label: "Run Another Round", description: "Reset convergence, run K more iterations from current pheromone" }
+    ]
+  }]
+})
+```
+
+### Action Handlers
+
+| Choice | Steps |
+|--------|-------|
+| Archive & Clean | session.status = "completed"; delete_team; output final summary |
+| Keep Active | session.status = "paused"; output resume instructions |
+| Export Best Solution | ask_user(target path); copy best-solution.md + best.json; then Archive & Clean |
+| Run Another Round | ask_user(additional K); reset convergence counters; re-enter Phase 3 iterate.md |
+
+## Failure Cases
+
+| Failure | Action |
+|---------|--------|
+| `aco.py report` fails | Read best.json directly + manual top-K from trails/ |
+| Analyst worker crashes | Generate minimal best-solution.md from best.json template |
+| best.json missing | Pipeline ran but no successful ant - report failure, keep session for inspection |
+| Run Another Round chosen but max_iterations already at limit | ask_user to raise the cap before continuing |

package/.agents/skills/team-swarm/roles/coordinator/commands/init-swarm.md

@@ -0,0 +1,136 @@
+# Command: init-swarm
+
+Phase 2 execution guide for coordinator. Initializes swarm session and pheromone state.
+
+## Inputs
+
+- `swarm-config.json` from Phase 1 (in-memory or already written to candidate session path)
+- `session_id` already computed (`TS-<slug>-<date>`)
+- `skill_root` = `<project>/.claude/skills/team-swarm`
+
+## Workflow
+
+### Step 1: Resolve paths
+
+```
+project_root = shell("pwd")
+skill_root = "<project_root>/.claude/skills/team-swarm"
+session_path = "<project_root>/.workflow/.team/<session_id>"
+```
+
+### Step 2: Create session directory tree
+
+```
+mkdir -p <session_path>/{pheromone/history,trails,scores,artifacts,wisdom,.msg}
+```
+
+### Step 3: Write swarm-config.json
+
+Write the Phase 1-generated config to `<session_path>/swarm-config.json`.
+
+Validate before write:
+- `task_space.nodes` OR `task_space.auto_discover_from` present
+- `swarm.n_ants` >= 2 (single-ant defeats swarm purpose)
+- `convergence.max_iterations` >= 1
+
+### Step 4: Create team
+
+```
+create_team({ name: "swarm" })
+```
+
+### Step 5: Write role-binding.json
+
+```json
+{
+  "ant": "<skill_root>/roles/ant/role.md",
+  "scorer": "<skill_root>/roles/scorer/role.md",
+  "analyst": "<skill_root>/roles/analyst/role.md"
+}
+```
+
+Saved at `<session_path>/role-binding.json` — workers resolve their role.md from this file.
+
+### Step 6: Call aco.py init
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session_path> init
+```
+
+Parse stdout JSON. On `status: "error"`:
+- exit_code 2 -> config validation error -> ask_user to fix
+- exit_code 1 -> runtime error -> log to issues.md + retry once
+
+On success, capture:
+- `n_nodes` — search space size
+- `n_edges` — initial edge count
+- `pheromone_path` — confirm written
+
+### Step 7: Initialize team-session.json
+
+```json
+{
+  "session_id": "<session-id>",
+  "task_description": "<user task>",
+  "status": "active",
+  "team_name": "swarm",
+  "skill": "team-swarm",
+  "iteration": 0,
+  "max_iterations": <config.convergence.max_iterations>,
+  "n_ants_per_iter": <config.swarm.n_ants>,
+  "config_path": "swarm-config.json",
+  "pheromone_path": "pheromone/current.json",
+  "roles": ["coordinator", "ant", "scorer", "analyst"],
+  "scoring_mode": "<config.scoring.mode>",
+  "active_workers": [],
+  "completed_iterations": [],
+  "completion_action": "interactive",
+  "created_at": "<iso8601>"
+}
+```
+
+### Step 8: Initialize wisdom files
+
+Create empty wisdom files with headers:
+- `wisdom/learnings.md` — cross-iteration insights
+- `wisdom/decisions.md` — config refinements made mid-pipeline
+- `wisdom/issues.md` — errors and hallucinations log
+
+### Step 9: Log initialization state_update
+
+```
+team_msg({
+  operation: "log",
+  session_id: "<session-id>",
+  from: "coordinator",
+  type: "state_update",
+  summary: "Swarm initialized: <n_nodes> nodes, <n_ants> ants/iter, max <K> iterations",
+  data: {
+    iteration: 0,
+    n_nodes: <n>,
+    n_ants: <n>,
+    max_iterations: <K>,
+    scoring_mode: "<mode>"
+  }
+})
+```
+
+### Step 10: Proceed to Phase 3 (iterate.md)
+
+Do NOT spawn any workers in this command. First spawn happens in iterate.md step 4.
+
+## Success Criteria
+
+- `<session>/swarm-config.json` exists and validates
+- `<session>/pheromone/current.json` exists with `iteration: 0`
+- `<session>/task-space.json` exists with `n_nodes > 0`
+- team-session.json initialized with `iteration: 0`
+
+## Failure Recovery
+
+| Failure | Action |
+|---------|--------|
+| Config invalid | ask_user, regenerate, retry |
+| `aco.py init` runtime error | Log to issues.md, retry once, then ask_user (abort/refine) |
+| Directory creation fails | Check disk space / permissions, retry |
+| create_team fails | Check team name conflict (existing swarm session), prompt to clean or resume |

package/.agents/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, ask_user (retry / abort).
+
+### Step 3: Create ant tasks
+
+For each assignment:
+
+```
+create_task({
+  subject: "ANT-<k>-<i>: explore from <start_node>",
+  description: "Session: <session_path>\nAssignment: <assignment JSON>\nObjective: <config.ant_prompt.objective>"
+})
+update_task({ 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:
+
+```
+delegate_subagent({
+  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 send_message.
+
+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"`:
+
+```
+delegate_subagent({
+  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, ask_user |
+| 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) |