@jstn-sdk/ma 0.1.0

package/scripts/skills-install.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { installSkills } from "../src/skill-installer.js";
+
+function parseArgs(argv) {
+  const args = { path: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--path") {
+      args.path = argv[index + 1];
+      index += 1;
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const { installed } = await installSkills({ targetRoot: args.path ?? undefined });
+  for (const skill of installed) {
+    console.log(`installed ${skill.name} -> ${skill.dest}`);
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/skills-manifest.js

@@ -0,0 +1,61 @@
+#!/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 manifestPath = path.join(skillsRoot, "index.json");
+
+function parseFrontmatterNameAndDescription(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error("Missing SKILL.md frontmatter");
+  }
+
+  const lines = match[1].split("\n");
+  let name = "";
+  let description = "";
+  for (const line of lines) {
+    if (line.startsWith("name:")) {
+      name = line.slice("name:".length).trim();
+    }
+    if (line.startsWith("description:")) {
+      description = line.slice("description:".length).trim().replace(/^"|"$/g, "");
+    }
+  }
+  return { name, description };
+}
+
+async function main() {
+  const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+  const skills = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const skillPath = path.join(skillsRoot, entry.name, "SKILL.md");
+    const content = await fs.readFile(skillPath, "utf8");
+    const meta = parseFrontmatterNameAndDescription(content);
+    skills.push({
+      name: meta.name,
+      path: `skills/${entry.name}`,
+      description: meta.description,
+    });
+  }
+
+  skills.sort((left, right) => left.name.localeCompare(right.name));
+  await fs.writeFile(
+    manifestPath,
+    `${JSON.stringify({ schemaVersion: "0.1.0", skills }, null, 2)}\n`,
+  );
+  console.log(manifestPath);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/skills-pack.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+const repoRoot = process.cwd();
+const distRoot = path.join(repoRoot, "dist");
+const bundlePath = path.join(distRoot, "meta-architect-skills.tgz");
+const skillsRoot = path.join(repoRoot, "skills");
+
+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 main() {
+  await fs.mkdir(distRoot, { recursive: true });
+  await fs.rm(bundlePath, { force: true });
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "meta-architect-skills-"));
+  const frozenSkillsRoot = path.join(tempRoot, "skills");
+  await copyDir(skillsRoot, frozenSkillsRoot);
+
+  const result = spawnSync("tar", ["-czf", bundlePath, "skills"], {
+    cwd: tempRoot,
+    encoding: "utf8",
+  });
+
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+
+  await fs.rm(tempRoot, { recursive: true, force: true });
+
+  console.log(bundlePath);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/skills-validate.js

@@ -0,0 +1,118 @@
+#!/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");
+
+function fail(message) {
+  console.error(message);
+  process.exitCode = 1;
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) {
+    return null;
+  }
+
+  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();
+    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 result;
+}
+
+async function validateSkillDir(skillDir) {
+  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.description || frontmatter.description.length < 10) {
+    throw new Error(`${skillName}: frontmatter description is missing or too short`);
+  }
+
+  const agentContent = await fs.readFile(agentPath, "utf8").catch(() => null);
+  if (!agentContent) {
+    throw new Error(`${skillName}: missing agents/openai.yaml`);
+  }
+
+  const requiredAgentKeys = [
+    "interface:",
+    "display_name:",
+    "short_description:",
+    "default_prompt:",
+  ];
+
+  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 });
+  const directories = entries.filter((entry) => entry.isDirectory());
+
+  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) => {
+  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: "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/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: "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/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: "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/skills/index.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": "0.1.0",
+  "skills": [
+    {
+      "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": "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",
+      "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": "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": "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": "vibe",
+      "path": "skills/vibe",
+      "description": "Use when the user wants a DX and UX review of the planned workflow before implementation proceeds."
+    }
+  ]
+}

package/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/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/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/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: "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/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: "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/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: "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/sprint/00-idea.md

@@ -0,0 +1,27 @@
+# Sprint 0: Idea
+
+## Goal
+
+Capture a project idea, clarify scope and constraints, and move the repository from an undefined request to a gate-ready project brief.
+
+## Inputs
+
+- raw product or system idea
+- high-level constraints
+- target users or operators if known
+
+## Expected outputs
+
+- idea decision entry in `.ma/decisions.json`
+- `idea_status = CLEAR` when the brief is good enough to proceed
+
+## Exit criteria
+
+- the project idea is explicit enough for `$arch`
+- major ambiguity that would break architecture work is removed
+
+## Failure conditions
+
+- empty or vague idea
+- contradictory scope
+- missing baseline constraints

package/sprint/01-architecture.md

@@ -0,0 +1,26 @@
+# Sprint 1: Architecture
+
+## Goal
+
+Produce a structured first-pass architecture blueprint, stack rationale, and downstream review handoff.
+
+## Inputs
+
+- `idea_status = CLEAR`
+- project brief from Sprint 0
+
+## Expected outputs
+
+- architecture decision in `.ma/decisions.json`
+- `architecture_status = APPROVED`
+
+## Exit criteria
+
+- major components are described
+- stack choices are justified
+- evidence requirements for `$sage` are explicit
+
+## Failure conditions
+
+- missing idea brief
+- architecture output lacks structure or downstream handoff

package/sprint/02-oss-evidence.md

@@ -0,0 +1,26 @@
+# Sprint 2: OSS Evidence
+
+## Goal
+
+Bind major architecture choices to approved GitMCP-backed evidence.
+
+## Inputs
+
+- `architecture_status = APPROVED`
+- configured MCP/GitMCP endpoints
+
+## Expected outputs
+
+- `.ma/evidence/sources.json`
+- `evidence_status = VERIFIED | PARTIAL | MISSING`
+
+## Exit criteria
+
+- at least one real approved source is probed successfully for `VERIFIED`
+- all blockers are explicit if evidence is partial or missing
+
+## Failure conditions
+
+- invalid endpoint configuration
+- live MCP failure
+- no approved source available

package/sprint/03-logic.md

@@ -0,0 +1,25 @@
+# Sprint 3: Logic
+
+## Goal
+
+Record a structured first-pass logic/state review and block progress if prerequisites are not ready.
+
+## Inputs
+
+- architecture approved
+- evidence at least partial
+
+## Expected outputs
+
+- logic review entry in `.ma/decisions.json`
+- `logic_status = GREEN | RED`
+
+## Exit criteria
+
+- the kernel’s baseline state review is recorded
+- blockers are explicit when the lane cannot turn green
+
+## Failure conditions
+
+- architecture or evidence not ready
+- hidden blockers