@jstn-sdk/ma 0.1.5 → 0.1.7

package/docs/skills-publishing.md

@@ -1,98 +1,231 @@
 # Skills Publishing
 
-Meta-Architect publishes a Codex-native runtime package plus aligned skill-distribution surfaces. Publishable skills are product artifacts, not loose markdown.
+Meta-Architect ships skills through a deliberate source-to-package pipeline. This repository treats publishable skills as product artifacts, not as raw markdown files.
 
-## Provenance standard
+## Two skill surfaces
 
-Meta-Architect `v0.1.5` uses npm trusted publishing from GitHub Actions as the canonical publish path.
+### 1. Internal runtime surface
 
-Required release conditions:
-- public package name: `@jstn-sdk/ma`
-- canonical source repository: `https://github.com/JustineDevs/meta-architect`
-- GitHub Actions OIDC enabled with `id-token: write`
-- `npm publish --provenance --access public`
-- post-publish verification with npm metadata checks plus `npm audit signatures`
+Location:
+- `.ma/skills/`
 
-## Distribution surfaces
+Purpose:
+- local runtime behavior
+- internal command contracts
+- generated or seeded operator surfaces
 
-Internal runtime surface:
-- `.omx/skills/`
+### 2. Publishable skill surface
 
-Publishable skill surface:
+Location:
 - `skills/`
 
-Plugin-facing bundle:
-- `plugins/meta-architect/`
+Purpose:
+- installable Codex skill folders
+- UI metadata via `agents/openai.yaml`
+- versionable public skill contract
 
-The runtime story stays the same across all three surfaces:
-- install `@openai/codex` and `@jstn-sdk/ma`
-- launch `ma --madmax --high`
-- operate through `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
+Do not confuse these two layers. The repo publishes `skills/`, not `.ma/`.
 
 ## Canonical packaging flow
 
+### Generate manifest
+
 ```bash
 npm run skills:manifest
+```
+
+Expected effect:
+- writes `skills/index.json`
+- manifest entries should match the actual skill directories
+
+### Validate skills
+
+```bash
 npm run skills:validate
+```
+
+Expected effect:
+- every skill folder passes the validator
+- missing or invalid frontmatter should fail the command
+- missing or structurally incomplete `agents/openai.yaml` should fail the command
+
+### Sync plugin mirror
+
+```bash
+npm run plugin:sync
+npm run plugin:verify
+```
+
+Expected effect:
+- `plugins/meta-architect/skills/` mirrors the canonical `skills/` surface
+- the local marketplace and plugin bundle remain aligned with the package skill contract
+- plugin drift fails verification instead of surviving into release artifacts
+
+### Create bundle
+
+```bash
 npm run skills:pack
+```
+
+Expected effect:
+- creates `dist/meta-architect-skills.tgz`
+- bundle should be non-empty
+
+### Smoke-test install
+
+```bash
 npm run skills:install -- --path ./dist/installed-skills
