@chllming/wave-orchestration 0.8.4 → 0.8.5

package/docs/reference/skills.md

@@ -109,6 +109,7 @@ Top-level and lane-local skill attachment use the same shape:
     "dir": "skills",
     "base": ["wave-core", "repo-coding-rules"],
     "byRole": {
+      "design": ["role-design"],
       "deploy": ["role-deploy"]
     },
     "byRuntime": {
@@ -123,6 +124,8 @@ Top-level and lane-local skill attachment use the same shape:
 
 Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
 
+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`.
+
 ## Resolution Order
 
 Resolved skills are gathered in this order:
@@ -195,6 +198,12 @@ Runtime delivery:
 
 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.
 
+For the optional `design` worker role, the default pattern is:
+
+- `role-design` for the design packet contract
+- `tui-design` only when the packet covers terminal UX, dashboards, or other operator surfaces
+- no runtime-specific coding bundle unless the wave explicitly gives the design steward code ownership and makes it a hybrid design steward
+
 ## Generated Artifacts
 
 Executor overlay directories can contain:
@@ -225,3 +234,4 @@ Missing or malformed bundles are configuration errors, not silent no-ops.
 - Use explicit per-agent `### Skills` for true exceptions, not as a substitute for missing activation metadata.
 - Keep provider skills role-scoped unless every role genuinely needs the provider context.
 - Keep bundle ids stable so traces and prompt fingerprints remain intelligible across runs.
+- 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

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,6 +2,25 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.8.5",
+      "date": "2026-03-25",
+      "summary": "Shipped design-role support, hybrid design-steward execution, release-surface alignment, and a practical migration guide.",
+      "features": [
+        "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.",
+        "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.",
+        "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.",
+        "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.",
+        "Shipped package metadata, README, current-state notes, sample-wave docs, and publishing guidance now point at the `0.8.5` release surface."
+      ],
+      "manualSteps": [
+        "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.",
+        "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.",
+        "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.",
+        "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."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.8.4",
       "date": "2026-03-25",

package/scripts/wave-orchestrator/agent-state.mjs

@@ -47,6 +47,8 @@ const WAVE_EVAL_REGEX =
   /^\[wave-eval\]\s*state=(satisfied|needs-more-work|blocked)\s+targets=(\d+)\s+benchmarks=(\d+)\s+regressions=(\d+)(?:\s+target_ids=([^\s]+))?(?:\s+benchmark_ids=([^\s]+))?\s*(?:detail=(.*))?$/gim;
 const WAVE_SECURITY_REGEX =
   /^\[wave-security\]\s*state=(clear|concerns|blocked)\s+findings=(\d+)\s+approvals=(\d+)\s*(?:detail=(.*))?$/gim;
+const WAVE_DESIGN_REGEX =
+  /^\[wave-design\]\s*state=(ready-for-implementation|needs-clarification|blocked)\s+decisions=(\d+)\s+assumptions=(\d+)\s+open_questions=(\d+)\s*(?:detail=(.*))?$/gim;
 const WAVE_GATE_REGEX =
   /^\[wave-gate\]\s*architecture=(pass|concerns|blocked)\s+integration=(pass|concerns|blocked)\s+durability=(pass|concerns|blocked)\s+live=(pass|concerns|blocked)\s+docs=(pass|concerns|blocked)\s*(?:detail=(.*))?$/gim;
 const WAVE_GAP_REGEX =
@@ -64,6 +66,7 @@ const STRUCTURED_SIGNAL_KIND_BY_TAG = {
   integration: "integration",
   eval: "eval",
   security: "security",
+  design: "design",
   gate: "gate",
   gap: "gap",
   component: "component",
@@ -76,6 +79,7 @@ const STRUCTURED_SIGNAL_LINE_REGEX_BY_KIND = {
   integration: new RegExp(WAVE_INTEGRATION_REGEX.source, "i"),
   eval: new RegExp(WAVE_EVAL_REGEX.source, "i"),
   security: new RegExp(WAVE_SECURITY_REGEX.source, "i"),
+  design: new RegExp(WAVE_DESIGN_REGEX.source, "i"),
   gate: new RegExp(WAVE_GATE_REGEX.source, "i"),
   gap: new RegExp(WAVE_GAP_REGEX.source, "i"),
   component: new RegExp(WAVE_COMPONENT_REGEX.source, "i"),
@@ -89,6 +93,7 @@ function buildEmptyStructuredSignalDiagnostics() {
     integration: { rawCount: 0, acceptedCount: 0, rejectedSamples: [] },
     eval: { rawCount: 0, acceptedCount: 0, rejectedSamples: [] },
     security: { rawCount: 0, acceptedCount: 0, rejectedSamples: [] },
+    design: { rawCount: 0, acceptedCount: 0, rejectedSamples: [] },
     gate: { rawCount: 0, acceptedCount: 0, rejectedSamples: [] },
     gap: { rawCount: 0, acceptedCount: 0, rejectedSamples: [] },
     component: { rawCount: 0, acceptedCount: 0, rejectedSamples: [], seenComponentIds: [] },
@@ -509,6 +514,13 @@ export function buildAgentExecutionSummary({ agent, statusRecord, logPath, repor
       approvals: Number.parseInt(String(match[3] || "0"), 10) || 0,
       detail: cleanText(match[4]),
     })),
+    design: findLastMatch(signalText, WAVE_DESIGN_REGEX, (match) => ({
+      state: match[1],
+      decisions: Number.parseInt(String(match[2] || "0"), 10) || 0,
+      assumptions: Number.parseInt(String(match[3] || "0"), 10) || 0,
+      openQuestions: Number.parseInt(String(match[4] || "0"), 10) || 0,
+      detail: cleanText(match[5]),
+    })),
     gate: findLastMatch(signalText, WAVE_GATE_REGEX, (match) => ({
       architecture: match[1],
       integration: match[2],
@@ -951,6 +963,58 @@ export function validateSecuritySummary(agent, summary) {
   };
 }
 
+export function validateDesignSummary(agent, summary) {
+  if (!summary?.design) {
+    return {
+      ok: false,
+      statusCode: "missing-wave-design",
+      detail: appendTerminationHint(
+        `Missing [wave-design] marker for ${agent?.agentId || "D1"}.`,
+        summary,
+      ),
+    };
+  }
+  if (!summary.reportPath) {
+    return {
+      ok: false,
+      statusCode: "missing-design-packet",
+      detail: `Missing design packet path for ${agent?.agentId || "D1"}.`,
+    };
+  }
+  if (!fs.existsSync(path.resolve(REPO_ROOT, summary.reportPath))) {
+    return {
+      ok: false,
+      statusCode: "missing-design-packet",
+      detail: `Missing design packet at ${summary.reportPath}.`,
+    };
+  }
+  if (summary.design.state === "blocked") {
+    return {
+      ok: false,
+      statusCode: "design-blocked",
+      detail:
+        summary.design.detail ||
+        `Design packet reported blocked for ${agent?.agentId || "D1"}.`,
+    };
+  }
+  if (summary.design.state === "needs-clarification") {
+    return {
+      ok: false,
+      statusCode: "design-needs-clarification",
+      detail:
+        summary.design.detail ||
+        `Design packet requested clarification for ${agent?.agentId || "D1"}.`,
+    };
+  }
+  return {
+    ok: true,
+    statusCode: "pass",
+    detail:
+      summary.design.detail ||
+      "Design packet is ready for implementation.",
+  };
+}
+
 export function validateIntegrationSummary(agent, summary) {
   if (!summary?.integration) {
     return {

package/scripts/wave-orchestrator/config.mjs

@@ -28,6 +28,7 @@ export const DEFAULT_INTEGRATION_ROLE_PROMPT_PATH = "docs/agents/wave-integratio
 export const DEFAULT_DOCUMENTATION_ROLE_PROMPT_PATH =
   "docs/agents/wave-documentation-role.md";
 export const DEFAULT_SECURITY_ROLE_PROMPT_PATH = "docs/agents/wave-security-role.md";
+export const DEFAULT_DESIGN_ROLE_PROMPT_PATH = "docs/agents/wave-design-role.md";
 export const DEFAULT_TERMINALS_PATH = ".vscode/terminals.json";
 export const DEFAULT_DOCS_DIR = "docs";
 export const DEFAULT_STATE_ROOT = ".tmp";
@@ -348,6 +349,10 @@ function normalizeRoles(rawRoles = {}) {
       rawRoles.securityRolePromptPath || DEFAULT_SECURITY_ROLE_PROMPT_PATH,
       "roles.securityRolePromptPath",
     ),
+    designRolePromptPath: normalizeRepoRelativePath(
+      rawRoles.designRolePromptPath || DEFAULT_DESIGN_ROLE_PROMPT_PATH,
+      "roles.designRolePromptPath",
+    ),
   };
 }
 

package/scripts/wave-orchestrator/coordination.mjs

@@ -17,6 +17,8 @@ import {
 import { resolveEvalTargetsAgainstCatalog } from "./evals.mjs";
 import {
   isContEvalImplementationOwningAgent,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
 } from "./role-helpers.mjs";
 
@@ -199,6 +201,8 @@ export function buildExecutionPrompt({
   evalTargets = null,
   benchmarkCatalogPath = null,
   sharedPlanDocs = null,
+  designPacketPaths = null,
+  designExecutionMode = null,
   contQaAgentId = "A0",
   contEvalAgentId = "E0",
   integrationAgentId = "A8",
@@ -222,6 +226,10 @@ export function buildExecutionPrompt({
   const contEvalImplementationOwning = isContEvalImplementationOwningAgent(agent, {
     contEvalAgentId,
   });
+  const hybridDesignAgent = isImplementationOwningDesignAgent(agent);
+  const designAgent = isDesignAgent(agent);
+  const designImplementationPass = designAgent && hybridDesignAgent && designExecutionMode === "implementation-pass";
+  const designPacketPass = designAgent && !designImplementationPass;
   const resolvedEvalTargets = (() => {
     try {
       return resolveEvalTargetsAgainstCatalog(evalTargets, { benchmarkCatalogPath }).targets;
@@ -269,6 +277,22 @@ export function buildExecutionPrompt({
         "- Use `clear` only when no unresolved findings or approvals remain. Use `blocked` only when the wave must stop before integration.",
       ]
     : [];
+  const designRequirements = designAgent
+    ? [
+        designImplementationPass
+          ? "- You are in the hybrid design steward's implementation follow-through pass. Keep the design packet current, implement only your explicit owned paths, and finish with both `[wave-design]` and the normal implementation proof markers."
+          : "- You are the wave's design steward. Stay packet-first and docs/spec-owned unless the wave explicitly assigns more.",
+        "- Leave one design packet with these sections in order: `Problem`, `Constraints`, `Decisions`, `Assumptions`, `Open Questions`, `Interface Impacts`, `Validation Plan`, `Implementation Handoff`.",
+        "- Emit one final structured design marker: `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`.",
+        "- Use `ready-for-implementation` only when downstream implementation owners can start without unresolved design ambiguity.",
+        "- Use `needs-clarification` when the wave should stop for a specific question or decision before coding starts.",
+        ...(hybridDesignAgent && !designImplementationPass
+          ? [
+              "- This wave also assigns you explicit implementation-owned files, but this first pass is still design-only. Do not claim implementation proof yet; the code-owning pass starts only after the design packet is ready.",
+            ]
+          : []),
+      ]
+    : [];
   const coordinationCommand = [
     "pnpm exec wave coord post",
     `--lane ${lane}`,
@@ -280,6 +304,7 @@ export function buildExecutionPrompt({
   ].join(" ");
   const implementationRequirements =
     ![contQaAgentId, documentationAgentId].includes(agent.agentId) &&
+    (!designAgent || designImplementationPass) &&
     !isSecurityReviewAgent(agent) &&
     (agent.agentId !== contEvalAgentId || contEvalImplementationOwning)
       ? [
@@ -294,7 +319,8 @@ export function buildExecutionPrompt({
           `- Route unresolved architecture, integration, durability, ops, or docs issues through \`${coordinationCommand}\`. Do not append \`[wave-gap]\` lines after the final implementation markers.`,
         ]
       : [];
-  const exitContractLines = agent.exitContract
+  const exitContractLines =
+    implementationRequirements.length > 0 && agent.exitContract
     ? [
         "Exit contract for this run:",
         `- completion: ${agent.exitContract.completion}`,
@@ -385,6 +411,7 @@ export function buildExecutionPrompt({
       : [];
   const ownedComponentLines =
     ![contQaAgentId, documentationAgentId].includes(agent.agentId) &&
+    (!designAgent || designImplementationPass) &&
     (agent.agentId !== contEvalAgentId || contEvalImplementationOwning) &&
     Array.isArray(agent.components) &&
     agent.components.length > 0
@@ -398,6 +425,7 @@ export function buildExecutionPrompt({
         ]
       : [];
   const deliverableLines =
+    (!designAgent || designImplementationPass) &&
     Array.isArray(agent.deliverables) && agent.deliverables.length > 0
       ? [
           "Deliverables required for this agent:",
@@ -405,7 +433,18 @@ export function buildExecutionPrompt({
           "",
         ]
       : [];
+  const designPacketLines =
+    !designAgent &&
+    Array.isArray(designPacketPaths) &&
+    designPacketPaths.length > 0
+      ? [
+          "Same-wave design packets to read before coding:",
+          ...designPacketPaths.map((designPacketPath) => `- ${designPacketPath}`),
+          "",
+        ]
+      : [];
   const proofArtifactLines =
+    implementationRequirements.length > 0 &&
     Array.isArray(agent.proofArtifacts) && agent.proofArtifacts.length > 0
       ? [
           "Proof artifacts required for this agent:",
@@ -473,6 +512,7 @@ export function buildExecutionPrompt({
     ...contEvalRequirements,
     ...docStewardRequirements,
     ...securityRequirements,
+    ...designRequirements,
     ...implementationRequirements,
     `- Update docs impacted by your implementation. If your work changes status, sequencing, ownership, or explicit proof expectations, update the relevant docs. If shared plan docs need changes outside your owned files, post the exact doc paths and exact delta needed for ${sharedPlanDocList} as a coordination record instead of leaving documentation drift for later cleanup.`,
     "- If the wave defines a documentation steward or other explicit owner for shared plan docs, coordinate those updates through that owner, notify them as soon as the delta is known, and stay engaged until they confirm `closed` or `no-change`. Do not treat the ownership boundary as the definition of done.",
@@ -503,6 +543,7 @@ export function buildExecutionPrompt({
     ...evalTargetLines,
     ...ownedComponentLines,
     ...deliverableLines,
+    ...designPacketLines,
     ...proofArtifactLines,
     ...skillLines,
     ...context7PromptLines,

package/scripts/wave-orchestrator/gate-engine.mjs

@@ -4,6 +4,7 @@ import {
   agentSummaryPathFromStatusPath,
   buildAgentExecutionSummary,
   readAgentExecutionSummary,
+  validateDesignSummary,
   validateContQaSummary,
   validateContEvalSummary,
   validateImplementationSummary,
@@ -33,7 +34,10 @@ import {
   writeJsonAtomic,
 } from "./shared.mjs";
 import {
+  isDocsOnlyDesignAgent,
   isSecurityReviewAgent,
+  isDesignAgent,
+  resolveDesignReportPath,
   resolveSecurityReviewReportPath,
   isContEvalReportOnlyAgent,
 } from "./role-helpers.mjs";
@@ -94,6 +98,10 @@ function resolveRunReportPath(wave, runInfo) {
     const securityReportPath = resolveSecurityReviewReportPath(runInfo.agent);
     return securityReportPath ? path.resolve(REPO_ROOT, securityReportPath) : null;
   }
+  if (isDesignAgent(runInfo.agent)) {
+    const designReportPath = resolveDesignReportPath(runInfo.agent);
+    return designReportPath ? path.resolve(REPO_ROOT, designReportPath) : null;
+  }
   return null;
 }
 
@@ -513,6 +521,7 @@ export function readWaveImplementationGate(wave, agentRuns, options = {}) {
     if (
       [contQaAgentId, integrationAgentId, documentationAgentId].includes(runInfo.agent.agentId) ||
       isContEvalReportOnlyAgent(runInfo.agent, { contEvalAgentId }) ||
+      isDocsOnlyDesignAgent(runInfo.agent) ||
       isSecurityReviewAgent(runInfo.agent)
     ) {
       continue;
@@ -563,6 +572,65 @@ export function readWaveImplementationGate(wave, agentRuns, options = {}) {
   };
 }
 
+export function readWaveDesignGate(wave, agentRuns, options = {}) {
+  const mode = normalizeReadMode(options.mode || "live");
+  const designRuns = (agentRuns || []).filter((run) => isDesignAgent(run.agent));
+  if (designRuns.length === 0) {
+    return {
+      ok: true,
+      agentId: null,
+      statusCode: "pass",
+      detail: "No design agent declared for this wave.",
+      logPath: null,
+    };
+  }
+  for (const runInfo of designRuns) {
+    const envelopeResult = readRunResultEnvelope(runInfo, wave, { mode });
+    if (mode === "live" && !envelopeResult.valid) {
+      return {
+        ok: false,
+        agentId: runInfo.agent.agentId,
+        statusCode:
+          envelopeResult.source === "missing-envelope"
+            ? "missing-result-envelope"
+            : "invalid-result-envelope",
+        detail:
+          envelopeResult.detail ||
+          `Missing structured design result envelope for ${runInfo.agent.agentId}.`,
+        logPath: path.relative(REPO_ROOT, runInfo.logPath),
+      };
+    }
+    const summary = envelopeResult.valid
+      ? projectLegacySummaryFromEnvelope(
+          envelopeResult.envelope,
+          buildEnvelopeReadOptions(
+            runInfo,
+            wave,
+            runInfo?.statusPath ? readStatusRecordIfPresent(runInfo.statusPath) : null,
+            resolveRunReportPath(wave, runInfo),
+          ),
+        )
+      : readRunExecutionSummary(runInfo, wave, { mode });
+    const validation = validateDesignSummary(runInfo.agent, summary);
+    if (!validation.ok) {
+      return {
+        ok: false,
+        agentId: runInfo.agent.agentId,
+        statusCode: validation.statusCode,
+        detail: validation.detail,
+        logPath: summary?.logPath || path.relative(REPO_ROOT, runInfo.logPath),
+      };
+    }
+  }
+  return {
+    ok: true,
+    agentId: null,
+    statusCode: "pass",
+    detail: "All design packets are ready for implementation.",
+    logPath: null,
+  };
+}
+
 export function analyzePromotedComponentOwners(componentId, agentRuns, summariesByAgentId) {
   const ownerRuns = (agentRuns || []).filter((runInfo) =>
     runInfo.agent.components?.includes(componentId),
@@ -1088,6 +1156,7 @@ export function readWaveImplementationGatePure(wave, agentResults, options = {})
     if (
       [contQaAgentId, integrationAgentId, documentationAgentId].includes(agent.agentId) ||
       isContEvalReportOnlyAgent(agent, { contEvalAgentId }) ||
+      isDocsOnlyDesignAgent(agent) ||
       isSecurityReviewAgent(agent)
     ) {
       continue;
@@ -1110,6 +1179,40 @@ export function readWaveImplementationGatePure(wave, agentResults, options = {})
   };
 }
 
+export function readWaveDesignGatePure(wave, agentResults) {
+  const agents = Array.isArray(wave.agents) ? wave.agents : [];
+  const designAgents = agents.filter((agent) => isDesignAgent(agent));
+  if (designAgents.length === 0) {
+    return {
+      ok: true,
+      agentId: null,
+      statusCode: "pass",
+      detail: "No design agent declared for this wave.",
+      logPath: null,
+    };
+  }
+  for (const agent of designAgents) {
+    const summary = agentResults?.[agent.agentId] || null;
+    const validation = validateDesignSummary(agent, summary);
+    if (!validation.ok) {
+      return {
+        ok: false,
+        agentId: agent.agentId,
+        statusCode: validation.statusCode,
+        detail: validation.detail,
+        logPath: summary?.logPath || null,
+      };
+    }
+  }
+  return {
+    ok: true,
+    agentId: null,
+    statusCode: "pass",
+    detail: "All design packets are ready for implementation.",
+    logPath: null,
+  };
+}
+
 export function readWaveContQaGatePure(wave, agentResults, options = {}) {
   const mode = String(options.mode || "live").trim().toLowerCase();
   const contQaAgentId = options.contQaAgentId || wave.contQaAgentId || "A0";
@@ -1312,6 +1415,7 @@ export function readWaveInfraGatePure(wave, agentResults, options = {}) {
 }
 
 export function buildGateSnapshotPure({ wave, agentResults, derivedState, validationMode = "live", laneConfig = {} }) {
+  const designGate = readWaveDesignGatePure(wave, agentResults);
   const implementationGate = readWaveImplementationGatePure(wave, agentResults, {
     contQaAgentId: laneConfig.contQaAgentId, contEvalAgentId: laneConfig.contEvalAgentId,
     integrationAgentId: laneConfig.integrationAgentId, documentationAgentId: laneConfig.documentationAgentId,
@@ -1363,7 +1467,7 @@ export function buildGateSnapshotPure({ wave, agentResults, derivedState, valida
   const helperAssignmentBarrier = derivedState?.helperAssignmentBarrier || { ok: true, statusCode: "pass", detail: "" };
   const dependencyBarrier = derivedState?.dependencyBarrier || { ok: true, statusCode: "pass", detail: "" };
   const orderedGates = [
-    ["implementationGate", implementationGate], ["componentGate", componentGate],
+    ["designGate", designGate], ["implementationGate", implementationGate], ["componentGate", componentGate],
     ["helperAssignmentBarrier", helperAssignmentBarrier], ["dependencyBarrier", dependencyBarrier],
     ["contEvalGate", contEvalGate], ["securityGate", securityGate],
     ["integrationBarrier", integrationBarrier], ["documentationGate", documentationGate],
@@ -1372,7 +1476,7 @@ export function buildGateSnapshotPure({ wave, agentResults, derivedState, valida
   ];
   const firstFailure = orderedGates.find(([, gate]) => gate?.ok === false);
   return {
-    implementationGate, componentGate, integrationGate: integrationMarkerGate,
+    designGate, implementationGate, componentGate, integrationGate: integrationMarkerGate,
     integrationBarrier, documentationGate, componentMatrixGate,
     contEvalGate, securityGate, contQaGate, infraGate,
     clarificationBarrier, helperAssignmentBarrier, dependencyBarrier,

package/scripts/wave-orchestrator/install.mjs

@@ -29,6 +29,7 @@ export const STARTER_TEMPLATE_PATHS = [
   "wave.config.json",
   "docs/README.md",
   "docs/agents/wave-documentation-role.md",
+  "docs/agents/wave-design-role.md",
   "docs/agents/wave-cont-qa-role.md",
   "docs/agents/wave-cont-eval-role.md",
   "docs/agents/wave-integration-role.md",
@@ -74,6 +75,8 @@ export const STARTER_TEMPLATE_PATHS = [
   "docs/reference/sample-waves.md",
   "docs/reference/skills.md",
   "docs/reference/wave-planning-lessons.md",
+  "skills/role-design/SKILL.md",
+  "skills/role-design/skill.json",
   "docs/reference/runtime-config/README.md",
   "docs/reference/runtime-config/codex.md",
   "docs/reference/runtime-config/claude.md",

package/scripts/wave-orchestrator/launcher-runtime.mjs

@@ -14,7 +14,7 @@ import { readStatusCodeIfPresent } from "./dashboard-state.mjs";
 import { buildExecutorLaunchSpec } from "./executors.mjs";
 import { hashAgentPromptFingerprint, prefetchContext7ForSelection } from "./context7.mjs";
 import { killTmuxSessionIfExists } from "./terminals.mjs";
-import { resolveWaveRoleBindings } from "./role-helpers.mjs";
+import { isDesignAgent, resolveDesignReportPath, resolveWaveRoleBindings } from "./role-helpers.mjs";
 import {
   resolveAgentSkills,
   summarizeResolvedSkills,
@@ -77,6 +77,7 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
     agentRateLimitBaseDelaySeconds,
     agentRateLimitMaxDelaySeconds,
     context7Enabled,
+    designExecutionMode = null,
     dryRun = false,
   } = params;
   ensureDirectory(path.dirname(promptPath));
@@ -123,6 +124,11 @@ export async function launchAgentSession(lanePaths, params, { runTmuxFn }) {
       evalTargets: resolvedWaveDefinition.evalTargets,
       benchmarkCatalogPath: lanePaths.laneProfile?.paths?.benchmarkCatalogPath,
       sharedPlanDocs: lanePaths.sharedPlanDocs,
+      designPacketPaths: (resolvedWaveDefinition.agents || [])
+        .filter((waveAgent) => isDesignAgent(waveAgent))
+        .map((waveAgent) => resolveDesignReportPath(waveAgent))
+        .filter(Boolean),
+      designExecutionMode,
     });
   const promptHash = hashAgentPromptFingerprint(agent);
   fs.writeFileSync(promptPath, `${prompt}\n`, "utf8");

package/scripts/wave-orchestrator/launcher.mjs

@@ -131,6 +131,8 @@ import {
   isContEvalImplementationOwningAgent,
   isContEvalReportOnlyAgent,
   isClosureRoleAgentId,
+  isDesignAgent,
+  isImplementationOwningDesignAgent,
   isSecurityReviewAgent,
   resolveWaveRoleBindings,
   resolveSecurityReviewReportPath,
@@ -496,6 +498,8 @@ function buildGateSnapshot(params) {
 
 function waveGateLabel(gateName) {
   switch (gateName) {
+    case "designGate":
+      return "Design packet";
     case "implementationGate":
       return "Implementation exit contract";
     case "componentGate":
@@ -527,6 +531,8 @@ function waveGateLabel(gateName) {
 
 function waveGateActionRequested(gateName, lanePaths) {
   switch (gateName) {
+    case "designGate":
+      return `Lane ${lanePaths.lane} owners should close the design packet or clarification gap before implementation starts.`;
     case "implementationGate":
       return `Lane ${lanePaths.lane} owners should resolve the implementation contract gap before wave progression.`;
     case "componentGate":
@@ -1335,8 +1341,11 @@ export async function runLauncherCli(argv) {
           });
 
           const launchedImplementationRuns = runsToLaunch.filter(
-            (run) => !isClosureRoleAgentId(run.agent.agentId, roleBindings),
+            (run) =>
+              !isClosureRoleAgentId(run.agent.agentId, roleBindings) &&
+              (!isDesignAgent(run.agent) || isImplementationOwningDesignAgent(run.agent)),
           );
+          const launchedDesignRuns = runsToLaunch.filter((run) => isDesignAgent(run.agent));
           const closureOnlyRetry =
             runsToLaunch.length > 0 &&
             launchedImplementationRuns.length === 0 &&
@@ -1395,6 +1404,14 @@ export async function runLauncherCli(argv) {
                 agentRateLimitBaseDelaySeconds: options.agentRateLimitBaseDelaySeconds,
                 agentRateLimitMaxDelaySeconds: options.agentRateLimitMaxDelaySeconds,
                 context7Enabled: options.context7Enabled,
+                designExecutionMode:
+                  isDesignAgent(runInfo.agent)
+                    ? launchedImplementationRuns.some(
+                        (candidate) => candidate.agent.agentId === runInfo.agent.agentId,
+                      )
+                      ? "implementation-pass"
+                      : "design-pass"
+                    : null,
                 attempt,
                 controlPlane: {
                   waveNumber: wave.wave,
@@ -1507,6 +1524,43 @@ export async function runLauncherCli(argv) {
           }
 
           if (failures.length === 0) {
+            if (launchedDesignRuns.length > 0 && launchedImplementationRuns.length === 0) {
+              const reducerDecision = refreshReducerSnapshot(attempt);
+              const designGate = reducerDecision?.reducerState?.gateSnapshot?.designGate || null;
+              const remainingImplementationRuns = agentRuns.filter(
+                (run) =>
+                  !preCompletedAgentIds.has(run.agent.agentId) &&
+                  !isClosureRoleAgentId(run.agent.agentId, roleBindings) &&
+                  (!isDesignAgent(run.agent) || isImplementationOwningDesignAgent(run.agent)),
+              );
+              if (designGate?.ok && remainingImplementationRuns.length > 0) {
+                recordAttemptState(lanePaths, wave.wave, attempt, "completed", {
+                  selectedAgentIds: runsToLaunch.map((run) => run.agent.agentId),
+                  detail: `Design pass complete; continuing with implementation agents ${remainingImplementationRuns.map((run) => run.agent.agentId).join(", ")}.`,
+                });
+                recordCombinedEvent({
+                  message: `Design pass complete; launching implementation agents next: ${remainingImplementationRuns.map((run) => run.agent.agentId).join(", ")}.`,
+                });
+                appendCoordination({
+                  event: "wave_design_ready",
+                  waves: [wave.wave],
+                  status: "running",
+                  details: `next_agents=${remainingImplementationRuns.map((run) => run.agent.agentId).join(",")}`,
+                  actionRequested: "None",
+                });
+                runsToLaunch = remainingImplementationRuns;
+                for (const run of runsToLaunch) {
+                  setWaveDashboardAgent(dashboardState, run.agent.agentId, {
+                    state: "pending",
+                    detail: "Queued after design handoff",
+                  });
+                }
+                flushDashboards();
+                attempt += 1;
+                traceAttempt += 1;
+                continue;
+              }
+            }
             const implementationGate = readWaveImplementationGate(wave, agentRuns);
             if (!implementationGate.ok) {
               failures = [