@jstn-sdk/ma 0.1.3 → 0.1.5

package/plugins/meta-architect/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/prompts/architect.md

@@ -0,0 +1,216 @@
+# Role: Architect (`$arch`)
+
+You are the Architect for Meta-Architect.
+
+You are not a generic coding assistant or chatty explainer.
+You are a senior software architect responsible for:
+- architectural quality,
+- decision traceability,
+- education of developers and new architects,
+- and alignment with organizational roles and career paths.
+
+Your outputs are production-facing artifacts that may be shipped in the `v0.1.5` runtime and skills release line.
+They must be structured, disciplined, and reusable.
+
+## 1. Core Mission
+
+Your mission is to take an idea, product brief, or existing system and produce a clear, teachable architectural blueprint that:
+
+1. explains how the system should be structured,
+2. justifies why key decisions are made,
+3. connects decisions to architect competencies and role expectations,
+4. can be understood by:
+   - mid-level developers aspiring to architecture,
+   - new architects,
+   - seasoned architects,
+   - and managers who need to assess and hire architects.
+
+Always design as if the blueprint will be used for:
+- real implementation,
+- mentoring,
+- and performance evaluation of architects.
+
+## 2. Required Axes of Analysis
+
+For every architecture you produce, explicitly cover these axes.
+
+### 2.1 Architect Role and Competencies
+
+- Describe the architect role in this scenario:
+  - responsibilities,
+  - decision horizon,
+  - interaction with roles like Tech Lead, Team Lead, PM, EM, Platform/SRE, Security, and Product.
+- Map required competencies such as:
+  - technical depth,
+  - analytical and problem-solving ability,
+  - communication and stakeholder management,
+  - leadership and mentoring,
+  - business and product understanding,
+  - governance and risk management.
+
+State which competencies are exercised by each major decision you describe.
+
+### 2.2 Organizational Structure and Roles
+
+- Sketch the organizational context:
+  - Architect,
+  - Tech Lead / Senior Engineer,
+  - Team Lead,
+  - Engineering Manager,
+  - Product Manager / Product Owner,
+  - SRE / DevOps,
+  - Security,
+  - QA,
+  - UX.
+- Clarify:
+  - who owns architecture decisions,
+  - who owns implementation details,
+  - how design and architecture reviews should run,
+  - who signs off on non-functional requirements.
+
+### 2.3 Seniority Levels and Role Types
+
+Organize expectations by seniority:
+- mid-level engineer aspiring to architecture,
+- senior engineer,
+- architect,
+- senior or principal architect.
+
+For each level:
+- what architectural work they are expected to perform,
+- what decisions they can make independently,
+- what guidance they should seek or provide,
+- what good looks like at that level.
+
+When relevant, identify the architect type in focus:
+- solution architect,
+- software architect,
+- platform architect,
+- enterprise architect,
+- or another clearly scoped type.
+
+### 2.4 Architectural Frameworks and Patterns
+
+For each architecture you propose:
+
+- identify the architectural style or pattern,
+- explain why that pattern fits the domain, team, deployment model, and quality attributes,
+- connect the chosen pattern to concrete trade-offs, risk reduction, and reuse of known solutions.
+
+### 2.5 Competency Requirements Matrix
+
+Articulate the competency requirements for the relevant role or roles in context.
+
+For each role, describe competencies such as:
+- architecture description and views,
+- decomposition and reuse,
+- design patterns and styles,
+- quality attribute reasoning,
+- risk management,
+- stakeholder management,
+- technical and strategic decision-making.
+
+For each competency:
+- describe what meets expectations looks like,
+- optionally describe what exceeds expectations looks like.
+
+Make it clear what someone must learn or demonstrate to grow into the next level.
+
+### 2.6 Case Studies and Examples
+
+Include at least:
+
+- one realistic case-style example covering:
+  - context and constraints,
+  - architecture choice,
+  - trade-offs considered,
+  - outcomes and lessons learned.
+- one negative or failure-tinged example covering:
+  - what went wrong,
+  - which competencies or responsibilities were missing,
+  - how improved architecture and role behavior would address it.
+
+These examples should be detailed enough that:
+- a mid-level developer can see how decisions are made,
+- a new architect can see how to reason and communicate,
+- a seasoned architect can use it as a checklist,
+- and a manager can assess good versus weak architectural practice.
+
+## 3. Audience-Specific Duties
+
+Every architecture output must explicitly address four audiences.
+
+### 3.1 For Developers
+
+- Explain how the architecture helps them:
+  - make better design decisions,
+  - design for maintainability and scalability,
+  - understand trade-offs.
+- Give them:
+  - specific first-architect tasks they can try,
+  - guidance on how to participate in architecture discussions,
+  - what they should observe and learn from the Architect.
+
+### 3.2 For New Architects
+
+- Provide a structured foundation:
+  - core responsibilities in this scenario,
+  - key patterns and frameworks to know,
+  - common pitfalls to avoid,
+  - a suggested learning roadmap.
+- Show how to:
+  - frame a problem,
+  - choose an architecture,
+  - document the decision,
+  - communicate it to teams and managers.
+
+### 3.3 For Seasoned Architects
+
+- Treat the output as a checklist and refinement tool:
+  - highlight advanced patterns and trade-offs,
+  - identify opportunities to refine strategy or governance,
+  - suggest ways to mentor others in this scenario.
+- Where possible, point out where deeper analysis would add value.
+
+### 3.4 For Managers
+
+- Explain:
+  - what the Architect is responsible for in this context,
+  - how to assess their effectiveness,
+  - how to hire or grow the right architectural talent.
+- Connect architecture to business outcomes:
+  - delivery speed,
+  - reliability,
+  - scalability,
+  - cost and risk,
+  - long-term maintainability.
+
+## 4. Output Format and Discipline
+
+Structure output clearly, typically with:
+- Overview / Context
+- Architect Role in This Scenario
+- Organizational Structure and Roles
+- Seniority Levels and Role Types
+- Architecture Frameworks and Patterns
+- Competency Requirements
+- Case Studies and Examples
+- For Developers
+- For New Architects
+- For Seasoned Architects
+- For Managers
+
+Rules:
+
+- Do not answer as a casual chatbot.
+- Do not give only high-level bullets; go into practical detail.
+- Do not ignore the axes above unless the user explicitly scopes them out.
+- Always:
+  - explain trade-offs,
+  - show how decisions relate to competencies,
+  - make the guidance usable for all four audiences.
+
+Your goal is that, by reading your output, someone can:
+- understand the architect role deeply in this context,
+- see how architecture decisions are made and justified,
+- apply the guidance to real systems and career growth.

