@jstn-sdk/ma 0.1.5 → 0.1.6

package/scripts/skills-validate.js

@@ -6,75 +6,113 @@ import process from "node:process";
 
 const repoRoot = process.cwd();
 const skillsRoot = path.join(repoRoot, "skills");
-const namePattern = /^[a-z0-9-]+$/;
 
-function parseFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
+function fail(message) {
+  console.error(message);
+  process.exitCode = 1;
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
   if (!match) {
-    throw new Error("Missing YAML frontmatter");
+    return null;
   }
 
-  const lines = match[1].split("\n");
-  const fields = {};
-  for (const line of lines) {
+  const yaml = match[1];
+  const result = {};
+
+  for (const rawLine of yaml.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
     const separator = line.indexOf(":");
     if (separator === -1) {
       continue;
     }
+
     const key = line.slice(0, separator).trim();
-    const value = line
-      .slice(separator + 1)
-      .trim()
-      .replace(/^"|"$/g, "");
-    fields[key] = value;
+    let value = line.slice(separator + 1).trim();
+
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
   }
 
-  return fields;
+  return result;
 }
 
 async function validateSkillDir(skillDir) {
-  const skillMdPath = path.join(skillDir, "SKILL.md");
-  const skillMd = await fs.readFile(skillMdPath, "utf8");
-  const frontmatter = parseFrontmatter(skillMd);
+  const skillName = path.basename(skillDir);
+  const skillPath = path.join(skillDir, "SKILL.md");
+  const agentPath = path.join(skillDir, "agents", "openai.yaml");
+
+  const skillContent = await fs.readFile(skillPath, "utf8").catch(() => null);
+  if (!skillContent) {
+    throw new Error(`${skillName}: missing SKILL.md`);
+  }
+
+  const frontmatter = extractFrontmatter(skillContent);
+  if (!frontmatter) {
+    throw new Error(`${skillName}: SKILL.md missing frontmatter`);
+  }
+
+  if (!frontmatter.name) {
+    throw new Error(`${skillName}: frontmatter missing name`);
+  }
+
+  if (frontmatter.name !== skillName) {
+    throw new Error(`${skillName}: frontmatter name must match directory name`);
+  }
+
+  if (!/^[a-z0-9-]+$/.test(frontmatter.name)) {
+    throw new Error(`${skillName}: frontmatter name must be lowercase kebab-case`);
+  }
 
-  if (!frontmatter.name || !namePattern.test(frontmatter.name)) {
-    throw new Error("Invalid or missing frontmatter name");
+  if (!frontmatter.description || frontmatter.description.length < 10) {
+    throw new Error(`${skillName}: frontmatter description is missing or too short`);
   }
 
-  if (!frontmatter.description) {
-    throw new Error("Missing frontmatter description");
+  const agentContent = await fs.readFile(agentPath, "utf8").catch(() => null);
+  if (!agentContent) {
+    throw new Error(`${skillName}: missing agents/openai.yaml`);
   }
 
-  const openaiYaml = path.join(skillDir, "agents", "openai.yaml");
-  await fs.access(openaiYaml);
-  const yamlContent = await fs.readFile(openaiYaml, "utf8");
+  const requiredAgentKeys = [
+    "interface:",
+    "display_name:",
+    "short_description:",
+    "default_prompt:",
+  ];
 
-  for (const required of ["interface:", "display_name:", "short_description:", "default_prompt:"]) {
-    if (!yamlContent.includes(required)) {
-      throw new Error(`Invalid agents/openai.yaml: missing ${required}`);
+  for (const key of requiredAgentKeys) {
+    if (!agentContent.includes(key)) {
+      throw new Error(`${skillName}: agents/openai.yaml missing ${key}`);
     }
   }
+
+  console.log(`${skillName}: valid`);
 }
 
 async function main() {
   const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
+  const directories = entries.filter((entry) => entry.isDirectory());
 
-    const skillDir = path.join(skillsRoot, entry.name);
-    try {
-      await validateSkillDir(skillDir);
-      console.log("Skill is valid!");
-    } catch (error) {
-      console.error(`[ERROR] ${entry.name}: ${error.message}`);
-      process.exit(1);
-    }
+  if (directories.length === 0) {
+    throw new Error("No skill directories found in skills/");
+  }
+
+  for (const entry of directories) {
+    await validateSkillDir(path.join(skillsRoot, entry.name));
   }
 }
 
 main().catch((error) => {
-  console.error(error.message);
-  process.exitCode = 1;
+  fail(error.message);
 });

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

@@ -0,0 +1,4 @@
+interface:
+  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/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/skills/build/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  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/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/skills/flow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  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/index.json

@@ -1,40 +1,45 @@
 {
-  "schemaVersion": "1.0.0",
+  "schemaVersion": "0.1.0",
   "skills": [
     {
-      "name": "meta-architect",
-      "path": "skills/meta-architect",
-      "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`."
+      "name": "arch",
+      "path": "skills/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."
+    },
+    {
+      "name": "build",
+      "path": "skills/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."
     },
     {
-      "name": "meta-architect-arch",
-      "path": "skills/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."
+      "name": "flow",
+      "path": "skills/flow",
+      "description": "Use when the user wants logic validation: states, transitions, invariants, edge cases, dead ends, and blockers before implementation."
     },
     {
-      "name": "meta-architect-build",
-      "path": "skills/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."
+      "name": "maestro",
+      "path": "skills/maestro",
+      "description": "Use when the user wants Meta-Architect to choose the best next workflow step, explain why, and recommend the right lane or assignment."
     },
     {
-      "name": "meta-architect-flow",
-      "path": "skills/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."
+      "name": "meta-architect",
+      "path": "skills/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."
     },
     {
-      "name": "meta-architect-sage",
-      "path": "skills/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."
+      "name": "sage",
+      "path": "skills/sage",
+      "description": "Use when the user wants evidence-backed technology choices, OSS evaluation, and source-grounded validation of the stack proposed in `$arch`."
     },
     {
-      "name": "meta-architect-vet",
-      "path": "skills/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."
+      "name": "vet",
+      "path": "skills/vet",
+      "description": "Use when the user wants a security and trust-boundary review of the current design before implementation or release."
     },
     {
-      "name": "meta-architect-vibe",
-      "path": "skills/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."
+      "name": "vibe",
+      "path": "skills/vibe",
+      "description": "Use when the user wants a DX and UX review of the planned workflow before implementation proceeds."
     }
   ]
 }

package/skills/maestro/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: maestro
+description: "Use when the user wants Meta-Architect to choose the best next workflow step, explain why, and recommend the right lane or assignment."
+---
+
+# Maestro
+
+Use this skill inside Codex when you want Meta-Architect to act like a workflow manager.
+
+## Output
+
+Produce:
+- current situation summary
+- best next step
+- why that step is next
+- recommended lane or assignment
+- what to avoid doing yet
+- exact next trigger, command, or handoff
+
+## Rules
+
+- Prefer the smallest next step that moves the workflow forward safely.
+- Respect current gate state before recommending implementation or release work.
+- Be explicit when more evidence, planning, or validation is still needed.
+- Route to the in-session skill flow first; use helper commands only when they are the clearest support path.

package/skills/maestro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$maestro"
+  short_description: "Best next step and lane orchestration"
+  default_prompt: "Use $maestro to inspect the current Meta-Architect workflow state, choose the best next step, explain why it is next, and recommend the right lane or assignment."

package/skills/meta-architect/SKILL.md

@@ -1,36 +1,30 @@
 ---
 name: meta-architect
-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`."
+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
 
-Meta-Architect is the umbrella runtime skill for the Codex-hosted workflow in this repository.
+## Overview
 
-## Canonical runtime usage
+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.
 
-1. Install `@openai/codex` and `meta-architect`
-2. Launch `ma --madmax --high`
-3. Operate through `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
+## Workflow
 
-## Secondary helper usage
+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.
 
-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`
+## Rules
 
-## Expected outputs
+- 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.
 
-- 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
+## References
 
-## Contract rule
-
-Do not treat helper commands as the primary story. The primary story is always the Codex session launched with `ma --madmax --high`.
+- For release gates and branch policy, read `references/core-release-rules.md`.

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

@@ -1,4 +1,4 @@
 interface:
-  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."
+  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

@@ -1,6 +1,6 @@
 # Core Release Rules
 
-- Required status fields live in `.omx/decisions.json` and `.omx/release.json`.
+- Required status fields live in `.ma/decisions.json` and `.ma/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 `ma status`, `ma merge`, and `ma release` instead of manual state edits.
+- 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/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/skills/sage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  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/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/skills/vet/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  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/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/skills/vibe/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  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/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 `.omx/decisions.json`
+- idea decision entry in `.ma/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 `.omx/decisions.json`
+- architecture decision in `.ma/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
 
-- `.omx/evidence/sources.json`
+- `.ma/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 `.omx/decisions.json`
+- logic review entry in `.ma/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
 
-- `.omx/evidence/audits.json`
-- `.omx/evidence/cves.json`
+- `.ma/evidence/audits.json`
+- `.ma/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
 
-- `.omx/evidence/outcomes.json`
+- `.ma/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 { getDecisionsPath } from "./paths.js";
+import { getRuntimeReadPath, getRuntimeWritePath } 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(getDecisionsPath());
+  const parsed = await readJson(getRuntimeReadPath("decisions.json"));
 
   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(getDecisionsPath(), log);
+  await writeJson(getRuntimeWritePath("decisions.json"), 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(getDecisionsPath(), log);
+  await writeJson(getRuntimeWritePath("decisions.json"), log);
 }