@jstn-sdk/ma 0.1.0 → 0.1.2

package/plugins/meta-architect/README.md

@@ -60,7 +60,7 @@ npm uninstall -g @jstn-sdk/ma
 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.
+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)
@@ -105,7 +105,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.0`
+- plugin scope is aligned to Meta-Architect `v0.1.2`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Architect"
-  short_description: "Architecture and stack design for MA flows"
+  display_name: "$arch"
+  short_description: "Architecture-first product and system design"
   default_prompt: "Use $arch to produce architecture, stack rationale, subsystem boundaries, tradeoffs, and a phased delivery plan."

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Build"
-  short_description: "Gated build planning and branch/worktree prep"
+  display_name: "$build"
+  short_description: "Build-readiness decision and next implementation step"
   default_prompt: "Use $build to decide whether implementation is ready, what remains blocked, and what the next build slice should be."

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Flow"
-  short_description: "Business logic and state validation for MA"
+  display_name: "$flow"
+  short_description: "Logic, states, transitions, and blockers"
   default_prompt: "Use $flow to map business logic, state transitions, invariants, and blockers in the current design."

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Meta-Architect"
-  short_description: "Core orchestration and gated build workflows"
+  display_name: "$meta-architect"
+  short_description: "Full Meta-Architect skill workflow"
   default_prompt: "Use $meta-architect to run the full Meta-Architect workflow inside Codex, then route through $arch, $sage, $flow, $vet, $vibe, and $build as needed."

package/plugins/meta-architect/skills/meta-architect/references/core-release-rules.md

@@ -10,4 +10,4 @@
   - `experience_status = GREEN` or `WAIVED`
 - Feature work merges into `development`, never directly into `prod`.
 - Release promotion is allowed only from `development` or approved `release/*`.
-- Use the helper CLI only when repo-local state automation is explicitly needed; otherwise stay inside Codex and carry the gate decisions in the session.
+- Use the helper command path only when repo-local state automation is explicitly needed; otherwise stay inside Codex and carry the gate decisions in the session.

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Sage"
-  short_description: "GitMCP-backed OSS evidence selection"
+  display_name: "$sage"
+  short_description: "Evidence-backed stack and OSS validation"
   default_prompt: "Use $sage to validate stack choices with official docs, upstream repos, and approved GitMCP-backed sources."

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Vet"
-  short_description: "Security, CVE, and risk review for MA"
+  display_name: "$vet"
+  short_description: "Security and trust-boundary review"
   default_prompt: "Use $vet to review trust boundaries, security risks, abuse cases, and safer alternatives in the current design."

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Vibe"
-  short_description: "DX and UX review before Meta-Architect build"
+  display_name: "$vibe"
+  short_description: "DX and UX review before implementation"
   default_prompt: "Use $vibe to review developer and user experience risks before the build lane proceeds."

package/scripts/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import process from "node:process";
-import { installSkills } from "../src/skill-installer.js";
+import { installSkills, installSupportBundle } from "../src/skill-installer.js";
 
 async function main() {
   if (process.env.MA_SKIP_AUTO_INSTALL === "1") {
@@ -9,8 +9,12 @@ async function main() {
     return;
   }
 
-  const { targetRoot, installed } = await installSkills();
-  console.log(`meta-architect: installed ${installed.length} Codex skills into ${targetRoot}`);
+  const [
+    { targetRoot: skillRoot, installed: skills },
+    { targetRoot: bundleRoot, installed: assets },
+  ] = await Promise.all([installSkills(), installSupportBundle()]);
+  console.log(`meta-architect: installed ${skills.length} Codex skills into ${skillRoot}`);
+  console.log(`meta-architect: installed ${assets.length} support assets into ${bundleRoot}`);
 }
 
 main().catch((error) => {

package/skills/arch/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Architect"
-  short_description: "Architecture and stack design for MA flows"
+  display_name: "$arch"
+  short_description: "Architecture-first product and system design"
   default_prompt: "Use $arch to produce architecture, stack rationale, subsystem boundaries, tradeoffs, and a phased delivery plan."

package/skills/build/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Build"
-  short_description: "Gated build planning and branch/worktree prep"
+  display_name: "$build"
+  short_description: "Build-readiness decision and next implementation step"
   default_prompt: "Use $build to decide whether implementation is ready, what remains blocked, and what the next build slice should be."

package/skills/flow/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Flow"
-  short_description: "Business logic and state validation for MA"
+  display_name: "$flow"
+  short_description: "Logic, states, transitions, and blockers"
   default_prompt: "Use $flow to map business logic, state transitions, invariants, and blockers in the current design."

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

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Meta-Architect"
-  short_description: "Core orchestration and gated build workflows"
+  display_name: "$meta-architect"
+  short_description: "Full Meta-Architect skill workflow"
   default_prompt: "Use $meta-architect to run the full Meta-Architect workflow inside Codex, then route through $arch, $sage, $flow, $vet, $vibe, and $build as needed."

package/skills/meta-architect/references/core-release-rules.md

@@ -10,4 +10,4 @@
   - `experience_status = GREEN` or `WAIVED`
 - Feature work merges into `development`, never directly into `prod`.
 - Release promotion is allowed only from `development` or approved `release/*`.
-- Use the helper CLI only when repo-local state automation is explicitly needed; otherwise stay inside Codex and carry the gate decisions in the session.
+- Use the helper command path only when repo-local state automation is explicitly needed; otherwise stay inside Codex and carry the gate decisions in the session.

package/skills/sage/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Sage"
-  short_description: "GitMCP-backed OSS evidence selection"
+  display_name: "$sage"
+  short_description: "Evidence-backed stack and OSS validation"
   default_prompt: "Use $sage to validate stack choices with official docs, upstream repos, and approved GitMCP-backed sources."

package/skills/vet/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Vet"
-  short_description: "Security, CVE, and risk review for MA"
+  display_name: "$vet"
+  short_description: "Security and trust-boundary review"
   default_prompt: "Use $vet to review trust boundaries, security risks, abuse cases, and safer alternatives in the current design."

package/skills/vibe/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "MA Vibe"
-  short_description: "DX and UX review before Meta-Architect build"
+  display_name: "$vibe"
+  short_description: "DX and UX review before implementation"
   default_prompt: "Use $vibe to review developer and user experience risks before the build lane proceeds."

package/src/launcher.js

@@ -6,6 +6,7 @@ const nativeCommands = new Set([
   "init",
   "idea",
   "skills",
+  "sdk-path",
   "status",
   "merge",
   "release",
@@ -45,10 +46,10 @@ export function runCodex(args) {
 
   if (result.error) {
     if (result.error.code === "ENOENT") {
-      throw new Error("Codex CLI not found. Install it with: npm install -g @openai/codex");
+      throw new Error("Codex not found. Install it with: npm install -g @openai/codex");
     }
 
-    throw new Error(`Failed to start Codex CLI: ${result.error.message}`);
+    throw new Error(`Failed to start Codex: ${result.error.message}`);
   }
 
   return typeof result.status === "number" ? result.status : 1;

package/src/mcp-live-client.js

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

package/src/runtime-artifacts.js

@@ -19,7 +19,7 @@ function renderProjectContext({ idea = null }) {
     "",
     "- `.ma/decisions.json` tracks gate and decision history",
     "- `.ma/release.json` tracks release-state fields",
-    "- `.ma/runbook.md` defines the local operator workflow",
+    "- `.ma/runbook.md` defines the local helper workflow",
     "",
     "## Next Recommended Trigger",
     "",
@@ -240,7 +240,7 @@ function renderRunbook() {
     "",
     "## Purpose",
     "",
-    "This runbook defines the local helper-path workflow for Meta-Architect.",
+    "This runbook defines the local helper-path workflow that supports the primary in-session skill flow.",
     "",
     "## Canonical Sequence",
     "",

package/src/skill-installer.js

@@ -3,9 +3,16 @@ import os from "node:os";
 import path from "node:path";
 import { packageRoot } from "./paths.js";
 
+function resolveCodexHome() {
+  return process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
+}
+
 function resolveSkillInstallRoot() {
-  const codexHome = process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
-  return path.join(codexHome, "skills");
+  return path.join(resolveCodexHome(), "skills");
+}
+
+function resolveSupportBundleRoot() {
+  return path.join(resolveCodexHome(), "meta-architect-sdk");
 }
 
 async function copyDir(src, dest) {
@@ -26,6 +33,10 @@ export function getSkillInstallRoot() {
   return resolveSkillInstallRoot();
 }
 
+export function getSupportBundleRoot() {
+  return resolveSupportBundleRoot();
+}
+
 export async function loadSkillManifest() {
   const manifestPath = path.join(packageRoot, "skills", "index.json");
   const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
@@ -47,3 +58,141 @@ export async function installSkills({ targetRoot = getSkillInstallRoot() } = {})
 
   return { targetRoot, installed };
 }
+
+async function copyPath(src, dest) {
+  const stat = await fs.stat(src);
+  if (stat.isDirectory()) {
+    await fs.rm(dest, { recursive: true, force: true });
+    await copyDir(src, dest);
+    return "directory";
+  }
+
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.copyFile(src, dest);
+  return "file";
+}
+
+export async function installSupportBundle({ targetRoot = getSupportBundleRoot() } = {}) {
+  const assets = [
+    {
+      name: "mcp",
+      src: path.join(packageRoot, "mcp"),
+      dest: path.join(targetRoot, "mcp"),
+    },
+    {
+      name: "sprint",
+      src: path.join(packageRoot, "sprint"),
+      dest: path.join(targetRoot, "sprint"),
+    },
+    {
+      name: "prompts",
+      src: path.join(packageRoot, ".codex", "prompts"),
+      dest: path.join(targetRoot, "prompts"),
+    },
+    {
+      name: "scripts",
+      src: path.join(packageRoot, "scripts"),
+      dest: path.join(targetRoot, "scripts"),
+    },
+    {
+      name: "plugin",
+      src: path.join(packageRoot, "plugins", "meta-architect"),
+      dest: path.join(targetRoot, "plugins", "meta-architect"),
+    },
+    {
+      name: "templates",
+      src: path.join(packageRoot, "templates"),
+      dest: path.join(targetRoot, "templates"),
+    },
+    {
+      name: "docs-readme",
+      src: path.join(packageRoot, "docs", "README.md"),
+      dest: path.join(targetRoot, "docs", "README.md"),
+    },
+  ];
+
+  await fs.mkdir(targetRoot, { recursive: true });
+  const installed = [];
+  for (const asset of assets) {
+    await copyPath(asset.src, asset.dest);
+    installed.push({ name: asset.name, dest: asset.dest });
+  }
+
+  const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+  const manifest = {
+    packageName: pkg.name,
+    packageVersion: pkg.version,
+    installedAt: new Date().toISOString(),
+    root: targetRoot,
+    assets: installed,
+  };
+  await fs.writeFile(
+    path.join(targetRoot, "asset-manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+
+  return { targetRoot, installed };
+}
+
+export async function areSkillsInstalled({ targetRoot = getSkillInstallRoot() } = {}) {
+  const skills = await loadSkillManifest();
+
+  for (const skill of skills) {
+    const skillDir = path.join(targetRoot, path.basename(skill.path));
+    try {
+      await fs.access(path.join(skillDir, "SKILL.md"));
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export async function isSupportBundleInstalled({ targetRoot = getSupportBundleRoot() } = {}) {
+  const requiredFiles = [
+    path.join(targetRoot, "asset-manifest.json"),
+    path.join(targetRoot, "mcp", "servers.json"),
+    path.join(targetRoot, "sprint", "07-release.md"),
+    path.join(targetRoot, "prompts", "onboarding.md"),
+    path.join(targetRoot, "scripts", "skills-install.js"),
+    path.join(targetRoot, "plugins", "meta-architect", ".codex-plugin", "plugin.json"),
+    path.join(targetRoot, "templates", "AGENTS.md"),
+  ];
+
+  for (const file of requiredFiles) {
+    try {
+      await fs.access(file);
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export async function ensureSkillsInstalled({ targetRoot = getSkillInstallRoot() } = {}) {
+  if (process.env.MA_SKIP_AUTO_INSTALL === "1") {
+    return { targetRoot, installed: [], skipped: true };
+  }
+
+  if (await areSkillsInstalled({ targetRoot })) {
+    return { targetRoot, installed: [], skipped: false };
+  }
+
+  const result = await installSkills({ targetRoot });
+  return { ...result, skipped: false };
+}
+
+export async function ensureSupportBundleInstalled({ targetRoot = getSupportBundleRoot() } = {}) {
+  if (process.env.MA_SKIP_AUTO_INSTALL === "1") {
+    return { targetRoot, installed: [], skipped: true };
+  }
+
+  if (await isSupportBundleInstalled({ targetRoot })) {
+    return { targetRoot, installed: [], skipped: false };
+  }
+
+  const result = await installSupportBundle({ targetRoot });
+  return { ...result, skipped: false };
+}

package/src/skills.js

@@ -243,7 +243,7 @@ export async function runVibe() {
   const outcomes = await readJson(getRuntimeWritePath("evidence", "outcomes.json"));
   const note = {
     area: "developer-experience",
-    summary: "Core CLI and gated workflow remain the primary operator surface",
+    summary: "The in-session skill flow remains the primary Meta-Architect surface",
   };
   outcomes.items.push(note);
   await writeJson(getRuntimeWritePath("evidence", "outcomes.json"), outcomes);
@@ -344,8 +344,8 @@ export async function runInit() {
       path.join(getRepoRoot(), "docs", "release-spec.md"),
     ],
     [
-      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.0.md"),
-      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.0.md"),
+      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.2.md"),
+      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.2.md"),
     ],
   ];
 

package/templates/AGENTS.md

@@ -0,0 +1,130 @@
+# Meta-Architect Operating Contract
+
+This repository uses Meta-Architect as a structured orchestration layer for programmatic architecture and verified engineering. The purpose of this contract is to make repository behavior explicit, reviewable, and stable enough to be reused across generated or installed surfaces.
+
+## Core triggers
+
+The primary trigger surfaces are:
+
+- `$arch` — architecture and stack blueprinting
+- `$sage` — evidence-backed OSS discovery through MCP/GitMCP collections
+- `$flow` — business logic and state-transition review
+- `$vet` — security and risk review
+- `$vibe` — DX/UX review
+- `$build` — bounded implementation planning and build execution handoff
+
+## Core rule
+
+No implementation should proceed as if it were approved unless the required architecture, evidence, logic, and security gates are satisfied.
+
+## Kernel vs extension model
+
+Meta-Architect should be treated as a core system plus extension surfaces:
+
+- **Core system**
+  - state and decision files
+  - gate enforcement
+  - MCP endpoint policy
+  - CLI orchestration commands
+- **Extension surfaces**
+  - publishable skill folders
+  - plugin bundle
+  - missions and demos
+  - prompts and templates
+
+The core must stay stable and inspectable. Extensions may vary, but they must not weaken the kernel contract.
+
+## Gate rules
+
+The repository recognizes the following status fields:
+
+- `idea_status`
+- `architecture_status`
+- `evidence_status`
+- `logic_status`
+- `security_status`
+- `experience_status`
+- `build_status`
+- `merge_status`
+- `release_status`
+
+### Build lock rule
+
+`$build` must remain locked unless all of the following are true:
+
+- `idea_status = CLEAR`
+- `architecture_status = APPROVED`
+- `evidence_status = VERIFIED`
+- `logic_status = GREEN`
+- `security_status = GREEN`
+- `experience_status = GREEN` or `WAIVED`
+
+If any required field is missing, red, or unverified, the workflow should stop and report blockers clearly.
+
+### Merge and release rule
+
+- `feature/*` work merges into `development`
+- release promotion is allowed only from `development` or approved `release/*`
+- no direct `feature/* -> prod`
+
+## Evidence rule
+
+Major technology recommendations must be supported by evidence from configured MCP/GitMCP sources. Do not invent fake repositories, fake endpoints, or unsupported claims.
+
+### Exact endpoint rule
+
+- Prefer repo-specific `https://gitmcp.io/{owner}/{repo}` endpoints
+- Treat `https://gitmcp.io/docs` as fallback policy only, not a normal approved evidence source for build-unlocking decisions
+
+## Logging rule
+
+Architecture decisions, evidence, audits, and release-relevant outcomes should be written to repository-visible local files where applicable, especially:
+
+- `.ma/decisions.json`
+- `.ma/release.json`
+- `.ma/evidence/sources.json`
+- `.ma/evidence/audits.json`
+- `.ma/evidence/cves.json`
+
+## Skill routing
+
+Use the role that best matches the task:
+
+- Use `$arch` for system shape, stack options, component boundaries, trade-offs, and blueprinting.
+- Use `$sage` for evidence-backed package, framework, and library selection.
+- Use `$flow` for workflow correctness, state transitions, data flow, and edge-case review.
+- Use `$vet` for security checks, dependency risk review, and release-sensitive blocking findings.
+- Use `$vibe` for developer experience and user experience review.
+- Use `$build` only after required gates are satisfied and only for bounded implementation planning or execution.
+
+## Prompt behavior
+
+When working in this repository:
+
+- prefer explicit reasoning and explicit file changes
+- do not skip validation steps silently
+- do not weaken hooks or gates for convenience
+- do not commit runtime `.ma` state
+- do not treat release-sensitive changes as trivial edits
+
+## Contributor expectation
+
+Changes to skills, prompts, package metadata, workflows, release docs, or plugin surfaces are release-sensitive. These changes should be tested, documented, and described clearly in pull requests.
+
+## Release expectation
+
+Production release means:
+
+- the core trigger flow works end-to-end
+- release artifacts are validated
+- skills packaging and installation succeed
+- docs reflect actual behavior
+- no hidden runtime residue is shipped as source
+
+## Related surfaces
+
+- `CONTRIBUTING.md`
+- `docs/release-spec.md`
+- `templates/catalog-manifest.json`
+- `prompts/`
+- `skills/`

package/templates/catalog-manifest.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "skills": [
+    "meta-architect",
+    "meta-architect-arch",
+    "meta-architect-sage",
+    "meta-architect-flow",
+    "meta-architect-vet",
+    "meta-architect-vibe",
+    "meta-architect-build"
+  ],
+  "prompts": [
+    "architect",
+    "sage",
+    "flow",
+    "security-reviewer",
+    "vibe",
+    "builder",
+    "release-manager",
+    "verifier"
+  ]
+}

package/templates/model-instructions/core.md

@@ -0,0 +1,39 @@
+# Core Model Instructions
+
+Use these instructions when generating or applying repository content to the Meta-Architect core system.
+
+## Core expectations
+
+- Keep Meta-Architect skills, gates, evidence, and release behavior explicit.
+- Prefer inspectable files over hidden side effects.
+- Do not bypass the `.ma` gate model.
+- Treat CLI, skill contracts, plugin surfaces, and docs as one coherent product system.
+
+## Kernel rule
+
+The kernel contains the minimum stable logic that makes the system trustworthy:
+- status files
+- decision logging
+- evidence capture
+- build/merge/release policy
+- packaging and validation commands
+
+Do not treat those as negotiable convenience features.
+
+## Documentation rule
+
+When writing docs:
+- describe what the runtime actually does today
+- distinguish baseline first-pass review from deep autonomous analysis when necessary
+- show exact commands and expected outcomes
+- cross-link related surfaces
+
+## Change rule
+
+Any change that weakens:
+- inspectability
+- evidence traceability
+- gate enforcement
+- or packaging determinism
+
+should be treated as a regression.

package/templates/model-instructions/release.md

@@ -0,0 +1,41 @@
+# Release Model Instructions
+
+These instructions apply when generating or reviewing release-facing artifacts.
+
+## Release posture
+
+Fail closed on:
+- missing release artifacts
+- failing checks
+- blocked channels
+- ambiguous publish claims
+
+## Versioning rule
+
+Preserve stable public contracts for the active release line unless a major version is intentionally planned.
+
+## Publication rule
+
+Never claim a publication channel succeeded without concrete evidence.
+
+This includes:
+- git branch push
+- tag push
+- GitHub release creation
+- GitHub asset upload
+- npm publish
+- plugin or marketplace publish
+
+## Release artifact minimum
+
+Release-facing changes should stay aligned across:
+- `package.json`
+- `CHANGELOG.md`
+- `RELEASE.md`
+- `docs/qa/`
+- `skills/index.json`
+- tarball outputs
+
+## Hygiene rule
+
+Do not ship local runtime state, caches, or accidental build outputs as public source.