@jstn-sdk/ma 0.1.0

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

@@ -0,0 +1,27 @@
+---
+name: arch
+description: "Use when the user wants architecture-first product and system design with explicit stack rationale, boundaries, tradeoffs, data model choices, and phased delivery planning."
+---
+
+# Arch
+
+Use this skill inside Codex to turn a product idea into a concrete architecture brief.
+
+## Output
+
+Produce:
+- problem framing
+- user and workload assumptions
+- system architecture and subsystem boundaries
+- stack recommendation with tradeoffs
+- data model and storage choices
+- auth, security, and operational concerns
+- phased delivery plan
+- top risks and open questions
+- exact next trigger, usually `$sage`
+
+## Rules
+
+- Ask only for constraints that materially change the architecture.
+- Keep the design biased toward the simplest system that can satisfy the stated requirements.
+- Be explicit about tradeoffs, failure modes, and what should stay out of the first version.

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

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

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

@@ -0,0 +1,24 @@
+---
+name: build
+description: "Use when the user wants to decide whether implementation is ready, what remains blocked, and what the exact next build step should be."
+---
+
+# Build
+
+Use this skill inside Codex to convert the earlier review lanes into an implementation-ready decision.
+
+## Output
+
+Produce:
+- current readiness verdict
+- blockers that still prevent implementation
+- the narrowest viable build slice
+- branch or worktree suggestions when relevant
+- test and verification expectations
+- the exact next implementation step
+
+## Rules
+
+- Do not claim readiness if architecture, evidence, logic, security, or DX/UX gaps remain unresolved.
+- Keep the recommended build slice small, testable, and reversible.
+- If the user wants code immediately and the path is clear, end with a concrete implementation plan rather than more review prose.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MA Build"
+  short_description: "Gated build planning and branch/worktree prep"
+  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/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: flow
+description: "Use when the user wants logic validation: states, transitions, invariants, edge cases, dead ends, and blockers before implementation."
+---
+
+# Flow
+
+Use this skill inside Codex to pressure-test how the system behaves, not just how it is structured.
+
+## Output
+
+Produce:
+- key actors and system states
+- main flows and failure flows
+- invariants and state transitions
+- race conditions, dead ends, and consistency risks
+- missing requirements or ambiguous behavior
+- exact next trigger, usually `$vet`
+
+## Rules
+
+- Focus on behavior, not UI polish or low-level code details.
+- Surface ambiguity aggressively when it affects correctness.
+- Prefer simple state models over sprawling branching logic.

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

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

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

@@ -0,0 +1,30 @@
+---
+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."
+---
+
+# Meta-Architect
+
+## Overview
+
+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.
+
+## Workflow
+
+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.
+
+## Rules
+
+- 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.
+
+## References
+
+- For release gates and branch policy, read `references/core-release-rules.md`.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Meta-Architect"
+  short_description: "Core orchestration and gated build workflows"
+  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

