@chllming/wave-orchestration 0.8.3 → 0.8.5
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 +36 -1
- package/README.md +60 -11
- package/docs/README.md +8 -2
- package/docs/agents/wave-design-role.md +47 -0
- package/docs/concepts/what-is-a-wave.md +11 -7
- package/docs/guides/author-and-run-waves.md +24 -0
- package/docs/guides/planner.md +44 -0
- package/docs/plans/architecture-hardening-migration.md +8 -1
- package/docs/plans/current-state.md +19 -7
- package/docs/plans/end-state-architecture.md +88 -70
- package/docs/plans/examples/wave-example-design-handoff.md +262 -0
- package/docs/plans/examples/wave-example-live-proof.md +1 -1
- package/docs/plans/migration.md +370 -64
- package/docs/plans/wave-orchestrator.md +49 -13
- package/docs/reference/cli-reference.md +46 -14
- package/docs/reference/coordination-and-closure.md +19 -6
- package/docs/reference/npmjs-trusted-publishing.md +5 -4
- package/docs/reference/sample-waves.md +14 -7
- package/docs/reference/skills.md +10 -0
- package/package.json +1 -1
- package/releases/manifest.json +39 -0
- package/scripts/wave-orchestrator/agent-state.mjs +64 -491
- package/scripts/wave-orchestrator/autonomous.mjs +10 -6
- package/scripts/wave-orchestrator/{launcher-closure.mjs → closure-engine.mjs} +190 -74
- package/scripts/wave-orchestrator/config.mjs +5 -0
- package/scripts/wave-orchestrator/coordination.mjs +42 -1
- package/scripts/wave-orchestrator/{launcher-derived-state.mjs → derived-state-engine.mjs} +34 -146
- package/scripts/wave-orchestrator/{launcher-gates.mjs → gate-engine.mjs} +501 -141
- package/scripts/wave-orchestrator/human-input-resolution.mjs +14 -10
- package/scripts/wave-orchestrator/human-input-workflow.mjs +104 -0
- package/scripts/wave-orchestrator/implementation-engine.mjs +120 -0
- package/scripts/wave-orchestrator/install.mjs +3 -0
- package/scripts/wave-orchestrator/launcher-runtime.mjs +11 -6
- package/scripts/wave-orchestrator/launcher.mjs +324 -723
- package/scripts/wave-orchestrator/ledger.mjs +56 -27
- package/scripts/wave-orchestrator/local-executor.mjs +37 -0
- package/scripts/wave-orchestrator/planner.mjs +24 -4
- package/scripts/wave-orchestrator/projection-writer.mjs +256 -0
- package/scripts/wave-orchestrator/reconcile-format.mjs +32 -0
- package/scripts/wave-orchestrator/reducer-snapshot.mjs +297 -0
- package/scripts/wave-orchestrator/replay.mjs +3 -1
- package/scripts/wave-orchestrator/result-envelope.mjs +620 -0
- package/scripts/wave-orchestrator/retry-control.mjs +22 -2
- package/scripts/wave-orchestrator/{launcher-retry.mjs → retry-engine.mjs} +352 -18
- package/scripts/wave-orchestrator/role-helpers.mjs +124 -1
- package/scripts/wave-orchestrator/{launcher-supervisor.mjs → session-supervisor.mjs} +178 -103
- package/scripts/wave-orchestrator/shared.mjs +2 -0
- package/scripts/wave-orchestrator/skills.mjs +1 -0
- package/scripts/wave-orchestrator/task-entity.mjs +65 -45
- package/scripts/wave-orchestrator/traces.mjs +10 -1
- package/scripts/wave-orchestrator/wave-files.mjs +96 -10
- package/scripts/wave-orchestrator/wave-state-reducer.mjs +76 -12
- package/skills/README.md +7 -0
- package/skills/role-design/SKILL.md +50 -0
- package/skills/role-design/skill.json +36 -0
- package/skills/tui-design/SKILL.md +77 -0
- package/skills/tui-design/references/tui-design.md +259 -0
- package/skills/tui-design/skill.json +36 -0
- package/wave.config.json +15 -1
|
@@ -7,6 +7,19 @@ summary: "Complete syntax reference for all wave CLI commands, flags, and operat
|
|
|
7
7
|
|
|
8
8
|
Complete syntax for every `wave` command. All commands use `pnpm exec wave` as the entry point.
|
|
9
9
|
|
|
10
|
+
## Command Families
|
|
11
|
+
|
|
12
|
+
- Runtime:
|
|
13
|
+
`wave launch`, `wave autonomous`, and `wave local` cover dry-run validation, live execution, and executor-specific prompt transport.
|
|
14
|
+
- Operator control:
|
|
15
|
+
`wave control` is the preferred surface for live status, tasks, reruns, proof bundles, and telemetry.
|
|
16
|
+
- Compatibility and inspection:
|
|
17
|
+
`wave coord`, `wave retry`, and `wave proof` remain available where older runbooks still depend on them.
|
|
18
|
+
- Planning and transient work:
|
|
19
|
+
`wave project`, `wave draft`, and `wave adhoc` cover defaults, authored waves, and operator-driven one-off runs.
|
|
20
|
+
- Setup and lifecycle:
|
|
21
|
+
`wave init`, `wave doctor`, `wave upgrade`, and `wave self-update` cover workspace adoption, validation, and package upgrades.
|
|
22
|
+
|
|
10
23
|
## wave launch
|
|
11
24
|
|
|
12
25
|
Launch waves for execution.
|
|
@@ -15,6 +28,10 @@ Launch waves for execution.
|
|
|
15
28
|
wave launch [options]
|
|
16
29
|
```
|
|
17
30
|
|
|
31
|
+
Defaults below reflect the starter workspace surface in this repo. Lane config can override executor, timeout, retry, and terminal defaults.
|
|
32
|
+
|
|
33
|
+
Closure-role bindings do not have a CLI override surface. When a wave file declares custom integration, documentation, `cont-QA`, `cont-EVAL`, or security-review role ids, launch, retry, reducer, and closure flows honor those wave-level bindings end to end.
|
|
34
|
+
|
|
18
35
|
| Flag | Default | Description |
|
|
19
36
|
|------|---------|-------------|
|
|
20
37
|
| `--lane <name>` | `main` | Lane name |
|
|
@@ -22,20 +39,23 @@ wave launch [options]
|
|
|
22
39
|
| `--end-wave <n>` | last available | Last wave to launch |
|
|
23
40
|
| `--auto-next` | off | Start from next unfinished wave and continue |
|
|
24
41
|
| `--resume-control-state` | off | Preserve the prior auto-generated relaunch plan instead of treating the launch as a fresh wave start |
|
|
25
|
-
| `--executor <id>` |
|
|
42
|
+
| `--executor <id>` | `codex` | Default executor: `codex`, `claude`, `opencode`, `local` |
|
|
26
43
|
| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox isolation level |
|
|
27
|
-
| `--timeout-minutes <n>` | `
|
|
28
|
-
| `--max-retries-per-wave <n>` | `
|
|
29
|
-
| `--agent-rate-limit-retries <n>` | `
|
|
30
|
-
| `--agent-rate-limit-base-delay-seconds <n>` | `
|
|
31
|
-
| `--agent-rate-limit-max-delay-seconds <n>` | `
|
|
32
|
-
| `--agent-launch-stagger-ms <n>` | `
|
|
33
|
-
| `--terminal-surface <mode>` |
|
|
44
|
+
| `--timeout-minutes <n>` | `240` | Max minutes to wait per wave |
|
|
45
|
+
| `--max-retries-per-wave <n>` | `1` | Relaunch failed agents per wave |
|
|
46
|
+
| `--agent-rate-limit-retries <n>` | `2` | Per-agent retries for 429 errors |
|
|
47
|
+
| `--agent-rate-limit-base-delay-seconds <n>` | `20` | Base exponential backoff for 429 |
|
|
48
|
+
| `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max backoff delay for 429 |
|
|
49
|
+
| `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
|
|
50
|
+
| `--terminal-surface <mode>` | `vscode` | `tmux`, `vscode`, or `none` |
|
|
34
51
|
| `--no-dashboard` | off | Disable per-wave tmux dashboard |
|
|
35
52
|
| `--cleanup-sessions` | on | Kill lane tmux sessions after each wave |
|
|
36
53
|
| `--keep-sessions` | off | Keep lane tmux sessions |
|
|
37
54
|
| `--keep-terminals` | off | Keep temporary terminal entries |
|
|
38
55
|
| `--orchestrator-id <id>` | generated | Stable orchestrator identity |
|
|
56
|
+
| `--orchestrator-board <path>` | default board path | Write coordination-board updates to a specific shared board |
|
|
57
|
+
| `--no-orchestrator-board` | off | Disable shared orchestrator-board writes for this run |
|
|
58
|
+
| `--coordination-note <text>` | empty | Append a startup intent note to orchestrator-board updates |
|
|
39
59
|
| `--resident-orchestrator` | off | Launch long-running non-owning orchestrator session |
|
|
40
60
|
| `--no-telemetry` | off | Disable Wave Control event publication |
|
|
41
61
|
| `--no-context7` | off | Disable Context7 prefetch |
|
|
@@ -57,13 +77,13 @@ wave autonomous [options]
|
|
|
57
77
|
| `--lane <name>` | `main` | Lane name |
|
|
58
78
|
| `--executor <id>` | lane config | `codex`, `claude`, or `opencode` (not `local`) |
|
|
59
79
|
| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox mode |
|
|
60
|
-
| `--timeout-minutes <n>` | `
|
|
61
|
-
| `--max-retries-per-wave <n>` | `
|
|
80
|
+
| `--timeout-minutes <n>` | `240` | Per-wave timeout passed to launcher |
|
|
81
|
+
| `--max-retries-per-wave <n>` | `1` | Per-wave relaunches inside launcher |
|
|
62
82
|
| `--max-attempts-per-wave <n>` | `1` | External attempts per wave |
|
|
63
|
-
| `--agent-rate-limit-retries <n>` | `
|
|
64
|
-
| `--agent-rate-limit-base-delay-seconds <n>` | `
|
|
65
|
-
| `--agent-rate-limit-max-delay-seconds <n>` | `
|
|
66
|
-
| `--agent-launch-stagger-ms <n>` | `
|
|
83
|
+
| `--agent-rate-limit-retries <n>` | `2` | Per-agent 429 retries |
|
|
84
|
+
| `--agent-rate-limit-base-delay-seconds <n>` | `20` | Base 429 backoff |
|
|
85
|
+
| `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max 429 backoff |
|
|
86
|
+
| `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
|
|
67
87
|
| `--orchestrator-id <id>` | `<lane>-autonomous` | Orchestrator identity |
|
|
68
88
|
| `--resident-orchestrator` | off | Launch resident orchestrator for each wave |
|
|
69
89
|
| `--dashboard` | off | Enable dashboards |
|
|
@@ -514,6 +534,18 @@ wave draft --show-run <run-id>
|
|
|
514
534
|
wave draft --apply-run <run-id>
|
|
515
535
|
```
|
|
516
536
|
|
|
537
|
+
Interactive draft currently offers worker role kinds:
|
|
538
|
+
|
|
539
|
+
- `design`
|
|
540
|
+
- `implementation`
|
|
541
|
+
- `qa`
|
|
542
|
+
- `infra`
|
|
543
|
+
- `deploy`
|
|
544
|
+
- `research`
|
|
545
|
+
- `security`
|
|
546
|
+
|
|
547
|
+
Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.5` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
|
|
548
|
+
|
|
517
549
|
## Ad-Hoc Task Commands
|
|
518
550
|
|
|
519
551
|
**Plan and run ad-hoc tasks:**
|
|
@@ -25,6 +25,17 @@ Those are related, but they are not the same.
|
|
|
25
25
|
|
|
26
26
|
An implementation agent can be locally complete and still leave the wave blocked if it created open helper work, unresolved clarification chains, or required dependencies.
|
|
27
27
|
|
|
28
|
+
At runtime, those distinctions map onto separate modules:
|
|
29
|
+
|
|
30
|
+
- `implementation-engine.mjs` selects implementation work
|
|
31
|
+
- `derived-state-engine.mjs` rebuilds the blackboard projections
|
|
32
|
+
- `gate-engine.mjs` evaluates closure and barrier state from envelopes plus canonical logs
|
|
33
|
+
- `retry-engine.mjs` decides what can safely resume
|
|
34
|
+
- `closure-engine.mjs` sequences the staged closeout
|
|
35
|
+
- `session-supervisor.mjs` only launches sessions and records observed facts
|
|
36
|
+
|
|
37
|
+
Closure roles are resolved from the wave definition first, then from starter defaults. In other words, integration, documentation, `cont-QA`, `cont-EVAL`, and security review keep the same semantics even when a wave overrides the default role ids such as `A8`, `A9`, `A0`, `E0`, or `A7`.
|
|
38
|
+
|
|
28
39
|
## Durable State Surfaces
|
|
29
40
|
|
|
30
41
|
The runtime writes several different artifacts, but they do different jobs:
|
|
@@ -52,6 +63,8 @@ The runtime writes several different artifacts, but they do different jobs:
|
|
|
52
63
|
|
|
53
64
|
The important rule is that decisions come from the canonical authority set: wave definitions, the coordination log, the control-plane log, and immutable result envelopes. The markdown board is a projection for humans. See [wave-orchestrator.md](../plans/wave-orchestrator.md).
|
|
54
65
|
|
|
66
|
+
That control-plane log also carries observed `wave_run`, `attempt`, and `agent_run` lifecycle facts from `session-supervisor.mjs`. When human feedback or escalation remains open, the reducer materializes the wave as `clarifying` with blocked `waveState` instead of flattening it into generic progress.
|
|
67
|
+
|
|
55
68
|
Live waves now keep refreshing that derived state while agents are still running. Shared summaries, inboxes, dashboard coordination metrics, and clarification routing are not only recomputed at attempt boundaries; they are also refreshed during active wave execution so stale clarification and acknowledgement timing is machine-visible before the attempt ends.
|
|
56
69
|
|
|
57
70
|
## What Agents Should Use
|
|
@@ -61,7 +74,7 @@ Use the coordination log for conversational or workflow state:
|
|
|
61
74
|
- `request`
|
|
62
75
|
Use this when you need another agent or capability owner to do work. Target it explicitly. This is the kind that becomes a helper assignment.
|
|
63
76
|
- `blocker`
|
|
64
|
-
Use this when the wave is blocked, but not because the
|
|
77
|
+
Use this when the wave is blocked, but not because the runtime needs to route work to a specific assignee.
|
|
65
78
|
- `handoff`
|
|
66
79
|
Use this for continuity and context transfer. This is informative by itself; it is not the same as a blocking helper assignment.
|
|
67
80
|
- `evidence`
|
|
@@ -164,7 +177,7 @@ pnpm exec wave control task create \
|
|
|
164
177
|
What happens next:
|
|
165
178
|
|
|
166
179
|
- the request lands in the canonical coordination log
|
|
167
|
-
- the
|
|
180
|
+
- the runtime derives a helper assignment for `agent:A8`
|
|
168
181
|
- that assignment is written into the assignment snapshot
|
|
169
182
|
- the shared summary and A8 inbox now show the open helper work
|
|
170
183
|
|
|
@@ -230,9 +243,9 @@ pnpm exec wave coord post \
|
|
|
230
243
|
|
|
231
244
|
What happens next:
|
|
232
245
|
|
|
233
|
-
1. the
|
|
246
|
+
1. the orchestrator triages the clarification from repo policy, ownership, prior decisions, and routing context
|
|
234
247
|
2. if it can answer inside the wave, it writes the resolution back into coordination state
|
|
235
|
-
3. if another owner can answer it, the
|
|
248
|
+
3. if another owner can answer it, the runtime opens a targeted follow-up request and keeps the clarification chain blocking
|
|
236
249
|
4. only after policy and routed follow-up paths are exhausted does it create human feedback or escalation artifacts
|
|
237
250
|
5. until that chain is resolved, clarification remains a closure barrier and any routed follow-up also remains blocking helper work
|
|
238
251
|
|
|
@@ -406,7 +419,7 @@ That gives Wave two useful properties:
|
|
|
406
419
|
|
|
407
420
|
## Targeted Retry Behavior
|
|
408
421
|
|
|
409
|
-
When closure fails, the
|
|
422
|
+
When closure fails, the runtime does not always relaunch the entire wave.
|
|
410
423
|
|
|
411
424
|
It tries to relaunch only the implicated owners:
|
|
412
425
|
|
|
@@ -425,7 +438,7 @@ pnpm exec wave control rerun get --lane main --wave 10 --json
|
|
|
425
438
|
pnpm exec wave control rerun request --lane main --wave 10 --agent A2 --agent A7 --clear-reuse A2 --reason "Resume sibling-owned component closure"
|
|
426
439
|
```
|
|
427
440
|
|
|
428
|
-
The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the
|
|
441
|
+
The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the retry engine on the next retry decision, and then cleared by default after one application. This is the supported path for:
|
|
429
442
|
|
|
430
443
|
- rerunning only specific owners
|
|
431
444
|
- preserving explicit reuse selectors such as attempt ids, proof bundle ids, derived-summary reuse, and invalidated component ids through the compatibility projection
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
|
|
4
4
|
|
|
5
|
-
The current `0.8.
|
|
5
|
+
The current `0.8.5` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
|
|
6
6
|
|
|
7
7
|
## What This Repo Already Does
|
|
8
8
|
|
|
@@ -47,6 +47,7 @@ If this repo later needs private npm dependencies during CI, consider a separate
|
|
|
47
47
|
1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
|
|
48
48
|
2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
|
|
49
49
|
3. Confirm the package version has been bumped and committed.
|
|
50
|
-
4.
|
|
51
|
-
5.
|
|
52
|
-
6. Verify
|
|
50
|
+
4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
|
|
51
|
+
5. Push the release commit and release tag, for example `v0.8.5`.
|
|
52
|
+
6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
|
|
53
|
+
7. Verify the npmjs publish completes successfully for the tagged source.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Sample Waves"
|
|
3
|
-
summary: "Showcase-first sample waves that demonstrate the
|
|
3
|
+
summary: "Showcase-first sample waves that demonstrate the shipped 0.8.5 authored surface, including the optional design-role path."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Sample Waves
|
|
7
7
|
|
|
8
|
-
This guide points to showcase-first sample waves that demonstrate the
|
|
8
|
+
This guide points to showcase-first sample waves that demonstrate the shipped `0.8.5` authored Wave surface.
|
|
9
9
|
|
|
10
10
|
The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
|
|
11
11
|
|
|
@@ -15,7 +15,10 @@ The examples are intentionally denser than typical production waves. Their job i
|
|
|
15
15
|
Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
|
|
16
16
|
|
|
17
17
|
- [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
|
|
18
|
-
Shows the combined `0.8.
|
|
18
|
+
Shows the combined `0.8.5` 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.
|
|
19
|
+
|
|
20
|
+
- [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
|
|
21
|
+
Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
|
|
19
22
|
|
|
20
23
|
## What These Examples Teach
|
|
21
24
|
|
|
@@ -35,10 +38,11 @@ The examples are intentionally denser than typical production waves. Their job i
|
|
|
35
38
|
- sticky retry for proof-bearing owners
|
|
36
39
|
- deploy environments and provider-skill examples
|
|
37
40
|
- infra and deploy-verifier specialist slices
|
|
41
|
+
- optional pre-implementation design packets and design-to-implementation handoff
|
|
38
42
|
|
|
39
43
|
## Feature Coverage Map
|
|
40
44
|
|
|
41
|
-
Together these samples cover the main surfaces added or hardened
|
|
45
|
+
Together these samples cover the main surfaces added or hardened through `0.8.5`:
|
|
42
46
|
|
|
43
47
|
- repo-landed maturity discipline and anti-overclaim framing
|
|
44
48
|
- explicit shared-plan closure for future-wave safety
|
|
@@ -56,6 +60,7 @@ Together these samples cover the main surfaces added or hardened for `0.8.3`:
|
|
|
56
60
|
- proof-first live-wave prompts
|
|
57
61
|
- deploy environments and deploy-kind-aware skills
|
|
58
62
|
- integration, documentation, and cont-QA closure-role structure
|
|
63
|
+
- optional `design` worker role and `design-pass` executor profile
|
|
59
64
|
|
|
60
65
|
## When To Copy Literally Vs Adapt
|
|
61
66
|
|
|
@@ -76,6 +81,7 @@ Adapt more aggressively when:
|
|
|
76
81
|
## How This Example Maps To Other Docs
|
|
77
82
|
|
|
78
83
|
- Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use these samples to see how a human would enrich the generated draft for either repo-landed or proof-first work.
|
|
84
|
+
- Use [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) when the wave should start with a reusable design packet before implementation begins.
|
|
79
85
|
- Use [docs/evals/README.md](../evals/README.md) with the full modern sample when you need to see delegated and pinned benchmark targets in a real wave.
|
|
80
86
|
- Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with the full modern sample when you need proof-first authoring for `pilot-live` and above.
|
|
81
87
|
- Use [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) for the operational runbook that explains how the launcher interprets these sections.
|
|
@@ -83,9 +89,10 @@ Adapt more aggressively when:
|
|
|
83
89
|
## Suggested Reading Order
|
|
84
90
|
|
|
85
91
|
1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
|
|
86
|
-
2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy surface.
|
|
87
|
-
3. Read [
|
|
88
|
-
4. Read [docs/
|
|
92
|
+
2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.8.5` surface.
|
|
93
|
+
3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
|
|
94
|
+
4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
|
|
95
|
+
5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
|
|
89
96
|
|
|
90
97
|
## Why These Examples Live In `docs/plans/examples/`
|
|
91
98
|
|
package/docs/reference/skills.md
CHANGED
|
@@ -109,6 +109,7 @@ Top-level and lane-local skill attachment use the same shape:
|
|
|
109
109
|
"dir": "skills",
|
|
110
110
|
"base": ["wave-core", "repo-coding-rules"],
|
|
111
111
|
"byRole": {
|
|
112
|
+
"design": ["role-design"],
|
|
112
113
|
"deploy": ["role-deploy"]
|
|
113
114
|
},
|
|
114
115
|
"byRuntime": {
|
|
@@ -123,6 +124,8 @@ Top-level and lane-local skill attachment use the same shape:
|
|
|
123
124
|
|
|
124
125
|
Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
|
|
125
126
|
|
|
127
|
+
Optional design workers in the shipped `0.8.5` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
|
|
128
|
+
|
|
126
129
|
## Resolution Order
|
|
127
130
|
|
|
128
131
|
Resolved skills are gathered in this order:
|
|
@@ -195,6 +198,12 @@ Runtime delivery:
|
|
|
195
198
|
|
|
196
199
|
These runtime projections are guidance surfaces. They should stay aligned with the canonical authority model, but they are not replay inputs or decision state on their own.
|
|
197
200
|
|
|
201
|
+
For the optional `design` worker role, the default pattern is:
|
|
202
|
+
|
|
203
|
+
- `role-design` for the design packet contract
|
|
204
|
+
- `tui-design` only when the packet covers terminal UX, dashboards, or other operator surfaces
|
|
205
|
+
- no runtime-specific coding bundle unless the wave explicitly gives the design steward code ownership and makes it a hybrid design steward
|
|
206
|
+
|
|
198
207
|
## Generated Artifacts
|
|
199
208
|
|
|
200
209
|
Executor overlay directories can contain:
|
|
@@ -225,3 +234,4 @@ Missing or malformed bundles are configuration errors, not silent no-ops.
|
|
|
225
234
|
- Use explicit per-agent `### Skills` for true exceptions, not as a substitute for missing activation metadata.
|
|
226
235
|
- Keep provider skills role-scoped unless every role genuinely needs the provider context.
|
|
227
236
|
- Keep bundle ids stable so traces and prompt fingerprints remain intelligible across runs.
|
|
237
|
+
- Keep `role-design` docs/spec-first by default; add `tui-design` when terminal or operator-surface work is in scope, and only attach broader coding bundles when the wave explicitly assigns code ownership and expects the same design steward to return for implementation.
|
package/package.json
CHANGED
package/releases/manifest.json
CHANGED
|
@@ -2,6 +2,45 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"packageName": "@chllming/wave-orchestration",
|
|
4
4
|
"releases": [
|
|
5
|
+
{
|
|
6
|
+
"version": "0.8.5",
|
|
7
|
+
"date": "2026-03-25",
|
|
8
|
+
"summary": "Shipped design-role support, hybrid design-steward execution, release-surface alignment, and a practical migration guide.",
|
|
9
|
+
"features": [
|
|
10
|
+
"The optional `design` worker role is now part of the published release surface, including the standing design prompt, `role-design`, and `tui-design` starter bundles.",
|
|
11
|
+
"Design stewards are docs-first by default, but waves can now explicitly give them implementation ownership so the same agent runs a design pass first and then rejoins implementation with normal proof obligations.",
|
|
12
|
+
"Design-aware validation, prompts, gates, retry or resume planning, reducer state, local-executor smoke behavior, and result-envelope projection now all agree on the same hybrid-design contract.",
|
|
13
|
+
"The migration guide now covers fresh adoption plus upgrades from `0.8.4`, `0.8.0`-`0.8.4`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier, including repo-owned starter-surface sync guidance and `planner-agentic` corpus notes.",
|
|
14
|
+
"Shipped package metadata, README, current-state notes, sample-wave docs, and publishing guidance now point at the `0.8.5` release surface."
|
|
15
|
+
],
|
|
16
|
+
"manualSteps": [
|
|
17
|
+
"Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.5` design-role and hybrid-design behavior.",
|
|
18
|
+
"If your repo copied starter prompts, skills, or authoring docs, sync `docs/agents/wave-design-role.md`, `skills/role-design/`, `skills/tui-design/`, `wave.config.json` design-role keys, and any local planner or runbook pages that should describe the new design-steward model.",
|
|
19
|
+
"If a repo uses hybrid design stewards, make sure each one still owns a design packet path and that any explicit implementation ownership also carries the expected exit contract, deliverables, proof artifacts, and component declarations where your lane validation requires them.",
|
|
20
|
+
"If your repo uses planner workflows and copied the planner starter corpus, keep `docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry in sync before relying on local planner docs."
|
|
21
|
+
],
|
|
22
|
+
"breaking": false
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"version": "0.8.4",
|
|
26
|
+
"date": "2026-03-25",
|
|
27
|
+
"summary": "Contradiction replay repair, consistent component-promotion thresholds, projection-writer persistence centralization, and 0.8.4 release-surface alignment.",
|
|
28
|
+
"features": [
|
|
29
|
+
"Hermetic contradiction replay no longer depends on component-matrix parsing when the trace does not declare promoted components.",
|
|
30
|
+
"`requireComponentPromotionsFromWave` now gates both component-promotion proof validation and component-matrix current-level validation consistently across live and replay paths.",
|
|
31
|
+
"Projection persistence is now centralized under `projection-writer.mjs`, while `derived-state-engine.mjs` computes projection payloads without writing them directly.",
|
|
32
|
+
"The operator migration guide now covers fresh adoption plus upgrades from `0.8.3`, `0.8.0`-`0.8.2`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier with explicit repo-owned surface sync guidance.",
|
|
33
|
+
"Shipped package metadata, README, migration guidance, current-state notes, sample-wave docs, and npm publishing instructions now point at the `0.8.4` release surface."
|
|
34
|
+
],
|
|
35
|
+
"manualSteps": [
|
|
36
|
+
"Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.4` replay, projection, and component-threshold behavior.",
|
|
37
|
+
"If your adopted repo uses planner workflows and copied the starter planner corpus, sync `docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry in `docs/context7/bundles.json`.",
|
|
38
|
+
"If your repo copied the shipped starter docs or skills, sync the current operator runbook, architecture docs, launcher or orchestrator prompts, planner corpus, and relevant runtime or closure-role starter skills before relying on local runbooks.",
|
|
39
|
+
"If your repo keeps historical replay fixtures, replay at least one contradiction-blocked trace and one promoted-component trace after the upgrade so both code paths stay covered.",
|
|
40
|
+
"If an older adopted repo still carries legacy evaluator wording or pre-control-plane operator docs, complete the repo-owned prompt and runbook migration described in `docs/plans/migration.md` before cutting live waves on `0.8.4`."
|
|
41
|
+
],
|
|
42
|
+
"breaking": false
|
|
43
|
+
},
|
|
5
44
|
{
|
|
6
45
|
"version": "0.8.3",
|
|
7
46
|
"date": "2026-03-24",
|