@chllming/wave-orchestration 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -1,6 +1,46 @@
 # Changelog
 
-## Unreleased
+## 0.8.6 - 2026-03-25
+
+### Added
+
+- Added canonical wave and per-agent signal projections under `.tmp/<lane>-wave-launcher/signals/`, plus the `signal-hygiene` starter skill for long-running agents that should wait on versioned wake signals instead of exiting after a one-shot pass.
+- Added seeded operator wrappers `scripts/wave-status.sh` and `scripts/wave-watch.sh` as thin readers over `wave control status --json`, including `--agent <id>` targeting and `--until-change` polling for external automation.
+- Added [docs/guides/signal-wrappers.md](./docs/guides/signal-wrappers.md), a dedicated operator guide for signal snapshots, wrapper exit codes, and the ack-loop contract used by long-running agents and the resident orchestrator.
+
+### Changed
+
+- Updated the shipped package metadata, README, current-state notes, migration guide, terminal and CLI docs, architecture docs, sample-wave docs, and npm publishing instructions to advertise `0.8.6` as the current release surface.
+- Documented the long-running signal model explicitly: prompt-level signal-state plus ack-path injection, versioned signal snapshots for both waves and agents, and wrapper-driven monitoring for external operator scripts.
+
+### Fixed And Hardened
+
+- Agent signal materialization now treats wave-level `completed` and `failed` as terminal, so stale answered feedback or pending coordination tasks cannot keep long-running agents in a non-terminal wait state after the wave has already closed.
+- Resident orchestrator signal versions now bump when only `targetAgentIds` change, so reroutes that keep the same signal kind still wake long-running residents and watchers correctly.
+- Wrapper exit semantics now treat `failed` as terminal with exit code `40`, so external monitors and `signal-hygiene` loops stop waiting when the wave fails instead of hanging on the generic active path.
+
+### Testing And Validation
+
+- Added regression coverage for terminal signal precedence, resident reroute versioning, and terminal-failure wrapper exits.
+- Re-ran the full Vitest suite, `wave doctor --json`, and `wave launch --lane main --dry-run --no-dashboard`.
+
+## 0.8.5 - 2026-03-25
+
+### Added
+
+- Shipped the optional `design` worker role as a first-class release surface instead of a main-branch-only addition, including the standing prompt in `docs/agents/wave-design-role.md`, the `role-design` skill bundle, and the `tui-design` reference bundle for terminal or operator-surface work.
+- Added support for hybrid design stewards: design agents stay 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 the implementation fan-out with normal proof obligations.
+- Added regression coverage for hybrid design validation, prompt shaping, local-executor marker emission, reducer task splitting, and post-design implementation fan-out.
+
+### Changed
+
+- Updated README, current-state notes, planner and authoring guides, sample-wave docs, skills reference, and architecture docs so they all describe the shipped `0.8.5` surface instead of distinguishing `0.8.4` from unpublished main-branch behavior.
+- Rewrote the migration guide as a practical upgrade guide for 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, with explicit repo-owned starter-surface sync guidance and concrete validation steps.
+
+### Fixed And Hardened
+
+- Design-aware validation, gates, retry or resume planning, reducer state, task materialization, and result-envelope projection now agree on the same hybrid-design contract instead of treating all design agents as permanently report-only.
+- Hybrid design prompts now switch cleanly between packet-first design work and implementation follow-through, and local-executor smoke behavior now emits both `[wave-design]` and implementation proof markers when that second pass is active.
 
 ## 0.8.4 - 2026-03-25
 

package/README.md

@@ -28,16 +28,18 @@ The framework does three things:
 1. Define shared docs plus `docs/plans/waves/wave-<n>.md` files, or generate them with `wave draft`.
 2. Run `wave launch --dry-run` to validate the wave and materialize prompts, shared summaries, inboxes, dashboards, and executor previews before any live execution.
 3. During live execution, implementation agents write claims, evidence, requests, and decisions into the canonical coordination log instead of relying on ad hoc terminal narration.