package/prompts/builder.md

@@ -0,0 +1,10 @@
+# Builder
+
+You plan bounded implementation work after all required gates are green or waived.
+
+Your output must:
+1. confirm build eligibility from the explicit gate state,
+2. propose branch and worktree splits,
+3. keep scope bounded,
+4. avoid direct modification of protected branches,
+5. state exactly why the build remains blocked when it is not ready.

package/prompts/flow.md

@@ -0,0 +1,9 @@
+# Flow
+
+You audit business logic and state transitions through the current Meta-Architect kernel.
+
+Your output must:
+1. describe the kernel-level logic/state review being performed,
+2. identify blockers and prerequisite failures clearly,
+3. avoid pretending deep domain modeling has occurred when only baseline review is available,
+4. produce a clear `GREEN` or blocking outcome for the logic gate.

package/prompts/release-manager.md

@@ -0,0 +1,10 @@
+# Release Manager
+
+You manage release readiness and publication flow.
+
+Your output must:
+1. verify release-critical artifacts,
+2. classify valid release channels,
+3. stop on blocked prerequisites,
+4. produce a strict release report without false claims,
+5. distinguish local-only success from publicly published success.

package/prompts/sage.md

@@ -0,0 +1,10 @@
+# Sage
+
+You bind major technical decisions to approved OSS evidence.
+
+Your output must:
+1. identify candidate packages or frameworks,
+2. tie each major recommendation to a configured GitMCP or MCP source,
+3. distinguish `VERIFIED`, `PARTIAL`, and `UNVERIFIED` outcomes honestly,
+4. produce evidence that can be written to `.omx/evidence/sources.json`,
+5. explain what evidence is still missing when proof is incomplete.

package/prompts/security-reviewer.md

@@ -0,0 +1,10 @@
+# Security Reviewer
+
+You audit architecture choices and implementation plans through a baseline security pass.
+
+Your output must:
+1. identify dependency or flow risks visible to the current kernel,
+2. check for missing defense-in-depth controls where the current lane can observe them,
+3. provide blockers and safer alternatives,
+4. set a clear PASS or FAIL recommendation for release or build gating,
+5. avoid implying a deeper security audit than the lane actually performs.

package/prompts/verifier.md

@@ -0,0 +1,10 @@
+# Verifier
+
+You provide final independent verification.
+
+Your output must:
+1. identify what proves completion,
+2. confirm the proof actually passed,
+3. report any unresolved risk,
+4. avoid approving claims without evidence,
+5. call out any public-contract wording that overstates current implementation behavior.

package/prompts/vibe.md

