@jstn-sdk/ma 0.1.4 → 0.1.5

package/docs/skills.md

@@ -1,119 +1,182 @@
-# Skills
+# Skills Reference
 
-Meta-Architect’s canonical Codex runtime surface is:
-- `$arch`
-- `$sage`
-- `$flow`
-- `$vet`
-- `$vibe`
-- `$build`
+Meta-Architect exposes six core runtime skills inside Codex. These skill tags are the main product surface.
 
-## Real usage path
+## Runtime-first rule
 
-Install the package once, start Codex context if needed, and use the skills directly in-session.
+Canonical runtime usage:
 
 ```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-
-# Start Codex context if needed
+npm i -g @openai/codex @jstn-sdk/ma
 ma --madmax --high
+```
 
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
+Then operate inside Codex with:
 
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
+```text
+$arch
+$sage
+$flow
+$vet
+$vibe
+$build
 ```
 
-Then inside the Codex session:
-1. Start with the structured `$arch` prompt
-2. Continue through `$sage -> $flow -> $vet -> $vibe -> $build`
+Scripted helpers such as `ma idea`, `ma status`, and `ma run ...` exist for automation, smoke checks, and repo-local maintenance. They are not the primary story.
+
+## Shared output contract
+
+Every lane must preserve this shape:
+- `decision`
+- `status`
+- `evidence`
+- `blockers`
+- `next_allowed_triggers`
 
-## Simple difference
+Publishable skill folders live in [skills/](../skills/). Internal runtime logic lives in [src/skills.js](../src/skills.js).
 
-Meta-Architect has two surfaces:
+## Skill overview
+
+| Skill | Trigger | Purpose | Status effect |
+| --- | --- | --- | --- |
+| Meta-Architect Arch | `$arch` | architecture blueprint and tradeoff framing | `architecture_status` |
+| Meta-Architect Sage | `$sage` | GitMCP-backed evidence binding | `evidence_status` |
+| Meta-Architect Flow | `$flow` | logic and state review | `logic_status` |
+| Meta-Architect Vet | `$vet` | security review | `security_status` |
+| Meta-Architect Vibe | `$vibe` | developer/user experience review | `experience_status` |
+| Meta-Architect Build | `$build` | build-gate evaluation and bounded branch planning | `build_status` |
+
+## `$arch`
+
+Canonical trigger inside Codex:
+- `$arch`
 
-- terminal commands
-- in-session skills
+Purpose:
+- produce the first architecture blueprint from the captured idea
+- define stack rationale, tradeoffs, and downstream evidence requirements
 
-Terminal commands are run in the shell:
+Scripted helper path:
 
 ```bash
-ma setup
-ma init
-ma idea "Build a product"
-ma status
+ma idea "Build a SaaS billing dashboard"
 ma run '$arch'
 ```
 
-In-session skills are used inside the Codex conversation:
+Expected result:
+- `.omx/decisions.json` records the architecture decision
+- `.omx/release.json` moves `architecture_status` to `APPROVED`
 
-```text
-$arch
-$sage
-$flow
-$vet
-$vibe
-$build
+## `$sage`
+
+Canonical trigger inside Codex:
+- `$sage`
+
+Purpose:
+- bind major technical choices to approved GitMCP evidence
+- record verified vs partial vs missing evidence honestly
+
+Scripted helper path:
+
+```bash
+ma run '$sage'
 ```
 
-Short rule:
-- `ma ...` means "run a helper command in the terminal"
-- `$...` means "run a Meta-Architect skill inside the Codex session"
+Expected result:
+- `.omx/evidence/sources.json` records validated endpoints and live-probe metadata
+- `evidence_status` becomes `VERIFIED`, `PARTIAL`, or `MISSING`
 
-Important:
-- `ma setup` and `ma init` currently do the same thing
-- they only create local support files
-- they do not replace the in-session skill flow
+## `$flow`
 
-## Installed support bundle
+Canonical trigger inside Codex:
+- `$flow`
 
-Meta-Architect also installs a standard packaged support bundle for relevant files.
+Purpose:
+- review logic, state transitions, and blockers
+- stop early if architecture or evidence prerequisites are not ready
 
-Default path:
+Scripted helper path:
 
-```text
-~/.codex/meta-architect-sdk/
+```bash
+ma run '$flow'
 ```
 