-4. The reducer and derived-state engines materialize blackboard projections from the canonical authority set: rolling board, shared summary, per-agent inboxes, ledger, docs queue, dependency views, and integration summaries. Helper-assignment blocking, retry target selection, and resume planning read from reducer state during live runs.
-5. The derived-state engine computes projection payloads and the projection writer persists them, so dashboards, traces, board projections, summaries, inboxes, ledgers, docs queues, and integration or security summaries all flow through one projection boundary.
-6. Live closure is result-envelope-first. Optional `cont-EVAL`, optional security review, integration, documentation, and `cont-QA` evaluate validated envelopes plus canonical state through the wave's effective closure-role bindings, with starter defaults (`E0`, security reviewer, `A8`, `A9`, `A0`) filling gaps only when a wave does not override them.
+4. Optional design workers can run before code-owning implementation workers. When present, they publish design packets under `docs/plans/waves/design/` and implementation does not start until those packets are `ready-for-implementation`.
+5. Design stewards are docs-first by default, but a wave may explicitly give one source-code ownership. That hybrid design steward runs a design pass first, then rejoins the implementation fan-out with normal proof obligations.
+6. The reducer and derived-state engines materialize blackboard projections from the canonical authority set: rolling board, shared summary, per-agent inboxes, ledger, docs queue, dependency views, and integration summaries. Helper-assignment blocking, retry target selection, and resume planning read from reducer state during live runs.
+7. The derived-state engine computes projection payloads and the projection writer persists them, so dashboards, traces, board projections, summaries, inboxes, ledgers, docs queues, and integration or security summaries all flow through one projection boundary.
+8. Live closure is result-envelope-first. Optional `cont-EVAL`, optional security review, integration, documentation, and `cont-QA` evaluate validated envelopes plus canonical state through the wave's effective closure-role bindings, with starter defaults (`E0`, security reviewer, `A8`, `A9`, `A0`) filling gaps only when a wave does not override them.
 
 ## Runtime Modules
 
 - `launcher.mjs`
   Thin orchestrator: parses args, acquires the launcher lock, and sequences the engines.
 - `implementation-engine.mjs`
-  Selects the implementation fan-out for a wave or retry attempt.
+  Selects the design-first or implementation fan-out for a wave or retry attempt.
 - `derived-state-engine.mjs`
   Computes shared summary, inboxes, assignments, dependency views, ledger, docs queue, and integration/security projection payloads from canonical state.
 - `gate-engine.mjs`
@@ -101,18 +103,18 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.4`
-- Release tag: [`v0.8.4`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.4)
+- `@chllming/wave-orchestration@0.8.6`
+- Release tag: [`v0.8.6`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.6)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.4`:
+Highlights in `0.8.6`:
 
-- Hermetic contradiction replay no longer depends on component-matrix parsing when the trace does not declare promoted components.
-- `requireComponentPromotionsFromWave` now gates both component-promotion proof validation and component-matrix current-level validation consistently in live and replay paths.
-- Projection persistence is now centralized under `projection-writer.mjs`, while `derived-state-engine.mjs` stays compute-only.
-- The migration guide now includes explicit upgrade guidance for `0.8.3`, `0.8.0`-`0.8.2`, `0.6.x`-`0.7.x`, and older starter repos instead of only a narrow point upgrade.
-- Release docs, sample waves, current-state notes, and npm publishing instructions now point at the `0.8.4` surface.
+- The shipped starter surface now includes `skills/signal-hygiene/` plus seeded `scripts/wave-status.sh` and `scripts/wave-watch.sh` wrappers for long-running-agent and operator wait loops.
+- Long-running agents and resident orchestrators now get prompt-level signal-state and signal-ack paths, so wakeups are edge-triggered by versioned signal changes instead of relying on terminal injection.
+- Versioned wave or agent signal snapshots are now a first-class operator surface under `.tmp/<lane>-wave-launcher/signals/`, with failure treated as terminal in both the runtime and the wrapper exit contract.
+- `0.8.5` design-role and hybrid design-steward behavior remains part of the shipped release surface, and the current migration guide now covers the new signal-wrapper model on top of that design-first runtime.
+- Release docs, current-state notes, and publishing instructions now point at the `0.8.6` surface.
 
 Requirements:
 
