@chllming/wave-orchestration 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {
@@ -16,6 +16,7 @@
   },
   "files": [
     "scripts",
+    "skills",
     "docs",
     "releases",
     "wave.config.json",

package/releases/manifest.json

@@ -2,6 +2,23 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.5.4",
+      "date": "2026-03-22",
+      "summary": "Planner foundation, cross-runtime skills, and clearer docs and reconcile output.",
+      "features": [
+        "The planner foundation now ships with `.wave/project-profile.json`, `wave project setup|show`, and `wave draft`, which writes both structured JSON specs and launcher-compatible wave markdown.",
+        "Canonical repo-owned skill bundles now live under `skills/`, with attachment by base, role, runtime, deploy kind, and explicit per-agent `### Skills`, then projection into Codex, Claude Code, OpenCode, and local executor overlays.",
+        "The docs surface now includes a docs index plus focused concept, guide, and reference pages for waves, planner workflow, operating modes, Context7 vs skills, terminal surfaces, and runtime-agnostic orchestration.",
+        "Reconcile output now explains why incomplete waves cannot be reconstructed, making `wave launch --reconcile-status` failures easier to interpret."
+      ],
+      "manualSteps": [
+        "After upgrading, run `pnpm exec wave project setup` once so the repo has an explicit project profile with default lane, oversight mode, terminal surface, and deploy-environment memory.",
+        "Review `wave.config.json` `skills` mappings and the seeded `skills/` bundles before relying on runtime-specific or deploy-specific skill attachment.",
+        "Dry-run at least one generated or existing wave with `pnpm exec wave launch --lane main --dry-run --no-dashboard` to inspect the new skill overlay artifacts and launch previews."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.5.3",
       "date": "2026-03-22",

package/scripts/wave-orchestrator/config.mjs

@@ -1,6 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { WORKSPACE_ROOT } from "./roots.mjs";
+import {
+  emptySkillsConfig,
+  mergeSkillsConfig,
+  normalizeSkillsConfig,
+} from "./skills.mjs";
 
 const REPO_ROOT = WORKSPACE_ROOT;
 
@@ -388,6 +393,10 @@ function normalizeRuntimePolicy(rawRuntimePolicy = {}) {
   };
 }
 
+function normalizeLaneSkills(rawSkills = {}, lane = "skills", options = {}) {
+  return normalizeSkillsConfig(rawSkills, lane, options);
+}
+
 function normalizeClaudePromptMode(value, label = "executors.claude.appendSystemPromptMode") {
   const normalized = String(value || "append")
     .trim()
@@ -751,6 +760,7 @@ export function loadWaveConfig(configPath = DEFAULT_WAVE_CONFIG_PATH) {
     roles: normalizeRoles(rawConfig.roles),
     validation: normalizeValidation(rawConfig.validation),
     executors: normalizeExecutors(rawConfig.executors),
+    skills: normalizeLaneSkills(rawConfig.skills, "skills"),
     capabilityRouting: normalizeCapabilityRouting(rawConfig.capabilityRouting),
     runtimePolicy: normalizeRuntimePolicy(rawConfig.runtimePolicy),
     sharedPlanDocs,
@@ -785,6 +795,12 @@ export function resolveLaneProfile(config, laneInput = config.defaultLane) {
   const executors = normalizeExecutors(
     mergeExecutors(config.executors, laneConfig.executors),
   );
+  const skills = mergeSkillsConfig(
+    config.skills || emptySkillsConfig(),
+    normalizeLaneSkills(laneConfig.skills, `${lane}.skills`, {
+      preserveOmittedDir: true,
+    }),
+  );
   const capabilityRouting = normalizeCapabilityRouting({
     ...config.capabilityRouting,
     ...(laneConfig.capabilityRouting || {}),
@@ -812,6 +828,7 @@ export function resolveLaneProfile(config, laneInput = config.defaultLane) {
     roles,
     validation,
     executors,
+    skills,
     capabilityRouting,
     runtimePolicy,
     paths: {

package/scripts/wave-orchestrator/context7.mjs

@@ -221,6 +221,15 @@ export function buildAgentPromptFingerprintSource(agent) {
     components: agent?.components || [],
     componentTargets: agent?.componentTargets || null,
     executorResolved: agent?.executorResolved || null,
+    skillsResolved: agent?.skillsResolved
+      ? {
+          ids: agent.skillsResolved.ids || [],
+          role: agent.skillsResolved.role || null,
+          runtime: agent.skillsResolved.runtime || null,
+          deployKind: agent.skillsResolved.deployKind || null,
+          promptHash: agent.skillsResolved.promptHash || null,
+        }
+      : null,
   });
 }
 

package/scripts/wave-orchestrator/coordination.mjs

@@ -349,6 +349,21 @@ export function buildExecutionPrompt({
           "",
         ]
       : [];
+  const skillLines =
+    Array.isArray(agent.skillsResolved?.ids) && agent.skillsResolved.ids.length > 0
+      ? [
+          "Active skill packs for this run:",
+          ...agent.skillsResolved.ids.map((skillId) => `- ${skillId}`),
+          "- Treat the following skill payload as additive guidance. Repository source, standing role prompts, and ownership boundaries remain authoritative.",
+          "",
+          "## Skill context",
+          "",
+          "```text",
+          agent.skillsResolved.promptText || "",
+          "```",
+          "",
+        ]
+      : [];
 
   return [
     `Working directory: ${REPO_ROOT}`,
@@ -413,6 +428,7 @@ export function buildExecutionPrompt({
     ...promotedComponentLines,
     ...ownedComponentLines,
     ...deliverableLines,
+    ...skillLines,
     ...context7PromptLines,
     "Assigned implementation prompt:",
     "```",

package/scripts/wave-orchestrator/executors.mjs

@@ -134,7 +134,7 @@ function buildClaudeSettingsPath(executor, overlayDir) {
   return settingsPath;
 }
 
-function buildOpenCodeConfig({ agent, executor, agentName, promptFileName, overlayDir }) {
+function buildOpenCodeConfig({ agent, executor, agentName, promptFileName, overlayDir, skillProjection }) {
   const promptAgent = {
     description: `Wave agent ${agent.agentId}: ${agent.title}`,
     mode: "primary",
@@ -149,7 +149,11 @@ function buildOpenCodeConfig({ agent, executor, agentName, promptFileName, overl
   const baseAgentConfig = isPlainObject(baseConfig.agent) ? baseConfig.agent : {};
   const config = mergeJsonObjects(baseConfig, {
     $schema: baseConfig.$schema || "https://opencode.ai/config.json",
-    instructions: mergeUniqueStringArrays(baseConfig.instructions, executor.opencode.instructions),
+    instructions: mergeUniqueStringArrays(
+      baseConfig.instructions,
+      executor.opencode.instructions,
+      skillProjection?.opencodeInstructions,
+    ),
     agent: {
       ...baseAgentConfig,
       [agentName]: mergeJsonObjects(baseAgentConfig[agentName], promptAgent),
@@ -201,7 +205,11 @@ export function buildCodexExecInvocation(
 function buildClaudeLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
   const executor = agent.executorResolved;
   const systemPromptPath = path.join(overlayDir, "claude-system-prompt.txt");
-  writeTextAtomic(systemPromptPath, `${renderHarnessSystemPrompt(agent, "claude")}\n`);
+  const skillText = String(agent?.skillsResolved?.promptText || "").trim();
+  writeTextAtomic(
+    systemPromptPath,
+    `${renderHarnessSystemPrompt(agent, "claude")}${skillText ? `\n\n${skillText}` : ""}\n`,
+  );
   const tokens = [executor.claude.command, "-p", "--no-session-persistence"];
   const settingsPath = buildClaudeSettingsPath(executor, overlayDir);
   appendSingleValueFlag(tokens, "--output-format", executor.claude.outputFormat || "text");
@@ -234,7 +242,7 @@ function buildClaudeLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
   };
 }
 
-function buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
+function buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir, skillProjection }) {
   const executor = agent.executorResolved;
   const requestedAgentName = String(executor.opencode.agent || `wave-${agent.agentId}`)
     .trim()
@@ -252,12 +260,17 @@ function buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
     agentName,
     promptFileName,
     overlayDir,
+    skillProjection,
   });
   const tokens = [executor.opencode.command, "run", "--agent", shellQuote(agentName)];
   appendSingleValueFlag(tokens, "--model", executor.opencode.model || executor.model);
   appendSingleValueFlag(tokens, "--format", executor.opencode.format || "default");
   appendSingleValueFlag(tokens, "--attach", executor.opencode.attach);
-  appendRepeatedFlag(tokens, "--file", executor.opencode.files);
+  appendRepeatedFlag(
+    tokens,
+    "--file",
+    mergeUniqueStringArrays(executor.opencode.files, skillProjection?.opencodeFiles),
+  );
   appendSingleValueFlag(tokens, "--title", `wave-${agent.agentId}`);
   return {
     executorId: "opencode",
@@ -286,7 +299,7 @@ function buildLocalLaunchSpec({ promptPath, logPath }) {
   };
 }
 
-function buildCodexLaunchSpec({ agent, promptPath, logPath }) {
+function buildCodexLaunchSpec({ agent, promptPath, logPath, skillProjection }) {
   const executor = agent.executorResolved;
   return {
     executorId: "codex",
@@ -304,7 +317,7 @@ function buildCodexLaunchSpec({ agent, promptPath, logPath }) {
           config: executor.codex.config,
           search: executor.codex.search,
           images: executor.codex.images,
-          addDirs: executor.codex.addDirs,
+          addDirs: mergeUniqueStringArrays(executor.codex.addDirs, skillProjection?.codexAddDirs),
           json: executor.codex.json,
           ephemeral: executor.codex.ephemeral,
         },
@@ -313,19 +326,19 @@ function buildCodexLaunchSpec({ agent, promptPath, logPath }) {
   };
 }
 
-export function buildExecutorLaunchSpec({ agent, promptPath, logPath, overlayDir }) {
+export function buildExecutorLaunchSpec({ agent, promptPath, logPath, overlayDir, skillProjection }) {
   const executorId = normalizeExecutorMode(agent?.executorResolved?.id || DEFAULT_EXECUTOR_MODE);
   ensureDirectory(overlayDir);
   if (executorId === "local") {
     return buildLocalLaunchSpec({ promptPath, logPath });
   }
   if (executorId === "claude") {
-    return buildClaudeLaunchSpec({ agent, promptPath, logPath, overlayDir });
+    return buildClaudeLaunchSpec({ agent, promptPath, logPath, overlayDir, skillProjection });
   }
   if (executorId === "opencode") {
-    return buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir });
+    return buildOpenCodeLaunchSpec({ agent, promptPath, logPath, overlayDir, skillProjection });
   }
-  return buildCodexLaunchSpec({ agent, promptPath, logPath });
+  return buildCodexLaunchSpec({ agent, promptPath, logPath, skillProjection });
 }
 
 export function commandForExecutor(executor, executorId = executor?.id) {

package/scripts/wave-orchestrator/install.mjs

@@ -7,6 +7,7 @@ import {
 import { buildLanePaths, ensureDirectory, PACKAGE_ROOT, readJsonOrNull, REPO_ROOT, writeJsonAtomic } from "./shared.mjs";
 import { loadWaveConfig } from "./config.mjs";
 import { applyExecutorSelectionsToWave, parseWaveFiles, validateWaveDefinition } from "./wave-files.mjs";
+import { validateLaneSkillConfiguration } from "./skills.mjs";
 
 export const INSTALL_STATE_SCHEMA_VERSION = 1;
 export const INSTALL_STATE_DIR = ".wave";
@@ -16,10 +17,17 @@ export const CHANGELOG_MANIFEST_PATH = path.join(PACKAGE_ROOT, "releases", "mani
 export const PACKAGE_METADATA_PATH = path.join(PACKAGE_ROOT, "package.json");
 export const STARTER_TEMPLATE_PATHS = [
   "wave.config.json",
+  "docs/README.md",
   "docs/agents/wave-documentation-role.md",
   "docs/agents/wave-evaluator-role.md",
   "docs/agents/wave-integration-role.md",
+  "docs/concepts/context7-vs-skills.md",
+  "docs/concepts/operating-modes.md",
+  "docs/concepts/runtime-agnostic-orchestration.md",
+  "docs/concepts/what-is-a-wave.md",
   "docs/context7/bundles.json",
+  "docs/guides/planner.md",
+  "docs/guides/terminal-surfaces.md",
   "docs/plans/component-cutover-matrix.json",
   "docs/plans/component-cutover-matrix.md",
   "docs/plans/context7-wave-orchestrator.md",
@@ -29,6 +37,7 @@ export const STARTER_TEMPLATE_PATHS = [
   "docs/plans/wave-orchestrator.md",
   "docs/plans/waves/wave-0.md",
   "docs/reference/repository-guidance.md",
+  "docs/reference/skills.md",
   "docs/reference/runtime-config/README.md",
   "docs/reference/runtime-config/codex.md",
   "docs/reference/runtime-config/claude.md",
@@ -37,6 +46,8 @@ export const STARTER_TEMPLATE_PATHS = [
 ];
 const REQUIRED_GITIGNORE_ENTRIES = [
   ".tmp/",
+  ".wave/",
+  ".vscode/terminals.json",
   "docs/research/cache/",
   "docs/research/agent-context-cache/",
   "docs/research/papers/",
@@ -69,7 +80,7 @@ function ensureWorkspaceSubdir(relPath) {
 }
 
 function templateStatusList() {
-  return STARTER_TEMPLATE_PATHS.map((relPath) => ({
+  return starterTemplatePaths().map((relPath) => ({
     path: relPath,
     sourcePath: path.join(PACKAGE_ROOT, relPath),
     targetPath: path.join(REPO_ROOT, relPath),
@@ -77,6 +88,30 @@ function templateStatusList() {
   }));
 }
 
+function starterSkillTemplatePaths() {
+  const skillsRoot = path.join(PACKAGE_ROOT, "skills");
+  if (!fs.existsSync(skillsRoot)) {
+    return [];
+  }
+  const files = [];
+  const visit = (targetDir) => {
+    for (const entry of fs.readdirSync(targetDir, { withFileTypes: true })) {
+      const fullPath = path.join(targetDir, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+      } else {
+        files.push(path.relative(PACKAGE_ROOT, fullPath).replaceAll(path.sep, "/"));
+      }
+    }
+  };
+  visit(skillsRoot);
+  return files.toSorted();
+}
+
+function starterTemplatePaths() {
+  return [...STARTER_TEMPLATE_PATHS, ...starterSkillTemplatePaths()];
+}
+
 function existingBootstrapMarkers() {
   return templateStatusList()
     .filter((entry) => entry.exists)
@@ -242,6 +277,10 @@ export function runDoctor() {
           errors.push(`Missing required Wave file: ${relPath}`);
         }
       }
+      const skillValidation = validateLaneSkillConfiguration(lanePaths.laneProfile);
+      if (!skillValidation.ok) {
+        errors.push(...skillValidation.errors);
+      }
       if (fs.existsSync(lanePaths.wavesDir)) {
         const context7BundleIndex = loadContext7BundleIndex(lanePaths.context7BundleIndexPath);
         parseWaveFiles(lanePaths.wavesDir, { laneProfile: lanePaths.laneProfile })
@@ -314,7 +353,7 @@ export function initializeWorkspace(options = {}) {
   if (adoptExisting) {
     adoptedFiles.push(...markers);
   } else {
-    for (const relPath of STARTER_TEMPLATE_PATHS) {
+    for (const relPath of starterTemplatePaths()) {
       copyTemplateFile(relPath);
       seededFiles.push(relPath);
     }