@jstn-sdk/ma 0.1.13 → 0.14.1

package/README.md

@@ -1,13 +1,18 @@
 <div align="center">
-  <img src="./docs/assets/meta-architect-logo.svg" alt="Meta-Architect logo" width="1024" height="240">
-  <p>Production-grade Codex skills and plugin package for architecture, evidence-backed OSS selection, gate-driven review, and release-minded build guidance.</p>
+  <img src="./docs/assets/banner.png" alt="Meta-Architect: quality gates and evidence verification for AI coding agents" width="1000">
+  <h1>Meta-Architect</h1>
+  <p><strong>Quality gates and evidence verification for AI coding agents.</strong></p>
+  <p>Your agent writes code fast. Meta-Architect makes it prove each stage first. Design, evidence, logic, security, experience, build. Each gate stays locked until the one before it passes.</p>
   <p>
+    <img src="https://img.shields.io/github/v/release/JustineDevs/meta-architect?display_name=tag&sort=semver" alt="GitHub release">
     <img src="https://img.shields.io/npm/v/%40jstn-sdk%2Fma" alt="npm version">
-    <img src="https://img.shields.io/badge/node-%3E%3D20-339933" alt="Node.js 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>
+    <img src="https://img.shields.io/npm/dm/%40jstn-sdk%2Fma" alt="npm downloads">
+    <a href="https://badge.socket.dev/npm/package/@jstn-sdk/ma/0.14.1">
+      <img src="https://badge.socket.dev/npm/package/@jstn-sdk/ma/0.14.1" alt="Socket security">
+    </a>
+    <a href="https://security.snyk.io/package/npm/%252540jstn-sdk%25252Fma">
+      <img src="https://snyk.io/test/npm/%40jstn-sdk%2Fma/badge.svg" alt="Snyk security">
+    </a>
     <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>
@@ -15,468 +20,127 @@
       <img src="https://img.shields.io/badge/GitHub%20Sponsors-JustineDevs-1f6feb?style=flat-square&logo=githubsponsors&logoColor=white" alt="GitHub Sponsors">
     </a>
   </p>
+  <p><a href="#quick-start">Quick Start</a> · <a href="./DEMO.md">Demo</a> · <a href="./COVERAGE.md">Verified Coverage</a> · <a href="#how-do-i-contribute">Contributing</a> · <a href="https://github.com/JustineDevs/meta-architect/issues">Issues</a></p>
 </div>
 
-> [!IMPORTANT]
-> Meta-Architect `v0.1.13` is a production-grade skills line.
-> It is not a lightweight demo branch.
-> From `v0.1.13` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
-
-## Navigate
-
-<table>
-  <tr>
-    <td><strong>Start</strong></td>
-    <td><a href="#cli-install">CLI Install</a> · <a href="#quick-start">Quick Start</a> · <a href="#setup">Setup</a></td>
-  </tr>
-  <tr>
-    <td><strong>Operate</strong></td>
-    <td><a href="#skill-surface">Skill Surface</a> · <a href="#gated-lanes">Gated Lanes</a> · <a href="#gate-model">Gate Model</a> · <a href="#learning-loop-core">Learning Loop Core</a></td>
-  </tr>
-  <tr>
-    <td><strong>Ship</strong></td>
-    <td><a href="#release-and-packaging">Release and Packaging</a> · <a href="#package-surface">Package Surface</a> · <a href="#release-hygiene">Release Hygiene</a></td>
-  </tr>
-  <tr>
-    <td><strong>Reference</strong></td>
-    <td><a href="#repository-structure">Repository Structure</a> · <a href="#documentation">Documentation</a> · <a href="#core-maintainers">Core Maintainers</a></td>
-  </tr>
-</table>
-
-## Overview
-
-Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.
-
-It adds:
-
-- an architecture-first lane before implementation
-- evidence-backed OSS selection through GitMCP-connected sources
-- explicit logic, security, and DX/UX review gates
-- a singular `$maestro` bounded autonomous manager plus non-gating helper skills for alignment, diagnosis, test-first work, and cleanup
-- installable skills and a reproducible package surface
-
 > [!NOTE]
+> Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.
 > Meta-Architect does not replace your coding runtime.
 > It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.
 
