@jstn-sdk/ma 0.1.0

package/docs/skills-publishing.md

@@ -0,0 +1,231 @@
+# Skills Publishing
+
+Meta-Architect ships skills through a deliberate source-to-package pipeline. This repository treats publishable skills as product artifacts, not as raw markdown files.
+
+## Two skill surfaces
+
+### 1. Internal runtime surface
+
+Location:
+- `.ma/skills/`
+
+Purpose:
+- local runtime behavior
+- internal command contracts
+- generated or seeded operator surfaces
+
+### 2. Publishable skill surface
+
+Location:
+- `skills/`
+
+Purpose:
+- installable Codex skill folders
+- UI metadata via `agents/openai.yaml`
+- versionable public skill contract
+
+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
+```
+
+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`
+
+## Expected outputs
+
+### `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/`
+- `skills/`
+- `docs/`
+- `scripts/`
+- `index.js`
+- `README.md`
+- `LICENSE`
+
+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/`
+
+is related but not identical to the npm/package skill bundle.
+
+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
+
+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
+
+## Real commands for a release-minded flow
+
+```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
+npm run pack:inspect
+```
+
+## 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

@@ -0,0 +1,91 @@
+# Skills
+
+Meta-Architect’s canonical Codex runtime surface is:
+- `$arch`
+- `$sage`
+- `$flow`
+- `$vet`
+- `$vibe`
+- `$build`
+
+## Real usage path
+
+Install the package once, launch through `ma`, and use the skills directly in-session.
+
+```bash
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# Launch
+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
+```
+
+Then inside the Codex session:
+1. Start with the structured `$arch` prompt
+2. Continue through `$sage -> $flow -> $vet -> $vibe -> $build`
+
+## Simple difference
+
+Meta-Architect has two surfaces:
+
+- terminal commands
+- in-session skills
+
+Terminal commands are run in the shell:
+
+```bash
+ma setup
+ma init
+ma idea "Build a product"
+ma status
+ma run '$arch'
+```
+
+In-session skills are used inside the Codex conversation:
+
+```text
+$arch
+$sage
+$flow
+$vet
+$vibe
+$build
+```
+
+Short rule:
+- `ma ...` means "run a helper command in the terminal"
+- `$...` means "run a Meta-Architect skill inside the Codex session"
+
+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
+
+## Shared output contract
+
+Every skill result must include:
+- `decision`
+- `status`
+- `evidence`
+- `blockers`
+- `next_allowed_triggers`
+
+## Status ownership
+
+- project brief -> architecture input
+- `$arch` -> `architecture_status`
+- `$sage` -> `evidence_status`
+- `$flow` -> `logic_status`
+- `$vet` -> `security_status`
+- `$vibe` -> `experience_status`
+- `$build` -> `build_status`
+
+## Operator note
+
+The runtime trigger surface is primary. The `ma` helper commands exist to launch Codex with Meta-Architect attached and to provide repo-local state automation when scripted verification is needed.

package/index.js

@@ -0,0 +1,28 @@
+export {
+  evaluateBuildGate,
+  formatBuildBlockers,
+  formatNextAllowedTriggers,
+} from "./src/build-gate.js";
+export {
+  appendDecision,
+  loadDecisionLog,
+  updateDecisionStatuses,
+} from "./src/decision-log.js";
+export { isValidGitMcpEndpoint, loadMcpServers, validateMcpServers } from "./src/mcp-config.js";
+export {
+  canMarkBuildDone,
+  rejectsDirectProdPromotion,
+  validateMergeTarget,
+  validateReleaseOrigin,
+} from "./src/policy.js";
+export { loadReleaseState, saveReleaseState, validateReleaseState } from "./src/release-state.js";
+export {
+  listSkills,
+  runArch,
+  runFlow,
+  runIdea,
+  runInit,
+  runSage,
+  runVet,
+  runVibe,
+} from "./src/skills.js";

package/mcp/collections.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": "0.1.0",
+  "collections": {
+    "arch": [
+      "meta-list",
+      "typescript",
+      "rust",
+      "go",
+      "python",
+      "java",
+      "dotnet",
+      "self-hosted",
+      "system-design"
+    ],
+    "sage": ["meta-list", "typescript", "rust", "go", "python", "java", "dotnet", "self-hosted"],
+    "vet": ["security"],
+    "flow": [],
+    "vibe": [],
+    "build": []
+  }
+}

package/mcp/fallback.json

@@ -0,0 +1,7 @@
+{
+  "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

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": "0.1.0",
+  "servers": [
+    {
+      "category": "meta-list",
+      "repo": "sindresorhus/awesome",
+      "endpoint": "https://gitmcp.io/sindresorhus/awesome"
+    },
+    {
+      "category": "typescript",
+      "repo": "dzharii/awesome-typescript",
+      "endpoint": "https://gitmcp.io/dzharii/awesome-typescript"
+    },
+    {
+      "category": "rust",
+      "repo": "rust-unofficial/awesome-rust",
+      "endpoint": "https://gitmcp.io/rust-unofficial/awesome-rust"
+    },
+    {
+      "category": "go",
+      "repo": "avelino/awesome-go",
+      "endpoint": "https://gitmcp.io/avelino/awesome-go"
+    },
+    {
+      "category": "python",
+      "repo": "vinta/awesome-python",
+      "endpoint": "https://gitmcp.io/vinta/awesome-python"
+    },
+    {
+      "category": "java",
+      "repo": "akullpp/awesome-java",
+      "endpoint": "https://gitmcp.io/akullpp/awesome-java"
+    },
+    {
+      "category": "dotnet",
+      "repo": "quozd/awesome-dotnet",
+      "endpoint": "https://gitmcp.io/quozd/awesome-dotnet"
+    },
+    {
+      "category": "security",
+      "repo": "sbilly/awesome-security",
+      "endpoint": "https://gitmcp.io/sbilly/awesome-security"
+    },
+    {
+      "category": "self-hosted",
+      "repo": "awesome-selfhosted/awesome-selfhosted",
+      "endpoint": "https://gitmcp.io/awesome-selfhosted/awesome-selfhosted"
+    },
+    {
+      "category": "system-design",
+      "repo": "checkcheckzz/system-design-interview",
+      "endpoint": "https://gitmcp.io/checkcheckzz/system-design-interview"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@jstn-sdk/ma",
+  "version": "0.1.0",
+  "description": "Codex-native runtime layer for architecture, evidence, review, and gated build workflows.",
+  "license": "MIT",
+  "author": "JustineDevs",
+  "homepage": "https://github.com/JustineDevs/meta-architect#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JustineDevs/meta-architect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JustineDevs/meta-architect/issues"
+  },
+  "keywords": [
+    "meta-architect",
+    "codex",
+    "skills",
+    "mcp",
+    "gitmcp",
+    "ai",
+    "agent",
+    "orchestration",
+    "cli",
+    "developer-tools"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "meta-architect": "bin/ma.js",
+    "ma": "bin/ma.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    ".codex/",
+    ".agents/plugins/",
+    "mcp/",
+    "plugins/",
+    "sprint/",
+    "skills/",
+    "docs/",
+    "scripts/",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "postinstall": "node ./scripts/postinstall.js",
+    "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: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 .",
+    "format": "biome format .",
+    "check": "biome check ."
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "npm@10",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "husky": "^9.1.7"
+  }
+}

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

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

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

@@ -0,0 +1,23 @@
+{
+  "name": "meta-architect",
+  "version": "0.1.0",
+  "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
+  "author": {
+    "name": "JustineDevs",
+    "url": "https://github.com/JustineDevs"
+  },
+  "homepage": "https://github.com/JustineDevs/meta-architect",
+  "repository": "https://github.com/JustineDevs/meta-architect.git",
+  "license": "MIT",
+  "keywords": ["codex", "skills", "architecture", "workflow", "review"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Meta-Architect",
+    "shortDescription": "Architecture-first skill bundle for Codex workflows.",
+    "longDescription": "Plugin = Meta-Architect skill discovery plus plugin-scoped MCP and app metadata. Runtime = the ma launcher plus .ma state, release gates, and scripted helper commands when a repository needs local workflow state.",
+    "developerName": "JustineDevs",
+    "category": "Developer Tools"
+  }
+}

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

@@ -0,0 +1,12 @@
+{
+  "name": "meta-architect",
+  "version": "0.1.0",
+  "collections": [
+    "sindresorhus/awesome",
+    "dzharii/awesome-typescript",
+    "rust-unofficial/awesome-rust",
+    "sbilly/awesome-security",
+    "awesome-selfhosted/awesome-selfhosted"
+  ],
+  "notes": "Replace with repo-specific gitmcp.io endpoints in consuming environments."
+}

package/plugins/meta-architect/README.md

@@ -0,0 +1,121 @@
+# 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.
+
+## What the plugin contains
+
+- plugin metadata:
+  - `.codex-plugin/plugin.json`
+  - `.app.json`
+  - `.mcp.json`
+- bundled Meta-Architect skill surfaces under `skills/`
+- a release-scoped version line aligned to the repo
+
+## What the plugin does not contain
+
+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
+- every source file in the repository
+- the entire release engineering toolchain
+
+It is an installable skill bundle, not a complete clone of the repo.
+
+## How it differs from core repo source
+
+Core repo source contains:
+- implementation code
+- packaging scripts
+- CI/release workflows
+- contributor docs
+- missions
+- templates
+
+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.
+
+## Install and use
+
+The plugin-facing bundle should be consumed alongside the repository’s documented packaging/install flow.
+
+Canonical package/runtime path:
+
+```bash
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# Launch
+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 launcher when you want the full Meta-Architect runtime posture.
+
+Primary related surfaces:
+- [docs/skills-publishing.md](../../docs/skills-publishing.md)
+- [skills/](../../skills/)
+
+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
+```
+
+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
+
+## MCP wiring expectations
+
+The plugin metadata in `.mcp.json` is only a starting point.
+
+Consumers are expected to:
+- replace placeholder or generic collection notes with real repo-specific GitMCP endpoints
+- align MCP wiring with their own environment
+- preserve the same evidence policy used by the core repo
+
+Do not assume the plugin alone provides a fully wired live MCP environment.
+
+## Safe consumer guidance
+
+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
+- preserve the gate/evidence semantics documented in the repo
+
+## Version and release relation
+
+The plugin version should track the release scope of the core repo.
+
+For this repository:
+- plugin scope is aligned to Meta-Architect `v0.1.0`
+- any breaking contract change should be versioned intentionally
+
+The plugin is one distribution surface of the same product, not a separate product line.
+
+## Related surfaces
+
+- [README.md](../../README.md)
+- [docs/skills.md](../../docs/skills.md)
+- [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)