@@ -141,6 +143,19 @@ pnpm exec wave init --adopt-existing
 
 Fresh init also seeds a starter `skills/` library plus `docs/evals/benchmark-catalog.json`. The launcher projects those skill bundles into Codex, Claude, OpenCode, and local executor overlays after the final runtime for each agent is resolved, and waves that include `cont-EVAL` can declare `## Eval targets` against that catalog.
 
+The starter surface includes:
+
+- `docs/agents/wave-design-role.md`
+- `skills/role-design/`
+- `skills/tui-design/` for terminal and operator-surface design work
+- `skills/signal-hygiene/` for intentionally long-running watcher agents
+- `scripts/wave-status.sh` and `scripts/wave-watch.sh` for external wait loops
+- `wave.config.json` defaults for `roles.designRolePromptPath`, `skills.byRole.design`, and the `design-pass` executor profile
+
+Interactive `wave draft` scaffolds the docs-first design-steward path. If you want a hybrid design steward, author that wave explicitly or use an agentic planner payload that gives the same design agent implementation-owned paths plus the normal implementation contract sections.
+
+If a non-resident agent should stay alive and react only to orchestrator-written signal changes, add `signal-hygiene` explicitly in `### Skills`. That bundle uses the prompt-injected signal-state and ack paths instead of inventing a second wakeup surface. For shell automation and the wrapper contract, see [docs/guides/signal-wrappers.md](./docs/guides/signal-wrappers.md).
+
 When runtime launch commands detect a newer npmjs release, Wave prints a non-blocking update notice on stderr. The fast path is `pnpm exec wave self-update`, which updates the dependency, prints the changelog delta, and then records the workspace upgrade report.
 
 ## Common Commands
@@ -172,7 +187,7 @@ pnpm exec wave self-update
 - `wave launch` and `wave autonomous`
   Live execution, dry-run validation, retry cadence, terminal surfaces, and orchestrator options.
 - `wave control`
-  Read-only live status plus operator task, rerun, proof, and telemetry control surfaces.
+  Read-only live status plus operator task, rerun, proof, telemetry, and versioned signal surfaces. Seeded helper scripts `scripts/wave-status.sh` and `scripts/wave-watch.sh` are thin readers over `wave control status --json`.
 - `wave coord` and `wave dep`
   Coordination-log and cross-lane dependency utilities. `wave control` is the preferred operator surface; `wave coord` remains useful for direct log inspection and rendering.
 - `wave project`, `wave draft`, and `wave adhoc`
@@ -213,8 +228,11 @@ codex mcp list
 - [docs/concepts/runtime-agnostic-orchestration.md](./docs/concepts/runtime-agnostic-orchestration.md): how one orchestration substrate spans Claude, Codex, OpenCode, and local execution
 - [docs/concepts/context7-vs-skills.md](./docs/concepts/context7-vs-skills.md): compiled context, external truth, and repo-owned operating knowledge
 - [docs/guides/planner.md](./docs/guides/planner.md): `wave project` and `wave draft` workflow
+- [docs/agents/wave-design-role.md](./docs/agents/wave-design-role.md): standing prompt for the optional pre-implementation design steward
 - [docs/guides/terminal-surfaces.md](./docs/guides/terminal-surfaces.md): tmux, VS Code terminal registry, and dry-run surfaces