-npm run pack:inspect
 ```
 
-Expected outputs:
-- `skills/index.json`
-- `dist/meta-architect-skills.tgz`
-- installable skill folders under `dist/installed-skills/`
+Expected effect:
+- all publishable skill folders are copied to the target install path
+- install target should contain:
+  - `meta-architect`
+  - `arch`
+  - `sage`
+  - `flow`
+  - `vet`
+  - `vibe`
+  - `build`
 
-## Public npm package
+## Expected outputs
 
-The npm package should include only the intended public surfaces from `package.json > files`, including:
+### `skills/index.json`
+
+Should contain:
+- schema version
+- skill names
+- repo-local path mapping
+- descriptions
+
+### `dist/meta-architect-skills.tgz`
+
+Should contain:
+- `skills/`
+- each skill folder
+- each `SKILL.md`
+- each `agents/openai.yaml`
+- any intended references/assets
+
+It should **not** rely on hidden runtime state.
+
+Important:
+- `npm run skills:pack` creates the **skills bundle tarball only**
+- it is not the same thing as the broader npm package tarball from `npm pack`
+- the npm package surface is controlled separately by `package.json > files`
+
+## Source vs package contents
+
+The npm package and tarball should stay explicit.
+
+Current package intent:
+- package name: `@jstn-sdk/ma`
+- public publish config
+- explicit `files` list in `package.json`
+
+The publishable package should include:
 - `bin/`
-- `src/`
-- `.codex/`
-- `mcp/`
-- `prompts/`
 - `skills/`
 - `docs/`
-- `plugins/`
-- `templates/`
+- `scripts/`
+- `index.js`
 - `README.md`
 - `LICENSE`
 
-It must not include local runtime residue such as:
-- `.omx/logs/`
-- `.omx/state/`
-- `.omx/tmp/`
-- `.omx/cache/`
-- `.omx/metrics.json`
-
-## Release verification
+It should not include:
+- runtime `.ma` state
+- local logs
+- temp install targets
+- generated local caches
+
+The `skills:pack` tarball is narrower than the npm package:
+- `skills:pack` => `skills/` distribution bundle
+- `npm pack` => public npm package with the explicit `files` list
+
+## Release and dist-tag discipline
+
+Meta-Architect release behavior is lane-aware:
+- stable versions publish to npm `latest`
+- prerelease versions publish to explicit lanes such as `next`, `beta`, or `canary`
+- prereleases must use `npm publish --tag <lane>`
+- stable releases keep the default `latest` behavior and public scoped access
+
+Before publish:
+1. bump version with `npm version <version> --no-git-tag-version`
+2. update changelog and release docs
+3. run `npm run release:verify`
+4. run `npm run release:check`
+5. create and push tag `v<version>`
+6. publish the package with the correct lane behavior
+   - preferred: run `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
+   - local fallback: omit `--provenance` and publish with `npm publish --access public` or `npm publish --access public --tag <lane>`
+7. verify the resulting dist-tags with `npm view @jstn-sdk/ma version dist-tags time --json`
+
+## Plugin relation
+
+The plugin bundle in:
+- `plugins/meta-architect/`
 
-Before a release is considered real:
-- `npm run release:check` passes
-- `skills/index.json` is current
-- `dist/meta-architect-skills.tgz` exists and is non-empty
-- package metadata matches the canonical repo identity
-- release notes, changelog, QA doc, and workflows all reference the same version/tag
-- publish workflow remains provenance-capable
+is related but not identical to the npm/package skill bundle.
 
-## Post-publish provenance verification
+Relationship:
+- `skills/` is the canonical publishable skill source
+- `plugins/meta-architect/` is the plugin-installable consumer-facing bundle
+- both should remain aligned in behavior and version intent
+- `.agents/plugins/marketplace.json` advertises the local plugin source for discovery
+- `plugins/meta-architect/.codex-plugin/plugin.json` is the plugin contract entrypoint
 
-After publish:
+If a skill contract changes:
+1. update `skills/`
+2. regenerate manifest
+3. sync the plugin mirror
+4. validate skills
+5. ensure plugin-facing bundle still reflects the same product contract
 
-1. Verify the published package version on npm.
-2. Install `@jstn-sdk/ma@<version>` in a clean temp directory.
-3. Run:
+## Real commands for a release-minded flow
 
 ```bash
-npm audit signatures
+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
+npm run pack:inspect
 ```
 
-4. Confirm the npm package provenance points back to `JustineDevs/meta-architect` and the GitHub Actions publish workflow.
+## Expected failure modes
+
+- manifest drift:
+  - `skills/index.json` does not match actual skill directories
+- invalid skill:
+  - malformed frontmatter
+  - missing `SKILL.md`
+  - invalid `agents/openai.yaml`
+- package drift:
+  - tarball includes files not intended for public distribution
+- plugin drift:
+  - plugin bundle no longer matches the published skill contract
+
+## Release artifact expectations
+
+Before a release is considered real:
+- `skills/index.json` must be current
+- `dist/meta-architect-skills.tgz` must exist
+- install smoke test must pass
+- package inspection must be sane
+- docs must match the published behavior
 
 ## Related surfaces
 
 - [README.md](../README.md)
 - [docs/skills.md](./skills.md)
 - [plugins/meta-architect/README.md](../plugins/meta-architect/README.md)
