@jstn-sdk/ma 0.1.4 → 0.1.6

package/README.md

@@ -7,12 +7,20 @@
     <img src="https://img.shields.io/github/v/release/JustineDevs/meta-architect" alt="GitHub release">
     <img src="https://img.shields.io/badge/license-MIT-16A34A" alt="MIT License">
   </p>
+  <p>
+    <a href="https://www.buymeacoffee.com/justinedevs">
+      <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ffdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
+    </a>
+    <a href="https://github.com/sponsors/JustineDevs">
+      <img src="https://img.shields.io/badge/GitHub%20Sponsors-JustineDevs-1f6feb?style=flat-square&logo=githubsponsors&logoColor=white" alt="GitHub Sponsors">
+    </a>
+  </p>
 </div>
 
 > [!IMPORTANT]
-> Meta-Architect `v0.1.4` is a production-grade skills line.
+> Meta-Architect `v0.1.6` is a production-grade skills line.
 > It is not a lightweight demo branch.
-> From `v0.1.4` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
+> From `v0.1.6` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
 
 ## Overview
 
@@ -29,6 +37,11 @@ It adds:
 > Meta-Architect does not replace your coding runtime.
 > It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.
 
+## Support
+
+- [GitHub Sponsors](https://github.com/sponsors/JustineDevs)
+- [Buy Me A Coffee](https://www.buymeacoffee.com/justinedevs)
+
 <table>
   <tr>
     <td><strong>npm package</strong></td>
@@ -44,7 +57,7 @@ It adds:
   </tr>
   <tr>
     <td><strong>Release line</strong></td>
-    <td><code>v0.1.4</code></td>
+    <td><code>v0.1.6</code></td>
   </tr>
   <tr>
     <td><strong>License</strong></td>
@@ -52,6 +65,26 @@ It adds:
   </tr>
 </table>
 
+## Screenshots
+
+<table>
+  <tr>
+    <td><img src="./docs/assets/image/Screenshot(1).png" alt="Meta-Architect screenshot 1" width="280"></td>
+    <td><img src="./docs/assets/image/Screenshot(2).png" alt="Meta-Architect screenshot 2" width="280"></td>
+    <td><img src="./docs/assets/image/Screenshot(3).png" alt="Meta-Architect screenshot 3" width="280"></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/assets/image/Screenshot(4).png" alt="Meta-Architect screenshot 4" width="280"></td>
+    <td><img src="./docs/assets/image/Screenshot(5).png" alt="Meta-Architect screenshot 5" width="280"></td>
+    <td><img src="./docs/assets/image/Screenshot(6).png" alt="Meta-Architect screenshot 6" width="280"></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/assets/image/Screenshot(7).png" alt="Meta-Architect screenshot 7" width="280"></td>
+    <td><img src="./docs/assets/image/Screenshot(8).png" alt="Meta-Architect screenshot 8" width="280"></td>
+    <td><img src="./docs/assets/image/Screenshot(9).png" alt="Meta-Architect screenshot 9" width="280"></td>
+  </tr>
+</table>
+
 ## Prerequisites
 
 - Node.js `>=20`
@@ -164,6 +197,10 @@ Use the same operator shape defined in [example/usage-workflow.md](./example/usa
 Quick-start prompt:
 
 ```text
+$maestro
+
+Or start directly with:
+
 $arch I want to build: [PROJECT IDEA]
 
 Context:
@@ -193,7 +230,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.4
+8. Delivery plan for v0.1.6
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -204,6 +241,7 @@ Required output:
 After `$arch`, continue exactly like the usage workflow:
 
 ```text
+$maestro
 $sage
 $flow
 $vet
@@ -327,6 +365,7 @@ ma run '$arch'
 In-session skills are prompts you use inside the Codex conversation after launch:
 
 ```text
+$maestro
 $arch
 $sage
 $flow
@@ -347,6 +386,7 @@ What `ma setup` and `ma init` do:
 
 What to use when:
 - use Codex and run the skills in-session
+- use `$maestro` when you want Meta-Architect to choose the best next step for you
 - use `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` inside the Codex session
 - use `ma setup` or `ma init` only when you want local scaffolding or scripted helper automation from the terminal
 - use `ma sdk-path` when you need the exact installed support-bundle path for packaged prompts, MCP files, sprint files, scripts, plugin metadata, or templates
@@ -523,7 +563,7 @@ Release automation:
 | [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
 | [Collaborative Whiteboard Mission](./missions/collaborative-whiteboard/mission.md) | concrete scenario walkthrough |
 | [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.4.md) | QA evidence for the `v0.1.4` line |
+| [Release Readiness](./docs/qa/release-readiness-0.1.6.md) | QA evidence for the `v0.1.6` line |
 
 ## Release Hygiene
 

package/bin/ma.js

@@ -26,6 +26,7 @@ import {
   runFlow,
   runIdea,
   runInit,
+  runMaestro,
   runSage,
   runVet,
   runVibe,
@@ -41,7 +42,7 @@ function printUsage() {
   console.error("  ma skills");
   console.error("  ma sdk-path");
   console.error("  ma status");
-  console.error("  ma run $arch|$sage|$flow|$vet|$vibe|$build");
+  console.error("  ma run $maestro|$arch|$sage|$flow|$vet|$vibe|$build");
   console.error("  ma merge <source-branch> <target-branch>");
   console.error("  ma release <origin-branch> <target-branch>");
 }
@@ -266,6 +267,12 @@ async function main() {
     return;
   }
 
+  if (command === "run" && arg === "$maestro") {
+    await runMaestro();
+    console.log("$maestro complete");
+    return;
+  }
+
   if (command === "run" && arg === "$build") {
     const releaseState = await loadReleaseState();
     await runBuild(releaseState);

package/docs/README.md

@@ -17,7 +17,7 @@ Meta-Architect documentation is organized by operator task.
 
 ## QA and readiness
 
-- [Release Readiness 0.1.4](./qa/release-readiness-0.1.4.md)
+- [Release Readiness 0.1.6](./qa/release-readiness-0.1.6.md)
 
 ## Repo structure references
 

package/docs/getting-started.md

@@ -74,7 +74,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.4
+8. Delivery plan for v0.1.6
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -163,6 +163,7 @@ ma run '$arch'
 In-session skills are prompts used after you are already inside Codex:
 
 ```text
+$maestro
 $arch
 $sage
 $flow
@@ -222,6 +223,22 @@ If this fails:
 
 ## 7. Run the helper skill sequence
 
+### 5.0 Workflow manager
+
+```bash
+ma run '$maestro'
+```
+
+Expected effects:
+- reads the current gate state
+- recommends the best next step
+- writes `.ma/plans/maestro.md`
+- records an advisory decision entry
+
+Generated or updated:
+- `.ma/decisions.json`
+- `.ma/plans/maestro.md`
+
 ### 5.1 Architecture
 
 ```bash

package/docs/qa/{release-readiness-0.1.4.md → release-readiness-0.1.5.md}

@@ -1,25 +1,25 @@
-# Release Readiness 0.1.4
+# Release Readiness 0.1.5
 
 ## Production bar
 
-`v0.1.4` is treated as production only when:
+`v0.1.5` is treated as production only when:
 - the package installs cleanly from the canonical public install command
 - the Codex-hosted runtime path works end to end
 - the helper flow remains valid for scripted verification
-- release docs, package metadata, and workflows all agree on `0.1.4`
+- release docs, package metadata, and workflows all agree on `0.1.5`
 
 Target release state:
-- npm package: `@jstn-sdk/ma@0.1.4`
+- npm package: `@jstn-sdk/ma@0.1.5`
 - npm registry state: pending publish
-- publishability note: `0.1.3` is already published, so `0.1.4` is the next publishable package line
-- git tag: `v0.1.4`
-- GitHub release: pending publish for `v0.1.4`
+- publishability note: `0.1.4` is already published, so `0.1.5` is the next publishable package line
+- git tag: `v0.1.5`
+- GitHub release: pending publish for `v0.1.5`
 
 ## Production checklist
 
 - skills-first product identity: PASS
 - package/plugin identity aligned to `@jstn-sdk/ma`: PASS
-- version/tag alignment `0.1.4` / `v0.1.4`: PASS
+- version/tag alignment `0.1.5` / `v0.1.5`: PASS
 - install/uninstall docs aligned: PASS
 - onboarding is concise and sequential: PASS
 - helper command documented as secondary: PASS

package/docs/qa/release-readiness-0.1.6.md

@@ -0,0 +1,79 @@
+# Release Readiness 0.1.6
+
+## Production bar
+
+`v0.1.6` is treated as production only when:
+- the package installs cleanly from the canonical public install command
+- the Codex-hosted runtime path works end to end
+- the helper flow remains valid for scripted verification
+- release docs, package metadata, and workflows all agree on `0.1.6`
+
+Target release state:
+- npm package: `@jstn-sdk/ma@0.1.6`
+- npm registry state: pending publish
+- publishability note: `0.1.5` is already published, so `0.1.6` is the next publishable package line
+- git tag: `v0.1.6`
+- GitHub release: pending publish for `v0.1.6`
+
+## Production checklist
+
+- skills-first product identity: PASS
+- package/plugin identity aligned to `@jstn-sdk/ma`: PASS
+- version/tag alignment `0.1.6` / `v0.1.6`: PASS
+- install/uninstall docs aligned: PASS
+- onboarding is concise and sequential: PASS
+- helper command documented as secondary: PASS
+- skills/prompts/manifests aligned: PASS
+- packaging includes required assets: PASS
+- tests pass: PASS
+- package dry-run passes: PASS
+- installed-package behavior passes: PASS
+- workflow/release/provenance docs aligned: PASS
+- no stale package names remain in tracked repo surfaces: PASS
+- no conflicting CLI-first product story remains in tracked product docs: PASS
+
+## Automated checks run
+
+```bash
+npm run release:check
+```
+
+That must cover:
+- skills manifest generation
+- skill validation
+- skill bundle packaging
+- repo checks
+- automated tests
+- npm package dry-run inspection
+
+## Manual/behavioral checks run
+
+Canonical launch:
+
+```bash
+ma --madmax --high
+```
+
+Helper-path validation:
+
+```bash
+ma setup
+ma idea "Build a demo app"
+ma run '$arch'
+ma run '$sage'
+ma run '$flow'
+ma run '$vet'
+ma run '$vibe'
+ma status
+ma run '$build'
+```
+
+Expected evidence:
+- `.ma/release.json` remains the source of truth
+- `.ma/decisions.json` records the helper-path activity
+- `$build` stays blocked until upstream gates are green, then becomes ready
+
+## Known limitations
+
+- interactive Codex conversation quality depends on the installed Codex host
+- release publication still depends on npm ownership/authorization for the target package name

package/docs/release-spec.md

@@ -1,13 +1,13 @@
-# v0.1.4 Requirements & Rules
+# v0.1.6 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.4` is production only when:
+Meta-Architect `v0.1.6` is production only when:
 1. the package/install surface works
 2. the in-session skill workflow from `$arch` through `$build` works
 3. the release evidence matches the actual package and git tag
 
-## What `v0.1.4` must have
+## What `v0.1.6` must have
 
 ### 1. Canonical package/runtime path
 
@@ -49,11 +49,11 @@ Canonical state files:
 
 ### 4. Required release evidence
 
-- `package.json` version `0.1.4`
-- git tag `v0.1.4`
+- `package.json` version `0.1.6`
+- git tag `v0.1.6`
 - `RELEASE.md`
 - `CHANGELOG.md`
-- `docs/qa/release-readiness-0.1.4.md`
+- `docs/qa/release-readiness-0.1.6.md`
 - green `npm run release:check`
 
 ### 5. Dist-tag discipline

package/docs/skills.md

@@ -1,6 +1,7 @@
 # Skills
 
 Meta-Architect’s canonical Codex runtime surface is:
+- `$maestro`
 - `$arch`
 - `$sage`
 - `$flow`
@@ -27,8 +28,9 @@ npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
 Then inside the Codex session:
-1. Start with the structured `$arch` prompt
-2. Continue through `$sage -> $flow -> $vet -> $vibe -> $build`
+1. Start with `$maestro` when you want Meta-Architect to choose the best next step
+2. Or start with `$arch` when you already know the architecture lane is next
+3. Continue through `$sage -> $flow -> $vet -> $vibe -> $build`
 
 ## Simple difference
 
@@ -50,6 +52,7 @@ ma run '$arch'
 In-session skills are used inside the Codex conversation:
 
 ```text
+$maestro
 $arch
 $sage
 $flow
@@ -106,6 +109,7 @@ Every skill result must include:
 
 ## Status ownership
 
+- `$maestro` -> next-step recommendation
 - project brief -> architecture input
 - `$arch` -> `architecture_status`
 - `$sage` -> `evidence_status`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
   "license": "MIT",
   "author": "JustineDevs",

package/plugins/meta-architect/.app.json

@@ -1,7 +1,7 @@
 {
   "name": "meta-architect",
   "displayName": "Meta-Architect",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Programmatic architecture and verified engineering skills for Codex-native workflows.",
   "entry": "./README.md",
   "skillsDir": "./skills"

package/plugins/meta-architect/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
   "author": {
     "name": "JustineDevs",

package/plugins/meta-architect/.mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "collections": [
     "sindresorhus/awesome",
     "dzharii/awesome-typescript",

package/plugins/meta-architect/README.md

@@ -105,7 +105,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.4`
+- plugin scope is aligned to Meta-Architect `v0.1.6`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.

package/plugins/meta-architect/skills/maestro/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: maestro
+description: "Use when the user wants Meta-Architect to choose the best next workflow step, explain why, and recommend the right lane or assignment."
+---
+
+# Maestro
+
+Use this skill inside Codex when you want Meta-Architect to act like a workflow manager.
+
+## Output
+
+Produce:
+- current situation summary
+- best next step
+- why that step is next
+- recommended lane or assignment
+- what to avoid doing yet
+- exact next trigger, command, or handoff
+
+## Rules
+
+- Prefer the smallest next step that moves the workflow forward safely.
+- Respect current gate state before recommending implementation or release work.
+- Be explicit when more evidence, planning, or validation is still needed.
+- Route to the in-session skill flow first; use helper commands only when they are the clearest support path.

package/plugins/meta-architect/skills/maestro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$maestro"
+  short_description: "Best next step and lane orchestration"
+  default_prompt: "Use $maestro to inspect the current Meta-Architect workflow state, choose the best next step, explain why it is next, and recommend the right lane or assignment."

package/scripts/plugin-sync.js

@@ -25,6 +25,7 @@ async function copyDir(src, dest) {
       await copyDir(srcPath, destPath);
     } else {
       await fs.copyFile(srcPath, destPath);
+      await fs.chmod(destPath, 0o644);
     }
   }
 }

package/skills/index.json

@@ -16,6 +16,11 @@
       "path": "skills/flow",
       "description": "Use when the user wants logic validation: states, transitions, invariants, edge cases, dead ends, and blockers before implementation."
     },