-## Acknowledgement
-
-Meta-Architect was shaped in part by ideas surfaced through the `oh-my-codex` ecosystem.
-Acknowledgement is due for the inspiration around Codex-native workflow packaging, skill distribution, and practical delivery surfaces that helped inform this project.
-
-## Support
-
-- [GitHub Sponsors](https://github.com/sponsors/JustineDevs)
-- [Buy Me A Coffee](https://www.buymeacoffee.com/justinedevs)
-
-<table>
-  <tr>
-    <td><strong>Linux-native packages</strong></td>
-    <td><code>.deb</code> for Debian-family distros, <code>.pkg.tar.xz</code> for Arch-family distros, and <code>.rpm</code> for Fedora/openSUSE-style distros</td>
-  </tr>
-  <tr>
-    <td><strong>npm package</strong></td>
-    <td><code>@jstn-sdk/ma</code> (fallback install path)</td>
-  </tr>
-  <tr>
-    <td><strong>Helper command</strong></td>
-    <td><code>ma</code> (secondary support surface)</td>
-  </tr>
-  <tr>
-    <td><strong>Runtime</strong></td>
-    <td>Node.js <code>&gt;=20</code>, npm <code>@10</code></td>
-  </tr>
-  <tr>
-    <td><strong>Release line</strong></td>
-    <td><code>v0.1.13</code></td>
-  </tr>
-  <tr>
-    <td><strong>License</strong></td>
-    <td><a href="./LICENSE">MIT</a></td>
-  </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`
-- npm `>=10`
-- Git
-- an MCP-capable coding runtime
-- Codex for the recommended package-first path
-- macOS, Linux, or WSL2 recommended
-
-> [!TIP]
-> The most reliable default environment is a Unix-like shell with Git, Node.js, and an MCP-capable runtime already configured.
-
-## CLI Install
-
-macOS, Linux, WSL, and Git-Bash:
-
-```bash
-# One-line install (POSIX shells only; see Windows note below)
-curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh
-```
-
-This jsDelivr-backed installer runs the canonical package install:
-
-```bash
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-```
-
-Then it seeds the local MA runtime with `ma setup`. Start with:
-
-```bash
-ma --madmax --high
-```
-
-Windows note: use WSL or Git-Bash for the one-line POSIX installer. In PowerShell, use the npm fallback command directly.
-
-## Default Install Surfaces
-
-Meta-Architect is a Codex-native session workflow. The jsDelivr CLI installer is the recommended quick-start path for POSIX shells; Linux distro packages remain available for distro-managed installs.
-
-<details>
-<summary><strong>Platform package commands</strong></summary>
-
-### Debian, Ubuntu, Linux Mint, Pop!_OS
-
-Download the GitHub release `.deb` asset and install it with your normal package command:
-
-```bash
-sudo apt install ./meta-architect_<version>_all.deb
-```
-
-### Arch, Manjaro, EndeavourOS
-
-Download the GitHub release pacman package asset and install it with:
-
-```bash
-sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
-```
+<img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/v0.14.1/docs/assets/DEMO_VIDEO.gif" alt="Meta-Architect demo video" width="800">
 
-### Fedora, RHEL-family, openSUSE
+## 🧩 Quick start
 
-Download the GitHub release RPM asset and install it with your distro-native command:
-
-```bash
-sudo dnf install ./meta-architect-<version>-1.noarch.rpm
-# or
-sudo zypper install ./meta-architect-<version>-1.noarch.rpm
-```
-
-These packages install the Meta-Architect payload and expose `ma` / `meta-architect`, but the product still runs inside a Codex-native session. They do not create a separate desktop or terminal product.
-
-</details>
-
-<details open>
-<summary><strong>npm fallback and runtime assumptions</strong></summary>
-
-### npm fallback
-
-```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-
-# Start Codex context if needed
-ma --madmax --high
-
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
-
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
-```
-
-What this assumes:
-
-- Codex is installed globally
-- Meta-Architect is installed globally as the skills/plugin package
-- Meta-Architect installs its published skill surface into the active Codex home
-- the product experience happens through the skill workflow inside Codex
-
-> [!IMPORTANT]
-> The jsDelivr installer is a POSIX-shell convenience wrapper around the canonical npm install. Use the distro packages when you specifically need distro-managed install assets.
-
-</details>
-
-## Repository Branch Strategy
-
-Meta-Architect’s repository workflow follows a stricter release posture focused on gated promotion:
-
-- `main` = release-facing protected branch
-- `development` = normal integration branch
-- `feature/*` = short-lived contribution branches
-- contributors branch from `development`
-- normal PRs target `development`
-- only curated promotions move `development` into `main`
+| ✅ Recommended | 🧰 All available installation commands |
+| --- | --- |
+| Use the signed jsDelivr installer on macOS, Linux, WSL, or Git Bash.<br><br>`curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh`<br><br>`curl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256`<br><br>`sed 's#scripts/install.sh#install.sh#' install.sh.sha256 \| sha256sum -c -`<br><br>`sh install.sh`<br><br>`ma --madmax --high`<br><br>`$maestro I want to build: [your project idea]` | **npm global**<br><br>`npm i -g @openai/codex@latest @jstn-sdk/ma@latest`<br><br>**Meta-Architect only**<br><br>`npm i -g @jstn-sdk/ma@latest`<br><br>**Windows PowerShell**<br><br>`npm i -g @openai/codex@latest @jstn-sdk/ma@latest`<br><br>**Debian / Ubuntu**<br><br>`sudo apt install ./meta-architect_&lt;version&gt;_all.deb`<br><br>**Arch Linux**<br><br>`sudo pacman -U ./meta-architect-&lt;version&gt;-1-any.pkg.tar.xz`<br><br>**Fedora / openSUSE**<br><br>`sudo dnf install ./meta-architect-&lt;version&gt;-1.noarch.rpm` |
 
-> [!CAUTION]
-> `main` is intended to be protected and exceptional.
-> Maintainers should stop bypass-pushing to `main` except for genuine emergency or admin recovery cases.
+### AI agent installation prompt
 
-## Setup
+Copy and paste this prompt into your AI coding agent:
 
-### Package setup
+```text
+Install Meta-Architect for this project.
 
-Debian-family install:
+1. Detect the current AI host and its native project configuration surface.
+2. Install or update `@jstn-sdk/ma@latest` using the host's supported package manager.
+3. Set `MA_AGENT` to the detected host ID when a host-specific surface is available.
+4. Run `ma setup` and accept the detected project scope and targets.
+5. Verify the generated `.ma/` state and native host artifacts.
+6. Report the installed version, selected host, generated files, and any unsupported capabilities.
 
-```bash
-sudo apt install ./meta-architect_<version>_all.deb
+Do not overwrite user-owned files, modify unrelated configuration, or claim a host is supported without verification.
 ```
 
-Arch-family install:
+More install options: [docs/getting-started.md](./docs/getting-started.md)
 
-```bash
-sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
-```
+Uninstall Meta-Architect: `npm uninstall -g @jstn-sdk/ma`
+Uninstall Meta-Architect and Codex: `npm uninstall -g @jstn-sdk/ma @openai/codex`
 
-Fedora/openSUSE install:
+### Install into an AI vendor host
 
-```bash
-sudo dnf install ./meta-architect-<version>-1.noarch.rpm
-```
-
-npm fallback:
+Install Meta-Architect once, then select the host surface before launch. The
+pre-launch step detects installed hosts and writes the selected scope and
+targets to `.ma/prelaunch.json`.
 
 ```bash
-# Install
+# Codex (reference host)
 npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-
-# Launch
 ma --madmax --high
 
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
+# Claude Code
+MA_AGENT=claude-code npm i -g @jstn-sdk/ma@latest
+MA_AGENT=claude-code ma --madmax --high
 
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
-```
-
-This gives you:
-
-- the installed Meta-Architect skill surface
-- the canonical Meta-Architect skill entrypoints inside a Codex session
-- the optional `ma` helper command when a guided start is useful
+# Cursor
+MA_AGENT=cursor npm i -g @jstn-sdk/ma@latest
+MA_AGENT=cursor ma --madmax --high
 
-### Contributor setup: source checkout
-
-Use this path only if you want to work on Meta-Architect itself.
-
-```bash
-git clone https://github.com/JustineDevs/meta-architect.git
-cd meta-architect
-npm install
-npm link
+# Any registered host surface
+MA_AGENT=<host-id> npm i -g @jstn-sdk/ma@latest
+MA_AGENT=<host-id> ma --madmax --high
 ```
 
-`npm link` makes `ma` and `meta-architect` available from the local checkout.
+MA installs or reuses the native skill/configuration surface for the selected
+host and keeps the canonical workflow unchanged. See the [host compatibility
+evidence](./docs/agent-compat-integration-report.md) for supported surfaces.
 
-## Quick Start
-
-### 1. Start Codex context if needed
-
-```bash
-ma --madmax --high
-```
+### Claude Code marketplace
 
-### 2. Start with the real usage-workflow prompt
-
-Use the same operator shape defined in [example/usage-workflow.md](./example/usage-workflow.md).
-
-Quick-start prompt:
+The repository includes a hosted Claude Code marketplace for the existing
+`plugins/meta-architect` bundle:
 
 ```text
-$maestro
-
-Or start directly with:
-
-$arch I want to build: [PROJECT IDEA]
-
-Context:
-- Product type: [web app / mobile app / API / marketplace / agent system / internal tool]
-- Users: [who will use it]
-- Core problem: [what problem it solves]
-- Main features:
-  1. [feature one]
-  2. [feature two]
-  3. [feature three]
-- Constraints:
-  - Budget: [low / medium / high]
-  - Team size: [solo / small / medium]
-  - Timeline: [e.g. 2 weeks MVP, 3 months beta]
-  - Preferred stack: [optional]
-  - Avoid: [optional]
-- Quality priorities:
-  - [e.g. speed, low cost, security, DX, maintainability, scalability]
-- Deployment target:
-  - [Vercel / Docker / VPS / AWS / GCP / local-first / hybrid]
-
-Required output:
-1. Problem framing
-2. Recommended architecture
-3. Stack decision with justification
-4. System components and responsibilities
-5. Data model and storage choices
-6. Auth/security considerations
-7. DX/UX considerations
-8. Delivery plan for v0.1.13
-9. Risks and trade-offs
-10. Decision log
-11. Exact next trigger to run after this
+/plugin marketplace add JustineDevs/meta-architect
+/plugin install meta-architect@meta-architect
 ```
 
-### 3. Run the full trigger sequence inside Codex
+<details>
+<summary><strong>🔌 All 33 plugins & features</strong></summary>
 
-The singular umbrella in-session entry point is `$maestro`. It is the bounded autonomous manager for the in-session workflow. The package does not ship a separate `$meta-architect` skill.
+The plugin and feature inventory is maintained in the [support bundle manifest](./support-bundle.json) and [skills manifest](./skills/index.json), with verification in the [coverage documentation](./COVERAGE.md).
+</details>
 
-The release-gated sequence stays fixed:
+<details>
+<summary><strong>Why do AI coding agents need gates?</strong></summary>
 
-```text
-$arch
-$sage
-$flow
-$vet
-$vibe
-$build
-```
+Your agent writes code faster than you review it. Studies and dev surveys keep finding the same failures:
 
-Optional publishable non-gating helper skills available around that sequence:
+- Plausible code with wrong logic
+- Imports of packages which don't exist
+- Outdated APIs from training cutoffs
+- "Done" claims with zero proof
 
-```text
-$align
-$diagnose
-$tdd
-$cleanup
-```
+Meta-Architect blocks each one:
 
-See [example/usage-workflow.md](./example/usage-workflow.md) for the full prompt templates for each step.
+- No architecture without a decision record. `$arch` writes the blueprint and the trade-offs.
+- No stack claims without evidence. `$sage` grades every dependency claim VERIFIED, PARTIAL, or MISSING against upstream repos through GitMCP.
+- No build while a gate is red. Logic, security, and DX reviews fail closed.
+- No release claims without proof. Releases need issue-linked, production-verified evidence.
 
-### 4. Secondary helper path
+## What is Meta-Architect?
 
-If you are working from a repository directly and need scaffolded local support files, use:
+An open-source workflow governor for AI coding agents. You install it as a skill package in your agent host. It adds six gated lanes plus `$maestro`, a bounded manager which routes your work through them. It doesn't replace your agent, runtime, or model. It governs what they produce.
 
-```bash
-ma bootstrap
-ma bootstrap --init-mcp
-ma doctor
-ma setup
-ma
-```
+| Fact | Value |
+| --- | --- |
+| Type | Skill and plugin package for AI coding agent hosts |
+| Reference host | Codex (full support) |
+| Compatibility scope | Codex, OpenCode, Gemini CLI, Amp, Claude Code, Goose, Hermes, Pi, Cursor, Windsurf, Cline, Continue, Roo, Kiro CLI, Junie, GitHub Copilot, and Antigravity ([coverage evidence](./docs/agent-compat-integration-report.md)) |
+| Runtime | Node.js 20+ |
+| Install | `npm i -g @jstn-sdk/ma` |
+| Evidence sources | GitMCP / MCP endpoints |
+| License | MIT |
 
-Recommended lazy-user path:
-- run `ma bootstrap` first to repair packaged assets, scaffold local runtime files, and verify the environment
-- add `--init-mcp` if you want starter GitMCP source files written into the local `mcp/` folder when it is empty or invalid
-- use `ma doctor` later when you want a check-only readiness report without changing files
+## How does it work?
 
-Expected output for `ma setup`:
+State your intent once. `$maestro` picks the next safe step and stops when something fails.
 
 ```text
-meta-architect setup
-====================
-ready: .codex/agents
-ready: .codex/prompts
-ready: .ma/skills
-ready: .ma/evidence
-ready: .ma/context
-ready: .ma/specs
-ready: .ma/plans
-ready: mcp
-ready: docs
-ready: docs/qa
-ready: sprint
-```
-
-### 5. Configure GitMCP sources
-
-Add real repository-backed endpoints in `mcp/servers.json`.
-
-Example:
-
-```json
-{
-  "category": "candidate",
-  "repo": "owner/repo",
-  "endpoint": "https://gitmcp.io/owner/repo"
-}
-```
-
-Recommended source-selection posture:
-
-- use packaged native references to narrow candidate families first
-- map serious candidates to exact upstream GitMCP endpoints
-- verify final choices against upstream repos and official docs before approval
-
-Core discovery standard:
-
-- `https://ossium.live/home`
-- use Ossium to discover trending OSS, curated repos, YC-backed repos, GSoC orgs, and contribution opportunities faster
-- `https://trendshift.io/`
-- use Trendshift for rising GitHub engagement and topic-driven trend discovery
-- `https://devhunt.org/`
-- use Dev Hunt for recently launched developer tools and current dev-tool discovery
-- `https://libraries.io/`
-- use Libraries.io for package and dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
-- `https://openhub.net/`
-- use Open Hub for project activity, contributor, popularity, and comparison signals
-- `https://www.opensourceprojects.dev/`
-- use Open-source Projects for curated OSS discovery and detailed project writeups
-- treat all of these as discovery acceleration, then convert promising finds into exact upstream GitMCP mappings and official-doc checks for `$sage`
-
-Useful native references:
-
-- `skills/maestro/references/native-ingest-map.md`
-- `skills/sage/references/source-selection.md`
-- `skills/vet/references/security-playbooks.md`
-
-Canonical `$sage` order:
-
-1. Start with the upstream repo and official docs if you already know them.
-2. Use discovery accelerators only when you need help finding or narrowing candidates.
-3. Map selected candidates to exact upstream GitMCP endpoints.
-4. Verify against upstream repos and official docs before treating anything as approved evidence.
-
-> [!IMPORTANT]
-> Verified release evidence must come from repository-form GitMCP endpoints such as `https://gitmcp.io/{owner}/{repo}`.
-> A generic documentation endpoint such as `https://gitmcp.io/docs` does not count as VERIFIED evidence for build unlocking.
-> Discovery surfaces such as Ossium, Trendshift, Dev Hunt, Libraries.io, Open Hub, and Open-source Projects are not substitutes for upstream repo or official-doc verification.
-
-### 6. Secondary helper flow outside Codex
-
-If you need scripted repo-local validation rather than the interactive runtime workflow:
-
-```bash
-ma idea "Prepare Meta-Architect v0.1.13 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
-ma run '$arch'
-ma run '$sage'
-ma run '$flow'
-ma run '$vet'
-ma run '$vibe'
-ma status
-ma run '$build'
+$maestro I want to build: a multi-tenant analytics API for logistics customers
 ```
 
-Expected status before the helper-path `$build`:
-
 ```text
 Meta-Architect Status
 =====================
@@ -487,387 +151,66 @@ Logic: GREEN
 Security: GREEN
 Experience: GREEN
 Build: LOCKED
-Next allowed triggers:
-$build
 ```
 
-Expected helper-path build output:
-
-```text
-Build gate is green.
-Suggested branches:
-- feature/implementation
-- feature/verification
-Optional worktree commands:
-git worktree add ../implementation feature/implementation
-git worktree add ../verification feature/verification
-```
-
-### 7. Simple command guide
-
-Meta-Architect has two surfaces.
-
-- terminal helper commands
-- in-session skills
-
-The umbrella in-session entry point is `$maestro`. There is no separate shipped `$meta-architect` skill surface.
-
-Terminal commands are normal shell commands you run in the terminal:
-
-```bash
-ma setup
-ma init
-ma idea "Build a product"
-ma status
-ma status --maestro-view
-ma verify --architect
-ma run '$arch'
-ma run '$maestro' --auto-heal --parallel
-```
-
-In-session skills are prompts you use inside the Codex conversation after launch:
-
-```text
-$maestro
-$arch
-$sage
-$flow
-$vet
-$vibe
-$build
-$align
-$diagnose
-$tdd
-$cleanup
-```
-
-Plain-language difference:
-- `ma ...` = helper commands in the terminal
-- `$...` = the product experience inside Codex
-
-Autonomous-manager contract:
-- `$maestro` is the only umbrella in-session surface
-- it manages the next allowed step and lane handoff, but it does not replace the gated outputs owned by `$arch -> $sage -> $flow -> $vet -> $vibe -> $build`
-- `$align`, `$diagnose`, `$tdd`, and `$cleanup` are publishable helper skills that do not move release gates
-
-What `ma setup` and `ma init` do:
-- both currently do the same thing
-- they create the local support files and folders
-- they prepare `.ma/` runtime files such as context, specs, plans, evidence, and runbook files
-- they do not run the skill workflow by themselves
-
-What `ma bootstrap` does:
-- checks whether `codex` is callable
-- repairs installed skills and support-bundle assets when possible
-- runs local scaffold setup
-- can seed starter MCP files with `--init-mcp` when the local MCP config is empty or invalid
-- reports `READY`, `READY_WITH_WARNINGS`, or `BLOCKED`
-
-What `ma doctor` does:
-- runs the same environment checks without changing files
-- prints the current readiness state and exact next step
-
-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 or act as the bounded autonomous manager for the umbrella workflow
-- use `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` inside the Codex session
-- use `$align`, `$diagnose`, `$tdd`, or `$cleanup` when a helper is enough and the release gate should stay where it is
-- use `ma bootstrap` when you want the lazy-user setup path
-- use `ma doctor` when you want a check-only environment report
-- 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
+Build stays LOCKED until every upstream gate passes. Red stays red.
 
-## Skill Surface
+## The six gates
 
-> [!TIP]
-> Remember the surface as **manager -> gated lanes -> helpers**.
-> `$maestro` coordinates, gated lanes move release state, and helper skills support without unlocking build.
-
-Meta-Architect’s in-session surface has three layers:
-
-- umbrella autonomous manager: `$maestro`
-- fixed gated lanes: `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
-- non-gating helper skills: `$align`, `$diagnose`, `$tdd`, `$cleanup`
-
-Helper skills are publishable surfaces, but they do not own release-state transitions.
-
-> [!NOTE]
-> MA also discovers existing repo-local skills, MCP configs, and plugin manifests through the Environment Awareness Core.
-> Discovered capabilities are `available_capability` context only: MA may select them when task-relevant, but it does not auto-run, mutate, or treat them as build evidence.
-
-> [!NOTE]
-> Universal Plugin Broker Core uses a hybrid model for cross-agent plugins: MCP stdio tooling for hosts that support MCP config injection, and `.agents/skills` context payloads for the broader supported-agent surface.
-> Plugin broker receipts are compatibility configuration, not build evidence or lane approval.
-
-## Core Maintainers
-
-<table>
-  <tr>
-    <td><strong>Role</strong></td>
-    <td><strong>Name</strong></td>
-    <td><strong>GitHub</strong></td>
-  </tr>
-  <tr>
-    <td>Creator / Maintainer</td>
-    <td>JustineDevs</td>
-    <td><a href="https://github.com/JustineDevs">@JustineDevs</a></td>
-  </tr>
-</table>
-
-## Gated Lanes
-
-> [!IMPORTANT]
-> Read this as a release runway: **design -> evidence -> logic -> security -> experience -> build**.
-> Do not skip lanes when the release gate is still locked.
-
-<details open>
-<summary><strong>Release-gated lane map</strong></summary>
-
-| Trigger | Purpose | Main output | Gate effect |
-| --- | --- | --- | --- |
-| `$arch` | Produce the first-pass architecture blueprint | decision entry | `architecture_status = APPROVED` |
-| `$sage` | Ground major choices in configured GitMCP evidence | evidence records | `evidence_status = VERIFIED | PARTIAL | MISSING` |
-| `$flow` | Review baseline logic and state transitions | logic review entry | `logic_status = PENDING | GREEN | RED` |
-| `$vet` | Run baseline security and dependency review | audit and CVE records | `security_status = PENDING | GREEN | RED` |
-| `$vibe` | Review developer and user experience implications | DX/UX outcome record | `experience_status = PENDING | GREEN | RED | WAIVED` |
-| `$build` | Run a bounded build-readiness loop | build-ready decision + `.ma/plans/build.md` | `build_status = READY | RUNNING | DONE` |
-
-</details>
-
-## Helper Skills
-
-<details>
-<summary><strong>Non-gating helper skill map</strong></summary>
-
-| Trigger | Purpose | Gate effect |
+| Lane | Question it answers | Gate |
 | --- | --- | --- |
-| `$align` | Normalize terminology, tighten scope, and improve prompt or docs clarity | none |
-| `$diagnose` | Decompose blocked-lane symptoms into hypotheses and next probes | none |
-| `$tdd` | Lock behavior with regression-first or test-first scaffolding | none |
-| `$cleanup` | Simplify noisy output and run a final-pass anti-slop cleanup | none |
-
-> [!NOTE]
-> Helper skills are backed by `helper_orchestration_core`.
-> They write helper receipts, return authority to `$maestro` or the owning lane, and never record as gate approval.
+| `$arch` | What are you building, and why this shape? | architecture_status |
+| `$sage` | Do your stack choices trace to real upstream evidence? | evidence_status |
+| `$flow` | Do the logic and state transitions hold? | logic_status |
+| `$vet` | Does it survive security and dependency review? | security_status |
+| `$vibe` | Will developers and users tolerate it? | experience_status |
+| `$build` | What's the narrowest safe thing to build now? | build_status |
 
-</details>
+Four helpers support the lanes without moving gates: `$align`, `$diagnose`, `$tdd`, `$cleanup`.
 
-## Gate Model
+### How is it different from Spec Kit, BMAD, or Agent OS?
 
-Meta-Architect is intentionally fail-closed.
+Spec-driven tools structure what your agent writes. Meta-Architect enforces what your agent proves.
 
-> [!NOTE]
-> Green states allow the next safe move.
-> Red or locked states preserve the blocker instead of pretending the workflow is ready.
+| | Spec Kit | BMAD | Agent OS | Meta-Architect |
+| --- | --- | --- | --- | --- |
+| Structured workflow | Yes | Yes | Yes | Yes |
+| Gates which block | No | No | No | Yes |
+| External evidence verification | No | No | No | Yes, GitMCP-graded |
+| Learning loop with promotion rules | No | No | No | Yes |
+| Multi-host | Yes | Yes | Yes | Codex today, expanding |
 
-<details open>
-<summary><strong>Status vocabulary</strong></summary>
-
-| Status | Meaning |
-| --- | --- |
-| `CLEAR` | enough input exists to proceed |
-| `APPROVED` | the architecture lane produced an acceptable first-pass blueprint |
-| `VERIFIED` | live evidence was grounded through approved GitMCP sources |
-| `PARTIAL` | evidence is configured but live proof is incomplete or unavailable |
-| `PENDING` | the lane has recorded interim review state but not final approval or rejection yet |
-| `GREEN` | the current baseline review passed |
-| `RED` | the lane is blocked or failed |
-| `WAIVED` | the lane was intentionally waived with a recorded reason |
-| `LOCKED` | downstream work is not allowed yet |
-| `READY` | the next bounded gated step is prepared |
-| `RUNNING` | the bounded build substep is active |
-| `DONE` | the current bounded build substep completed with recorded evidence |
+Already using a spec tool? Keep it. Their specs become inputs. MA's gates verify the execution.
 
 </details>
 
-> [!CAUTION]
-> `$build` must stay locked until the upstream release state in `.ma/release.json` satisfies the gate contract.
-> Meta-Architect is designed to stop on blockers rather than silently continue.
-> Rich runtime artifacts live in `.ma/context/`, `.ma/specs/`, `.ma/plans/`, and `.ma/runbook.md`.
+## Who is it for?
 
-## Learning Loop Core
+- Solo builders shipping with AI agents who want release discipline without enterprise process
+- OSS contributors who need stack decisions they defend in review
+- Skip it if you want an unattended agent writing code. MA governs your agent. It isn't one.
 
-> [!NOTE]
-> Meta-Architect records learnings as candidates first.
-> A learning can influence future context only after it has source, evidence, authority, and a next verification path.
+## How do I contribute?
 
-<details open>
-<summary><strong>Reliability domains</strong></summary>
+1. Open an issue before a PR. It saves rework.
+2. Start here: [issues labeled `triage`](https://github.com/JustineDevs/meta-architect/issues)
+3. Branch from `dev`. `main` is protected and release-facing.
+4. Run `npm test` before you submit. Follow [AGENTS.md](./AGENTS.md).
+5. AI-assisted PRs welcome. Explain every line you submit or expect a close.
 
-| Domain | What improves over time |
-| --- | --- |
-| Core & Orchestration | manager runs, lane handoffs, and autonomous routing |
-| Memory & Knowledge | project notes, Obsidian vault context, and semantic receipts |
-| Intelligence & Learning | prompt strategy, context budgeting, and rehearsal outcomes |
-| Code Quality & Testing | test failures, build results, and execution learnings |
-| Security & Compliance | trust-boundary findings, exposure scans, and redaction receipts |
-| Architecture & Methodology | decisions, tradeoffs, and reusable patterns |
-| DevOps & Observability | release checks, package smokes, runtime traces, and hook audits |
-| Extensibility | skills, plugins, MCP policy, and host compatibility |
-| Domain-Specific | stack facts, project domain notes, and trusted source context |
+## Learn more
 
-</details>
-
-## Release and Packaging
-
-Meta-Architect has three related but different distribution surfaces.
-
-> [!TIP]
-> Use **npm** for the public package, **Linux packages** for distro-managed installs, and **skills bundle** when only the skill payload is needed.
-
-<details open>
-<summary><strong>Distribution surfaces</strong></summary>
-
-| Surface | Purpose | Produced by |
-| --- | --- | --- |
-| Linux native packages | distro-managed install assets for Debian-family and Arch-family environments | `npm run linux:packages:build` and GitHub release assets |
-| npm package | public package containing the installable Meta-Architect skills/plugin system, docs, scripts, and canonical skills | `npm publish` or `npm pack` |
-| skills bundle | narrower tarball containing `skills/` only | `npm run skills:pack` |
-
-</details>
-
-Required packaging commands:
-
-```bash
-npm run skills:manifest
-npm run skills:validate
-npm run skills:pack
-npm run skills:install -- --path ./dist/installed-skills
-npm run linux:packages:build
-npm run release:assets
-npm run pack:inspect
-```
-
-Pre-publish rules:
-
-- `skills/index.json` must be current
-- `npm run skills:validate` must pass
-- `dist/meta-architect-skills.tgz` must exist
-- `dist/meta-architect_<version>_all.deb` must exist for Debian-family installs
-- `dist/meta-architect-<version>-1-any.pkg.tar.xz` must exist for Arch-family installs
-- `dist/meta-architect-<version>-1.noarch.rpm` must exist for Fedora/openSUSE-style installs
-- `npm pack --dry-run` must show only intended public files
-- docs must match the real skills/plugin and release behavior
-
-Release lane discipline:
-- stable versions publish to npm `latest`
-- prerelease versions such as `0.2.0-beta.1` must publish with an explicit dist-tag such as `beta`
-- alternate lanes such as `next`, `beta`, and `canary` must never overwrite `latest`
-
-Maintainer version-bump flow:
-1. Bump the package with `npm version <version> --no-git-tag-version`
-2. Update `CHANGELOG.md`, `RELEASE.md`, and `docs/qa/release-readiness-<version>.md`
-3. Run `npm run release:verify`
-4. Run `npm run release:check`
-5. Create and push tag `v<version>`
-6. Build and smoke-check the Linux native packages with `npm run linux:packages:build`, `npm run linux:packages:smoke`, and `npm run release:assets` on Linux
-7. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
-7. Local shell fallback when not publishing from GitHub Actions or GitLab CI/CD:
-   - Stable publish: `npm publish --access public`
-   - Prerelease publish: `npm publish --access public --tag <lane>`
-8. Verify publish state with `npm view @jstn-sdk/ma version dist-tags time --json`
-9. Confirm the GitHub release includes `dist/meta-architect-skills.tgz`, `meta-architect_<version>_all.deb`, `meta-architect-<version>-1-any.pkg.tar.xz`, and `meta-architect-<version>-1.noarch.rpm`
-
-Provenance note:
-- `npm publish --provenance` requires a supported cloud CI/CD provider
-- a local shell publish will fail with `Automatic provenance generation not supported for provider: null`
-- use the repository publish workflow when provenance is required
-
-Release automation:
-- `npm run release:sync` bumps and synchronizes the active release line only when watched release-relevant files changed
-- `npm run release:advance` force-bumps the next patch line and rewrites the same version-bearing files
-- `.github/workflows/release-sync.yml` runs the sync path on `main` pushes that touch watched release-relevant paths
-- `.github/workflows/release-advance.yml` runs after a published GitHub release and advances the repo to the next patch line automatically
-
-> [!CAUTION]
-> Do not claim npm, GitHub release, or any other publish channel until that channel has actually succeeded.
-> Release documentation must match reality, not intent.
-
-## Package Surface
-
-<table>
-  <tr>
-    <td><strong>Included</strong></td>
-    <td><code>bin/</code>, <code>skills/</code>, <code>docs/</code>, <code>data/</code>, <code>scripts/</code>, <code>index.js</code>, <code>README.md</code>, <code>DEMO.md</code>, <code>COVERAGE.md</code>, <code>LICENSE</code></td>
-  </tr>
-  <tr>
-    <td><strong>Excluded</strong></td>
-    <td><code>.ma/</code> runtime state, context, specs, plans, logs, caches, and temp install outputs</td>
-  </tr>
-</table>
-
-## Repository Structure
-
-> [!NOTE]
-> The repository is split by responsibility: runtime prompts, public skills, plugin distribution, docs, MCP evidence config, and release tooling stay in separate folders.
-
-<table>
-  <tr>
-    <td><strong>Path</strong></td>
-    <td><strong>Responsibility</strong></td>
-  </tr>
-  <tr>
-    <td><code>.codex/</code></td>
-    <td>runtime prompts, hooks, and repo guidance</td>
-  </tr>
-  <tr>
-    <td><code>skills/</code></td>
-    <td>canonical public skill contracts</td>
-  </tr>
-  <tr>
-    <td><code>plugins/meta-architect/</code></td>
-    <td>plugin-oriented distribution surface</td>
-  </tr>
-  <tr>
-    <td><code>docs/</code></td>
-    <td>installation, publishing, and release documentation</td>
-  </tr>
-  <tr>
-    <td><code>missions/</code></td>
-    <td>reproducible scenario-driven workflows</td>
-  </tr>
-  <tr>
-    <td><code>mcp/</code></td>
-    <td>GitMCP endpoint and collection configuration</td>
-  </tr>
-  <tr>
-    <td><code>scripts/</code></td>
-    <td>validation, packing, and install helpers</td>
-  </tr>
-  <tr>
-    <td><code>sprint/</code></td>
-    <td>human-readable phased workflow documents</td>
-  </tr>
-</table>
-
-## Documentation
-
-<details open>
-<summary><strong>Primary docs and evidence surfaces</strong></summary>
-
-| Surface | Purpose |
-| --- | --- |
-| [Getting Started](./docs/getting-started.md) | end-to-end local onboarding |
-| [Skills Reference](./docs/skills.md) | trigger-by-trigger contract guide |
-| [Installed Support Bundle](./docs/installed-sdk.md) | standard packaged asset path for skills and helper flows |
-| [Skills Publishing](./docs/skills-publishing.md) | source-to-package pipeline |
-| [MCP Setup](./docs/mcp-setup.md) | evidence endpoint policy |
-| [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
-| [Production Demo Guide](./DEMO.md) | real MA release-hardening walkthrough |
-| [Coverage Matrix](./COVERAGE.md) | current verified capability and package proof map |
-| [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.13.md) | QA evidence for the `v0.1.13` line |
-
-</details>
-
-## Release Hygiene
-
-> [!WARNING]
-> Runtime `.ma` logs, state, tmp, and cache files must not be shipped.
-> Public docs must match actual package behavior.
-> Publish statements must match reality.
-> Skill contracts must stay aligned across canonical and plugin-facing copies.
+- [Getting Started](./docs/getting-started.md)
+- [Skills Reference](./docs/skills.md)
+- [Demo](./DEMO.md)
+- [Coverage Matrix](./COVERAGE.md): the proof behind every claim on this page
+- [Release Spec](./docs/release-spec.md)
+- [Disk-Bounded Test and Review Runs](./docs/disk-optimization.md)
+- [MCP Setup](./docs/mcp-setup.md)
+- [ChatGPT Integration](./docs/chatgpt-integration.md): deployment requirements and publication boundary
 
 ## License
 
-[MIT](./LICENSE)
+[MIT](./LICENSE). Built by [@JustineDevs](https://github.com/JustineDevs). Shaped by ideas from the `oh-my-codex` ecosystem.
+
+Found a bad claim before it shipped? Star the repo. It helps other developers find it.