+- [docs/guides/signal-wrappers.md](./docs/guides/signal-wrappers.md): versioned signal snapshots, wrapper scripts, and long-running-agent ack loops
 - [docs/reference/sample-waves.md](./docs/reference/sample-waves.md): showcase-first authored waves, including a high-fidelity repo-landed rollout example
+- [docs/plans/examples/wave-example-design-handoff.md](./docs/plans/examples/wave-example-design-handoff.md): optional design-steward example that hands a validated design packet to downstream implementation owners
 - [docs/plans/examples/wave-example-rollout-fidelity.md](./docs/plans/examples/wave-example-rollout-fidelity.md): concrete example of what good wave fidelity looks like for a narrow, closure-ready outcome
 - [docs/reference/cli-reference.md](./docs/reference/cli-reference.md): complete CLI syntax for all commands and flags
 - [docs/plans/end-state-architecture.md](./docs/plans/end-state-architecture.md): canonical runtime architecture, engine boundaries, and artifact ownership

package/docs/README.md

@@ -35,6 +35,10 @@ The useful path is journey-first:
   Read [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md) for the compiled-context model: shared summary, inboxes, project defaults, skills, Context7, and runtime overlays.
 - Drafting or revising waves:
   Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) as the operator runbook.
+- Adding an optional pre-implementation design steward:
+  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.8.6` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
+- Want signal-driven automation or long-running watcher loops:
+  Read [guides/signal-wrappers.md](./guides/signal-wrappers.md). It covers the seeded `wave-status.sh` and `wave-watch.sh` wrappers, the versioned signal snapshot files, and the ack-loop contract behind `signal-hygiene`.
 - Adding a security review pass:
   Read [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) and the standing reviewer prompt in [agents/wave-security-role.md](./agents/wave-security-role.md).
 - Upgrading an existing repo:

package/docs/agents/wave-design-role.md

@@ -0,0 +1,47 @@
+---
+title: "Wave Design Role"
+summary: "Standing prompt for an optional pre-implementation design steward that produces a design packet and explicit implementation handoff."
+---
+
+# Wave Design Role
+
+Use this prompt when an agent should act as the design steward for a wave.
+
+## Standing prompt
+
+```text
+You are the wave design steward for the current wave.
+
+Your job is to produce an implementation-ready design packet before code-owning implementation work begins. You are report-first and docs/spec-owned by default. Do not silently expand into broad coding work unless the wave explicitly assigns it.
+If the wave explicitly gives you source-code ownership, expect a hybrid two-pass contract: design packet first, then a later implementation pass for those owned files.
+
+Operating rules:
+- Re-read the compiled shared summary, your inbox, the generated wave board projection, and any earlier packets before major decisions.
+- Turn ambiguity into explicit decisions, assumptions, and exact open questions.
+- Keep interface impacts concrete: name exact files, APIs, schema fields, CLI flags, contracts, and ownership changes.
+- If the wave touches terminal UX, dashboards, or other operator surfaces, use `skills/tui-design/references/tui-design.md` as the deep heuristic reference.
+- Keep operator surfaces thin by design: ask for reducer or projection truth instead of inventing UI-local state or hiding system uncertainty behind polish.
+- Prefer exact observations tied to concrete surfaces, state transitions, interaction paths, and missing projection-backed affordances over generic design commentary.
+- Prefer a narrow, actionable handoff over a long architecture essay.
+- If the wave needs a human choice or unresolved upstream answer before coding, fail closed and say so directly.
+- Route code changes back to implementation owners unless the wave explicitly gives you source-code ownership.
+
+What you must do:
+- leave one design packet with these sections in order:
+  `Problem`
+  `Constraints`
+  `Decisions`
+  `Assumptions`
+  `Open Questions`
+  `Interface Impacts`
+  `Validation Plan`
+  `Implementation Handoff`
+- make the `Implementation Handoff` section concrete enough that implementation owners can start without re-deriving the same design
+- emit one final structured marker:
+  `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`
+- when you later rejoin implementation as a hybrid design steward, keep the design packet current and re-emit `[wave-design]` alongside the normal implementation proof markers
+
+Use `ready-for-implementation` only when the design packet is sufficient for downstream implementation owners to proceed.
+Use `needs-clarification` when a specific unresolved question should stop implementation until it is answered.
+Use `blocked` only when the wave cannot safely continue because the design packet found a fundamental blocker.
+```

package/docs/concepts/what-is-a-wave.md

@@ -20,7 +20,7 @@ It is not just a prompt file. A wave is a bounded slice of repository work with:
 - Wave
   One numbered work package inside a lane, usually stored as `docs/plans/waves/wave-<n>.md`.
 - Agent
-  One role inside the wave, such as implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, or deploy.
+  One role inside the wave, such as design, implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, or deploy.
 - Attempt
   One execution pass of a wave. A wave can have multiple attempts due to retries or fallback.
 - Closure
@@ -89,7 +89,7 @@ Inside each agent block, the important sections are:
 
 ## Standard Roles
 
-The starter runtime ships with three default closure roles plus up to two optional review specialists. A wave may override the role ids, but the closure semantics stay the same:
+The starter runtime ships with three default closure roles plus optional specialists. A wave may override the role ids, but the closure semantics stay the same:
 
 - `A8`
   Integration steward
@@ -101,6 +101,8 @@ The starter runtime ships with three default closure roles plus up to two option
   Optional `cont-EVAL` for iterative benchmark or output tuning; report-only by default, implementation-owning only when explicitly assigned non-report files
 - `A7`
   Optional security reviewer; report-only by default and used to publish a threat-model-first security review before integration closure
+- `D1` or another custom id
+  Optional design steward; report-first and docs/spec-owned by default, used to publish a design packet before code-owning implementation fans out. If the wave explicitly gives that same agent source-code ownership, it becomes a hybrid design steward that rejoins the later implementation fan-out.
 
 Implementation or specialist agents own the actual work slices. Closure roles do not replace implementation ownership; they decide whether the combined result is closure-ready. `cont-EVAL` is the one hybrid role: most waves keep it report-only, but human-authored waves may assign explicit tuning files to `E0`, in which case it must satisfy both implementation proof and eval proof.
 
@@ -109,11 +111,12 @@ Implementation or specialist agents own the actual work slices. Closure roles do
 1. Author or draft the wave.
 2. Run `wave launch --dry-run --no-dashboard`.
 3. The launcher parses the wave, resolves executors and skills, rebuilds reducer state, and materializes operator surfaces.
-4. A live run launches implementation agents first when implementation work remains.
-5. Agents write structured coordination events instead of relying on ad hoc terminal output.
-6. The reducer, gate engine, and retry or closure engines evaluate implementation contracts, promoted-component proof, helper assignments, dependencies, contradictions, and clarification state.
-7. If implementation is ready, closure runs in order: optional `cont-EVAL`, optional security review, integration, documentation, then cont-QA.
-8. The attempt is captured in per-wave traces, ledgers, inboxes, summaries, and copied artifacts.
+4. A live run launches design agents first when the wave declares them.
+5. Code-owning implementation agents start only after every design packet is `ready-for-implementation`; hybrid design stewards rejoin that implementation fan-out once the design gate clears.
+6. Agents write structured coordination events instead of relying on ad hoc terminal output.
+7. The reducer, gate engine, and retry or closure engines evaluate design readiness, implementation contracts, promoted-component proof, helper assignments, dependencies, contradictions, and clarification state.
+8. If implementation is ready, closure runs in order: optional `cont-EVAL`, optional security review, integration, documentation, then cont-QA.
+9. The attempt is captured in per-wave traces, ledgers, inboxes, summaries, and copied artifacts.
 
 ## Runtime And Operating Posture
 
@@ -170,6 +173,7 @@ That is why switching an agent between Codex, Claude, or OpenCode does not requi
 A wave is not done because an agent said so. It is done only when the runtime surfaces agree:
 
 - implementation exit contracts pass
+- if present, design packets are complete and every design worker reports `ready-for-implementation`
 - required deliverables exist and stay within ownership boundaries
 - required proof artifacts exist when the wave declares proof-first live evidence
 - required component proof and promotions pass

package/docs/context7/bundles.json

@@ -13,33 +13,28 @@
       "description": "Node.js and TypeScript runtime docs for JavaScript service and tooling work.",
       "libraries": [
         {
-          "libraryName": "nodejs",
+          "libraryId": "/nodejs/node",
           "queryHint": "runtime APIs, child processes, streams, filesystem behavior, and process lifecycle"
         },
         {
-          "libraryName": "typescript",
+          "libraryId": "/microsoft/typescript",
           "queryHint": "types, declarations, module resolution, tsconfig, and compiler behavior"
         }
       ]
     },
     "planner-agentic": {
-      "description": "Repo-curated planning research published as a custom Context7 library for the agentic planner.",
-      "libraries": [
-        {
-          "libraryName": "wave-planner-agentic",
-          "queryHint": "wave planning best practices, maturity alignment, closure gates, proof surfaces, rollout evidence, and coordination failure prevention"
-        }
-      ]
+      "description": "Placeholder bundle for a repo-published planner corpus. Keep this empty until the planner corpus is published to Context7 and the exact libraryId is known.",
+      "libraries": []
     },
     "react-web": {
       "description": "React and Next.js docs for frontend work.",
       "libraries": [
         {
-          "libraryName": "react",
+          "libraryId": "/reactjs/react.dev",
           "queryHint": "components, hooks, rendering, forms, and data flow"
         },
         {
-          "libraryName": "nextjs",
+          "libraryId": "/websites/nextjs",
           "queryHint": "routing, server components, data fetching, and app router behavior"
         }
       ]
@@ -48,11 +43,11 @@
       "description": "Python backend docs for API and worker services.",
       "libraries": [
         {
-          "libraryName": "python",
+          "libraryId": "/websites/python_3",
           "queryHint": "language features, packaging, typing, and standard library behavior"
         },
         {
-          "libraryName": "fastapi",
+          "libraryId": "/fastapi/fastapi",
           "queryHint": "routing, request validation, dependency injection, and OpenAPI behavior"
         }
       ]
@@ -61,11 +56,15 @@
       "description": "Go service and workflow docs for backend work.",
       "libraries": [
         {
-          "libraryName": "golang",
-          "queryHint": "packages, testing, concurrency, errors, and module layout"
+          "libraryId": "/websites/go_dev_ref_spec",
+          "queryHint": "language syntax, testing, concurrency, errors, and module semantics"
+        },
+        {
+          "libraryId": "/websites/pkg_go_dev",
+          "queryHint": "standard packages, modules, package layout, and reference behavior"
         },
         {
-          "libraryName": "temporal",
+          "libraryId": "/temporalio/documentation",
           "queryHint": "workflow setup, activities, schedules, retries, and worker bootstrap"
         }
       ]
@@ -74,11 +73,11 @@
       "description": "Database and storage docs for persistence work.",
       "libraries": [
         {
-          "libraryName": "postgresql",
+          "libraryId": "/websites/postgresql_current",
           "queryHint": "schema changes, indexes, transactions, constraints, and query behavior"
         },
         {
-          "libraryName": "sqlite",
+          "libraryId": "/websites/sqlite_docs",
           "queryHint": "local persistence, fts, schema migration, and durability patterns"
         }
       ]
@@ -87,11 +86,11 @@
       "description": "Infrastructure and service-manager docs for deployment and operations work.",
       "libraries": [
         {
-          "libraryName": "docker",
+          "libraryId": "/docker/docs",
           "queryHint": "images, builds, volumes, networking, and runtime configuration"
         },
         {
-          "libraryName": "systemd",
+          "libraryId": "/websites/systemd_io",
           "queryHint": "units, dependencies, restart policies, readiness, and service management"
         }
       ]

package/docs/context7/planner-agent/README.md

@@ -13,7 +13,10 @@ Why it exists:
 Publish target:
 
 - bundle id: `planner-agentic`
-- library name: `wave-planner-agentic`
+- committed repo config should stay empty until the planner corpus is published
+  and Context7 returns an exact `libraryId`
+- once published, record that returned `libraryId` in
+  `docs/context7/bundles.json` instead of committing a guessed library name
 
 Refresh the copied corpus after updating the agent-context cache:
 

package/docs/guides/author-and-run-waves.md

@@ -43,12 +43,38 @@ When you review the generated wave, tighten the parts the planner cannot fully i
 - file ownership
 - validation commands
 - proof artifacts
+- whether the wave needs an optional pre-implementation design steward
 - `cont-EVAL` targets when needed
 - security review expectations when needed
 - explicit `### Skills` only where defaults are not enough
