self-evolving-workflow 0.0.0-stage → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +27 -0
- package/README.md +90 -2
- package/dist/agent-memory-prompts.d.ts +13 -0
- package/dist/agent-memory-prompts.js +55 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +6 -0
- package/dist/closeout.d.ts +105 -0
- package/dist/closeout.js +479 -0
- package/dist/code.d.ts +39 -0
- package/dist/code.js +124 -0
- package/dist/common.d.ts +9 -0
- package/dist/common.js +42 -0
- package/dist/context-envelope.d.ts +59 -0
- package/dist/context-envelope.js +23 -0
- package/dist/host-adapters.d.ts +34 -0
- package/dist/host-adapters.js +151 -0
- package/dist/http.d.ts +3 -0
- package/dist/http.js +90 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +13 -0
- package/dist/knowledge-cli.d.ts +183 -0
- package/dist/knowledge-cli.js +654 -0
- package/dist/knowledge-reads.d.ts +71 -0
- package/dist/knowledge-reads.js +193 -0
- package/dist/memory.d.ts +97 -0
- package/dist/memory.js +250 -0
- package/dist/retrospective.d.ts +57 -0
- package/dist/retrospective.js +248 -0
- package/dist/search.d.ts +36 -0
- package/dist/search.js +112 -0
- package/dist/skill-addition.d.ts +25 -0
- package/dist/skill-addition.js +89 -0
- package/dist/skill-design.d.ts +96 -0
- package/dist/skill-design.js +226 -0
- package/dist/skill-replay.d.ts +55 -0
- package/dist/skill-replay.js +451 -0
- package/dist/skill-route.d.ts +30 -0
- package/dist/skill-route.js +75 -0
- package/dist/transcript-evidence.d.ts +3 -0
- package/dist/transcript-evidence.js +58 -0
- package/dist/upstream/chunker.d.ts +24 -0
- package/dist/upstream/chunker.js +96 -0
- package/dist/upstream/file-protocol.d.ts +45 -0
- package/dist/upstream/file-protocol.js +117 -0
- package/dist/upstream/frontmatter.d.ts +47 -0
- package/dist/upstream/frontmatter.js +86 -0
- package/dist/upstream/graph-search.d.ts +33 -0
- package/dist/upstream/graph-search.js +67 -0
- package/dist/upstream/l1-extraction.d.ts +26 -0
- package/dist/upstream/l1-extraction.js +405 -0
- package/dist/upstream/llm.d.ts +8 -0
- package/dist/upstream/llm.js +1 -0
- package/dist/upstream/merge.d.ts +50 -0
- package/dist/upstream/merge.js +153 -0
- package/dist/upstream/prompts.d.ts +53 -0
- package/dist/upstream/prompts.js +185 -0
- package/dist/upstream/search-utils.d.ts +34 -0
- package/dist/upstream/search-utils.js +55 -0
- package/dist/upstream/slug.d.ts +26 -0
- package/dist/upstream/slug.js +103 -0
- package/dist/upstream/template.d.ts +29 -0
- package/dist/upstream/template.js +80 -0
- package/dist/upstream/tokenize.d.ts +4 -0
- package/dist/upstream/tokenize.js +29 -0
- package/dist/wiki-change.d.ts +76 -0
- package/dist/wiki-change.js +299 -0
- package/dist/wiki-entry.d.ts +26 -0
- package/dist/wiki-entry.js +93 -0
- package/dist/wiki-ingest.d.ts +12 -0
- package/dist/wiki-ingest.js +126 -0
- package/dist/wiki-migration.d.ts +16 -0
- package/dist/wiki-migration.js +268 -0
- package/dist/wiki-tokens.d.ts +1 -0
- package/dist/wiki-tokens.js +46 -0
- package/dist/wiki.d.ts +103 -0
- package/dist/wiki.js +330 -0
- package/dist/workflow-cli.d.ts +2 -0
- package/dist/workflow-cli.js +258 -0
- package/dist/workflow-install.d.ts +36 -0
- package/dist/workflow-install.js +148 -0
- package/dist/workflow-knowledge.d.ts +16 -0
- package/dist/workflow-knowledge.js +24 -0
- package/dist/workflow-mcp.d.ts +2 -0
- package/dist/workflow-mcp.js +144 -0
- package/dist/workflow-names.d.ts +4 -0
- package/dist/workflow-names.js +18 -0
- package/dist/workflow-runtime.d.ts +622 -0
- package/dist/workflow-runtime.js +627 -0
- package/dist/workflow-skills.d.ts +48 -0
- package/dist/workflow-skills.js +141 -0
- package/package.json +76 -4
- package/skills/ew-odyssey/SKILL.md +237 -0
- package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
- package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
- package/skills/ew-odyssey/references/odyssey-base.md +278 -0
- package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
- package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
- package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
- package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
- package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
- package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
- package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
- package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
- package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
- package/skills/ew-odyssey/references/odyssey-review.md +251 -0
- package/skills/ew-odyssey/references/odyssey-security.md +249 -0
- package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
- package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
- package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
- package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
- package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
- package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
- package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
- package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
- package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
- package/skills/ew-orchestrate/SKILL.md +236 -0
- package/skills/ew-orchestrate/references/auto-policy.md +165 -0
- package/skills/ew-orchestrate/references/companion-route.md +52 -0
- package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
- package/skills/ew-orchestrate/references/goal.md +53 -0
- package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
- package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
- package/skills/ew-orchestrate/references/planning.md +137 -0
- package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
- package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
- package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
- package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
- package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
- package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
- package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
- package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
- package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
- package/skills/ew-skill-design/SKILL.md +28 -0
- package/skills/ew-skill-design/references/package-contract.md +28 -0
- package/skills/ew-skill-design/references/validation.md +7 -0
- package/skills/team-swarm/SKILL.md +231 -0
- package/skills/team-swarm/references/mcp-coordination.md +10 -0
- package/skills/team-swarm/roles/analyst/role.md +181 -0
- package/skills/team-swarm/roles/ant/role.md +149 -0
- package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
- package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
- package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
- package/skills/team-swarm/roles/coordinator/role.md +228 -0
- package/skills/team-swarm/roles/scorer/role.md +150 -0
- package/skills/team-swarm/scripts/aco.py +646 -0
- package/skills/team-swarm/scripts/pheromone.py +144 -0
- package/skills/team-swarm/scripts/scoring.py +111 -0
- package/skills/team-swarm/scripts/test_aco.py +606 -0
- package/skills/team-swarm/specs/ant-output-schema.md +127 -0
- package/skills/team-swarm/specs/convergence-criteria.md +108 -0
- package/skills/team-swarm/specs/pheromone-schema.md +125 -0
- package/skills/team-swarm/specs/swarm-config-template.json +71 -0
- package/skills/team-swarm/specs/swarm-protocol.md +123 -0
- package/skills/workflow-closeout/SKILL.md +10 -0
- package/skills/workflow-evolve/SKILL.md +79 -0
- package/skills/workflow-evolve/references/agy-gate.md +27 -0
- package/skills/workflow-evolve/references/auto-loop.md +20 -0
- package/skills/workflow-evolve/references/history-review.md +14 -0
- package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
- package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
- package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
- package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
- package/workflows/index.json +23 -0
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
> **Agent timeout**: `spawn_agent` 异步执行且无内置超时 — 除明确短任务外一律 `spawn_agent` 后立即 `wait_agent({ timeout_ms: 3600000 })`(上限 1 小时)阻塞等待,绝不依赖 30000 默认值;`timed_out: true` 且 Agent 未完成时再次 `wait_agent` 续等,不丢弃。批量场景使用 `spawn_agents_on_csv({ max_runtime_seconds: 3600, ... })`。
|
|
3
|
+
|
|
4
|
+
> **Plan tracking**: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 `update_plan({ explanation?, plan: [{ step, status }] })` 维护(整体提交步骤数组,status: `pending` | `in_progress` | `completed`),权威状态始终在 session 工件中;依赖/认领(addBlockedBy/owner)是工件字段,不是工具参数。
|
|
5
|
+
# Command: iterate
|
|
6
|
+
|
|
7
|
+
## Two Entry Points
|
|
8
|
+
|
|
9
|
+
| Entry | Trigger | Action |
|
|
10
|
+
|-------|---------|--------|
|
|
11
|
+
| **Iteration start** | Phase 3 invoked OR previous iteration converged=false | Run "Iteration Start" workflow |
|
|
12
|
+
| **Iteration end** | All ants of current iter reported via callback | Run "Iteration End" workflow |
|
|
13
|
+
|
|
14
|
+
## Iteration Start Workflow
|
|
15
|
+
|
|
16
|
+
### Step 1: Determine iteration number
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
k = session.iteration + 1
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
If `k > session.max_iterations`: force converge to Phase 4 (safety net).
|
|
23
|
+
|
|
24
|
+
### Step 2: Call aco.py select
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> select --iter <k>
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Parse stdout JSON. Expected:
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"status": "ok",
|
|
34
|
+
"iteration": <k>,
|
|
35
|
+
"n_assignments": <N>,
|
|
36
|
+
"assignments": [
|
|
37
|
+
{
|
|
38
|
+
"ant_id": "ANT-<k>-<i>",
|
|
39
|
+
"start_node": "<node>",
|
|
40
|
+
"edge_preferences": {"a::b": 0.4, ...},
|
|
41
|
+
"max_path_length": <int>,
|
|
42
|
+
"iteration": <k>
|
|
43
|
+
}, ...
|
|
44
|
+
]
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
On error -> log to issues.md, request_user_input (retry / abort).
|
|
49
|
+
|
|
50
|
+
For a Run, `select --iter <k>` persists `assignments/<k>.json` before dispatch. Re-run the same command after an interruption to recover the original IDs and start nodes. Use the roster and task mapping to reuse live jobs and completed artifacts. Create a worker only for an assignment that still needs one.
|
|
51
|
+
|
|
52
|
+
### Step 3: Create ant tasks
|
|
53
|
+
|
|
54
|
+
For each assignment:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
update_plan({
|
|
58
|
+
subject: "ANT-<k>-<i>: explore from <start_node>",
|
|
59
|
+
description: "Session: <session_path>\nAssignment: <assignment JSON>\nObjective: <config.ant_prompt.objective>"
|
|
60
|
+
})
|
|
61
|
+
update_plan({ taskId: <new>, owner: "ant" })
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Set the task ID to match `ANT-<k>-<i>` (or record mapping in `.msg/meta.json` if framework auto-assigns IDs).
|
|
65
|
+
|
|
66
|
+
### Step 4: Spawn N ant workers in parallel
|
|
67
|
+
|
|
68
|
+
For each assignment, spawn one team-worker:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
spawn_agent({ task_name: "ant_<k>_<i>", message: "Spawn ant <ANT-k-i>", fork_turns: "none", agent_type: "team_worker" })
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
All N spawns in a single message (parallel).
|
|
75
|
+
|
|
76
|
+
### Step 5: Update session state
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
session.iteration = <k> (mark "in progress")
|
|
80
|
+
session.active_workers = [<list of ant IDs>]
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Persist the iteration and assignment IDs in team-session.json.
|
|
84
|
+
|
|
85
|
+
### Step 6: STOP
|
|
86
|
+
|
|
87
|
+
Wait for ant callbacks. Each ant uses evolve team report for its assignment. When ALL N reported, callback handler invokes "Iteration End" workflow.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Iteration End Workflow
|
|
92
|
+
|
|
93
|
+
### Step 1: Verify completion
|
|
94
|
+
|
|
95
|
+
Check `ANT-<k>-*` task statuses. If any still in_progress: not yet complete, do nothing.
|
|
96
|
+
|
|
97
|
+
If all completed -> proceed.
|
|
98
|
+
|
|
99
|
+
### Step 2: (Conditional) Spawn scorer
|
|
100
|
+
|
|
101
|
+
If `config.scoring.mode == "llm"`:
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
spawn_agent({
|
|
105
|
+
subagent_type: "team-worker",
|
|
106
|
+
team_name: "swarm",
|
|
107
|
+
name: "scorer-<k>",
|
|
108
|
+
run_in_background: true,
|
|
109
|
+
prompt: `## Role Assignment
|
|
110
|
+
role: scorer
|
|
111
|
+
role_spec: <skill_root>/roles/scorer/role.md
|
|
112
|
+
session: <session_path>
|
|
113
|
+
session_id: <run-id>
|
|
114
|
+
run_dir: <exact run_dir from the birth packet or team-session.json.run.run_dir>
|
|
115
|
+
team_name: swarm
|
|
116
|
+
requirement: score iteration <k> ants
|
|
117
|
+
inner_loop: false
|
|
118
|
+
|
|
119
|
+
## Context
|
|
120
|
+
Iteration to score: <k>
|
|
121
|
+
Output file: {run_dir}/work/team/scores/iter-<k>-scores.json
|
|
122
|
+
Read all artifacts: {run_dir}/outputs/ant-<k>-*.json`
|
|
123
|
+
})
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
STOP and await scorer callback. On callback resume at Step 3.
|
|
127
|
+
|
|
128
|
+
The callback must identify `SCORE-<k>` and the same iteration. Check that the output covers all ant artifacts for this iteration before invoking `update`. Once the controller has committed the iteration, replay with the same scoring decision and inputs.
|
|
129
|
+
|
|
130
|
+
If `scoring.mode == "script"` or `"fallback"` -> proceed directly to Step 3.
|
|
131
|
+
|
|
132
|
+
### Step 3: Call aco.py update
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> update --iter <k>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Parse stdout JSON. Expected:
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"status": "ok",
|
|
142
|
+
"iteration": <k>,
|
|
143
|
+
"n_ants_processed": <N>,
|
|
144
|
+
"mean_score": <float>,
|
|
145
|
+
"best_score": <float>,
|
|
146
|
+
"delta": <float>,
|
|
147
|
+
"elite_updated": <bool>,
|
|
148
|
+
"hallucinations_flagged": [<ant_ids>],
|
|
149
|
+
"stats": {<pheromone stats>}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Step 4: Log iteration result
|
|
154
|
+
|
|
155
|
+
Save the phase summary in team-session.json.
|
|
156
|
+
|
|
157
|
+
If `hallucinations_flagged.length > N/2`: append warning to wisdom/issues.md (high-noise iteration).
|
|
158
|
+
|
|
159
|
+
### Step 5: Call aco.py converged
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> converged
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Parse:
|
|
166
|
+
```json
|
|
167
|
+
{ "converged": <bool>, "triggered_by": [...], "reason": "...", "metrics": {...} }
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Step 6: Branch on convergence
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
if converged:
|
|
174
|
+
update session: completed_iterations.push(k), status = "converging"
|
|
175
|
+
-> proceed to Phase 4 (converge.md)
|
|
176
|
+
else:
|
|
177
|
+
update session: completed_iterations.push(k), active_workers = []
|
|
178
|
+
-> re-enter "Iteration Start" workflow with k+1
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Step 7: Output progress to user
|
|
182
|
+
|
|
183
|
+
After each iteration:
|
|
184
|
+
```
|
|
185
|
+
[coordinator] Iteration <k>/<max> complete.
|
|
186
|
+
[coordinator] best=<best_score> mean=<mean_score> delta=<delta>
|
|
187
|
+
[coordinator] entropy=<entropy> hallucinations=<count>
|
|
188
|
+
[coordinator] Status: <converged | continuing to iter k+1>
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Edge Cases
|
|
194
|
+
|
|
195
|
+
| Condition | Handling |
|
|
196
|
+
|-----------|----------|
|
|
197
|
+
| Ant task failed | Mark task failed; if >50% failed in iter -> halt, request_user_input |
|
|
198
|
+
| Ant produced no artifact | Script's update will skip it; if all skipped -> error -> halt |
|
|
199
|
+
| `aco.py update` fails | Retry once; if persistent -> halt with error report |
|
|
200
|
+
| Scorer worker fails | Record the failure. For an intentional self-score fallback in a Run, use `update --iter <k> --allow-score-fallback` and record that choice for replay. |
|
|
201
|
+
| Iteration takes too long | After timeout (configurable), check the host job and Evolve assignment roster |
|
|
202
|
+
| User sends `feedback <text>` mid-iteration | Append to wisdom/learnings.md; apply at next iteration start (not mid-iter) |
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
---
|
|
2
|
+
role: coordinator
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
> **Plan tracking**: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 `update_plan({ explanation?, plan: [{ step, status }] })` 维护(整体提交步骤数组,status: `pending` | `in_progress` | `completed`),权威状态始终在 session 工件中;依赖/认领(addBlockedBy/owner)是工件字段,不是工具参数。
|
|
6
|
+
|
|
7
|
+
# Coordinator Role — team-swarm
|
|
8
|
+
|
|
9
|
+
## Identity
|
|
10
|
+
|
|
11
|
+
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
|
12
|
+
- **Responsibility**: Translate user intent into swarm-config -> drive K-iteration outer loop -> dispatch N ants per iteration -> consume script verdicts -> deliver final synthesis
|
|
13
|
+
|
|
14
|
+
## Boundaries
|
|
15
|
+
|
|
16
|
+
### MUST
|
|
17
|
+
- Generate `swarm-config.json` from user task description (Phase 1)
|
|
18
|
+
- Invoke `scripts/aco.py` for ALL numeric decisions (selection, update, convergence)
|
|
19
|
+
- Spawn ant workers with strict role-spec assignment + path hints from script
|
|
20
|
+
- After each iteration callback: call `aco.py update` -> `aco.py converged` -> decide loop/exit
|
|
21
|
+
- Persist session state in the Evolve assignment roster and Python controller checkpoints
|
|
22
|
+
- Trigger analyst for final synthesis when converged
|
|
23
|
+
|
|
24
|
+
### MUST NOT
|
|
25
|
+
- Make selection/update/convergence decisions on its own — these belong to the script
|
|
26
|
+
- Modify `pheromone/*.json`, `best.json`, or `trails/*.jsonl` directly — script owns these
|
|
27
|
+
- Skip the convergence check after each iteration
|
|
28
|
+
- Spawn more than `config.swarm.n_ants` ants per iteration
|
|
29
|
+
- Exceed `config.convergence.max_iterations` outer loops
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Message Types
|
|
34
|
+
|
|
35
|
+
| Type | Direction | Trigger |
|
|
36
|
+
|------|-----------|---------|
|
|
37
|
+
| state_update | outbound | Iteration start/end, session init |
|
|
38
|
+
| task_unblocked | outbound | Ant batch ready |
|
|
39
|
+
| ant_done | inbound | Individual ant completion (rolled up to batch check) |
|
|
40
|
+
| iteration_complete | inbound | All ants in batch reported |
|
|
41
|
+
| capability_gap | inbound | Ant requests config change |
|
|
42
|
+
| error | inbound | Worker / script failure |
|
|
43
|
+
|
|
44
|
+
## Command Execution Protocol
|
|
45
|
+
|
|
46
|
+
When coordinator needs to execute a phase command:
|
|
47
|
+
|
|
48
|
+
1. Read the command file: `roles/coordinator/commands/<command-name>.md`
|
|
49
|
+
2. Follow the workflow defined inline
|
|
50
|
+
3. Commands are inline execution guides — NOT separate agents
|
|
51
|
+
|
|
52
|
+
## Toolbox
|
|
53
|
+
|
|
54
|
+
| Tool | Type | Purpose |
|
|
55
|
+
|------|------|---------|
|
|
56
|
+
| [Initialization](commands/init-swarm.md) | Command | Phase 2: build swarm-config + call `aco.py init` |
|
|
57
|
+
| [Iteration](commands/iterate.md) | Command | Phase 3: single iteration loop body (select/spawn/update) |
|
|
58
|
+
| [Convergence](commands/converge.md) | Command | Phase 4: convergence handler + analyst spawn |
|
|
59
|
+
| `scripts/aco.py` | Script | All numeric decisions (Bash subprocess) |
|
|
60
|
+
| team-worker | Subagent | Worker spawning (ant, scorer, analyst) |
|
|
61
|
+
| update_plan / list_agents / wait_agent / update_plan | System | Task lifecycle |
|
|
62
|
+
| evolve team | Evolve runtime | Assignment and result receipts |
|
|
63
|
+
| send_message / request_user_input | System | Comms |
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Entry Router
|
|
68
|
+
|
|
69
|
+
| Detection | Condition | Handler |
|
|
70
|
+
|-----------|-----------|---------|
|
|
71
|
+
| Worker callback | Message contains `[ant]` / `[scorer]` / `[analyst]` | -> handleCallback |
|
|
72
|
+
| Status check | Args contain `check` or `status` | -> handleCheck |
|
|
73
|
+
| Manual resume | Args contain `resume` or `continue` | -> handleResume |
|
|
74
|
+
| Iteration complete | All ants of current iteration reported | -> Phase 3.5 (update + converged?) |
|
|
75
|
+
| Pipeline complete | aco.py converged returned true | -> Phase 4 |
|
|
76
|
+
| Interrupted session | Active session exists in `{run_dir}/work/team/` | -> Phase 0 |
|
|
77
|
+
| New session | None of above | -> Phase 1 |
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Phase 0: Session Resume Check
|
|
82
|
+
|
|
83
|
+
1. **Exact Run locator first**: when the birth packet supplies `run_id` / `run_dir`, inspect only `{run_dir}/work/team/team-session.json`. An exact `run_dir` contains at most one team session; do not scan sibling Runs and do not enter a multiple-candidate branch.
|
|
84
|
+
2. Reconcile the exact candidate through the runtime lifecycle adapter before resuming: canonical Run status, broker-backed live agents, non-terminal team tasks, and the ordered activity clock (message/task -> meta -> sidecar -> legacy filesystem fallback).
|
|
85
|
+
3. Resume only a verified matching `team-swarm` session whose canonical lifecycle is `active` or `paused`. Reconcile list_agents vs `session.iteration` vs `pheromone/current.json` before dispatching any worker.
|
|
86
|
+
4. **Locator-less legacy recovery**: enumerate and rank candidates through the runtime resume ranker, then show the ranked evidence with request_user_input. Never select candidate index 0 implicitly; ties, `stale_candidate`, `unknown`, or `inconsistent` health always require an explicit choice.
|
|
87
|
+
5. `stale_candidate` is derived health, never a lifecycle and never cleanup eligibility. An operator may explicitly resume an active/paused stale candidate after reviewing evidence, or request an audited transition to `abandoned`; TTL alone must not persist abandonment or delete state.
|
|
88
|
+
6. Abandonment and cleanup are separate confirmed operations. Abandon only after rechecking Run status, live agents, non-terminal tasks, and activity; cleanup requires a second confirmation and may remove only `{run_dir}/work/team`, never `run.json`, `outputs/`, artifacts, evidence, or Session metadata.
|
|
89
|
+
7. Reopen the saved assignment batch for this iteration. Match each task with its roster entry, callback and artifact. Wait for live workers and retain completed work. Retry only a missing or failed assignment. For LLM scoring, recover the scorer job and score file before updating. If `pheromone/updates/<k>.json` exists, use its `scoring` value for replay (`fallback` requires `--allow-score-fallback`). Continue with the controller's committed iteration.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Phase 1: Task Analysis + Config Generation
|
|
94
|
+
|
|
95
|
+
**Objective**: Translate user task into `swarm-config.json`.
|
|
96
|
+
|
|
97
|
+
**Workflow**:
|
|
98
|
+
|
|
99
|
+
1. Parse user task description (text-level only, no codebase exploration)
|
|
100
|
+
2. Clarify via request_user_input if ambiguous:
|
|
101
|
+
- What is the search space? (file glob, explicit node list, abstract decisions)
|
|
102
|
+
- What is the objective? (find best X, discover Y, optimize Z)
|
|
103
|
+
- How should results be scored? (test pass rate, lint, custom rule, LLM judge)
|
|
104
|
+
- Budget? (max iterations, max ants per iter, token budget)
|
|
105
|
+
3. Generate `swarm-config.json` (see template at `specs/swarm-config-template.json`):
|
|
106
|
+
- `swarm.n_ants` (default 5)
|
|
107
|
+
- `swarm.max_iterations` -> mirrored into `convergence.max_iterations`
|
|
108
|
+
- `aco.alpha/beta/rho/q` (defaults sane)
|
|
109
|
+
- `task_space.nodes` OR `task_space.auto_discover_from`
|
|
110
|
+
- `scoring.mode` ∈ {script, llm, fallback} based on user answer
|
|
111
|
+
- `ant_prompt.objective` — the actual goal injected into ant role-spec at spawn
|
|
112
|
+
4. Keep config in memory until the Run birth packet provides the exact `run_dir` (self-start Run allocation is the first action of Phase 2). Never write into a guessed Run directory.
|
|
113
|
+
|
|
114
|
+
**CRITICAL**: Phase 1 does NOT call `aco.py`. It only produces the config.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Phase 2: Init Swarm + Session Setup
|
|
119
|
+
|
|
120
|
+
Delegate to `@commands/init-swarm.md`:
|
|
121
|
+
|
|
122
|
+
1. Resolve or self-start the exact Session/Run as described in `init-swarm.md` before any Run-scoped file write.
|
|
123
|
+
2. Create session folder structure:
|
|
124
|
+
```
|
|
125
|
+
{run_dir}/work/team/
|
|
126
|
+
├── swarm-config.json (from Phase 1)
|
|
127
|
+
├── pheromone/, trails/, scores/, artifacts/, wisdom/
|
|
128
|
+
├── .msg/
|
|
129
|
+
└── role-binding.json (paths to role.md files)
|
|
130
|
+
```
|
|
131
|
+
3. TeamCreate with team_name = `swarm`
|
|
132
|
+
4. Bash: `python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> init`
|
|
133
|
+
5. Parse stdout JSON: capture `n_nodes`, `n_edges`, `pheromone_path`
|
|
134
|
+
6. Initialize team-session.json with `iteration: 0`, `status: "active"`
|
|
135
|
+
7. Record the config summary in team-session.json
|
|
136
|
+
|
|
137
|
+
### Run Lifecycle Integration
|
|
138
|
+
|
|
139
|
+
Before creating the session folder or writing `swarm-config.json`:
|
|
140
|
+
|
|
141
|
+
1. **Resolve Run** (birth-packet first): if the dispatch context already carries `run_id` / `run_dir` (injected by an orchestrator), retain them in memory and persist them at init-swarm Step 7 after creating the parent directory; skip self-start — a second allocation mints a duplicate Run. Otherwise execute this receipt-chained self-start recipe; every revision comes from the immediately preceding receipt and `--actor` carries the authorized identity (`--participant` defaults to it; the CLI derives a stable request ID per distinct invocation):
|
|
142
|
+
```bash
|
|
143
|
+
evolve session open "<task summary>" --id <slug> --actor {actor_id} --json
|
|
144
|
+
evolve session chain insert --session {session_id} --step-id {step_id} --command team-swarm --arg "<task summary>" --actor {actor_id} --expected-orchestration-revision {open_orchestration_revision} --json
|
|
145
|
+
evolve run next --session {session_id} --actor {actor_id} --expected-orchestration-revision {insert_orchestration_revision} --json
|
|
146
|
+
```
|
|
147
|
+
- Slug format: `YYYYMMDD-team-swarm-<topic>` (ASCII, ≤64 chars)
|
|
148
|
+
- Store returned canonical `session_id`, `run_id`, and `run_dir` in `team-session.json`:
|
|
149
|
+
```json
|
|
150
|
+
"run": { "session_id": "<canonical-session-id>", "run_id": "<id>", "run_dir": "<path>" }
|
|
151
|
+
```
|
|
152
|
+
2. **Resume**: Resolve exact `session_id` + `run_id` + `run_dir` from the birth packet or `team-session.json.run`; never infer a Run ID from output files. Read `evolve run check <run_id> --session <session_id> --json` for status/output blockers, then `evolve run brief <run_id> --session <session_id> --json` for the structured `continuation`. If sealed, follow the brief's continuation; allocate another Run only through a freshly fenced `run next` when it reports a pending step. If the locator is absent or inconsistent, fail closed rather than minting a duplicate Run.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Phase 3: Iteration Loop
|
|
157
|
+
|
|
158
|
+
**Objective**: Run iteration k = 1..K. Each iteration = spawn-and-stop + callback resume.
|
|
159
|
+
|
|
160
|
+
**Per-iteration workflow** (delegate to `@commands/iterate.md`):
|
|
161
|
+
|
|
162
|
+
1. Increment iteration counter: k = session.iteration + 1
|
|
163
|
+
2. Bash: `python aco.py --session {run_dir}/work/team select --iter <k>`
|
|
164
|
+
-> returns `{assignments: [{ant_id, start_node, edge_preferences, max_path_length}, ...]}`
|
|
165
|
+
3. For each assignment:
|
|
166
|
+
- update_plan `ANT-<k>-<i>` with description including session path + assignment
|
|
167
|
+
- update_plan set owner = `ant`
|
|
168
|
+
4. Spawn N × team-worker(ant) in background, each with assignment injected into prompt:
|
|
169
|
+
```
|
|
170
|
+
role: ant
|
|
171
|
+
role_spec: <skill_root>/roles/ant/role.md
|
|
172
|
+
session: {run_dir}/work/team
|
|
173
|
+
session_id: <run-id>
|
|
174
|
+
run_dir: <exact run_dir from the birth packet or team-session.json.run.run_dir>
|
|
175
|
+
team_name: swarm
|
|
176
|
+
requirement: <ant_prompt.objective> | Assignment: <full assignment JSON>
|
|
177
|
+
inner_loop: false
|
|
178
|
+
```
|
|
179
|
+
5. STOP
|
|
180
|
+
|
|
181
|
+
**On all-ants-complete callback** (Phase 3.5):
|
|
182
|
+
|
|
183
|
+
1. Verify all `ANT-<k>-*` tasks have status = completed
|
|
184
|
+
2. (Optional, if `scoring.mode == "llm"`) Spawn scorer worker for iteration k, await callback
|
|
185
|
+
3. Bash: `python aco.py --session {run_dir}/work/team --run-dir <run_dir> update --iter <k>`
|
|
186
|
+
-> parse `{best_score, mean_score, delta, hallucinations_flagged, ...}`
|
|
187
|
+
4. Bash: `python aco.py --session {run_dir}/work/team converged`
|
|
188
|
+
-> parse `{converged, triggered_by, reason, metrics}`
|
|
189
|
+
5. Update session.iteration = k, log state_update
|
|
190
|
+
6. Branch:
|
|
191
|
+
- `converged == true` -> Phase 4
|
|
192
|
+
- `converged == false` -> loop back to step 1 (iteration k+1)
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Phase 4: Converge + Synthesize
|
|
197
|
+
|
|
198
|
+
Delegate to `@commands/converge.md`:
|
|
199
|
+
|
|
200
|
+
1. Bash: `python aco.py --session {run_dir}/work/team --run-dir <run_dir> report` -> capture best + top_k + curve
|
|
201
|
+
2. Spawn analyst worker:
|
|
202
|
+
```
|
|
203
|
+
role: analyst
|
|
204
|
+
role_spec: <skill_root>/roles/analyst/role.md
|
|
205
|
+
requirement: synthesize swarm results | session: {run_dir}/work/team
|
|
206
|
+
```
|
|
207
|
+
3. Await analyst callback -> `best-solution.md` written
|
|
208
|
+
4. Build completion report:
|
|
209
|
+
- Total iterations, total ants
|
|
210
|
+
- Best score + best path + best solution summary
|
|
211
|
+
- Convergence reason
|
|
212
|
+
- Top 5 trails table
|
|
213
|
+
5. Execute completion action (interactive request_user_input: Archive / Keep / Export)
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Error Handling
|
|
218
|
+
|
|
219
|
+
| Error | Resolution |
|
|
220
|
+
|-------|------------|
|
|
221
|
+
| `aco.py` exits non-zero | Capture stderr, log to issues.md, retry once with same args |
|
|
222
|
+
| Ant produces invalid JSON | Script's `update` skips that artifact + logs warning; coordinator continues |
|
|
223
|
+
| All ants in iteration fail | Halt loop, request_user_input (retry / abort) |
|
|
224
|
+
| Convergence flag never trips | max_iterations safety net always triggers |
|
|
225
|
+
| Script not found | Resolve `<skill_root>/scripts/aco.py`; if missing, fail with install hint |
|
|
226
|
+
| Hallucination cluster (>50% ants flagged) | Pause, request_user_input (continue / refine config) |
|
|
227
|
+
| Task description too vague | request_user_input before Phase 1 config generation |
|
|
228
|
+
| Session corruption | Phase 0 reconciliation; if irrecoverable, archive and start fresh |
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
role: scorer
|
|
3
|
+
prefix: SCORE
|
|
4
|
+
inner_loop: false
|
|
5
|
+
output_tag: "[scorer]"
|
|
6
|
+
message_types:
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Scorer Role — Phase 2-4
|
|
10
|
+
|
|
11
|
+
## Boundaries
|
|
12
|
+
|
|
13
|
+
### MUST
|
|
14
|
+
- Read ALL `ant-<iter>-*.json` artifacts for the target iteration
|
|
15
|
+
- Apply a uniform scoring rubric across the batch (consistency over absolute correctness)
|
|
16
|
+
- Produce `{run_dir}/work/team/scores/iter-<k>-scores.json` matching the schema in specs/ant-output-schema.md
|
|
17
|
+
- Provide a one-line `rationale` per ant
|
|
18
|
+
- Use a different model from the ant if possible (configured via evolve delegate) to reduce same-source bias
|
|
19
|
+
|
|
20
|
+
### MUST NOT
|
|
21
|
+
- Modify ant artifacts
|
|
22
|
+
- Score ants outside the target iteration
|
|
23
|
+
- Use self_score as a starting reference (introduces anchoring bias) — score blind first, compare second
|
|
24
|
+
- Assign scores without grounding in evidence claimed by the ant
|
|
25
|
+
|
|
26
|
+
## Phase 2: Context Loading
|
|
27
|
+
|
|
28
|
+
| Input | Source | Required |
|
|
29
|
+
|-------|--------|----------|
|
|
30
|
+
| Target iteration | Task description (`Iteration to score: <k>`) | Yes |
|
|
31
|
+
| Objective | `{run_dir}/work/team/swarm-config.json#ant_prompt.objective` | Yes |
|
|
32
|
+
| Scoring rubric | `{run_dir}/work/team/swarm-config.json#scoring.rubric` (if defined) | Optional |
|
|
33
|
+
| Ant artifacts | `{run_dir}/outputs/ant-<k>-*.json` | Yes |
|
|
34
|
+
| Task space | `{run_dir}/work/team/task-space.json` (for context) | Optional |
|
|
35
|
+
|
|
36
|
+
Workflow:
|
|
37
|
+
1. Extract `k` from task description
|
|
38
|
+
2. `Glob("{run_dir}/outputs/ant-<k>-*.json")` -> N artifacts
|
|
39
|
+
3. Read all N artifacts in parallel
|
|
40
|
+
4. Read swarm-config.json -> capture objective + rubric
|
|
41
|
+
|
|
42
|
+
## Phase 3: Blind Batch Scoring
|
|
43
|
+
|
|
44
|
+
### 3.1 Build rubric
|
|
45
|
+
|
|
46
|
+
If `config.scoring.rubric` provided, use verbatim. Otherwise default rubric:
|
|
47
|
+
|
|
48
|
+
| Dimension | Weight |
|
|
49
|
+
|-----------|--------|
|
|
50
|
+
| Path relevance to objective | 0.35 |
|
|
51
|
+
| Evidence strength (count + specificity) | 0.30 |
|
|
52
|
+
| Candidate solution quality | 0.25 |
|
|
53
|
+
| Path coherence (decisions follow logical chain) | 0.10 |
|
|
54
|
+
|
|
55
|
+
### 3.2 Score each artifact
|
|
56
|
+
|
|
57
|
+
For each ant artifact (process them blind to self_score order):
|
|
58
|
+
|
|
59
|
+
1. Extract: `path`, `path_decisions[].rationale`, `evidence`, `candidate_solution`
|
|
60
|
+
2. **Do NOT read** `self_score` / `self_confidence` until after scoring
|
|
61
|
+
3. Apply rubric:
|
|
62
|
+
- Each dimension -> 0.0..1.0
|
|
63
|
+
- Weighted sum -> `verified_score`
|
|
64
|
+
4. One-line rationale: which dimensions drove the score
|
|
65
|
+
5. Append to scores dict
|
|
66
|
+
|
|
67
|
+
### 3.3 Calibrate across batch
|
|
68
|
+
|
|
69
|
+
After all individual scores:
|
|
70
|
+
- Compute mean + std of verified_scores
|
|
71
|
+
- If all scores within ±0.05 (compressed range) -> spread them apart by re-ranking with finer rubric application
|
|
72
|
+
- If exactly one is 1.0 and rest are < 0.3 -> double-check the outlier
|
|
73
|
+
|
|
74
|
+
### 3.4 Compose scores file
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"iteration": <k>,
|
|
79
|
+
"scorer_type": "llm",
|
|
80
|
+
"rubric_used": "default | custom_from_config",
|
|
81
|
+
"scores": {
|
|
82
|
+
"ANT-<k>-1": { "verified_score": <float>, "rationale": "<one-line>" },
|
|
83
|
+
"ANT-<k>-2": { "verified_score": <float>, "rationale": "<one-line>" },
|
|
84
|
+
...
|
|
85
|
+
},
|
|
86
|
+
"calibration": {
|
|
87
|
+
"mean": <float>,
|
|
88
|
+
"std": <float>,
|
|
89
|
+
"min": <float>,
|
|
90
|
+
"max": <float>
|
|
91
|
+
},
|
|
92
|
+
"computed_at": "<iso8601>"
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Phase 4: Verify + Publish
|
|
97
|
+
|
|
98
|
+
### Behavioral Traits
|
|
99
|
+
|
|
100
|
+
#### Accuracy
|
|
101
|
+
- Every `verified_score` in [0.0, 1.0]
|
|
102
|
+
- Every `ANT-<k>-i` in the input set has a score entry
|
|
103
|
+
- `rationale` references at least one dimension of the rubric
|
|
104
|
+
|
|
105
|
+
#### Feedback Contract
|
|
106
|
+
| Field | Required | Content |
|
|
107
|
+
|-------|----------|---------|
|
|
108
|
+
| artifacts_written | Always | `{run_dir}/work/team/scores/iter-<k>-scores.json` |
|
|
109
|
+
| n_ants_scored | Always | int |
|
|
110
|
+
| verification_method | Always | "blind_then_calibrated + range_check" |
|
|
111
|
+
|
|
112
|
+
#### Quality Gate
|
|
113
|
+
- All N ant artifacts must have a score entry — partial scoring is NOT acceptable
|
|
114
|
+
- If a single artifact is unparseable -> assign verified_score = 0.0 with rationale "artifact_invalid", continue
|
|
115
|
+
- Validation fails -> retry Phase 3 once
|
|
116
|
+
|
|
117
|
+
### Verification Steps
|
|
118
|
+
|
|
119
|
+
1. Re-read the scores file via Read
|
|
120
|
+
2. Parse JSON, validate schema
|
|
121
|
+
3. Confirm `len(scores) == n_ants_in_iteration`
|
|
122
|
+
4. Confirm score range
|
|
123
|
+
5. Write hallucination delta to wisdom for coordinator visibility:
|
|
124
|
+
- For each ant, compute `delta = |self_score - verified_score|`
|
|
125
|
+
- If `delta > 0.4` for >50% of ants in this iter -> append warning to `{run_dir}/work/team/wisdom/issues.md`
|
|
126
|
+
|
|
127
|
+
### State Update
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"task_id": "SCORE-<k>",
|
|
132
|
+
"role": "scorer",
|
|
133
|
+
"status": "completed",
|
|
134
|
+
"iteration": <k>,
|
|
135
|
+
"n_ants_scored": <N>,
|
|
136
|
+
"mean_verified_score": <float>,
|
|
137
|
+
"artifact_path": "{run_dir}/work/team/scores/iter-<k>-scores.json",
|
|
138
|
+
"verification": "blind_scored + schema_validated"
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Error Handling
|
|
143
|
+
|
|
144
|
+
| Scenario | Resolution |
|
|
145
|
+
|----------|------------|
|
|
146
|
+
| No artifacts found for iteration | Report error - coordinator either misrouted or ants all failed |
|
|
147
|
+
| Artifact parse fails | Score = 0.0, rationale = "artifact_invalid", continue |
|
|
148
|
+
| Rubric ambiguous for a path | Default to 0.5 with rationale "rubric_uncertain", lower confidence in calibration |
|
|
149
|
+
| All scores identical | Force differentiation via secondary tiebreaker (path length, evidence count) |
|
|
150
|
+
| Scores file write fails | Retry; on second failure report blocker |
|