@chllming/wave-orchestration 0.5.3 → 0.5.4

package/docs/plans/master-plan.md

@@ -9,8 +9,8 @@
 
 ## Near-Term Work
 
-- Keep the starter wave, role prompts, and component cutover matrix aligned with the shipped launcher behavior.
+- Keep the starter wave, role prompts, starter skills, and component cutover matrix aligned with the shipped launcher and planner behavior.
 - Expand `wave doctor` and migration guidance around cross-repo adoption, executor availability, and future breaking config changes.
-- Add richer starter templates for additional repository shapes after the generic single-repo path is stable.
+- Build on the shipped planner foundation with richer starter templates and eventually ad-hoc or forward-replan flows.
 - Extend replay and trace tooling from internal helpers and file-backed artifacts into easier operator workflows, larger historical fixtures, and a public replay surface if it proves stable.
-- Add the remaining roadmap items that are not yet shipped, especially richer capability routing and better operator workflows around cross-lane dependency tickets.
+- Add the remaining roadmap items that are not yet shipped, especially stronger operating-mode enforcement and better operator workflows around cross-lane dependency tickets.

package/docs/plans/migration.md

@@ -5,8 +5,8 @@
 1. Install the package from npmjs with `pnpm add -D @chllming/wave-orchestration`.
 2. For a fresh repo, run `pnpm exec wave init`.
 3. For a repo that already has Wave config, docs, or waves you want to preserve, run `pnpm exec wave init --adopt-existing`.
