@jstn-sdk/ma 0.1.4 → 0.1.5

package/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/skills/meta-architect/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  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."
+  display_name: "Meta-Architect"
+  short_description: "Codex-native runtime orchestration and gated build workflows"
+  default_prompt: "Use $meta-architect inside Codex to run the gated Meta-Architect runtime workflow in this repo."

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

@@ -1,6 +1,6 @@
 # Core Release Rules
 
-- Required status fields live in `.ma/decisions.json` and `.ma/release.json`.
+- Required status fields live in `.omx/decisions.json` and `.omx/release.json`.
 - `$build` is blocked unless:
   - `idea_status = CLEAR`
   - `architecture_status = APPROVED`
@@ -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 command path only when repo-local state automation is explicitly needed; otherwise stay inside Codex and carry the gate decisions in the session.
+- Use `ma status`, `ma merge`, and `ma release` instead of manual state edits.

package/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/skills/meta-architect-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 $meta-architect-arch to produce architecture and stack rationale for a Meta-Architect-managed project."

package/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/skills/meta-architect-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 $meta-architect-build to evaluate gates, propose feature branches, and prepare build execution."

package/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/skills/meta-architect-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 $meta-architect-flow to map business logic, states, transitions, and blockers in a Meta-Architect workflow."

package/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/skills/meta-architect-sage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MA Sage"
+  short_description: "GitMCP-backed OSS evidence selection"
+  default_prompt: "Use $meta-architect-sage to bind major technical choices to approved GitMCP-backed OSS sources."

package/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`

package/skills/meta-architect-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 $meta-architect-vet to review security risks, CVEs, and safer alternatives in a Meta-Architect project."

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

@@ -0,0 +1,24 @@
+---
+name: meta-architect-vibe
+description: "Use when Codex needs to run or inspect the Meta-Architect `$vibe` lane for developer-experience and user-experience review before build execution. Trigger for requests about DX friction, UX risks, operator flow quality, or whether the experience gate should be GREEN or WAIVED."
+---
+
+# Meta-Architect Vibe
+
+Use `$vibe` inside the Codex-hosted Meta-Architect runtime to review developer and user experience before build planning.
+
+## Canonical trigger
+
+- `$vibe`
+
+## Secondary 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`

package/skills/meta-architect-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 $meta-architect-vibe to review developer and user experience risks before a Meta-Architect build is unlocked."

package/sprint/00-idea.md

@@ -12,7 +12,7 @@ Capture a project idea, clarify scope and constraints, and move the repository f
 
 ## Expected outputs
 
-- idea decision entry in `.ma/decisions.json`
+- idea decision entry in `.omx/decisions.json`
 - `idea_status = CLEAR` when the brief is good enough to proceed
 
 ## Exit criteria

package/sprint/01-architecture.md

@@ -11,7 +11,7 @@ Produce a structured first-pass architecture blueprint, stack rationale, and dow
 
 ## Expected outputs
 
-- architecture decision in `.ma/decisions.json`
+- architecture decision in `.omx/decisions.json`
 - `architecture_status = APPROVED`
 
 ## Exit criteria

package/sprint/02-oss-evidence.md

@@ -11,7 +11,7 @@ Bind major architecture choices to approved GitMCP-backed evidence.
 
 ## Expected outputs
 
-- `.ma/evidence/sources.json`
+- `.omx/evidence/sources.json`
 - `evidence_status = VERIFIED | PARTIAL | MISSING`
 
 ## Exit criteria

package/sprint/03-logic.md

@@ -11,7 +11,7 @@ Record a structured first-pass logic/state review and block progress if prerequi
 
 ## Expected outputs
 
-- logic review entry in `.ma/decisions.json`
+- logic review entry in `.omx/decisions.json`
 - `logic_status = GREEN | RED`
 
 ## Exit criteria

package/sprint/04-security.md

@@ -10,8 +10,8 @@ Record a baseline security pass and keep the workflow blocked if prerequisites a
 
 ## Expected outputs
 