+- [plugins/meta-architect/.codex-plugin/plugin.json](../plugins/meta-architect/.codex-plugin/plugin.json)
+- [../.agents/plugins/marketplace.json](../.agents/plugins/marketplace.json)
 - [package.json](../package.json)
+- [scripts/skills-manifest.js](../scripts/skills-manifest.js)
+- [scripts/plugin-sync.js](../scripts/plugin-sync.js)
+- [scripts/skills-validate.js](../scripts/skills-validate.js)
+- [scripts/skills-pack.js](../scripts/skills-pack.js)
+- [scripts/skills-install.js](../scripts/skills-install.js)

package/docs/skills.md

@@ -1,182 +1,123 @@
-# Skills Reference
+# Skills
 
-Meta-Architect exposes six core runtime skills inside Codex. These skill tags are the main product surface.
+Meta-Architect’s canonical Codex runtime surface is:
+- `$maestro`
+- `$arch`
+- `$sage`
+- `$flow`
+- `$vet`
+- `$vibe`
+- `$build`
 
-## Runtime-first rule
+## Real usage path
 
-Canonical runtime usage:
+Install the package once, start Codex context if needed, and use the skills directly in-session.
 
 ```bash
-npm i -g @openai/codex @jstn-sdk/ma
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# Start Codex context if needed
 ma --madmax --high
-```
 
-Then operate inside Codex with:
+# Remove Meta-Architect only
+npm uninstall -g @jstn-sdk/ma
 
-```text
-$arch
-$sage
-$flow
-$vet
-$vibe
-$build
+# Remove Meta-Architect and Codex
+npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
-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`
+Then inside the Codex session:
+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`
 
-Publishable skill folders live in [skills/](../skills/). Internal runtime logic lives in [src/skills.js](../src/skills.js).
+## Simple difference
 
-## 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`
+Meta-Architect has two surfaces:
 
-Purpose:
-- produce the first architecture blueprint from the captured idea
-- define stack rationale, tradeoffs, and downstream evidence requirements
+- terminal commands
+- in-session skills
 
-Scripted helper path:
+Terminal commands are run in the shell:
 
 ```bash
-ma idea "Build a SaaS billing dashboard"
+ma setup
+ma init
+ma idea "Build a product"
+ma status
 ma run '$arch'
 ```
 
-Expected result:
-- `.omx/decisions.json` records the architecture decision
-- `.omx/release.json` moves `architecture_status` to `APPROVED`
-
-## `$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'
-```
+In-session skills are used inside the Codex conversation:
 
-Expected result:
-- `.omx/evidence/sources.json` records validated endpoints and live-probe metadata
-- `evidence_status` becomes `VERIFIED`, `PARTIAL`, or `MISSING`
-
-## `$flow`
-
-Canonical trigger inside Codex:
-- `$flow`
-
-Purpose:
-- review logic, state transitions, and blockers
-- stop early if architecture or evidence prerequisites are not ready
-
-Scripted helper path:
-
-```bash
-ma run '$flow'
+```text
+$maestro
+$arch
+$sage
+$flow
+$vet
+$vibe
+$build
 ```
 
-Expected result:
-- `.omx/decisions.json` records the logic review
-- `logic_status` becomes `GREEN` or `RED`
+Short rule:
+- `ma ...` means "run a helper command in the terminal"
+- `$...` means "run a Meta-Architect skill inside the Codex session"
 
-## `$vet`
+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
 
-Canonical trigger inside Codex:
-- `$vet`
+## Installed support bundle
 
-Purpose:
-- review security posture, dependency risk, and release-sensitive findings
+Meta-Architect also installs a standard packaged support bundle for relevant files.
 
-Scripted helper path:
+Default path:
 