-Use:
+Expected result:
+- `.omx/decisions.json` records the logic review
+- `logic_status` becomes `GREEN` or `RED`
+
+## `$vet`
+
+Canonical trigger inside Codex:
+- `$vet`
+
+Purpose:
+- review security posture, dependency risk, and release-sensitive findings
+
+Scripted helper path:
 
 ```bash
-ma sdk-path
+ma run '$vet'
 ```
 
-when you want the exact active path.
+Expected result:
+- `.omx/evidence/audits.json` and `.omx/evidence/cves.json` are updated
+- `security_status` becomes `GREEN` or `RED`
 
-Relevant packaged assets there include:
-- `mcp/`
-- `sprint/`
-- `prompts/`
-- `scripts/`
-- `plugins/meta-architect/`
-- `templates/`
+## `$vibe`
 
-This exists so Meta-Architect can use relevant packaged files without guessing paths.
+Canonical trigger inside Codex:
+- `$vibe`
 
-## Shared output contract
+Purpose:
+- review developer experience and user experience before build planning
 
-Every skill result must include:
-- `decision`
-- `status`
-- `evidence`
-- `blockers`
-- `next_allowed_triggers`
+Scripted helper path:
+
+```bash
+ma run '$vibe'
+ma run '$vibe' --waive --reason "Accepted for this release line"
+```
+
+Expected result:
+- `.omx/evidence/outcomes.json` is updated
+- `experience_status` becomes `GREEN`, `RED`, or `WAIVED`
+
+## `$build`
+
+Canonical trigger inside Codex:
+- `$build`
+
+Purpose:
+- evaluate gate readiness
+- emit bounded `feature/*` branch suggestions and optional worktree commands
+
+Scripted helper path:
+
+```bash
+ma status
+ma run '$build'
+```
+
+Expected result:
+- blocked builds explain exactly why they are blocked
+- ready builds set `build_status = READY` and print suggested branch/worktree commands
+
+## Helper commands
 
-## Status ownership
+Secondary helper commands:
+- `ma status`
+- `ma idea "..."`
+- `ma run '$arch'|'$sage'|'$flow'|'$vet'|'$vibe'|'$build'`
+- `ma merge`
+- `ma release`
+- `ma doctor`
+- `ma setup`
 
-- project brief -> architecture input
-- `$arch` -> `architecture_status`
-- `$sage` -> `evidence_status`
-- `$flow` -> `logic_status`
-- `$vet` -> `security_status`
-- `$vibe` -> `experience_status`
-- `$build` -> `build_status`
+These helpers support the runtime. They do not replace the Codex-hosted skill workflow.
 
-## Operator note
+## Related surfaces
 
-The in-session skill surface is primary. The `ma` helper commands only exist to start Codex context and to provide repo-local state automation when scripted verification is needed.
+- [docs/getting-started.md](./getting-started.md)
+- [docs/release-spec.md](./release-spec.md)
+- [docs/mcp-setup.md](./mcp-setup.md)
+- [plugins/meta-architect/README.md](../plugins/meta-architect/README.md)