-- `.ma/evidence/audits.json`
-- `.ma/evidence/cves.json`
+- `.omx/evidence/audits.json`
+- `.omx/evidence/cves.json`
 - `security_status = GREEN | RED`
 
 ## Exit criteria

package/sprint/05-dx-ux.md

@@ -10,7 +10,7 @@ Record a baseline developer and user experience pass before build unlock.
 
 ## Expected outputs
 
-- `.ma/evidence/outcomes.json`
+- `.omx/evidence/outcomes.json`
 - `experience_status = GREEN | RED | WAIVED`
 
 ## Exit criteria

package/src/decision-log.js

@@ -1,5 +1,5 @@
 import { readJson, writeJson } from "./fs-utils.js";
-import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
+import { getDecisionsPath } from "./paths.js";
 
 function validateDecisionShape(entry) {
   const required = ["decision", "status", "evidence", "blockers", "next_allowed_triggers"];
@@ -11,7 +11,7 @@ function validateDecisionShape(entry) {
 }
 
 export async function loadDecisionLog() {
-  const parsed = await readJson(getRuntimeReadPath("decisions.json"));
+  const parsed = await readJson(getDecisionsPath());
 
   if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.decisions)) {
     throw new Error("Decision log must be an object with a decisions array");
@@ -28,7 +28,7 @@ export async function appendDecision(entry) {
     timestamp: new Date().toISOString(),
   });
 
-  await writeJson(getRuntimeWritePath("decisions.json"), log);
+  await writeJson(getDecisionsPath(), log);
 }
 
 export async function updateDecisionStatuses(statusUpdates) {
@@ -36,5 +36,5 @@ export async function updateDecisionStatuses(statusUpdates) {
   for (const [field, value] of Object.entries(statusUpdates)) {
     log[field] = value;
   }
-  await writeJson(getRuntimeWritePath("decisions.json"), log);
+  await writeJson(getDecisionsPath(), log);
 }

package/src/doctor.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getRepoRoot } from "./paths.js";
+
+const checks = [
+  "AGENTS.md",
+  ".codex/config.toml",
+  ".codex/hooks.json",
+  ".codex/agents/architect.toml",
+  ".codex/prompts/enforcement.md",
+  ".omx/decisions.json",
+  ".omx/release.json",
+  "mcp/servers.json",
+  "templates/AGENTS.md",
+];
+
+export function runDoctor() {
+  const repoRoot = getRepoRoot();
+  let failures = 0;
+
+  for (const relativePath of checks) {
+    const ok = fs.existsSync(path.join(repoRoot, relativePath));
+    console.log(`${ok ? "[OK]" : "[MISSING]"} ${relativePath}`);
+    if (!ok) {
+      failures += 1;
+    }
+  }
+
+  return failures === 0 ? 0 : 1;
+}

package/src/launcher.js