+- `signal-hygiene` only when an agent is intentionally long-running and should wait for orchestrator-written signal changes instead of exiting after a one-shot pass
 
 If you want examples of denser hand-authored waves, read [docs/reference/sample-waves.md](../reference/sample-waves.md).
 
+## 2a. Add A Design Steward Only When It Actually Helps
+
+Use the optional `design` role when the wave needs a concrete handoff packet before coding starts, not just more prose.
+
+Good fits:
+
+- architecture-heavy or interface-heavy changes
+- multi-owner waves where downstream implementers need the same decisions and assumptions
+- ambiguous tasks where open questions should become explicit before code owners fan out
+
+The starter contract in `0.8.6` is:
+
+- import `docs/agents/wave-design-role.md`
+- own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
+- keep that agent docs/spec-only by default
+- add explicit `### Skills` such as `tui-design` when the packet covers terminal UX, dashboards, or other operator surfaces
+- end with `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`
+
+When a wave includes one or more design agents, the runtime runs them before code-owning implementation agents. Implementation does not start until every design packet is `ready-for-implementation`. `needs-clarification` and `blocked` behave like normal wave blockers.
+
+If a wave explicitly gives a design steward source-code ownership, that agent becomes a hybrid design steward. The runtime still runs its design pass first, then includes the same agent in the later implementation fan-out with normal proof obligations. Interactive `wave draft` scaffolds the docs-first default; use manual edits or an agentic planner payload when you want the hybrid path.
+
+For long-running non-design agents that should stay alive and react only to feedback or coordination changes, add `signal-hygiene` explicitly in `### Skills`. That skill is not for normal one-shot implementation work.
+
 ## 3. Choose The Execution Posture
 
 Every wave should be authored with an explicit operating posture in mind:
