@jstn-sdk/ma 0.1.5 → 0.1.7

package/plugins/meta-architect/.codex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "meta-architect",
+  "version": "0.1.7",
+  "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
+  "author": {
+    "name": "JustineDevs",
+    "url": "https://github.com/JustineDevs"
+  },
+  "homepage": "https://github.com/JustineDevs/meta-architect",
+  "repository": "https://github.com/JustineDevs/meta-architect.git",
+  "license": "MIT",
+  "keywords": ["codex", "skills", "architecture", "workflow", "review"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Meta-Architect",
+    "shortDescription": "Architecture-first skill bundle for Codex workflows.",
+    "longDescription": "Meta-Architect packages reusable Codex skills plus plugin-scoped MCP and app metadata. The in-session skill workflow is primary. The ma helper command and .ma state only support setup, release gates, and optional local helper automation.",
+    "developerName": "JustineDevs",
+    "category": "Developer Tools"
+  }
+}

package/plugins/meta-architect/.mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.0",
+  "version": "0.1.7",
   "collections": [
     "sindresorhus/awesome",
     "dzharii/awesome-typescript",

package/plugins/meta-architect/README.md

@@ -1,10 +1,11 @@
 # Meta-Architect Plugin Bundle
 
-This plugin bundle packages the Meta-Architect Codex-native skill surface.
+This plugin bundle packages the Meta-Architect skill surfaces for consumers that want an installable plugin-style distribution instead of working directly from the source repository.
 
 ## What the plugin contains
 
 - plugin metadata:
+  - `.codex-plugin/plugin.json`
   - `.app.json`
   - `.mcp.json`
 - bundled Meta-Architect skill surfaces under `skills/`
@@ -17,7 +18,7 @@ This plugin is **not** the full source repository.
 It does not attempt to ship:
 - repository `.github/` workflows
 - contributor-facing repo templates
-- local runtime `.omx` state
+- local runtime `.ma` state
 - every source file in the repository
 - the entire release engineering toolchain
 
@@ -37,20 +38,30 @@ Plugin bundle contains:
 - the installable skill-facing product layer
 - plugin metadata that describes the bundle to consumers
 
-Use the core repo when you want to develop Meta-Architect itself. Use the plugin bundle when you
-want the packaged Codex runtime layer.
+Use the core repo when you want to develop Meta-Architect itself. Use the plugin bundle when you want to consume the packaged skill surface.
 
 ## Install and use
 
-The plugin-facing bundle is meant to be consumed alongside the Codex-hosted runtime flow.
+The plugin-facing bundle should be consumed alongside the repository’s documented packaging/install flow.
 
-Primary runtime posture:
+Canonical package/runtime path:
 
 ```bash
-npm i -g @openai/codex @jstn-sdk/ma
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# Launch
 ma --madmax --high
+
+# Remove Meta-Architect only
+npm uninstall -g @jstn-sdk/ma
+
+# Remove Meta-Architect and Codex
+npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
+Use the plugin bundle when you need installable skill metadata or local marketplace discovery. Use the package and Codex skill flow when you want the full Meta-Architect product experience.
+
 Primary related surfaces:
 - [docs/skills-publishing.md](../../docs/skills-publishing.md)
 - [skills/](../../skills/)
@@ -59,7 +70,9 @@ If you are working from the repository directly, validate and package with:
 
 ```bash
 npm run skills:manifest
+npm run plugin:sync
 npm run skills:validate
+npm run plugin:verify
 npm run skills:pack
 npm run skills:install -- --path ./dist/installed-skills
 ```
@@ -67,7 +80,6 @@ npm run skills:install -- --path ./dist/installed-skills
 Consumer expectation:
 - the plugin ships the same public skill contracts as the canonical `skills/` directory
 - it does not define a looser or simplified product contract
-- the main operating surface remains runtime skill tags inside Codex
 
 ## MCP wiring expectations
 
@@ -85,7 +97,7 @@ Do not assume the plugin alone provides a fully wired live MCP environment.
 When consuming the plugin:
 - use committed `skills/` content as the contract source
 - validate installed skill folders
-- do not treat local runtime `.omx` state as part of the distributable plugin
+- do not treat local runtime `.ma` state as part of the distributable plugin
 - preserve the gate/evidence semantics documented in the repo
 
 ## Version and release relation
@@ -93,7 +105,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.5`
+- plugin scope is aligned to Meta-Architect `v0.1.7`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.
@@ -105,4 +117,5 @@ The plugin is one distribution surface of the same product, not a separate produ
 - [docs/skills-publishing.md](../../docs/skills-publishing.md)
 - [docs/mcp-setup.md](../../docs/mcp-setup.md)
 - [.app.json](./.app.json)
+- [.codex-plugin/plugin.json](./.codex-plugin/plugin.json)
 - [.mcp.json](./.mcp.json)

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: "$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/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: "$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/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: "$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/plugins/meta-architect/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/plugins/meta-architect/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/plugins/meta-architect/skills/meta-architect/SKILL.md

@@ -1,36 +1,32 @@
 ---
 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.
+- Use approved discovery accelerators such as Ossium, Trendshift, Dev Hunt, Libraries.io, Open Hub, and Open-source Projects when you need faster OSS candidate discovery, then validate any promising project through upstream repos and official docs.
+- Keep the `$sage` order explicit: known upstream sources first, discovery accelerators second, exact repo mapping third, approval only after upstream verification.
+- 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/plugins/meta-architect/skills/meta-architect/agents/openai.yaml

@@ -0,0 +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."

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 command path 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,37 @@
+---
+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
+
+- Follow this order:
+  - use known upstream repos and official docs first when they already exist
+  - use discovery accelerators to find or narrow candidates
+  - map the selected candidate back to an exact upstream repo
+  - verify against upstream repos and official docs before approving it
+- Use approved discovery accelerators when you need faster OSS candidate discovery:
+  - Ossium (`https://ossium.live/home`) for trending, curated, YC-backed, and GSoC-linked OSS discovery
+  - Trendshift (`https://trendshift.io/`) for rising GitHub engagement and topic momentum
+  - Dev Hunt (`https://devhunt.org/`) for newly launched developer tools
+  - Libraries.io (`https://libraries.io/`) for package/dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
+  - Open Hub (`https://openhub.net/`) for project activity, contributor, and comparison signals
+  - Open-source Projects (`https://www.opensourceprojects.dev/`) for curated OSS discovery and detailed project writeups
+- Do not invent package capabilities or maturity claims.
+- Prefer primary sources over summaries when validating technical details.
+- Do not treat discovery listings alone as VERIFIED evidence; promote candidates to upstream repos and official docs before approving them.
+- 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: "$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/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: "$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/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: "$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/scripts/doctor.js

@@ -7,8 +7,16 @@ 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/plugin-sync.js

@@ -0,0 +1,93 @@
+#!/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);
+      await fs.chmod(destPath, 0o644);
+    }
+  }
+}
+
+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,23 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { installSkills, installSupportBundle } 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: skillRoot, installed: skills },
+    { targetRoot: bundleRoot, installed: assets },
+  ] = await Promise.all([installSkills(), installSupportBundle()]);
+  console.log(`meta-architect: installed ${skills.length} Codex skills into ${skillRoot}`);
+  console.log(`meta-architect: installed ${assets.length} support assets into ${bundleRoot}`);
+}
+
+main().catch((error) => {
+  console.error(`meta-architect: failed to install Codex skills: ${error.message}`);
+  process.exitCode = 1;
+});