-4. Edit `wave.config.json` for the repo's docs, roles, validation rules, executor defaults, and component-cutover matrix paths.
-5. Replace the starter plan docs, sample waves, and component cutover matrix with repository-specific ones.
+4. Edit `wave.config.json` for the repo's docs, roles, validation rules, executor defaults, skill attachment policy, and component-cutover matrix paths.
+5. Replace the starter plan docs, sample waves, starter `skills/` bundles, and component cutover matrix with repository-specific ones.
 6. Configure Context7 bundles for the external libraries that repo actually uses.
 7. Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` until validation passes.
 8. Inspect seeded coordination and inbox artifacts with `pnpm exec wave coord show --lane main --wave 0 --dry-run --json` and `pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run`.
@@ -18,5 +18,6 @@ GitHub Packages remains available as an authenticated fallback path, and maintai
 
 - Package upgrades change the runtime behavior in `node_modules`; they do not copy a new starter scaffold into the repo.
 - `wave upgrade` writes `.wave/install-state.json` and `.wave/upgrade-history/*` only.
-- Existing `wave.config.json`, role prompts, plan docs, Context7 bundles, and wave files are never overwritten by the upgrade flow.
+- Existing `wave.config.json`, role prompts, plan docs, `skills/` bundles, Context7 bundles, and wave files are never overwritten by the upgrade flow.
+- Fresh `wave init` seeds the starter `skills/` library. `wave init --adopt-existing` records existing repo-owned skill bundles when they are already present, but does not replace or rewrite them.
 - The current runtime expects the post-roadmap model: typed coordination, compiled inboxes, `A8` integration, staged closure, orchestrator-first clarification, and operational runtime policy.

package/docs/plans/wave-orchestrator.md

@@ -2,6 +2,8 @@
 
 The Wave Orchestrator coordinates repository work as bounded execution waves.
 
+For the broader docs map, concept pages, and workflow guides, start at [docs/README.md](../README.md).
+
 ## What It Does
 
 - parses wave plans from `docs/plans/waves/`
@@ -19,6 +21,9 @@ The Wave Orchestrator coordinates repository work as bounded execution waves.
 
 ## Main Commands
 
+- `pnpm exec wave project setup`
+- `pnpm exec wave project show --json`
+- `pnpm exec wave draft --wave 1 --template implementation`
 - `pnpm exec wave init`
 - `pnpm exec wave init --adopt-existing`
 - `pnpm exec wave doctor`
@@ -37,10 +42,25 @@ The Wave Orchestrator coordinates repository work as bounded execution waves.
 
 ## Configuration
 
-- `wave.config.json` controls docs roots, shared plan docs, role prompts, validation thresholds, executor defaults, executor profiles, per-lane runtime policy, component-cutover matrix paths, capability-routing preferences, and Context7 bundle-index location.
+- `wave.config.json` controls docs roots, shared plan docs, role prompts, validation thresholds, executor defaults, executor profiles, per-lane runtime policy, skill attachment policy, component-cutover matrix paths, capability-routing preferences, and Context7 bundle-index location.
 - `docs/context7/bundles.json` controls allowed external library bundles and lane defaults.
 - `docs/plans/component-cutover-matrix.json` is the canonical machine-readable source for component maturity and per-wave promotion targets.
 - `.wave/install-state.json` records how the workspace was initialized and which package version is installed.
+- `.wave/project-profile.json` records planner defaults such as oversight mode, terminal surface, and deploy-environment memory.
+
+## Skill Packs
+
+- Wave skill bundles live under `skills/<skill-id>/`.
+- Each bundle requires `skill.json` and `SKILL.md`.
+- Bundles can also include runtime adapters at `adapters/<runtime>.md` for `codex`, `claude`, `opencode`, or `local`.
+- The starter config resolves skills in this order: global base, lane base, global role map, lane role map, global runtime map, lane runtime map, global deploy-kind map, lane deploy-kind map, then explicit per-agent `### Skills`.
+- The effective skill set is recomputed after final executor resolution, including retry-time runtime fallback, so a fallback from one runtime to another also swaps runtime-specific skill overlays.
+- Starter bundles in this repo cover:
+  - core Wave coordination and repo coding rules
+  - runtime packs for Codex, Claude, OpenCode, and local execution
+  - role packs for implementation, integration, documentation, evaluator, infra, deploy, and research work
+  - deploy and environment packs for Railway, Docker Compose, Kubernetes, SSH/manual rollout, and generic custom deploys
+  - explicit provider packs for GitHub release flow and AWS norms when a wave or lane wants to attach them
 
 ## Setup
 
@@ -48,7 +68,7 @@ The Wave Orchestrator coordinates repository work as bounded execution waves.
 2. Confirm `tmux` and at least one real executor (`codex`, `claude`, or `opencode`) are available if you want real wave execution.
 3. Run `pnpm exec wave init` for a fresh repo, or `pnpm exec wave init --adopt-existing` for a repo with existing Wave files you want preserved.
 4. Review [wave.config.json](../../wave.config.json).
-5. Review the role prompts and docs you want the repo to own.
+5. Review the role prompts, starter `skills/` bundles, and docs you want the repo to own.
 
 ## Recommended Launch Flow
 
@@ -143,6 +163,7 @@ pnpm exec wave changelog --since-installed
 - dashboards: `.tmp/<lane>-wave-launcher/dashboards/`
 - Context7 cache: `.tmp/<lane>-wave-launcher/context7-cache/`
 - executor overlays: `.tmp/<lane>-wave-launcher/executors/`
+  Each agent overlay can include `skills.resolved.md`, `skills.metadata.json`, and `<runtime>-skills.txt` in addition to the runtime-specific executor files.
 - cross-lane dependencies: `.tmp/wave-orchestrator/dependencies/`
   Required inbound tickets in this directory block both autonomous wave launch and lane finalization until they resolve.
 - cross-wave orchestration board: `.tmp/wave-orchestrator/messageboards/orchestrator.md`
@@ -164,7 +185,7 @@ pnpm exec wave changelog --since-installed
   - `structured-signals.json`
   - `quality.json`
   - `run-metadata.json`
-- `run-metadata.json` is the canonical trace index. It records attempt settings, artifact presence, executor history, prompt hashes, Context7 snippet hashes, the gate snapshot, `replayContext`, and the cumulative `historySnapshot` for that attempt.
+- `run-metadata.json` is the canonical trace index. It records attempt settings, artifact presence, executor history, prompt hashes, Context7 snippet hashes, resolved skill ids and bundle metadata, the gate snapshot, `replayContext`, and the cumulative `historySnapshot` for that attempt.
 - `outcome.json` is the stored replay baseline. Replay compares recomputed gates and quality against it instead of trusting only inline metadata.
 - For `traceVersion: 2`, launched agents must have copied prompt/log/status/inbox/summary artifacts, and promoted-component waves must include the copied component matrix JSON.
 - `quality.json` is cumulative through the current attempt. It is intended for regression comparison, not only for one-shot pass/fail reporting.
@@ -180,7 +201,9 @@ pnpm exec wave changelog --since-installed
 - From the configured thresholds onward, every non-A0/A8/A9 agent must declare `### Components` and emit `[wave-component]` markers for those components.
 - `### Capabilities` is optional and lets the scheduler route targeted follow-up work by capability.
 - `### Deliverables` is optional and lets a wave declare exact repo-relative file outputs that must exist, and that stay within the agent's declared file ownership, before an implementation agent can satisfy its exit contract.
+- `### Skills` is optional and adds explicit skill ids from `skills/` on top of the lane, role, runtime, and deploy-kind defaults.
 - `### Executor` can declare `profile`, `fallbacks`, `tags`, and runtime budgets in addition to vendor-specific overrides.
+- `## Deploy environments` lets the wave declare named deployment targets. The default deploy environment kind is also used for deploy-kind skill attachment.
 - Lane runtime policy can assign a default executor by role even when the wave omits `### Executor`.
 - Use `### Role prompts` for standing-role imports from `docs/agents/*.md`.
 - Optional standing roles available in this repo include `docs/agents/wave-infra-role.md` for infra proof and `docs/agents/wave-deploy-verifier-role.md` for rollout verification.
@@ -202,6 +225,7 @@ pnpm exec wave changelog --since-installed
 - `--executor local` exists only for smoke-testing prompt and closure behavior.
 - `--codex-sandbox danger-full-access` is the default because it avoids host bubblewrap assumptions.
 - Resolution order is: per-agent explicit executor id, executor profile id, lane role default, CLI `--executor`, then `executors.default`.
+- Skills resolve only after that executor choice is known. Runtime-specific skill overlays are regenerated whenever retry-time fallback changes the selected executor.
 - Runtime mix targets are enforced before launch and again before any retry-time fallback reassignment.
 - Fallbacks are declared in profiles or lane policy, can be applied automatically on retry when the next executor is available and still satisfies mix targets, and are recorded in the ledger, integration summary, and traces when used.
 - Generic `budget.minutes` caps per-agent attempt timeouts. Generic `budget.turns` seeds `claude.maxTurns` and `opencode.steps` when executor-specific values are not set.

package/docs/reference/runtime-config/README.md

@@ -38,6 +38,20 @@ Merge behavior:
 - lane executor overrides replace the corresponding global runtime fields before profile and agent resolution
 - a lane profile with the same name as a global profile replaces that profile definition for the lane
 
+Skill settings resolve after executor selection, because runtime and deploy-kind skill attachment depend on the resolved executor id and the wave's default deploy environment kind. The starter layering order is:
+
+1. `skills.base`
+2. `lanes.<lane>.skills.base`
+3. `skills.byRole[resolvedRole]`
+4. `lanes.<lane>.skills.byRole[resolvedRole]`
+5. `skills.byRuntime[resolvedExecutorId]`
+6. `lanes.<lane>.skills.byRuntime[resolvedExecutorId]`
+7. `skills.byDeployKind[defaultDeployEnvironmentKind]`
+8. `lanes.<lane>.skills.byDeployKind[defaultDeployEnvironmentKind]`
+9. agent `### Skills`
+
+When retry-time fallback changes the runtime, Wave recomputes the effective skill set and rewrites the executor overlay before relaunch.
+
 ## Common Fields
 
 These fields are shared across runtimes:
@@ -68,11 +82,16 @@ Wave writes runtime artifacts here:
 Common files:
 
 - `launch-preview.json`: resolved invocation lines, env vars, and retry mode
+- `skills.resolved.md`: canonical merged skill payload for the selected agent and runtime
+- `skills.metadata.json`: resolved skill ids, bundle metadata, hashes, and generated artifact paths
+- `<runtime>-skills.txt`: runtime-projected skill text used by the selected executor
 - `claude-system-prompt.txt`: generated Claude harness prompt overlay
 - `claude-settings.json`: generated Claude settings overlay when inline settings data is present
 - `opencode-agent-prompt.txt`: generated OpenCode harness prompt overlay
 - `opencode.json`: generated OpenCode runtime config overlay
 
+`launch-preview.json` also records the resolved skill metadata so dry-run can verify the exact runtime plus skill combination before any live launch.
+
 ## Recommended Validation Path
 
 Use dry-run before relying on a new runtime configuration:

package/docs/reference/skills.md

@@ -0,0 +1,156 @@
+# Skills Reference
+
+Skills are repo-owned reusable instruction bundles that can be attached by lane, role, runtime, deploy kind, or explicit per-agent declaration.
+
+## Canonical Bundle Layout
+
+Each bundle lives under `skills/<skill-id>/` and requires:
+
+- `skill.json`
+- `SKILL.md`
+
+Optional runtime adapters live under:
+
+- `adapters/codex.md`
+- `adapters/claude.md`
+- `adapters/opencode.md`
+- `adapters/local.md`
+
+Minimal example:
+
+```text
+skills/provider-railway/
+  skill.json
+  SKILL.md
+  adapters/
+    codex.md
+    claude.md
+    opencode.md
+    local.md
+```
+
+## `skill.json`
+
+Required fields in practice:
+
+- `id`
+- `title`
+- `description`
+
+The bundle directory name and manifest `id` must match the normalized skill id.
+
+## `SKILL.md`
+
+This is the canonical human-authored instruction body for the skill.
+
+Keep it focused on reusable guidance that should survive across:
+
+- many waves
+- multiple roles
+- multiple runtimes
+
+Do not duplicate volatile assignment-specific details that belong in the wave prompt instead.
+
+## `wave.config.json` Surface
+
+Top-level and lane-local skill attachment use the same shape:
+
+```json
+{
+  "skills": {
+    "dir": "skills",
+    "base": ["wave-core"],
+    "byRole": {
+      "implementation": ["role-implementation"]
+    },
+    "byRuntime": {
+      "codex": ["runtime-codex"]
+    },
+    "byDeployKind": {
+      "railway-mcp": ["provider-railway"]
+    }
+  }
+}
+```
+
+Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
+
+## Resolution Order
+
+Resolved skills attach in this order:
+
+1. global `skills.base`
+2. lane `skills.base`
+3. global `skills.byRole[resolvedRole]`
+4. lane `skills.byRole[resolvedRole]`
+5. global `skills.byRuntime[resolvedExecutorId]`
+6. lane `skills.byRuntime[resolvedExecutorId]`
+7. global `skills.byDeployKind[defaultDeployEnvironmentKind]`
+8. lane `skills.byDeployKind[defaultDeployEnvironmentKind]`
+9. agent `### Skills`
+
+Duplicates are removed while preserving first-seen order.
+
+## Per-Agent Attachment
+
+Wave markdown can add explicit skills:
+
+````md
+### Skills
+
+- provider-github-release
+- provider-aws
+````
+
+These are additive. They do not replace the base, role, runtime, or deploy-kind skill layers.
+
+## Deploy-Kind Attachment
+
+Deploy-kind mapping uses the wave's default deploy environment from `## Deploy environments`.
+
+If the wave declares:
+
+````md
+## Deploy environments
+
+- `prod`: `railway-mcp` default
+````
+
+then `byDeployKind.railway-mcp` skills become eligible for agents in that wave.
+
+## Runtime Projection
+
+The canonical bundle is shared, but projection is runtime specific:
+
+- Codex
+  Skill bundle directories become `--add-dir` inputs, and the merged skill text is included in the compiled prompt.
+- Claude
+  The merged skill payload is appended to the generated system-prompt overlay.
+- OpenCode
+  Skill instructions flow into `opencode.json`, and relevant files are attached through `--file`.
+- Local
+  Skill text stays prompt-only.
+
+## Generated Artifacts
+
+Executor overlay directories can contain:
+
+- `skills.resolved.md`
+- `skills.metadata.json`
+- `<runtime>-skills.txt`
+
+Dry-run `launch-preview.json` and live trace metadata also record the resolved skill ids and bundle metadata.
+
+## Validation
+
+`wave doctor` validates that all configured skill bundles referenced by lane skill config exist and can be loaded.
+
+Missing or malformed bundles are treated as configuration errors, not silent no-ops.
+
+## Best Practices
+
+- Put repo-specific norms into skills, not repeated wave prompts.
+- Keep skills short and reusable.
+- Use runtime adapters only for runtime-specific instructions.
+- Prefer deploy-kind mapping for environment conventions and explicit `### Skills` only for special cases.
+- Keep bundle ids stable so traces and prompt fingerprints stay intelligible across runs.