@@ -1,56 +1,52 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
-const nativeCommands = new Set([
+const maintenanceCommands = new Set([
   "setup",
   "init",
+  "doctor",
   "idea",
   "skills",
-  "sdk-path",
   "status",
+  "run",
   "merge",
   "release",
-  "run",
 ]);
 
 export function shouldDelegateToCodex(args) {
   if (args.length === 0) {
-    return true;
+    return false;
   }
 
-  return !nativeCommands.has(args[0]);
+  const first = args[0];
+  return first.startsWith("-") || !maintenanceCommands.has(first);
 }
 
-function normalizeCodexArgs(args) {
+export function normalizeCodexArgs(args) {
   return args.filter((arg) => arg !== "--madmax" && arg !== "--high");
 }
 
 function resolveCodexCommand() {
-  if (process.env.MA_CODEX_BIN) {
-    return process.env.MA_CODEX_BIN;
-  }
-
-  return "codex";
+  return process.env.MA_CODEX_BIN ?? "codex";
 }
 
 export function runCodex(args) {
   const codexCommand = resolveCodexCommand();
   const codexArgs = normalizeCodexArgs(args);
-  const commandArgs =
-    path.extname(codexCommand) === ".js" || path.extname(codexCommand) === ".mjs"
-      ? [codexCommand, ...codexArgs]
-      : codexArgs;
-  const command = commandArgs[0] === codexCommand ? process.execPath : codexCommand;
-  const finalArgs = command === process.execPath ? commandArgs : codexArgs;
-  const result = spawnSync(command, finalArgs, { stdio: "inherit" });
+  const useNode = path.extname(codexCommand) === ".js" || path.extname(codexCommand) === ".mjs";
+  const command = useNode ? process.execPath : codexCommand;
+  const finalArgs = useNode ? [codexCommand, ...codexArgs] : codexArgs;
+  const result = spawnSync(command, finalArgs, {
+    stdio: "inherit",
+  });
 
   if (result.error) {
     if (result.error.code === "ENOENT") {
-      throw new Error("Codex not found. Install it with: npm install -g @openai/codex");
+      throw new Error("Codex CLI not found. Install it with: npm i -g @openai/codex");
     }
 
-    throw new Error(`Failed to start Codex: ${result.error.message}`);
+    throw new Error(`Failed to start Codex CLI: ${result.error.message}`);
   }
 
-  return typeof result.status === "number" ? result.status : 1;
+  return result.status ?? 1;
 }

package/src/mcp-live-client.js

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

package/src/paths.js

@@ -5,22 +5,46 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 export const packageRoot = path.resolve(__dirname, "..");
+export function getPackageRoot() {
+  return packageRoot;
+}
+
 export function getRepoRoot() {
-  return process.env.MA_ROOT ? path.resolve(process.env.MA_ROOT) : process.cwd();
+  return path.resolve(process.env.MA_ROOT ?? process.cwd());
+}
+
+export function resolveRepoPath(...parts) {
+  return path.join(getRepoRoot(), ...parts);
 }
 
-export function getRuntimeRoot() {
-  return path.join(getRepoRoot(), ".ma");
+export function getOmxRoot() {
+  return resolveRepoPath(".omx");
 }
 
-export function getRuntimeWritePath(...parts) {
-  return path.join(getRuntimeRoot(), ...parts);
+export function getReleaseStatePath() {
+  return path.join(getOmxRoot(), "release.json");
 }
 
-export function getRuntimeReadPath(...parts) {
-  return path.join(getRuntimeRoot(), ...parts);
+export function getDecisionsPath() {
+  return path.join(getOmxRoot(), "decisions.json");
 }
 
 export function getMcpServersPath() {
-  return path.join(getRepoRoot(), "mcp", "servers.json");
+  return resolveRepoPath("mcp", "servers.json");
+}
+
+export function getSourcesPath() {
+  return path.join(getOmxRoot(), "evidence", "sources.json");
+}
+
+export function getAuditsPath() {
+  return path.join(getOmxRoot(), "evidence", "audits.json");
+}
+
+export function getOutcomesPath() {
+  return path.join(getOmxRoot(), "evidence", "outcomes.json");
+}
+
+export function getCvesPath() {
+  return path.join(getOmxRoot(), "evidence", "cves.json");
 }

package/src/release-state.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import { writeJson } from "./fs-utils.js";
-import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
+import { getReleaseStatePath } from "./paths.js";
 
 const allowedStatuses = {
   idea_status: ["DRAFT", "CLEAR", "BLOCKED"],
@@ -43,7 +43,7 @@ export function validateReleaseState(state) {
 }
 
 export async function loadReleaseState() {
-  const raw = await fs.readFile(getRuntimeReadPath("release.json"), "utf8");
+  const raw = await fs.readFile(getReleaseStatePath(), "utf8");
   const parsed = JSON.parse(raw);
   return validateReleaseState(parsed);
 }
@@ -54,6 +54,6 @@ export async function saveReleaseState(state) {
     ...state,
     updatedAt: new Date().toISOString(),
   };
-  await writeJson(getRuntimeWritePath("release.json"), next);
+  await writeJson(getReleaseStatePath(), next);
   return next;
 }