-```bash
-ma run '$vet'
+```text
+~/.codex/meta-architect-sdk/
 ```
 
-Expected result:
-- `.omx/evidence/audits.json` and `.omx/evidence/cves.json` are updated
-- `security_status` becomes `GREEN` or `RED`
-
-## `$vibe`
-
-Canonical trigger inside Codex:
-- `$vibe`
-
-Purpose:
-- review developer experience and user experience before build planning
-
-Scripted helper path:
+Use:
 
 ```bash
-ma run '$vibe'
-ma run '$vibe' --waive --reason "Accepted for this release line"
+ma sdk-path
 ```
 
-Expected result:
-- `.omx/evidence/outcomes.json` is updated
-- `experience_status` becomes `GREEN`, `RED`, or `WAIVED`
+when you want the exact active path.
 
-## `$build`
+Relevant packaged assets there include:
+- `mcp/`
+- `sprint/`
+- `prompts/`
+- `scripts/`
+- `plugins/meta-architect/`
+- `templates/`
 
-Canonical trigger inside Codex:
-- `$build`
+This exists so Meta-Architect can use relevant packaged files without guessing paths.
 
-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
+## Shared output contract
 
-## Helper commands
+Every skill result must include:
+- `decision`
+- `status`
+- `evidence`
+- `blockers`
+- `next_allowed_triggers`
 
-Secondary helper commands:
-- `ma status`
-- `ma idea "..."`
-- `ma run '$arch'|'$sage'|'$flow'|'$vet'|'$vibe'|'$build'`
-- `ma merge`
-- `ma release`
-- `ma doctor`
-- `ma setup`
+## Status ownership
 
-These helpers support the runtime. They do not replace the Codex-hosted skill workflow.
+- `$maestro` -> next-step recommendation
+- project brief -> architecture input
+- `$arch` -> `architecture_status`
+- `$sage` -> `evidence_status`
+- `$flow` -> `logic_status`
+- `$vet` -> `security_status`
+- `$vibe` -> `experience_status`
+- `$build` -> `build_status`
 
-## Related surfaces
+## Operator note
 
-- [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)
+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.

package/mcp/collections.json

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

package/mcp/fallback.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "1.0.0",
+  "schemaVersion": "0.1.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": "1.0.0",
+  "schemaVersion": "0.1.0",
   "servers": [
     {
       "category": "meta-list",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.5",
-  "description": "Codex-native runtime layer for architecture, evidence, security, DX, and build workflows.",
+  "version": "0.1.7",
+  "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
   "license": "MIT",
   "author": "JustineDevs",
   "homepage": "https://github.com/JustineDevs/meta-architect#readme",
@@ -15,33 +15,32 @@
   "keywords": [
     "meta-architect",
     "codex",
-    "codex-native",
     "skills",
     "mcp",
     "gitmcp",
     "ai",
     "agent",
     "orchestration",
-    "cli",
-    "developer-tools"
+    "plugin",
+    "workflow-system"
   ],
   "type": "module",
   "main": "index.js",
   "bin": {
-    "meta-architect": "bin/meta-architect.js",
-    "ma": "bin/meta-architect.js"
+    "meta-architect": "bin/ma.js",
+    "ma": "bin/ma.js"
   },
   "files": [
     "bin/",
     "src/",
     ".codex/",
+    ".agents/plugins/",
     "mcp/",
-    "prompts/",
-    "sprint/",
+    "plugins/",
     "templates/",
+    "sprint/",
     "skills/",
     "docs/",
-    "plugins/",
     "scripts/",
     "index.js",
     "README.md",
@@ -56,17 +55,21 @@
   },
   "scripts": {
     "prepare": "husky",
-    "release": "npm publish --access public",
+    "postinstall": "node ./scripts/postinstall.js",
     "test": "node --test",
     "status": "node ./bin/ma.js status",
     "build:gate": "node ./bin/ma.js run '$build'",
-    "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",
+    "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",
     "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.0",
+  "version": "0.1.7",
   "description": "Programmatic architecture and verified engineering skills for Codex-native workflows.",
   "entry": "./README.md",
   "skillsDir": "./skills"