@chllming/wave-orchestration 0.5.3 → 0.6.0
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/CHANGELOG.md +53 -3
- package/README.md +81 -506
- package/docs/README.md +53 -0
- package/docs/agents/wave-cont-eval-role.md +36 -0
- package/docs/agents/{wave-evaluator-role.md → wave-cont-qa-role.md} +14 -11
- package/docs/agents/wave-documentation-role.md +1 -1
- package/docs/agents/wave-infra-role.md +1 -1
- package/docs/agents/wave-integration-role.md +3 -3
- package/docs/agents/wave-launcher-role.md +4 -3
- package/docs/agents/wave-security-role.md +40 -0
- package/docs/concepts/context7-vs-skills.md +94 -0
- package/docs/concepts/operating-modes.md +91 -0
- package/docs/concepts/runtime-agnostic-orchestration.md +95 -0
- package/docs/concepts/what-is-a-wave.md +183 -0
- package/docs/evals/README.md +166 -0
- package/docs/evals/benchmark-catalog.json +663 -0
- package/docs/guides/author-and-run-waves.md +135 -0
- package/docs/guides/planner.md +118 -0
- package/docs/guides/terminal-surfaces.md +82 -0
- package/docs/image.png +0 -0
- package/docs/plans/component-cutover-matrix.json +1 -1
- package/docs/plans/component-cutover-matrix.md +1 -1
- package/docs/plans/context7-wave-orchestrator.md +2 -0
- package/docs/plans/current-state.md +29 -1
- package/docs/plans/examples/wave-example-live-proof.md +435 -0
- package/docs/plans/master-plan.md +3 -3
- package/docs/plans/migration.md +46 -3
- package/docs/plans/wave-orchestrator.md +71 -8
- package/docs/plans/waves/wave-0.md +4 -4
- package/docs/reference/live-proof-waves.md +177 -0
- package/docs/reference/migration-0.2-to-0.5.md +26 -19
- package/docs/reference/npmjs-trusted-publishing.md +6 -5
- package/docs/reference/runtime-config/README.md +29 -0
- package/docs/reference/sample-waves.md +87 -0
- package/docs/reference/skills.md +224 -0
- package/docs/research/agent-context-sources.md +130 -11
- package/docs/research/coordination-failure-review.md +266 -0
- package/docs/roadmap.md +164 -564
- package/package.json +3 -2
- package/releases/manifest.json +37 -2
- package/scripts/research/agent-context-archive.mjs +83 -1
- package/scripts/research/manifests/agent-context-expanded-2026-03-22.mjs +811 -0
- package/scripts/wave-orchestrator/adhoc.mjs +1331 -0
- package/scripts/wave-orchestrator/agent-state.mjs +358 -6
- package/scripts/wave-orchestrator/artifact-schemas.mjs +173 -0
- package/scripts/wave-orchestrator/clarification-triage.mjs +10 -3
- package/scripts/wave-orchestrator/config.mjs +65 -12
- package/scripts/wave-orchestrator/context7.mjs +11 -0
- package/scripts/wave-orchestrator/coord-cli.mjs +51 -19
- package/scripts/wave-orchestrator/coordination-store.mjs +26 -4
- package/scripts/wave-orchestrator/coordination.mjs +99 -9
- package/scripts/wave-orchestrator/dashboard-state.mjs +20 -8
- package/scripts/wave-orchestrator/dep-cli.mjs +5 -2
- package/scripts/wave-orchestrator/docs-queue.mjs +8 -2
- package/scripts/wave-orchestrator/evals.mjs +451 -0
- package/scripts/wave-orchestrator/executors.mjs +24 -11
- package/scripts/wave-orchestrator/feedback.mjs +15 -1
- package/scripts/wave-orchestrator/install.mjs +69 -7
- package/scripts/wave-orchestrator/launcher-closure.mjs +281 -0
- package/scripts/wave-orchestrator/launcher-runtime.mjs +334 -0
- package/scripts/wave-orchestrator/launcher.mjs +778 -577
- package/scripts/wave-orchestrator/ledger.mjs +123 -20
- package/scripts/wave-orchestrator/local-executor.mjs +99 -12
- package/scripts/wave-orchestrator/planner.mjs +1463 -0
- package/scripts/wave-orchestrator/project-profile.mjs +190 -0
- package/scripts/wave-orchestrator/replay.mjs +6 -3
- package/scripts/wave-orchestrator/role-helpers.mjs +84 -0
- package/scripts/wave-orchestrator/shared.mjs +77 -11
- package/scripts/wave-orchestrator/skills.mjs +979 -0
- package/scripts/wave-orchestrator/terminals.mjs +16 -0
- package/scripts/wave-orchestrator/traces.mjs +73 -27
- package/scripts/wave-orchestrator/wave-files.mjs +1224 -163
- package/scripts/wave.mjs +20 -0
- package/skills/README.md +202 -0
- package/skills/provider-aws/SKILL.md +117 -0
- package/skills/provider-aws/adapters/claude.md +1 -0
- package/skills/provider-aws/adapters/codex.md +1 -0
- package/skills/provider-aws/references/service-verification.md +39 -0
- package/skills/provider-aws/skill.json +54 -0
- package/skills/provider-custom-deploy/SKILL.md +64 -0
- package/skills/provider-custom-deploy/skill.json +50 -0
- package/skills/provider-docker-compose/SKILL.md +96 -0
- package/skills/provider-docker-compose/adapters/local.md +1 -0
- package/skills/provider-docker-compose/skill.json +53 -0
- package/skills/provider-github-release/SKILL.md +121 -0
- package/skills/provider-github-release/adapters/claude.md +1 -0
- package/skills/provider-github-release/adapters/codex.md +1 -0
- package/skills/provider-github-release/skill.json +55 -0
- package/skills/provider-kubernetes/SKILL.md +143 -0
- package/skills/provider-kubernetes/adapters/claude.md +1 -0
- package/skills/provider-kubernetes/adapters/codex.md +1 -0
- package/skills/provider-kubernetes/references/kubectl-patterns.md +58 -0
- package/skills/provider-kubernetes/skill.json +52 -0
- package/skills/provider-railway/SKILL.md +123 -0
- package/skills/provider-railway/adapters/claude.md +1 -0
- package/skills/provider-railway/adapters/codex.md +1 -0
- package/skills/provider-railway/adapters/local.md +1 -0
- package/skills/provider-railway/adapters/opencode.md +1 -0
- package/skills/provider-railway/references/verification-commands.md +39 -0
- package/skills/provider-railway/skill.json +71 -0
- package/skills/provider-ssh-manual/SKILL.md +97 -0
- package/skills/provider-ssh-manual/skill.json +54 -0
- package/skills/repo-coding-rules/SKILL.md +91 -0
- package/skills/repo-coding-rules/skill.json +34 -0
- package/skills/role-cont-eval/SKILL.md +90 -0
- package/skills/role-cont-eval/adapters/codex.md +1 -0
- package/skills/role-cont-eval/skill.json +36 -0
- package/skills/role-cont-qa/SKILL.md +93 -0
- package/skills/role-cont-qa/adapters/claude.md +1 -0
- package/skills/role-cont-qa/skill.json +36 -0
- package/skills/role-deploy/SKILL.md +96 -0
- package/skills/role-deploy/skill.json +36 -0
- package/skills/role-documentation/SKILL.md +72 -0
- package/skills/role-documentation/skill.json +36 -0
- package/skills/role-implementation/SKILL.md +68 -0
- package/skills/role-implementation/skill.json +36 -0
- package/skills/role-infra/SKILL.md +80 -0
- package/skills/role-infra/skill.json +36 -0
- package/skills/role-integration/SKILL.md +84 -0
- package/skills/role-integration/skill.json +36 -0
- package/skills/role-research/SKILL.md +64 -0
- package/skills/role-research/skill.json +36 -0
- package/skills/role-security/SKILL.md +60 -0
- package/skills/role-security/skill.json +36 -0
- package/skills/runtime-claude/SKILL.md +65 -0
- package/skills/runtime-claude/skill.json +36 -0
- package/skills/runtime-codex/SKILL.md +57 -0
- package/skills/runtime-codex/skill.json +36 -0
- package/skills/runtime-local/SKILL.md +44 -0
- package/skills/runtime-local/skill.json +36 -0
- package/skills/runtime-opencode/SKILL.md +57 -0
- package/skills/runtime-opencode/skill.json +36 -0
- package/skills/wave-core/SKILL.md +114 -0
- package/skills/wave-core/references/marker-syntax.md +62 -0
- package/skills/wave-core/skill.json +35 -0
- package/wave.config.json +61 -5
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Sample Waves"
|
|
3
|
+
summary: "A showcase-first sample wave that demonstrates the current 0.6.0 Wave surface."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Sample Waves
|
|
7
|
+
|
|
8
|
+
This guide points to one showcase-first sample wave that demonstrates the current `0.6.0` authored Wave surface.
|
|
9
|
+
|
|
10
|
+
The example is intentionally denser than a typical production wave. Its job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready file.
|
|
11
|
+
|
|
12
|
+
## Canonical Example
|
|
13
|
+
|
|
14
|
+
- [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
|
|
15
|
+
Shows the combined `0.6.0` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
|
|
16
|
+
|
|
17
|
+
## What This Example Teaches
|
|
18
|
+
|
|
19
|
+
- the standard closure-role structure with `A0`, `E0`, `A8`, and `A9`
|
|
20
|
+
- wave-level `## Eval targets`
|
|
21
|
+
- delegated versus pinned benchmark selection
|
|
22
|
+
- coordination benchmark families from `docs/evals/benchmark-catalog.json`
|
|
23
|
+
- richer executor blocks, runtime budgets, and retry policy
|
|
24
|
+
- cross-runtime `### Skills`
|
|
25
|
+
- helper-routing hints via `### Capabilities`
|
|
26
|
+
- `### Deliverables`
|
|
27
|
+
- `### Exit contract`
|
|
28
|
+
- proof-first `### Proof artifacts`
|
|
29
|
+
- sticky retry for proof-bearing owners
|
|
30
|
+
- deploy environments and provider-skill examples
|
|
31
|
+
- infra and deploy-verifier specialist slices
|
|
32
|
+
|
|
33
|
+
## Feature Coverage Map
|
|
34
|
+
|
|
35
|
+
This sample covers the main surfaces added or hardened for `0.6.0`:
|
|
36
|
+
|
|
37
|
+
- planner-era authored wave structure
|
|
38
|
+
- cross-runtime `### Skills`
|
|
39
|
+
- richer `### Executor` blocks and runtime budgets
|
|
40
|
+
- `cont-EVAL` plus `## Eval targets`
|
|
41
|
+
- delegated and pinned benchmark selection
|
|
42
|
+
- coordination benchmark families from `docs/evals/benchmark-catalog.json`
|
|
43
|
+
- helper-routing hints through `### Capabilities`
|
|
44
|
+
- `### Deliverables`
|
|
45
|
+
- `### Proof artifacts`
|
|
46
|
+
- sticky retry for proof-bearing owners
|
|
47
|
+
- proof-first live-wave prompts
|
|
48
|
+
- deploy environments and deploy-kind-aware skills
|
|
49
|
+
- integration, documentation, and cont-QA closure-role structure
|
|
50
|
+
|
|
51
|
+
## When To Copy Literally Vs Adapt
|
|
52
|
+
|
|
53
|
+
Copy more literally when:
|
|
54
|
+
|
|
55
|
+
- you need the section layout
|
|
56
|
+
- you want concrete wording for delegated versus pinned benchmark targets
|
|
57
|
+
- you want a proof-first owner example with local artifact bundles and sticky retry
|
|
58
|
+
|
|
59
|
+
Adapt more aggressively when:
|
|
60
|
+
|
|
61
|
+
- your repo has different role ids or role prompts
|
|
62
|
+
- your component promotions and maturity levels differ
|
|
63
|
+
- your runtime policy uses different executor profiles or runtime mix targets
|
|
64
|
+
- your deploy environments or provider skills differ from the example
|
|
65
|
+
|
|
66
|
+
## How This Example Maps To Other Docs
|
|
67
|
+
|
|
68
|
+
- Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use this sample to see how a human would enrich the generated draft.
|
|
69
|
+
- Use [docs/evals/README.md](../evals/README.md) with this sample when you need to see delegated and pinned benchmark targets in a real wave.
|
|
70
|
+
- Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with this sample when you need proof-first authoring for `pilot-live` and above.
|
|
71
|
+
- Use [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) for the operational runbook that explains how the launcher interprets these sections.
|
|
72
|
+
|
|
73
|
+
## Suggested Reading Order
|
|
74
|
+
|
|
75
|
+
1. Start with [Full modern sample wave](../plans/examples/wave-example-live-proof.md).
|
|
76
|
+
2. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
|
|
77
|
+
3. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
|
|
78
|
+
|
|
79
|
+
## Why This Example Lives In `docs/plans/examples/`
|
|
80
|
+
|
|
81
|
+
The example lives outside `docs/plans/waves/` on purpose.
|
|
82
|
+
|
|
83
|
+
That keeps it:
|
|
84
|
+
|
|
85
|
+
- easy to browse as teaching material
|
|
86
|
+
- clearly separate from the repo's real launcher-facing wave sequence
|
|
87
|
+
- safe to evolve as reference material without implying that it is part of the current lane's actual plan history
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# Skills Reference
|
|
2
|
+
|
|
3
|
+
Skills are repo-owned reusable instruction bundles. Wave resolves them by config layer, then filters them through each bundle's activation metadata before projecting them into the selected runtime.
|
|
4
|
+
|
|
5
|
+
## Canonical Bundle Layout
|
|
6
|
+
|
|
7
|
+
Each bundle lives under `skills/<skill-id>/` and requires:
|
|
8
|
+
|
|
9
|
+
- `skill.json`
|
|
10
|
+
- `SKILL.md`
|
|
11
|
+
|
|
12
|
+
Optional files:
|
|
13
|
+
|
|
14
|
+
- `adapters/codex.md`
|
|
15
|
+
- `adapters/claude.md`
|
|
16
|
+
- `adapters/opencode.md`
|
|
17
|
+
- `adapters/local.md`
|
|
18
|
+
- `references/**` for on-demand reference material
|
|
19
|
+
|
|
20
|
+
Minimal example:
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
skills/provider-railway/
|
|
24
|
+
skill.json
|
|
25
|
+
SKILL.md
|
|
26
|
+
adapters/
|
|
27
|
+
codex.md
|
|
28
|
+
claude.md
|
|
29
|
+
opencode.md
|
|
30
|
+
references/
|
|
31
|
+
verification-commands.md
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## `skill.json`
|
|
35
|
+
|
|
36
|
+
Required fields:
|
|
37
|
+
|
|
38
|
+
- `id`
|
|
39
|
+
- `title`
|
|
40
|
+
- `description`
|
|
41
|
+
- `activation.when`
|
|
42
|
+
|
|
43
|
+
Optional fields:
|
|
44
|
+
|
|
45
|
+
- `version`
|
|
46
|
+
- `tags`
|
|
47
|
+
- `activation.roles`
|
|
48
|
+
- `activation.runtimes`
|
|
49
|
+
- `activation.deployKinds`
|
|
50
|
+
- `termination.when`
|
|
51
|
+
- `permissions.network`
|
|
52
|
+
- `permissions.shell`
|
|
53
|
+
- `permissions.mcpServers`
|
|
54
|
+
- `trust.tier`
|
|
55
|
+
- `evalCases[]`
|
|
56
|
+
|
|
57
|
+
Example:
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"id": "provider-railway",
|
|
62
|
+
"title": "Railway",
|
|
63
|
+
"description": "Provider-aware Railway verification and rollback guidance.",
|
|
64
|
+
"activation": {
|
|
65
|
+
"when": "Attach when the wave deploy surface is Railway and the agent is acting in deploy, infra, integration, or cont-qa scope.",
|
|
66
|
+
"roles": ["deploy", "infra", "integration", "cont-qa"],
|
|
67
|
+
"runtimes": [],
|
|
68
|
+
"deployKinds": ["railway-cli", "railway-mcp"]
|
|
69
|
+
},
|
|
70
|
+
"termination": "Stop when Railway evidence is recorded or the blocking surface is explicit.",
|
|
71
|
+
"permissions": {
|
|
72
|
+
"network": ["railway.app"],
|
|
73
|
+
"shell": ["railway"],
|
|
74
|
+
"mcpServers": ["railway"]
|
|
75
|
+
},
|
|
76
|
+
"trust": {
|
|
77
|
+
"tier": "repo-owned"
|
|
78
|
+
},
|
|
79
|
+
"evalCases": [
|
|
80
|
+
{
|
|
81
|
+
"id": "deploy-railway-cli",
|
|
82
|
+
"role": "deploy",
|
|
83
|
+
"runtime": "opencode",
|
|
84
|
+
"deployKind": "railway-cli",
|
|
85
|
+
"expectActive": true
|
|
86
|
+
}
|
|
87
|
+
]
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The bundle directory name and manifest `id` must match the normalized skill id.
|
|
92
|
+
|
|
93
|
+
## `SKILL.md`
|
|
94
|
+
|
|
95
|
+
`SKILL.md` is the canonical instruction body. Keep it reusable and procedural:
|
|
96
|
+
|
|
97
|
+
- reusable across many waves
|
|
98
|
+
- free of assignment-specific details that belong in the wave prompt
|
|
99
|
+
- compact enough that long catalogs and command references can move into `references/`
|
|
100
|
+
|
|
101
|
+
## `wave.config.json` Surface
|
|
102
|
+
|
|
103
|
+
Top-level and lane-local skill attachment use the same shape:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"skills": {
|
|
108
|
+
"dir": "skills",
|
|
109
|
+
"base": ["wave-core", "repo-coding-rules"],
|
|
110
|
+
"byRole": {
|
|
111
|
+
"deploy": ["role-deploy"]
|
|
112
|
+
},
|
|
113
|
+
"byRuntime": {
|
|
114
|
+
"claude": ["runtime-claude"]
|
|
115
|
+
},
|
|
116
|
+
"byDeployKind": {
|
|
117
|
+
"railway-mcp": ["provider-railway"]
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
|
|
124
|
+
|
|
125
|
+
## Resolution Order
|
|
126
|
+
|
|
127
|
+
Resolved skills are gathered in this order:
|
|
128
|
+
|
|
129
|
+
1. global `skills.base`
|
|
130
|
+
2. lane `skills.base`
|
|
131
|
+
3. global `skills.byRole[resolvedRole]`
|
|
132
|
+
4. lane `skills.byRole[resolvedRole]`
|
|
133
|
+
5. global `skills.byRuntime[resolvedExecutorId]`
|
|
134
|
+
6. lane `skills.byRuntime[resolvedExecutorId]`
|
|
135
|
+
7. global `skills.byDeployKind[defaultDeployEnvironmentKind]`
|
|
136
|
+
8. lane `skills.byDeployKind[defaultDeployEnvironmentKind]`
|
|
137
|
+
9. agent `### Skills`
|
|
138
|
+
|
|
139
|
+
Then Wave applies manifest activation filtering:
|
|
140
|
+
|
|
141
|
+
- configured skills only stay active if their `activation.roles`, `activation.runtimes`, and `activation.deployKinds` match the agent context
|
|
142
|
+
- explicit agent `### Skills` still attach even if activation metadata would not auto-match
|
|
143
|
+
|
|
144
|
+
Duplicates are removed while preserving first-seen order.
|
|
145
|
+
|
|
146
|
+
## Deploy-Kind Attachment
|
|
147
|
+
|
|
148
|
+
Deploy-kind mapping uses the wave's default deploy environment from `## Deploy environments`.
|
|
149
|
+
|
|
150
|
+
If the wave declares:
|
|
151
|
+
|
|
152
|
+
````md
|
|
153
|
+
## Deploy environments
|
|
154
|
+
|
|
155
|
+
- `prod`: `railway-mcp` default
|
|
156
|
+
````
|
|
157
|
+
|
|
158
|
+
then `byDeployKind.railway-mcp` skills become eligible for that wave. Whether they actually attach still depends on each bundle's activation metadata.
|
|
159
|
+
|
|
160
|
+
Config-time validation rules:
|
|
161
|
+
|
|
162
|
+
- `skills.byRole` keys must be supported Wave roles
|
|
163
|
+
- `skills.byRuntime` keys must be supported runtimes
|
|
164
|
+
- `skills.byDeployKind` keys are validated by `wave doctor` against built-in kinds plus kinds declared in wave files
|
|
165
|
+
|
|
166
|
+
Built-in deploy kinds shipped by the starter profile are:
|
|
167
|
+
|
|
168
|
+
- `railway-cli`
|
|
169
|
+
- `railway-mcp`
|
|
170
|
+
- `docker-compose`
|
|
171
|
+
- `kubernetes`
|
|
172
|
+
- `ssh-manual`
|
|
173
|
+
- `custom`
|
|
174
|
+
- `aws`
|
|
175
|
+
- `github-release`
|
|
176
|
+
|
|
177
|
+
## Runtime Projection
|
|
178
|
+
|
|
179
|
+
Wave now projects skills metadata-first:
|
|
180
|
+
|
|
181
|
+
- `skills.resolved.md` is a compact catalog with bundle summaries, activation scope, permissions, manifest paths, adapter paths, and available references
|
|
182
|
+
- `skills.expanded.md` contains the full canonical `SKILL.md` bodies plus runtime adapters for debugging and audit
|
|
183
|
+
|
|
184
|
+
Runtime delivery:
|
|
185
|
+
|
|
186
|
+
- Codex
|
|
187
|
+
Bundle directories become `--add-dir` inputs. The compact catalog stays in the compiled prompt, and the agent can read bundle files directly from disk.
|
|
188
|
+
- Claude
|
|
189
|
+
The compact catalog is appended to the generated system-prompt overlay.
|
|
190
|
+
- OpenCode
|
|
191
|
+
The compact catalog is injected into `opencode.json`, and `skill.json`, `SKILL.md`, the selected adapter, and every recursive `references/**` file are attached through `--file`.
|
|
192
|
+
- Local
|
|
193
|
+
The compact catalog stays prompt-only.
|
|
194
|
+
|
|
195
|
+
## Generated Artifacts
|
|
196
|
+
|
|
197
|
+
Executor overlay directories can contain:
|
|
198
|
+
|
|
199
|
+
- `skills.resolved.md`
|
|
200
|
+
- `skills.expanded.md`
|
|
201
|
+
- `skills.metadata.json`
|
|
202
|
+
- `<runtime>-skills.txt`
|
|
203
|
+
|
|
204
|
+
Dry-run `launch-preview.json` and live trace metadata also record the resolved skill ids, bundle metadata, hashes, activation metadata, and artifact paths.
|
|
205
|
+
|
|
206
|
+
## Validation
|
|
207
|
+
|
|
208
|
+
`wave doctor` validates the skill surface end to end:
|
|
209
|
+
|
|
210
|
+
- referenced bundles exist and load
|
|
211
|
+
- every bundle under the skills directory has a valid manifest and `SKILL.md`
|
|
212
|
+
- `skills.byRole`, `skills.byRuntime`, and `skills.byDeployKind` selectors are valid
|
|
213
|
+
- config mapping does not contradict manifest activation metadata
|
|
214
|
+
- every shipped `evalCases[]` route resolves to the expected active or inactive outcome
|
|
215
|
+
|
|
216
|
+
Missing or malformed bundles are configuration errors, not silent no-ops.
|
|
217
|
+
|
|
218
|
+
## Best Practices
|
|
219
|
+
|
|
220
|
+
- Keep `SKILL.md` procedural and move long catalogs into `references/`.
|
|
221
|
+
- Put routing intent into `activation.*`, not only prose.
|
|
222
|
+
- Use explicit per-agent `### Skills` for true exceptions, not as a substitute for missing activation metadata.
|
|
223
|
+
- Keep provider skills role-scoped unless every role genuinely needs the provider context.
|
|
224
|
+
- Keep bundle ids stable so traces and prompt fingerprints remain intelligible across runs.
|
|
@@ -1,54 +1,173 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Agent Context Sources"
|
|
3
|
-
summary: "Primary external sources used as inspiration for harness design, long-running agents, blackboard coordination,
|
|
3
|
+
summary: "Primary external sources used as inspiration for planning, harness design, skills and procedural memory, long-running agents, blackboard coordination, repository-context evaluation, and secure code generation."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Agent Context Sources
|
|
7
7
|
|
|
8
8
|
This repository does not commit converted paper/article caches. Keep any hydrated local copies under `docs/research/agent-context-cache/` or another ignored cache directory.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Practice Articles
|
|
11
11
|
|
|
12
12
|
- [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
|
|
13
13
|
- [Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/)
|
|
14
14
|
- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
|
|
15
|
+
|
|
16
|
+
## Planning and Orchestration
|
|
17
|
+
|
|
18
|
+
- [SYMPHONY: Synergistic Multi-agent Planning with Heterogeneous Language Model Assembly](https://arxiv.org/abs/2601.22623)
|
|
19
|
+
- [Verified Multi-Agent Orchestration: A Plan-Execute-Verify-Replan Framework for Complex Query Resolution](https://arxiv.org/abs/2603.11445)
|
|
20
|
+
- [DOVA: Deliberation-First Multi-Agent Orchestration for Autonomous Research Automation](https://arxiv.org/abs/2603.13327)
|
|
21
|
+
- [TodoEvolve: Learning to Architect Agent Planning Systems](https://arxiv.org/abs/2602.07839)
|
|
22
|
+
- [Parallelized Planning-Acting for Efficient LLM-based Multi-Agent Systems in Minecraft](https://arxiv.org/abs/2503.03505)
|
|
23
|
+
- [OrchMAS: Orchestrated Reasoning with Multi Collaborative Heterogeneous Scientific Expert Structured Agents](https://arxiv.org/abs/2603.03005)
|
|
24
|
+
- [Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture](https://arxiv.org/abs/2507.01701)
|
|
25
|
+
- [LLM-Based Multi-Agent Blackboard System for Information Discovery in Data Science](https://arxiv.org/abs/2510.01285)
|
|
26
|
+
- [Terrarium: Revisiting the Blackboard for Multi-Agent Safety, Privacy, and Security Studies](https://arxiv.org/abs/2510.14312)
|
|
27
|
+
- [MACC: Multi-Agent Collaborative Competition for Scientific Exploration](https://arxiv.org/abs/2603.03780)
|
|
15
28
|
- [Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned](https://arxiv.org/abs/2603.05344)
|
|
16
29
|
- [VeRO: An Evaluation Harness for Agents to Optimize Agents](https://arxiv.org/abs/2602.22480)
|
|
17
30
|
- [EvoClaw: Evaluating AI Agents on Continuous Software Evolution](https://arxiv.org/abs/2603.13428)
|
|
31
|
+
- [Towards Engineering Multi-Agent LLMs: A Protocol-Driven Approach](https://arxiv.org/abs/2510.12120)
|
|
32
|
+
- [Advancing Multi-Agent Systems Through Model Context Protocol: Architecture, Implementation, and Applications](https://arxiv.org/abs/2504.21030)
|
|
33
|
+
- [Enhancing Model Context Protocol (MCP) with Context-Aware Server Collaboration](https://arxiv.org/abs/2601.11595)
|
|
34
|
+
- [Why Do Multi-Agent LLM Systems Fail?](https://arxiv.org/abs/2503.13657)
|
|
35
|
+
- [Systematic Failures in Collective Reasoning under Distributed Information in Multi-Agent LLMs](https://arxiv.org/abs/2505.11556)
|
|
36
|
+
- [Silo-Bench: A Scalable Environment for Evaluating Distributed Coordination in Multi-Agent LLM Systems](https://arxiv.org/abs/2603.01045)
|
|
37
|
+
- [DPBench: Large Language Models Struggle with Simultaneous Coordination](https://arxiv.org/abs/2602.13255)
|
|
38
|
+
- [Multi-Agent Teams Hold Experts Back](https://arxiv.org/abs/2602.01011)
|
|
39
|
+
- [A Survey on LLM-based Multi-agent Systems: Workflow, Infrastructure, and Challenges](https://link.springer.com/article/10.1007/s44336-024-00009-2)
|
|
40
|
+
- [LLM-Based Multi-Agent Systems for Software Engineering: Literature Review, Vision and the Road Ahead](https://arxiv.org/abs/2404.04834)
|
|
41
|
+
- [The Orchestration of Multi-Agent Systems: Architectures, Protocols, and Enterprise Adoption](https://arxiv.org/abs/2601.13671)
|
|
42
|
+
- [Describing Agentic AI Systems with C4: Lessons from Industry Projects](https://arxiv.org/abs/2603.15021)
|
|
43
|
+
- [A Taxonomy of Hierarchical Multi-Agent Systems: Design Patterns, Coordination Mechanisms, and Industrial Applications](https://arxiv.org/abs/2508.12683)
|
|
44
|
+
- [Blackboard Systems, Part One: The Blackboard Model of Problem Solving and the Evolution of Blackboard Architectures](https://ojs.aaai.org/index.php/aimagazine/article/view/537)
|
|
45
|
+
- [A Blackboard Architecture for Control](https://www.sciencedirect.com/science/article/abs/pii/0004370285900633)
|
|
46
|
+
- [Incremental Planning to Control a Blackboard-Based Problem Solver](https://cdn.aaai.org/AAAI/1986/AAAI86-010.pdf)
|
|
47
|
+
- [Blackboard Systems](https://mas.cs.umass.edu/Documents/Corkill/ai-expert.pdf)
|
|
48
|
+
|
|
49
|
+
## Harnesses, Context Engineering, and Long-Running Agents
|
|
50
|
+
|
|
51
|
+
- [Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned](https://arxiv.org/abs/2603.05344)
|
|
52
|
+
- [Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models](https://arxiv.org/abs/2510.04618)
|
|
53
|
+
- [ReSum: Unlocking Long-Horizon Search Intelligence via Context Summarization](https://arxiv.org/abs/2509.13313)
|
|
54
|
+
- [ARC: Active and Reflection-driven Context Management for Long-Horizon Information Seeking Agents](https://arxiv.org/abs/2601.12030)
|
|
55
|
+
- [Meta Context Engineering via Agentic Skill Evolution](https://arxiv.org/abs/2601.21557)
|
|
56
|
+
- [Context Engineering for AI Agents in Open-Source Software](https://arxiv.org/abs/2510.21413)
|
|
57
|
+
- [Context Engineering: From Prompts to Corporate Multi-Agent Architecture](https://arxiv.org/abs/2603.09619)
|
|
58
|
+
- [CEDAR: Context Engineering for Agentic Data Science](https://arxiv.org/abs/2601.06606)
|
|
59
|
+
- [VeRO: An Evaluation Harness for Agents to Optimize Agents](https://arxiv.org/abs/2602.22480)
|
|
60
|
+
- [EvoClaw: Evaluating AI Agents on Continuous Software Evolution](https://arxiv.org/abs/2603.13428)
|
|
61
|
+
- [Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers](https://arxiv.org/abs/2603.07670)
|
|
62
|
+
|
|
63
|
+
## Skills and Procedural Memory
|
|
64
|
+
|
|
65
|
+
- [SoK: Agentic Skills -- Beyond Tool Use in LLM Agents](https://arxiv.org/abs/2602.20867)
|
|
66
|
+
- [Agent Skills for Large Language Models: Architecture, Acquisition, Security, and the Path Forward](https://arxiv.org/abs/2602.12430)
|
|
67
|
+
- [Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers](https://arxiv.org/abs/2603.07670)
|
|
68
|
+
- [Meta Context Engineering via Agentic Skill Evolution](https://arxiv.org/abs/2601.21557)
|
|
69
|
+
- [Voyager: An Open-Ended Embodied Agent with Large Language Models](https://arxiv.org/abs/2305.16291)
|
|
70
|
+
- [Toolformer: Language Models Can Teach Themselves to Use Tools](https://arxiv.org/abs/2302.04761)
|
|
71
|
+
- [Large Language Models as Tool Makers](https://arxiv.org/abs/2305.17126)
|
|
72
|
+
- [Synapse: Trajectory-as-Exemplar Prompting with Memory for Computer Control](https://arxiv.org/abs/2306.07863)
|
|
73
|
+
- [ExpeL: LLM Agents Are Experiential Learners](https://arxiv.org/abs/2308.10144)
|
|
74
|
+
- [Agent Workflow Memory](https://arxiv.org/abs/2409.07429)
|
|
75
|
+
- [SkillWeaver: Web Agents can Self-Improve by Discovering and Honing Skills](https://arxiv.org/abs/2504.07079)
|
|
76
|
+
- [ReUseIt: Synthesizing Reusable AI Agent Workflows for Web Automation](https://arxiv.org/abs/2510.14308)
|
|
77
|
+
- [ProcMEM: Learning Reusable Procedural Memory from Experience via Non-Parametric PPO for LLM Agents](https://arxiv.org/abs/2602.01869)
|
|
78
|
+
- [Learning Hierarchical Procedural Memory for LLM Agents through Bayesian Selection and Contrastive Refinement](https://arxiv.org/abs/2512.18950)
|
|
79
|
+
- [Mem^p: Exploring Agent Procedural Memory](https://arxiv.org/abs/2508.06433)
|
|
80
|
+
- [MemSkill: Learning and Evolving Memory Skills for Self-Evolving Agents](https://arxiv.org/abs/2602.02474)
|
|
81
|
+
- [Reinforcement Learning for Self-Improving Agent with Skill Library](https://arxiv.org/abs/2512.17102)
|
|
82
|
+
- [Evolving Programmatic Skill Networks](https://arxiv.org/abs/2601.03509)
|
|
83
|
+
- [XSkill: Continual Learning from Experience and Skills in Multimodal Agents](https://arxiv.org/abs/2603.12056)
|
|
84
|
+
- [Memento-Skills: Let Agents Design Agents](https://arxiv.org/abs/2603.18743)
|
|
85
|
+
- [MetaClaw: Just Talk -- An Agent That Meta-Learns and Evolves in the Wild](https://arxiv.org/abs/2603.17187)
|
|
86
|
+
- [SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks](https://arxiv.org/abs/2602.12670)
|
|
87
|
+
|
|
88
|
+
## Agent Context Files and Configuration
|
|
89
|
+
|
|
90
|
+
- [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/html/2602.11988v1)
|
|
91
|
+
- [Agent READMEs: An Empirical Study of Context Files for Agentic Coding](https://arxiv.org/abs/2511.12884)
|
|
92
|
+
- [Beyond the Prompt: An Empirical Study of Cursor Rules](https://arxiv.org/abs/2512.18925)
|
|
93
|
+
- [Decoding the Configuration of AI Coding Agents: Insights from Claude Code Projects](https://arxiv.org/abs/2511.09268)
|
|
94
|
+
- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/abs/2601.20404)
|
|
95
|
+
- [Interpretable Context Methodology: Folder Structure as Agentic Architecture](https://arxiv.org/abs/2603.16021)
|
|
18
96
|
|
|
19
97
|
## Blackboard and Shared Workspaces
|
|
20
98
|
|
|
21
99
|
- [LLM-Based Multi-Agent Blackboard System for Information Discovery in Data Science](https://arxiv.org/abs/2510.01285)
|
|
22
100
|
- [Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture](https://arxiv.org/abs/2507.01701)
|
|
101
|
+
- [Terrarium: Revisiting the Blackboard for Multi-Agent Safety, Privacy, and Security Studies](https://arxiv.org/abs/2510.14312)
|
|
23
102
|
- [DOVA: Deliberation-First Multi-Agent Orchestration for Autonomous Research Automation](https://arxiv.org/abs/2603.13327)
|
|
103
|
+
- [MACC: Multi-Agent Collaborative Competition for Scientific Exploration](https://arxiv.org/abs/2603.03780)
|
|
104
|
+
- [M3-ACE: Rectifying Visual Perception in Multimodal Math Reasoning via Multi-Agentic Context Engineering](https://arxiv.org/abs/2603.08369)
|
|
24
105
|
- [SYMPHONY: Synergistic Multi-agent Planning with Heterogeneous Language Model Assembly](https://arxiv.org/abs/2601.22623)
|
|
25
106
|
- [Silo-Bench: A Scalable Environment for Evaluating Distributed Coordination in Multi-Agent LLM Systems](https://arxiv.org/abs/2603.01045)
|
|
26
107
|
- [An Open Agent Architecture](https://cdn.aaai.org/Symposia/Spring/1994/SS-94-03/SS94-03-001.pdf)
|
|
108
|
+
- [Blackboard Systems, Part One: The Blackboard Model of Problem Solving and the Evolution of Blackboard Architectures](https://ojs.aaai.org/index.php/aimagazine/article/view/537)
|
|
109
|
+
- [A Blackboard Architecture for Control](https://www.sciencedirect.com/science/article/abs/pii/0004370285900633)
|
|
110
|
+
- [Incremental Planning to Control a Blackboard-Based Problem Solver](https://cdn.aaai.org/AAAI/1986/AAAI86-010.pdf)
|
|
111
|
+
- [Blackboard Systems](https://mas.cs.umass.edu/Documents/Corkill/ai-expert.pdf)
|
|
27
112
|
|
|
28
|
-
##
|
|
113
|
+
## Multi-Agent Orchestration and Architecture
|
|
29
114
|
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
115
|
+
- [The Orchestration of Multi-Agent Systems: Architectures, Protocols, and Enterprise Adoption](https://arxiv.org/abs/2601.13671)
|
|
116
|
+
- [Agentic Artificial Intelligence (AI): Architectures, Taxonomies, and Evaluation of Large Language Model Agents](https://arxiv.org/abs/2601.12560)
|
|
117
|
+
- [Describing Agentic AI Systems with C4: Lessons from Industry Projects](https://arxiv.org/abs/2603.15021)
|
|
118
|
+
- [A Taxonomy of Hierarchical Multi-Agent Systems: Design Patterns, Coordination Mechanisms, and Industrial Applications](https://arxiv.org/abs/2508.12683)
|
|
34
119
|
|
|
35
|
-
##
|
|
120
|
+
## Security and Secure Code Generation
|
|
121
|
+
|
|
122
|
+
- [Prompting Techniques for Secure Code Generation: A Systematic Investigation](https://arxiv.org/abs/2407.07064)
|
|
123
|
+
- [Retrieve, Refine, or Both? Using Task-Specific Guidelines for Secure Python Code Generation](https://emaiannone.github.io/assets/pdf/c6.pdf)
|
|
124
|
+
- [Discrete Prompt Optimization Using Genetic Algorithm for Secure Python Code Generation](https://www.sciencedirect.com/science/article/pii/S0164121225003516)
|
|
125
|
+
- [SCGAgent: Recreating the Benefits of Reasoning Models for Secure Code Generation with Agentic Workflows](https://arxiv.org/abs/2506.07313)
|
|
126
|
+
- [RESCUE: Retrieval Augmented Secure Code Generation](https://arxiv.org/abs/2510.18204)
|
|
127
|
+
- [Improving LLM-Assisted Secure Code Generation through Retrieval-Augmented-Generation and Multi-Tool Feedback](https://arxiv.org/abs/2601.00509)
|
|
128
|
+
- [Autoregressive, Yet Revisable: In Decoding Revision for Secure Code Generation](https://arxiv.org/abs/2602.01187)
|
|
129
|
+
- [Security-by-Design for LLM-Based Code Generation: Leveraging Internal Representations for Concept-Driven Steering Mechanisms](https://arxiv.org/abs/2603.11212)
|
|
130
|
+
- [Persistent Human Feedback, LLMs, and Static Analyzers for Secure Code Generation and Vulnerability Detection](https://arxiv.org/abs/2602.05868)
|
|
131
|
+
|
|
132
|
+
## Security Benchmarks and Evaluation
|
|
133
|
+
|
|
134
|
+
- [SecRepoBench: Benchmarking Code Agents for Secure Code Completion in Real-World Repositories](https://arxiv.org/abs/2504.21205)
|
|
135
|
+
- [SecureAgentBench: Benchmarking Secure Code Generation under Realistic Vulnerability Scenarios](https://arxiv.org/abs/2509.22097)
|
|
136
|
+
- [SeCodePLT: A Unified Platform for Evaluating the Security of Code GenAI](https://arxiv.org/abs/2410.11096)
|
|
137
|
+
- [TOSSS: a CVE-based Software Security Benchmark for Large Language Models](https://arxiv.org/abs/2603.10969)
|
|
138
|
+
- [From Vulnerabilities to Remediation: A Systematic Literature Review of LLMs in Code Security](https://arxiv.org/abs/2412.15004)
|
|
139
|
+
- [Quality Assurance of LLM-generated Code: Addressing Non-Functional Quality Characteristics](https://arxiv.org/abs/2511.10271)
|
|
140
|
+
|
|
141
|
+
## Multi-Agent Security
|
|
142
|
+
|
|
143
|
+
- [Terrarium: Revisiting the Blackboard for Multi-Agent Safety, Privacy, and Security Studies](https://arxiv.org/abs/2510.14312)
|
|
144
|
+
- [Security Considerations for Multi-agent Systems](https://arxiv.org/abs/2603.09002)
|
|
145
|
+
|
|
146
|
+
## Skill Practice and Open Standards
|
|
147
|
+
|
|
148
|
+
- [Agent Skills - Codex](https://developers.openai.com/codex/skills/)
|
|
149
|
+
- [Customization - Codex](https://developers.openai.com/codex/concepts/customization/)
|
|
150
|
+
- [Testing Agent Skills Systematically with Evals](https://developers.openai.com/blog/eval-skills/)
|
|
151
|
+
- [Shell + Skills + Compaction: Tips for long-running agents that do real work](https://developers.openai.com/blog/skills-shell-tips/)
|
|
152
|
+
- [Using skills to accelerate OSS maintenance](https://developers.openai.com/blog/skills-agents-sdk/)
|
|
153
|
+
- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
|
|
154
|
+
- [Best practices for skill creators](https://agentskills.io/skill-creation/best-practices)
|
|
155
|
+
- [Using scripts in skills](https://agentskills.io/skill-creation/using-scripts)
|
|
156
|
+
|
|
157
|
+
## Adjacent Memory and Prompting Research
|
|
36
158
|
|
|
37
|
-
- [Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers](https://arxiv.org/abs/2603.07670)
|
|
38
159
|
- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
|
|
39
160
|
- [Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex/)
|
|
40
161
|
- [Prompt guidance for GPT-5](https://developers.openai.com/api/docs/guides/prompt-guidance/)
|
|
41
162
|
- [Codex Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide/)
|
|
42
163
|
- [Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
|
|
43
164
|
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
|
|
44
|
-
- [Context Engineering for AI Agents in Open-Source Software](https://arxiv.org/abs/2510.21413)
|
|
45
165
|
- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629)
|
|
46
166
|
- [Toolformer: Language Models Can Teach Themselves to Use Tools](https://arxiv.org/abs/2302.04761)
|
|
47
167
|
- [Plan-and-Solve Prompting](https://arxiv.org/abs/2305.04091)
|
|
48
168
|
- [Augmenting Language Models with Long-Term Memory](https://arxiv.org/abs/2306.07174)
|
|
49
169
|
- [MemGPT: Towards LLMs as Operating Systems](https://arxiv.org/abs/2310.08560)
|
|
50
170
|
- [Lost in the Middle: How Language Models Use Long Contexts](https://direct.mit.edu/tacl/article/doi/10.1162/tacl_a_00638/119630/Lost-in-the-Middle-How-Language-Models-Use-Long)
|
|
51
|
-
- [ReSum: Unlocking Long-Horizon Search Intelligence via Context Summarization](https://arxiv.org/abs/2509.13313)
|
|
52
171
|
|
|
53
172
|
## Notes
|
|
54
173
|
|