@@ -115,6 +141,7 @@ Useful flags:
 
 A wave is not done when an implementation agent says it is done. Closure depends on the canonical authority set, typed result state, and the combined runtime projections:
 
+- if present, design packets are complete and `ready-for-implementation` before code-owning work starts
 - implementation contracts pass
 - required deliverables exist
 - proof artifacts exist when the wave requires them

package/docs/guides/planner.md

@@ -6,6 +6,8 @@ If you want the full author-to-launch workflow, start with [author-and-run-waves
 
 It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
 
+The published `0.8.6` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
+
 ## What Ships Today
 
 - `wave project setup`
@@ -14,6 +16,7 @@ It reduces repeated setup questions, stores project defaults, and generates wave
 - agentic `wave draft --agentic --task "..."`
 - planner run review via `wave draft --show-run <run-id>`
 - explicit materialization via `wave draft --apply-run <run-id>`
+- worker role kinds including optional `design`
 - persistent project memory in `.wave/project-profile.json`
 - transient planner packets in `.wave/planner/runs/<run-id>/`
 - planner-run Context7 injection via `planner.agentic.context7Bundle`
@@ -87,6 +90,8 @@ The planner agent reads repo-local planning sources directly, and it can also
 prefetch a planner-specific Context7 bundle when
 `planner.agentic.context7Bundle` points at a published library. The tracked
 source corpus for that library lives under `docs/context7/planner-agent/`.
+The starter repo keeps that bundle as a placeholder until the planner corpus is
+actually published and the exact `libraryId` is known.
 
 Supported templates today:
 
@@ -95,6 +100,24 @@ Supported templates today:
 - `infra`
 - `release`
 
+Supported worker role kinds today:
+
+- `design`
+- `implementation`
+- `qa`
+- `infra`
+- `deploy`
+- `research`
+- `security`
+
+The interactive draft flow now offers `design` as a first-class worker role. Agentic planner payloads also accept `workerAgents[].roleKind = "design"`.
+
+`design` uses the `design-pass` executor profile by default and scaffolds the docs-first packet path before coding starts. The normal starter packet path is:
+
+- `docs/plans/waves/design/wave-<n>-<agentId>.md`
+
+If you want a hybrid design steward, keep the same design packet path but explicitly add implementation-owned paths and the normal implementation contract sections in the authored wave or agentic planner payload. Interactive draft does not ask a separate hybrid-design question yet; it stays on the docs-first default.
+
 Interactive draft writes canonical waves immediately:
 
 - `docs/plans/waves/specs/wave-<n>.json`
@@ -125,6 +148,7 @@ The draft flow asks for structured inputs such as:
 - deploy environments in scope
 - component promotions and target levels
 - worker count and worker roles
+- whether a wave needs a pre-implementation design steward
 - executor profiles
 - file ownership
 - Context7 defaults and per-agent bundles
@@ -133,6 +157,27 @@ The draft flow asks for structured inputs such as:
 
 That gives you a wave that is much closer to launch-ready than a blank markdown template.
 
+## When To Use `design`
+
+Use a design worker when the wave is heavy on:
+
+- architecture or sequencing decisions
+- interface or contract changes across multiple owners
+- ambiguous requirements that should become explicit assumptions and open questions
+- decision-lineage that downstream implementers should not have to rediscover
+
+Do not use a design worker just because the wave is large. If the task is straightforward code change plus validation, normal implementation agents are enough.
+
+A design worker should usually:
+
+- import `docs/agents/wave-design-role.md`
+- own one design packet under `docs/plans/waves/design/`
+- stay docs/spec-only unless the wave explicitly assigns code ownership
+- add `tui-design` in `### Skills` when the packet owns terminal UX, dashboards, or other operator surfaces
+- emit a final `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> ...` marker
+
+If the wave does explicitly assign code ownership, the same design agent becomes a hybrid design steward: it runs the design pass first, then rejoins implementation with the normal implementation proof contract while still keeping the packet current and re-emitting `[wave-design]`.
+
 ## Planner And Skills
 
 The planner does not auto-discover every possible skill bundle yet, but it supports explicit per-agent `### Skills` in the rendered output.
@@ -169,6 +214,7 @@ If you want concrete authored examples after the planner baseline, see [docs/ref
 - Treat `### Deliverables` and `### Proof artifacts` as part of the plan contract, not optional polish.
 - Keep `docs/context7/planner-agent/` in sync with the selected planning cache slice before publishing the planner bundle to Context7.
 - Add explicit `### Skills` only when the lane, role, runtime, and deploy-kind defaults are not enough.
+- Use `design` when you need a reusable handoff packet; keep straightforward implementation slices on `implementation`.
 - Use the component matrix as a planning contract, not just a reporting surface.
 - Prefer updating the project profile when the same answers recur across waves.
 - Use [docs/reference/sample-waves.md](../reference/sample-waves.md) when you want examples of denser human-authored waves that combine multiple modern surfaces such as `cont-EVAL`, delegated benchmark families, or proof-first live validation.