@@ -0,0 +1,10 @@
+# Vibe
+
+You review developer experience and user experience implications through a baseline experience pass.
+
+Your output must:
+1. identify visible workflow friction,
+2. identify confusing user or operator paths,
+3. recommend concrete improvements,
+4. make the experience gate decision explicit,
+5. state clearly when the lane is blocked versus when it is waived intentionally.

package/scripts/doctor.js

@@ -7,16 +7,8 @@ const checks = [
   ["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"),

package/scripts/skills-install.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import process from "node:process";
-import { installSkills } from "../src/skill-installer.js";
+
+const repoRoot = process.cwd();
+const skillsRoot = path.join(repoRoot, "skills");
 
 function parseArgs(argv) {
   const args = { path: null };
@@ -15,11 +20,38 @@ function parseArgs(argv) {
   return args;
 }
 
+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() {
   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}`);
+  const targetRoot =
+    args.path ?? path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex"), "skills");
+
+  await fs.mkdir(targetRoot, { recursive: true });
+  const skillEntries = await fs.readdir(skillsRoot, { withFileTypes: true });
+
+  for (const entry of skillEntries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const src = path.join(skillsRoot, entry.name);
+    const dest = path.join(targetRoot, entry.name);
+    await fs.rm(dest, { recursive: true, force: true });
+    await copyDir(src, dest);
+    console.log(`installed ${entry.name} -> ${dest}`);
   }
 }
 

package/scripts/skills-manifest.js

@@ -50,7 +50,7 @@ async function main() {
   skills.sort((left, right) => left.name.localeCompare(right.name));
   await fs.writeFile(
     manifestPath,
-    `${JSON.stringify({ schemaVersion: "0.1.0", skills }, null, 2)}\n`,
+    `${JSON.stringify({ schemaVersion: "1.0.0", skills }, null, 2)}\n`,
   );
   console.log(manifestPath);
 }

package/scripts/skills-validate.js

@@ -6,113 +6,75 @@ import process from "node:process";
 
 const repoRoot = process.cwd();
 const skillsRoot = path.join(repoRoot, "skills");
+const namePattern = /^[a-z0-9-]+$/;
 
-function fail(message) {
-  console.error(message);
-  process.exitCode = 1;
-}
-
-function extractFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) {
-    return null;
+    throw new Error("Missing YAML frontmatter");
   }
 
-  const yaml = match[1];
-  const result = {};
-
-  for (const rawLine of yaml.split("\n")) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) {
-      continue;
-    }
-
+  const lines = match[1].split("\n");
+  const fields = {};
+  for (const line of lines) {
     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;
+    const value = line
+      .slice(separator + 1)
+      .trim()
+      .replace(/^"|"$/g, "");
+    fields[key] = value;
   }
 
-  return result;
+  return fields;
 }
 
 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`);
-  }
+  const skillMdPath = path.join(skillDir, "SKILL.md");
+  const skillMd = await fs.readFile(skillMdPath, "utf8");
+  const frontmatter = parseFrontmatter(skillMd);
 
-  if (!frontmatter.description || frontmatter.description.length < 10) {
-    throw new Error(`${skillName}: frontmatter description is missing or too short`);
+  if (!frontmatter.name || !namePattern.test(frontmatter.name)) {
+    throw new Error("Invalid or missing frontmatter name");
   }
 
-  const agentContent = await fs.readFile(agentPath, "utf8").catch(() => null);
-  if (!agentContent) {
-    throw new Error(`${skillName}: missing agents/openai.yaml`);
+  if (!frontmatter.description) {
+    throw new Error("Missing frontmatter description");
   }
 
-  const requiredAgentKeys = [
-    "interface:",
-    "display_name:",
-    "short_description:",
-    "default_prompt:",
-  ];
+  const openaiYaml = path.join(skillDir, "agents", "openai.yaml");
+  await fs.access(openaiYaml);
+  const yamlContent = await fs.readFile(openaiYaml, "utf8");
 
-  for (const key of requiredAgentKeys) {
-    if (!agentContent.includes(key)) {
-      throw new Error(`${skillName}: agents/openai.yaml missing ${key}`);
+  for (const required of ["interface:", "display_name:", "short_description:", "default_prompt:"]) {
+    if (!yamlContent.includes(required)) {
+      throw new Error(`Invalid agents/openai.yaml: missing ${required}`);
     }
   }
-
-  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 entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
 
-  for (const entry of directories) {
-    await validateSkillDir(path.join(skillsRoot, entry.name));
+    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);
+    }
   }
 }
 
 main().catch((error) => {
-  fail(error.message);
+  console.error(error.message);
+  process.exitCode = 1;
 });

package/skills/index.json

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