@jstn-sdk/ma
Advanced tools
Codex-native skills system for architecture, evidence, review, and gated build guidance.
Quality gates and evidence verification for AI coding agents.
Your agent writes code fast. Meta-Architect makes it prove each stage first. Design, evidence, logic, security, experience, build. Each gate stays locked until the one before it passes.
Quick Start · Demo · Verified Coverage · Security · Contributing · Issues
[!NOTE] Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution. Meta-Architect does not replace your coding runtime. It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.
Requires Node.js 20+ and a TypeSafe API key for autonomous Maestro routing.
npm install --global @jstn-sdk/ma@latest
ma auth typesafe
# Enter the key once when prompted. It is stored owner-only at
# ~/.config/meta-architect/provider.env (or $XDG_CONFIG_HOME/meta-architect/provider.env).
ma setup
ma --madmax --high
For a project-local dotenv setup, create .env.local in the project root:
TYPESAFE_API_KEY=jv_live_your_key
Keep .env.local out of version control. Meta-Architect reads .env.local,
then .env, then the global credential file; explicit environment variables
still take precedence. The default jev-latest model is selected automatically;
no model setting is required. Check the resolved source without revealing the key:
ma auth typesafe --status
Then give Maestro the project goal inside your AI coding agent:
$maestro I want to build: [your project idea]
ma setup detects the active host, installs the compatible Meta-Architect
surface, and writes project state to .ma/. The credential is never written
to .ma/, receipts, logs, or generated context.
After setup, the normal workflow is one goal, not a manually selected lane sequence:
ma setup
ma --madmax --high
Inside the AI coding agent, state the goal once:
$maestro Build a multi-tenant analytics API with authentication and tests.
When the local Maestro runtime is running with the live provider configured,
Maestro reads the current .ma/ state, asks Jev to choose the next eligible
action, dispatches the owning lane, records evidence, and repeats the
decision-execute-verify loop. The user does not need to manually run
$arch, $sage, $flow, $vet, $vibe, or $build.
Loading $maestro as an in-session skill alone does not call Jev. Report
provider use: not verified unless a successful local Maestro receipt records
the provider decision.
$maestro
-> selects the next eligible lane
-> executes the lane
-> verifies the result
-> records evidence
-> continues until complete or blocked
Inspect the current state at any time:
ma status
ma doctor
Maestro stops for missing credentials, destructive operations, deployments,
or explicit approval gates. Interrupted work resumes from the persisted .ma/
state.
| ✅ Recommended | 🧰 All available installation commands |
|---|---|
Use the signed jsDelivr installer on macOS, Linux, WSL, or Git Bash.curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.shcurl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256sed 's#scripts/install.sh#install.sh#' install.sh.sha256 | sha256sum -c -sh install.shma --madmax --high$maestro I want to build: [your project idea] | npm globalnpm i -g @openai/codex@latest @jstn-sdk/ma@latestMeta-Architect only npm i -g @jstn-sdk/ma@latestWindows PowerShell npm i -g @openai/codex@latest @jstn-sdk/ma@latestDebian / Ubuntu sudo apt install ./meta-architect_<version>_all.debArch Linux sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xzFedora / openSUSE sudo dnf install ./meta-architect-<version>-1.noarch.rpm |
Copy and paste this prompt into your AI coding agent:
Install Meta-Architect for this project.
1. Detect the current AI host and its native project configuration surface.
2. Install or update `@jstn-sdk/ma@latest` using the host's supported package manager.
3. Set `MA_AGENT` to the detected host ID when a host-specific surface is available.
4. Run `ma setup` and accept the detected project scope and targets.
5. Verify the generated `.ma/` state and native host artifacts.
6. Report the installed version, selected host, generated files, and any unsupported capabilities.
Do not overwrite user-owned files, modify unrelated configuration, or claim a host is supported without verification.
More install options: docs/getting-started.md
Security reporting and OpenSSF evidence: SECURITY.md and the OpenSSF Best Practices evidence matrix.
Uninstall Meta-Architect: npm uninstall -g @jstn-sdk/ma
Uninstall Meta-Architect and Codex: npm uninstall -g @jstn-sdk/ma @openai/codex
Install Meta-Architect once, then select the host surface before launch. The
pre-launch step detects installed hosts and writes the selected scope and
targets to .ma/prelaunch.json.
# Codex (reference host)
npm i -g @openai/codex@latest @jstn-sdk/ma@latest
ma --madmax --high
# Claude Code
MA_AGENT=claude-code npm i -g @jstn-sdk/ma@latest
MA_AGENT=claude-code ma --madmax --high
# Cursor
MA_AGENT=cursor npm i -g @jstn-sdk/ma@latest
MA_AGENT=cursor ma --madmax --high
# Any registered host surface
MA_AGENT=<host-id> npm i -g @jstn-sdk/ma@latest
MA_AGENT=<host-id> ma --madmax --high
MA installs or reuses the native skill/configuration surface for the selected host and keeps the canonical workflow unchanged. See the host compatibility evidence for supported surfaces.
The repository includes a hosted Claude Code marketplace for the existing
plugins/meta-architect bundle:
/plugin marketplace add JustineDevs/meta-architect
/plugin install meta-architect@meta-architect
ChatGPT Desktop cannot resolve a direct link to a local Codex skill such as
[$maestro](/home/justine/.codex/skills/maestro/SKILL.md). Install the
portable plugin through the repository marketplace instead:
npm run plugin:validate
codex plugin marketplace add ./
Restart ChatGPT Desktop, open Plugins, select the local Meta-Architect
marketplace, and install Meta-Architect. Use the installed plugin or its
available @ mention with a normal request such as:
Use Meta-Architect Maestro to choose the next safe workflow step for this task.
The Desktop plugin packages the skills only. Live local ma and Jev
execution still requires the local Codex/Node runtime; hosted ChatGPT Work
execution requires a separately deployed authenticated MCP app. See the
ChatGPT integration guide.
The plugin and feature inventory is maintained in the support bundle manifest and skills manifest, with verification in the coverage documentation.
Your agent writes code faster than you review it. Studies and dev surveys keep finding the same failures:
Meta-Architect blocks each one:
$arch writes the blueprint and the trade-offs.$sage grades every dependency claim VERIFIED, PARTIAL, or MISSING against upstream repos through GitMCP.An open-source workflow governor for AI coding agents. You install it as a skill package in your agent host. It adds six gated lanes plus $maestro, a bounded manager which routes your work through them. It doesn't replace your agent, runtime, or model. It governs what they produce.
| Fact | Value |
|---|---|
| Type | Skill and plugin package for AI coding agent hosts |
| Reference host | Codex (full support) |
| Compatibility scope | Codex, OpenCode, Gemini CLI, Amp, Claude Code, Goose, Hermes, Pi, Cursor, Windsurf, Cline, Continue, Roo, Kiro CLI, Junie, GitHub Copilot, and Antigravity (coverage evidence) |
| Runtime | Node.js 20+ |
| Install | npm i -g @jstn-sdk/ma |
| Evidence sources | GitMCP / MCP endpoints |
| License | MIT |
State your intent once. $maestro picks the next safe step and stops when something fails.
$maestro I want to build: a multi-tenant analytics API for logistics customers
Meta-Architect Status
=====================
Idea: CLEAR
Architecture: APPROVED
Evidence: VERIFIED
Logic: GREEN
Security: GREEN
Experience: GREEN
Build: LOCKED
Build stays LOCKED until every upstream gate passes. Red stays red.
| Lane | Question it answers | Gate |
|---|---|---|
$arch | What are you building, and why this shape? | architecture_status |
$sage | Do your stack choices trace to real upstream evidence? | evidence_status |
$flow | Do the logic and state transitions hold? | logic_status |
$vet | Does it survive security and dependency review? | security_status |
$vibe | Will developers and users tolerate it? | experience_status |
$build | What's the narrowest safe thing to build now? | build_status |
Four helpers support the lanes without moving gates: $align, $diagnose, $tdd, $cleanup.
Spec-driven tools structure what your agent writes. Meta-Architect enforces what your agent proves.
| Spec Kit | BMAD | Agent OS | Meta-Architect | |
|---|---|---|---|---|
| Structured workflow | Yes | Yes | Yes | Yes |
| Gates which block | No | No | No | Yes |
| External evidence verification | No | No | No | Yes, GitMCP-graded |
| Learning loop with promotion rules | No | No | No | Yes |
| Multi-host | Yes | Yes | Yes | Codex today, expanding |
Already using a spec tool? Keep it. Their specs become inputs. MA's gates verify the execution.
triagedev. main is protected and release-facing.npm test before you submit. Follow CONTRIBUTING.md.See the Code of Conduct and security policy for participation and private vulnerability reporting.
MIT. Built by @JustineDevs. Shaped by ideas from the oh-my-codex ecosystem.
Found a bad claim before it shipped? Star the repo. It helps other developers find it.
FAQs
Codex-native skills system for architecture, evidence, review, and gated build guidance.
The npm package @jstn-sdk/ma receives a total of 521 weekly downloads. As such, @jstn-sdk/ma popularity was classified as not popular.
We found that @jstn-sdk/ma demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.