package/mcp/collections.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "1.0.0",
   "collections": {
     "arch": [
       "meta-list",

package/mcp/fallback.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "1.0.0",
   "fallback": {
     "endpoint": "https://gitmcp.io/docs",
     "policy": "Use only when no approved exact endpoint exists and log the exception as UNVERIFIED."

package/mcp/servers.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "1.0.0",
   "servers": [
     {
       "category": "meta-list",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.4",
-  "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
+  "version": "0.1.5",
+  "description": "Codex-native runtime layer for architecture, evidence, security, DX, and build workflows.",
   "license": "MIT",
   "author": "JustineDevs",
   "homepage": "https://github.com/JustineDevs/meta-architect#readme",
@@ -15,32 +15,33 @@
   "keywords": [
     "meta-architect",
     "codex",
+    "codex-native",
     "skills",
     "mcp",
     "gitmcp",
     "ai",
     "agent",
     "orchestration",
-    "plugin",
-    "workflow-system"
+    "cli",
+    "developer-tools"
   ],
   "type": "module",
   "main": "index.js",
   "bin": {
-    "meta-architect": "bin/ma.js",
-    "ma": "bin/ma.js"
+    "meta-architect": "bin/meta-architect.js",
+    "ma": "bin/meta-architect.js"
   },
   "files": [
     "bin/",
     "src/",
     ".codex/",
-    ".agents/plugins/",
     "mcp/",
-    "plugins/",
-    "templates/",
+    "prompts/",
     "sprint/",
+    "templates/",
     "skills/",
     "docs/",
+    "plugins/",
     "scripts/",
     "index.js",
     "README.md",
@@ -55,21 +56,17 @@
   },
   "scripts": {
     "prepare": "husky",
-    "postinstall": "node ./scripts/postinstall.js",
+    "release": "npm publish --access public",
     "test": "node --test",
     "status": "node ./bin/ma.js status",
     "build:gate": "node ./bin/ma.js run '$build'",
-    "release:meta": "node ./scripts/release-metadata.js",
-    "release:sync": "node ./scripts/release-sync.js",
-    "release:advance": "node ./scripts/release-sync.js --force --bump patch",
-    "release:verify": "node ./scripts/release-verify.js",
-    "release:check": "npm run release:verify && npm run skills:manifest && npm run plugin:sync && npm run skills:validate && npm run plugin:verify && npm run skills:pack && npm run check && npm test && npm run pack:inspect",
+    "release:check": "npm run skills:manifest && npm run skills:validate && npm run skills:pack && npm run validate:metadata && npm run validate:release && npm run check && npm test && npm run pack:inspect",
+    "validate:metadata": "node ./.github/scripts/validate-package-metadata.js",
+    "validate:release": "node ./.github/scripts/validate-release-assets.js && node ./.github/scripts/validate-release-config.js",
     "skills:manifest": "node ./scripts/skills-manifest.js",
     "skills:validate": "node ./scripts/skills-validate.js",
     "skills:install": "node ./scripts/skills-install.js",
     "skills:pack": "node ./scripts/skills-pack.js",
-    "plugin:sync": "node ./scripts/plugin-sync.js",
-    "plugin:verify": "node ./scripts/plugin-sync.js --check",
     "pack:inspect": "npm pack --dry-run --ignore-scripts --cache ./.npm-cache",
     "doctor": "node ./scripts/doctor.js",
     "lint": "biome lint .",

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

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

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

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

package/plugins/meta-architect/README.md

@@ -1,11 +1,10 @@
 # Meta-Architect Plugin Bundle
 
-This plugin bundle packages the Meta-Architect skill surfaces for consumers that want an installable plugin-style distribution instead of working directly from the source repository.
+This plugin bundle packages the Meta-Architect Codex-native skill surface.
 
 ## What the plugin contains
 
 - plugin metadata:
-  - `.codex-plugin/plugin.json`
   - `.app.json`
   - `.mcp.json`
 - bundled Meta-Architect skill surfaces under `skills/`
@@ -18,7 +17,7 @@ This plugin is **not** the full source repository.
 It does not attempt to ship:
 - repository `.github/` workflows
 - contributor-facing repo templates
-- local runtime `.ma` state
+- local runtime `.omx` state
 - every source file in the repository
 - the entire release engineering toolchain
 
@@ -38,30 +37,20 @@ Plugin bundle contains:
 - the installable skill-facing product layer
 - plugin metadata that describes the bundle to consumers
 
-Use the core repo when you want to develop Meta-Architect itself. Use the plugin bundle when you want to consume the packaged skill surface.
+Use the core repo when you want to develop Meta-Architect itself. Use the plugin bundle when you
+want the packaged Codex runtime layer.
 
 ## Install and use
 
-The plugin-facing bundle should be consumed alongside the repository’s documented packaging/install flow.
+The plugin-facing bundle is meant to be consumed alongside the Codex-hosted runtime flow.
 
-Canonical package/runtime path:
+Primary runtime posture:
 
 ```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-
-# Launch
+npm i -g @openai/codex @jstn-sdk/ma
 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
 ```
 
-Use the plugin bundle when you need installable skill metadata or local marketplace discovery. Use the package and Codex skill flow when you want the full Meta-Architect product experience.
-
 Primary related surfaces:
 - [docs/skills-publishing.md](../../docs/skills-publishing.md)
 - [skills/](../../skills/)
@@ -70,9 +59,7 @@ If you are working from the repository directly, validate and package with:
 
 ```bash
 npm run skills:manifest
-npm run plugin:sync
 npm run skills:validate
-npm run plugin:verify
 npm run skills:pack
 npm run skills:install -- --path ./dist/installed-skills
 ```
@@ -80,6 +67,7 @@ npm run skills:install -- --path ./dist/installed-skills
 Consumer expectation:
 - the plugin ships the same public skill contracts as the canonical `skills/` directory
 - it does not define a looser or simplified product contract
+- the main operating surface remains runtime skill tags inside Codex
 
 ## MCP wiring expectations
 
@@ -97,7 +85,7 @@ Do not assume the plugin alone provides a fully wired live MCP environment.
 When consuming the plugin:
 - use committed `skills/` content as the contract source
 - validate installed skill folders
-- do not treat local runtime `.ma` state as part of the distributable plugin
+- do not treat local runtime `.omx` state as part of the distributable plugin
 - preserve the gate/evidence semantics documented in the repo
 
 ## Version and release relation
@@ -105,7 +93,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.5`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.
@@ -117,5 +105,4 @@ The plugin is one distribution surface of the same product, not a separate produ
 - [docs/skills-publishing.md](../../docs/skills-publishing.md)
 - [docs/mcp-setup.md](../../docs/mcp-setup.md)
 - [.app.json](./.app.json)
-- [.codex-plugin/plugin.json](./.codex-plugin/plugin.json)
 - [.mcp.json](./.mcp.json)

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

@@ -1,30 +1,36 @@
 ---
 name: meta-architect
-description: "Use when the user wants the full Meta-Architect workflow inside Codex: architecture-first planning, evidence-backed OSS selection, logic review, security review, DX/UX review, and build readiness without leaving the Codex session."
+description: "Use when Codex needs the full Meta-Architect runtime layer in this repo: architecture, evidence, logic, security, experience, and build workflows operating through skill tags inside Codex. Trigger for requests about Meta-Architect orchestration, build gating, GitMCP-backed evidence, branch/worktree planning, or releasing through `development` and `prod`."
 ---
 
 # Meta-Architect
 
-## Overview
+Meta-Architect is the umbrella runtime skill for the Codex-hosted workflow in this repository.
 
-Run the full Meta-Architect workflow inside Codex. Use this skill when the user wants the gated design-and-review sequence rather than a single specialist lane.
+## Canonical runtime usage
 
-## Workflow
+1. Install `@openai/codex` and `meta-architect`
+2. Launch `ma --madmax --high`
+3. Operate through `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
 
-1. Start with `$arch` and turn the user's goal into a concrete architecture brief.
-2. Continue with `$sage` to validate core stack choices against official docs or approved repo-backed sources.
-3. Run `$flow` to map states, transitions, invariants, and blockers.
-4. Run `$vet` to review trust boundaries, auth, data handling, and abuse paths.
-5. Run `$vibe` to review developer and user experience quality.
-6. Finish with `$build` to decide whether implementation is ready, what remains blocked, and what the exact next execution step should be.
+## Secondary helper usage
 
-## Rules
+Use helper commands only for scripted validation, diagnostics, or repo-local maintenance:
+- `ma status`
+- `ma idea "..."`
+- `ma run ...`
+- `ma merge`
+- `ma release`
+- `ma doctor`
+- `ma setup`
 
-- Stay inside Codex unless the user explicitly asks for repo-local helper commands.
-- Keep the workflow architecture-first. Do not jump into code before the architecture and review lanes are grounded.
-- Prefer official docs, upstream repos, and repo-configured GitMCP sources when validating tooling choices.
-- End each lane with a clear result shape: decision, evidence, blockers, and exact next trigger.
+## Expected outputs
 
-## References
+- appended decisions in `.omx/decisions.json`
+- gate updates in `.omx/release.json`
+- evidence updates under `.omx/evidence/`
+- explicit blockers and next allowed triggers when work is blocked
 
-- For release gates and branch policy, read `references/core-release-rules.md`.
+## Contract rule
+
+Do not treat helper commands as the primary story. The primary story is always the Codex session launched with `ma --madmax --high`.

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

@@ -0,0 +1,24 @@
+---
+name: meta-architect-arch
+description: "Use when Codex needs to run or explain the Meta-Architect `$arch` lane for architecture, stack rationale, subsystem layout, and blueprint decisions. Trigger for requests about architecture design inside a Meta-Architect-managed repo or for producing the first design artifact after the idea is captured."
+---
+
+# Meta-Architect Arch
+
+Use `$arch` inside the Codex-hosted Meta-Architect runtime to produce the first architecture blueprint.
+
+## Canonical trigger
+
+- `$arch`
+
+## Secondary helper path
+
+```bash
+ma idea "Build a fintech operations dashboard"
+ma run '$arch'
+```
+
+## Expected result
+
+- architecture decision appended to `.omx/decisions.json`
+- `architecture_status = APPROVED` in `.omx/release.json`

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

@@ -0,0 +1,25 @@
+---
+name: meta-architect-build
+description: "Use when Codex needs to run or inspect the Meta-Architect `$build` lane for gate evaluation, branch suggestions, worktree planning, and build readiness. Trigger for requests about whether the build is unlocked, which gate is blocking, or what feature branches and worktree commands should be used next."
+---
+
+# Meta-Architect Build
+
+Use `$build` inside the Codex-hosted Meta-Architect runtime to evaluate gate readiness and prepare bounded implementation work.
+
+## Canonical trigger
+
+- `$build`
+
+## Secondary helper path
+
+```bash
+ma status
+ma run '$build'
+```
+
+## Expected result
+
+- blocked builds explain the exact gate failures
+- ready builds set `build_status = READY`
+- suggested `feature/*` branches and optional worktree commands are printed

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

@@ -0,0 +1,23 @@
+---
+name: meta-architect-flow
+description: "Use when Codex needs to run or inspect the Meta-Architect `$flow` lane for business logic, state transitions, and blockers. Trigger for requests about logic maps, dead ends, state validation, or whether the workflow is ready to proceed to security review."
+---
+
+# Meta-Architect Flow
+
+Use `$flow` inside the Codex-hosted Meta-Architect runtime to review logic, state transitions, and blockers.
+
+## Canonical trigger
+
+- `$flow`
+
+## Secondary helper path
+
+```bash
+ma run '$flow'
+```
+
+## Expected result
+
+- logic review appended to `.omx/decisions.json`
+- `logic_status` becomes `GREEN` or `RED`

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

@@ -0,0 +1,23 @@
+---
+name: meta-architect-sage
+description: "Use when Codex needs to run or inspect the Meta-Architect `$sage` lane for OSS evidence binding through GitMCP and MCP. Trigger for requests about verifying repos, collecting evidence from configured GitMCP endpoints, or checking whether a recommendation is VERIFIED, PARTIAL, or MISSING."
+---
+
+# Meta-Architect Sage
+
+Use `$sage` inside the Codex-hosted Meta-Architect runtime to bind architecture choices to approved GitMCP evidence.
+
+## Canonical trigger
+
+- `$sage`
+
+## Secondary helper path
+
+```bash
+ma run '$sage'
+```
+
+## Expected result
+
+- `.omx/evidence/sources.json` records validated endpoints and live-probe metadata
+- `evidence_status` moves to `VERIFIED`, `PARTIAL`, or `MISSING`

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

@@ -0,0 +1,23 @@
+---
+name: meta-architect-vet
+description: "Use when Codex needs to run or inspect the Meta-Architect `$vet` lane for security review, risk logging, and CVE-style findings. Trigger for requests about security posture, safer alternatives, audit evidence, or whether the build should stay blocked on security grounds."
+---
+
+# Meta-Architect Vet
+
+Use `$vet` inside the Codex-hosted Meta-Architect runtime to review security posture and release-sensitive findings.
+
+## Canonical trigger
+
+- `$vet`
+
+## Secondary helper path
+
+```bash
+ma run '$vet'
+```
+
+## Expected result
+
+- `.omx/evidence/audits.json` and `.omx/evidence/cves.json` are updated
+- `security_status` becomes `GREEN` or `RED`