@@ -0,0 +1,13 @@
+# Core Release Rules
+
+- Required status fields live in `.ma/decisions.json` and `.ma/release.json`.
+- `$build` is blocked unless:
+  - `idea_status = CLEAR`
+  - `architecture_status = APPROVED`
+  - `evidence_status = VERIFIED`
+  - `logic_status = GREEN`
+  - `security_status = GREEN`
+  - `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.

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

@@ -0,0 +1,24 @@
+---
+name: sage
+description: "Use when the user wants evidence-backed technology choices, OSS evaluation, and source-grounded validation of the stack proposed in `$arch`."
+---
+
+# Sage
+
+Use this skill inside Codex to verify or challenge stack choices with real sources.
+
+## Output
+
+Produce:
+- candidate tools, libraries, or services
+- why each option fits or fails the architecture
+- source-backed evidence from official docs, upstream repos, or approved GitMCP sources
+- recommendation with tradeoffs
+- unresolved gaps or missing evidence
+- exact next trigger, usually `$flow`
+
+## Rules
+
+- Do not invent package capabilities or maturity claims.
+- Prefer primary sources over summaries when validating technical details.
+- If the evidence is weak or contradictory, say so clearly and keep the recommendation conditional.

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

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

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

@@ -0,0 +1,25 @@
+---
+name: vet
+description: "Use when the user wants a security and trust-boundary review of the current design before implementation or release."
+---
+
+# Vet
+
+Use this skill inside Codex to review security posture before the build lane.
+
+## Output
+
+Produce:
+- trust boundaries
+- authn/authz expectations
+- sensitive data paths
+- abuse cases and likely failure modes
+- concrete mitigations
+- release blockers vs acceptable risks
+- exact next trigger, usually `$vibe`
+
+## Rules
+
+- Prioritize material risks over exhaustive but low-value checklists.
+- Call out missing assumptions that affect security posture.
+- Distinguish between must-fix blockers and documented accepted risk.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MA Vet"
+  short_description: "Security, CVE, and risk review for MA"
+  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/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: vibe
+description: "Use when the user wants a DX and UX review of the planned workflow before implementation proceeds."
+---
+
+# Vibe
+
+Use this skill inside Codex to review whether the system will feel coherent for both operators and end users.
+
+## Output
+
+Produce:
+- developer workflow risks
+- user workflow risks
+- complexity hotspots
+- onboarding or operability friction
+- simplifications that improve clarity
+- exact next trigger, usually `$build`
+
+## Rules
+
+- Focus on concrete friction, not aesthetics-only feedback.
+- Prefer fewer surfaces, fewer steps, and clearer operator outcomes.
+- Preserve the architecture and security constraints established earlier in the flow.

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

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

package/scripts/doctor.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+
+const checks = [
+  ["package.json", fs.existsSync("package.json")],
+  ["skills/index.json", fs.existsSync("skills/index.json")],
+  ["dist/meta-architect-skills.tgz", fs.existsSync("dist/meta-architect-skills.tgz")],
+  [".codex/hooks.json", fs.existsSync(".codex/hooks.json")],
+  [".ma/decisions.json", fs.existsSync(".ma/decisions.json")],
+  [".ma/release.json", fs.existsSync(".ma/release.json")],
+  ["docs/release-spec.md", fs.existsSync("docs/release-spec.md")],
+  [".agents/plugins/marketplace.json", fs.existsSync(".agents/plugins/marketplace.json")],
+  ["plugins/meta-architect/.app.json", fs.existsSync("plugins/meta-architect/.app.json")],
+  [
+    "plugins/meta-architect/.codex-plugin/plugin.json",
+    fs.existsSync("plugins/meta-architect/.codex-plugin/plugin.json"),
+  ],
+  ["plugins/meta-architect/.mcp.json", fs.existsSync("plugins/meta-architect/.mcp.json")],
+  [
+    "missions/collaborative-whiteboard/mission.md",
+    fs.existsSync("missions/collaborative-whiteboard/mission.md"),
+  ],
+  ["prompts/architect.md", fs.existsSync("prompts/architect.md")],
+];
+
+let failures = 0;
+for (const [label, ok] of checks) {
+  if (ok) {
+    console.log(`[OK] ${label}`);
+  } else {
+    console.log(`[MISSING] ${label}`);
+    failures += 1;
+  }
+}
+
+process.exitCode = failures === 0 ? 0 : 1;

package/scripts/plugin-sync.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const repoRoot = process.cwd();
+const skillsRoot = path.join(repoRoot, "skills");
+const pluginRoot = path.join(repoRoot, "plugins", "meta-architect");
+const pluginSkillsRoot = path.join(pluginRoot, "skills");
+
+function parseArgs(argv) {
+  return {
+    check: argv.includes("--check"),
+  };
+}
+
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function listSkillDirs(root) {
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+async function syncPluginSkills() {
+  const skillDirs = await listSkillDirs(skillsRoot);
+  await fs.mkdir(pluginSkillsRoot, { recursive: true });
+
+  const existingPluginDirs = await listSkillDirs(pluginSkillsRoot);
+  for (const name of existingPluginDirs) {
+    if (!skillDirs.includes(name)) {
+      await fs.rm(path.join(pluginSkillsRoot, name), { recursive: true, force: true });
+    }
+  }
+
+  for (const name of skillDirs) {
+    const src = path.join(skillsRoot, name);
+    const dest = path.join(pluginSkillsRoot, name);
+    await fs.rm(dest, { recursive: true, force: true });
+    await copyDir(src, dest);
+  }
+
+  return skillDirs;
+}
+
+async function verifyPluginSkills() {
+  const skillDirs = await listSkillDirs(skillsRoot);
+  const pluginDirs = await listSkillDirs(pluginSkillsRoot);
+  if (skillDirs.length !== pluginDirs.length) {
+    throw new Error("Plugin skill mirror drift: directory count mismatch");
+  }
+
+  for (let index = 0; index < skillDirs.length; index += 1) {
+    if (skillDirs[index] !== pluginDirs[index]) {
+      throw new Error(
+        `Plugin skill mirror drift: expected ${skillDirs[index]}, found ${pluginDirs[index]}`,
+      );
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.check) {
+    await verifyPluginSkills();
+    console.log(pluginSkillsRoot);
+    return;
+  }
+
+  await syncPluginSkills();
+  console.log(pluginSkillsRoot);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/postinstall.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { installSkills } from "../src/skill-installer.js";
+
+async function main() {
+  if (process.env.MA_SKIP_AUTO_INSTALL === "1") {
+    console.log("meta-architect: skipped Codex skill auto-install");
+    return;
+  }
+
+  const { targetRoot, installed } = await installSkills();
+  console.log(`meta-architect: installed ${installed.length} Codex skills into ${targetRoot}`);
+}
+
+main().catch((error) => {
+  console.error(`meta-architect: failed to install Codex skills: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/release-metadata.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import process from "node:process";
+
+function loadPackageJson() {
+  return JSON.parse(fs.readFileSync("package.json", "utf8"));
+}
+
+function parseVersion(version) {
+  const match = version.match(
+    /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:-(?<prerelease>[0-9A-Za-z.-]+))?$/,
+  );
+  if (!match?.groups) {
+    throw new Error(`Invalid package.json version: ${version}`);
+  }
+  return match.groups;
+}
+
+function computeMetadata(version) {
+  const parsed = parseVersion(version);
+  const prerelease = parsed.prerelease ?? "";
+  const prereleaseIdentifiers = prerelease ? prerelease.split(".") : [];
+  const isPrerelease = prereleaseIdentifiers.length > 0;
+  const distTag = isPrerelease ? prereleaseIdentifiers[0] : "latest";
+
+  return {
+    version,
+    gitTag: `v${version}`,
+    isPrerelease,
+    distTag,
+    prerelease,
+  };
+}
+
+function parseArgs(argv) {
+  const args = {
+    field: "",
+    githubOutput: "",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--field") {
+      args.field = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--github-output") {
+      args.githubOutput = argv[index + 1] ?? "";
+      index += 1;
+    }
+  }
+
+  return args;
+}
+
+function writeGithubOutput(outputPath, metadata) {
+  const lines = [
+    `version=${metadata.version}`,
+    `git_tag=${metadata.gitTag}`,
+    `dist_tag=${metadata.distTag}`,
+    `is_prerelease=${metadata.isPrerelease}`,
+  ];
+  fs.appendFileSync(outputPath, `${lines.join("\n")}\n`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const pkg = loadPackageJson();
+  const metadata = computeMetadata(pkg.version);
+
+  if (args.githubOutput) {
+    writeGithubOutput(args.githubOutput, metadata);
+  }
+
+  if (args.field) {
+    const value = metadata[args.field];
+    if (value === undefined) {
+      throw new Error(`Unknown metadata field: ${args.field}`);
+    }
+    console.log(value);
+    return;
+  }
+
+  console.log(JSON.stringify(metadata, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/release-verify.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const CANONICAL_PACKAGE = "@jstn-sdk/ma";
+const CANONICAL_INSTALL = "npm i -g @openai/codex@latest @jstn-sdk/ma@latest";
+const CANONICAL_LAUNCH = "ma --madmax --high";
+const UNINSTALL_MA = "npm uninstall -g @jstn-sdk/ma";
+const UNINSTALL_BOTH = "npm uninstall -g @jstn-sdk/ma @openai/codex";
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function readText(file) {
+  return fs.readFileSync(file, "utf8");
+}
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    fail(message);
+  }
+}
+
+function parseVersion(version) {
+  const match = version.match(
+    /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:-(?<prerelease>[0-9A-Za-z.-]+))?$/,
+  );
+  if (!match?.groups) {
+    fail(`Invalid package version: ${version}`);
+  }
+  return match.groups;
+}
+
+function verifyInstallBlock(file) {
+  const content = readText(file);
+  if (!content.includes(CANONICAL_INSTALL)) {
+    return;
+  }
+
+  assert(content.includes(CANONICAL_LAUNCH), `${file}: missing canonical launch command`);
+  assert(content.includes(UNINSTALL_MA), `${file}: missing uninstall Meta-Architect command`);
+  assert(
+    content.includes(UNINSTALL_BOTH),
+    `${file}: missing uninstall Meta-Architect + Codex command`,
+  );
+}
+
+function main() {
+  const pkg = readJson("package.json");
+  const lock = readJson("package-lock.json");
+  const version = pkg.version;
+  const gitTag = `v${version}`;
+  const parsed = parseVersion(version);
+  const isPrerelease = Boolean(parsed.prerelease);
+
+  assert(pkg.name === CANONICAL_PACKAGE, "package.json: wrong package name");
+  assert(lock.name === CANONICAL_PACKAGE, "package-lock.json: wrong package name");
+  assert(lock.version === version, "package-lock.json: version drift from package.json");
+  assert(lock.packages?.[""]?.version === version, "package-lock.json: root package version drift");
+  assert(
+    pkg.publishConfig?.access === "public",
+    "package.json: publishConfig.access must be public",
+  );
+
+  const changelog = readText("CHANGELOG.md");
+  assert(changelog.includes(`## ${gitTag}`), "CHANGELOG.md: missing current version heading");
+
+  const release = readText("RELEASE.md");
+  assert(release.includes(`# Meta-Architect ${gitTag}`), "RELEASE.md: wrong title version");
+
+  const releaseSpec = readText(path.join("docs", "release-spec.md"));
+  assert(
+    releaseSpec.includes(`# ${gitTag} Requirements & Rules`),
+    "docs/release-spec.md: wrong title version",
+  );
+  assert(
+    releaseSpec.includes(`package.json\` version \`${version}\``) ||
+      releaseSpec.includes(`package.json\` version \`${version}`),
+    "docs/release-spec.md: missing package version reference",
+  );
+  assert(
+    releaseSpec.includes(`git tag \`${gitTag}\``),
+    "docs/release-spec.md: missing git tag reference",
+  );
+
+  const qaPath = path.join("docs", "qa", `release-readiness-${version}.md`);
+  assert(fs.existsSync(qaPath), `Missing QA release-readiness file: ${qaPath}`);
+  const qa = readText(qaPath);
+  assert(qa.includes(`# Release Readiness ${version}`), `${qaPath}: wrong title version`);
+
+  const pluginApp = readJson(path.join("plugins", "meta-architect", ".app.json"));
+  const pluginMcp = readJson(path.join("plugins", "meta-architect", ".mcp.json"));
+  const pluginManifest = readJson(
+    path.join("plugins", "meta-architect", ".codex-plugin", "plugin.json"),
+  );
+  assert(pluginApp.version === version, "plugins/meta-architect/.app.json: version drift");
+  assert(pluginMcp.version === version, "plugins/meta-architect/.mcp.json: version drift");
+  assert(
+    pluginManifest.version === version,
+    "plugins/meta-architect/.codex-plugin/plugin.json: version drift",
+  );
+
+  for (const file of [
+    "README.md",
+    path.join("docs", "getting-started.md"),
+    path.join("docs", "onboarding.md"),
+    path.join("docs", "skills.md"),
+    path.join("plugins", "meta-architect", "README.md"),
+  ]) {
+    verifyInstallBlock(file);
+  }
+
+  const envTag =
+    process.env.RELEASE_TAG || process.env.GITHUB_REF_NAME || process.env.GIT_TAG || "";
+  if (envTag.startsWith("v")) {
+    assert(envTag === gitTag, `Release tag mismatch: expected ${gitTag}, got ${envTag}`);
+  }
+
+  if (isPrerelease) {
+    const prereleaseTag = parsed.prerelease.split(".")[0];
+    assert(
+      prereleaseTag && prereleaseTag !== "latest",
+      `Prerelease version ${version} must resolve to an explicit non-latest dist-tag`,
+    );
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        name: pkg.name,
+        version,
+        gitTag,
+        isPrerelease,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/setup-npmrc.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+function normalizeRegistry(registryUrl) {
+  return registryUrl.endsWith("/") ? registryUrl : `${registryUrl}/`;
+}
+
+async function main() {
+  const token = process.env.NPM_TOKEN || process.env.NODE_AUTH_TOKEN;
+  if (!token) {
+    console.log("No npm token detected. Skipping .npmrc generation.");
+    return;
+  }
+
+  const registry = normalizeRegistry(process.env.NPM_REGISTRY_URL || "https://registry.npmjs.org/");
+  const scope = process.env.NPM_SCOPE || "";
+  const host = new URL(registry).host;
+  const npmrcPath = path.join(process.cwd(), ".npmrc");
+
+  const content = [
+    `registry=${registry}`,
+    ...(scope ? [`${scope}:registry=${registry}`] : []),
+    `//${host}/:_authToken=${token}`,
+    "",
+  ].join("\n");
+
+  await fs.writeFile(npmrcPath, content, "utf8");
+  console.log(
+    `Wrote CI .npmrc for ${scope ? `scope ${scope}` : "the canonical unscoped package"}.`,
+  );
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});