+    {
+      "name": "maestro",
+      "path": "skills/maestro",
+      "description": "Use when the user wants Meta-Architect to choose the best next workflow step, explain why, and recommend the right lane or assignment."
+    },
     {
       "name": "meta-architect",
       "path": "skills/meta-architect",

package/skills/maestro/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: maestro
+description: "Use when the user wants Meta-Architect to choose the best next workflow step, explain why, and recommend the right lane or assignment."
+---
+
+# Maestro
+
+Use this skill inside Codex when you want Meta-Architect to act like a workflow manager.
+
+## Output
+
+Produce:
+- current situation summary
+- best next step
+- why that step is next
+- recommended lane or assignment
+- what to avoid doing yet
+- exact next trigger, command, or handoff
+
+## Rules
+
+- Prefer the smallest next step that moves the workflow forward safely.
+- Respect current gate state before recommending implementation or release work.
+- Be explicit when more evidence, planning, or validation is still needed.
+- Route to the in-session skill flow first; use helper commands only when they are the clearest support path.

package/skills/maestro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$maestro"
+  short_description: "Best next step and lane orchestration"
+  default_prompt: "Use $maestro to inspect the current Meta-Architect workflow state, choose the best next step, explain why it is next, and recommend the right lane or assignment."

package/src/mcp-live-client.js

@@ -38,7 +38,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.4",
+        version: "0.1.6",
       },
     });
 

package/src/runtime-artifacts.js

@@ -196,6 +196,50 @@ function renderImplementationPlan({ idea, blueprint }) {
   ].join("\n");
 }
 
+function renderMaestroPlan({ releaseState, recommendation }) {
+  return [
+    "# Maestro Plan",
+    "",
+    `Updated: ${new Date().toISOString()}`,
+    "",
+    "## Current Gate State",
+    "",
+    `- idea: ${releaseState.idea_status}`,
+    `- architecture: ${releaseState.architecture_status}`,
+    `- evidence: ${releaseState.evidence_status}`,
+    `- logic: ${releaseState.logic_status}`,
+    `- security: ${releaseState.security_status}`,
+    `- experience: ${releaseState.experience_status}`,
+    `- build: ${releaseState.build_status}`,
+    "",
+    "## Best Next Step",
+    "",
+    recommendation.nextStep,
+    "",
+    "## Why This Is Next",
+    "",
+    recommendation.why,
+    "",
+    "## Recommended Lane",
+    "",
+    `- primary: ${recommendation.primaryLane}`,
+    `- support: ${recommendation.supportLane}`,
+    "",
+    "## Suggested Assignment",
+    "",
+    ...recommendation.assignments.map((item) => `- ${item}`),
+    "",
+    "## Avoid For Now",
+    "",
+    ...recommendation.avoid.map((item) => `- ${item}`),
+    "",
+    "## Exact Next Trigger",
+    "",
+    recommendation.nextTrigger,
+    "",
+  ].join("\n");
+}
+
 function renderBuildPlan({ allowed, blockers, nextTriggers, suggestedBranches = [] }) {
   const lines = [
     "# Build Plan",
@@ -361,3 +405,7 @@ export async function writeBuildPlanArtifact({
     renderBuildPlan({ allowed, blockers, nextTriggers, suggestedBranches }),
   );
 }
+
+export async function writeMaestroPlan({ releaseState, recommendation }) {
+  await writeArtifact("plans/maestro.md", renderMaestroPlan({ releaseState, recommendation }));
+}

package/src/skills.js

@@ -11,13 +11,16 @@ import {
   writeEvidenceSpec,
   writeExperienceSpec,
   writeLogicSpec,
+  writeMaestroPlan,
   writeProjectContext,
   writeSecuritySpec,
 } from "./runtime-artifacts.js";
 import { syncStatusUpdates } from "./state-sync.js";
 
-const skillNames = ["$arch", "$sage", "$flow", "$vet", "$vibe", "$build"];
+const skillNames = ["$maestro", "$arch", "$sage", "$flow", "$vet", "$vibe", "$build"];
 const workflowTemplates = {
+  "maestro.skill.md":
+    "# `$maestro`\n\nChooses the best next workflow step and recommends the right lane or assignment.\n",
   "arch.skill.md":
     "# `$arch`\n\nProduces blueprint architecture, stack rationale, subsystem design, and tradeoffs.\n",
   "sage.skill.md":
@@ -35,6 +38,150 @@ export function listSkills() {
   return skillNames;
 }
 
+function chooseMaestroRecommendation(releaseState, idea) {
+  if (releaseState.idea_status !== "CLEAR") {
+    return {
+      nextStep: "Capture or refine the project brief before any design or validation lane starts.",
+      why: "The workflow still needs a concrete brief before architecture or build decisions can be trusted.",
+      primaryLane: "brief capture",
+      supportLane: "none",
+      assignments: ['Use `ma idea "..."` or provide the brief before running in-session skills.'],
+      avoid: ["Do not start architecture or implementation yet."],
+      nextTrigger: "`ma idea`",
+    };
+  }
+
+  if (releaseState.architecture_status !== "APPROVED") {
+    return {
+      nextStep: "Run the architecture lane first.",
+      why: "The brief exists, but the workflow still needs a concrete architecture before later gates can be trusted.",
+      primaryLane: "$arch",
+      supportLane: "$sage",
+      assignments: [
+        `Use $arch to shape the current brief${idea ? ` for: ${idea}` : ""}.`,
+        "After approval, move into $sage for source-backed stack validation.",
+      ],
+      avoid: ["Do not jump to build or release work yet."],
+      nextTrigger: "`$arch`",
+    };
+  }
+
+  if (releaseState.evidence_status !== "VERIFIED") {
+    return {
+      nextStep: "Validate the architecture against approved sources.",
+      why: "The architecture exists, but the evidence gate is not yet fully verified.",
+      primaryLane: "$sage",
+      supportLane: "$flow",
+      assignments: [
+        "Run $sage using the current architecture as the probe basis.",
+        "Prepare to hand off to $flow after evidence is verified.",
+      ],
+      avoid: ["Do not treat stack choices as settled yet."],
+      nextTrigger: "`$sage`",
+    };
+  }
+
+  if (releaseState.logic_status !== "GREEN") {
+    return {
+      nextStep: "Validate system behavior and state transitions.",
+      why: "Logic is the next unresolved gate before implementation readiness can be claimed.",
+      primaryLane: "$flow",
+      supportLane: "$vet",
+      assignments: [
+        "Run $flow to map actors, states, transitions, and blockers.",
+        "Queue $vet after the logic lane confirms behavior is sound.",
+      ],
+      avoid: ["Do not merge or release yet."],
+      nextTrigger: "`$flow`",
+    };
+  }
+
+  if (releaseState.security_status !== "GREEN") {
+    return {
+      nextStep: "Run the security and trust-boundary review.",
+      why: "Security is the next unresolved gate before the workflow can unlock implementation readiness.",
+      primaryLane: "$vet",
+      supportLane: "$vibe",
+      assignments: [
+        "Run $vet to capture trust boundaries, abuse cases, and mitigations.",
+        "Move to $vibe once security is green.",
+      ],
+      avoid: ["Do not unlock implementation readiness before security review."],
+      nextTrigger: "`$vet`",
+    };
+  }
+
+  if (!["GREEN", "WAIVED"].includes(releaseState.experience_status)) {
+    return {
+      nextStep: "Review workflow clarity and friction before build unlock.",
+      why: "The experience lane is the final quality gate before the build decision.",
+      primaryLane: "$vibe",
+      supportLane: "$build",
+      assignments: [
+        "Run $vibe to capture onboarding and operability friction.",
+        "Move to $build only after experience is green or intentionally waived.",
+      ],
+      avoid: ["Do not start release promotion yet."],
+      nextTrigger: "`$vibe`",
+    };
+  }
+
+  if (releaseState.build_status === "LOCKED") {
+    return {
+      nextStep: "Unlock bounded implementation planning.",
+      why: "All upstream quality gates are green, so the workflow can now evaluate build readiness.",
+      primaryLane: "$build",
+      supportLane: "implementation",
+      assignments: [
+        "Run $build to get the current build-readiness verdict.",
+        "Use the resulting narrow build slice as the next execution assignment.",
+      ],
+      avoid: ["Do not release directly from a task branch."],
+      nextTrigger: "`$build`",
+    };
+  }
+
+  if (releaseState.merge_status !== "MERGED_TO_DEVELOPMENT") {
+    return {
+      nextStep: "Finish the implementation slice and merge it into development.",
+      why: "The build gate is ready or done, but the branch promotion path has not completed yet.",
+      primaryLane: "implementation",
+      supportLane: "merge",
+      assignments: [
+        "Use the current build plan to finish the smallest viable implementation slice.",
+        "When ready, merge feature work into development with `ma merge`.",
+      ],
+      avoid: ["Do not promote directly to prod."],
+      nextTrigger: "`ma merge <feature/*> development`",
+    };
+  }
+
+  if (releaseState.release_status !== "SHIPPED_TO_PROD") {
+    return {
+      nextStep: "Promote the approved release line to prod.",
+      why: "Implementation and merge gates are complete, so the remaining step is the controlled release promotion.",
+      primaryLane: "release",
+      supportLane: "verification",
+      assignments: [
+        "Verify the origin branch is development or an approved release branch.",
+        "Run `ma release <origin> prod` when the line is ready.",
+      ],
+      avoid: ["Do not reopen earlier gates unless a new blocker appears."],
+      nextTrigger: "`ma release <development|release/*> prod`",
+    };
+  }
+
+  return {
+    nextStep: "The workflow is already at the terminal release state.",
+    why: "All gates, merge, and release states are complete.",
+    primaryLane: "done",
+    supportLane: "verification",
+    assignments: ["Confirm final release evidence and start a new brief for the next cycle."],
+    avoid: ["Do not rerun build or release steps without a new task."],
+    nextTrigger: "`ma idea` or `$arch` for the next task",
+  };
+}
+
 async function readIdeaText() {
   const decisions = await readJson(getRuntimeReadPath("decisions.json"));
   const ideaDecision = [...decisions.decisions].reverse().find((entry) => entry.kind === "idea");
@@ -262,6 +409,23 @@ export async function runVibe() {
   await syncStatusUpdates({ experience_status: "GREEN" });
 }
 
+export async function runMaestro() {
+  const releaseState = await readJson(getRuntimeReadPath("release.json"));
+  const idea = await readIdeaText();
+  const recommendation = chooseMaestroRecommendation(releaseState, idea);
+
+  await writeMaestroPlan({ releaseState, recommendation });
+  await appendDecision({
+    kind: "skill",
+    skill: "$maestro",
+    decision: "Recommended the next workflow step and assignment lane",
+    status: "ADVISORY",
+    evidence: [recommendation],
+    blockers: [],
+    next_allowed_triggers: [recommendation.nextTrigger.replaceAll("`", "")],
+  });
+}
+
 export async function runInit() {
   const created = [];
   const targets = [
@@ -344,8 +508,8 @@ export async function runInit() {
       path.join(getRepoRoot(), "docs", "release-spec.md"),
     ],
     [
-      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.4.md"),
-      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.4.md"),
+      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.6.md"),
+      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.6.md"),
     ],
   ];