Production-grade skills package and CLI for programmatic architecture, evidence-backed OSS selection, gate-driven review, and release-minded build unlocking.

npm version GitHub release

[!IMPORTANT] Meta-Architect v0.1.0 is a production-grade skills line. It is not a lightweight demo branch. From v0.1.0 onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.

Overview

Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.

It adds:

an architecture-first lane before implementation
evidence-backed OSS selection through GitMCP-connected sources
explicit logic, security, and DX/UX review gates
installable skills and a reproducible package surface

[!NOTE] Meta-Architect does not replace your coding runtime. It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.

npm package	`meta-architect`
CLI commands	`ma`, `meta-architect`
Runtime	Node.js `>=20`, npm `@10`
Release line	`v0.1.0`
License	MIT

Prerequisites

Node.js >=20
npm >=10
Git
an MCP-capable coding runtime
OpenAI Codex CLI for the recommended package-first path
macOS, Linux, or WSL2 recommended

[!TIP] The most reliable default environment is a Unix-like shell with Git, Node.js, and an MCP-capable runtime already configured.

Recommended Default Flow

Meta-Architect is intended to be consumed as an installed package, not primarily as a git clone.

Default operator path:

npm install -g @openai/codex @jstn-sdk/meta-architect@latest
ma setup
ma

What this assumes:

Codex CLI is installed globally
Meta-Architect is installed globally as a package
ma setup is run inside the repository you want Meta-Architect to scaffold
ma starts the local Codex session after scaffolding is in place

[!IMPORTANT] The recommended default flow is package-first. The git clone path is for contributors and maintainers, not the main user-facing install story.

Repository Branch Strategy

Meta-Architect’s repository workflow follows a stricter release posture focused on gated promotion:

main = release-facing protected branch
development = normal integration branch
feature/* = short-lived contribution branches
contributors branch from development
normal PRs target development
only curated promotions move development into main

[!CAUTION] main is intended to be protected and exceptional. Maintainers should stop bypass-pushing to main except for genuine emergency or admin recovery cases.

Setup

Package setup

Install the consumer package directly:

npm install -g @openai/codex @jstn-sdk/meta-architect@latest

This gives you:

codex
ma
meta-architect
the canonical Meta-Architect runtime entrypoints

Contributor setup: source checkout

Use this path only if you want to work on Meta-Architect itself.

git clone https://github.com/JustineDevs/meta-architect.git
cd meta-architect
npm install
npm link

npm link makes ma and meta-architect available from the local checkout.

Quick Start

1. Initialize the project

Initialize the repository you want Meta-Architect to govern:

ma setup

Then start the local Codex session through ma:

ma

Expected output:

meta-architect setup
====================
ready: .codex/agents
ready: .codex/prompts
ready: .ma/skills
ready: .ma/evidence
ready: mcp
ready: docs
ready: docs/qa
ready: sprint

ma with no arguments launches the local Codex CLI. Legacy compatibility flags such as ma --madmax --high are still accepted, but they are no longer the recommended path.

2. Configure GitMCP sources

Add real repository-backed endpoints in mcp/servers.json.

Example:

{
  "category": "meta-list",
  "repo": "sindresorhus/awesome",
  "endpoint": "https://gitmcp.io/sindresorhus/awesome"
}

Recommended starter endpoints:

https://gitmcp.io/sindresorhus/awesome
https://gitmcp.io/dzharii/awesome-typescript
https://gitmcp.io/sbilly/awesome-security

[!IMPORTANT] Verified release evidence must come from repository-form GitMCP endpoints such as https://gitmcp.io/{owner}/{repo}. A generic documentation endpoint such as https://gitmcp.io/docs does not count as VERIFIED evidence for build unlocking.

3. Record the idea

ma idea "Build a real-time collaborative whiteboard for product teams"

Expected effect:

appends an idea entry to .ma/decisions.json
sets idea_status = CLEAR

4. Run the gated workflow

ma run '$arch'
ma run '$sage'
ma run '$flow'
ma run '$vet'
ma run '$vibe'
ma status
ma run '$build'

Expected status before $build:

Meta-Architect Status
=====================
Idea: CLEAR
Architecture: APPROVED
Evidence: VERIFIED
Logic: GREEN
Security: GREEN
Experience: GREEN
Build: LOCKED
Next allowed triggers:
$build

Expected build output:

Build gate is green.
Suggested branches:
- feature/ui
- feature/api
Optional worktree commands:
git worktree add ../ui feature/ui
git worktree add ../api feature/api

Core Maintainers

Role	Name	GitHub
Creator / Maintainer	JustineDevs	@JustineDevs

Core Triggers

Trigger	Purpose	Main output	Gate effect
`$arch`	Produce the first-pass architecture blueprint	decision entry	`architecture_status = APPROVED`
`$sage`	Ground major choices in configured GitMCP evidence	evidence records	`evidence_status = VERIFIED
`$flow`	Review baseline logic and state transitions	logic review entry	`logic_status = GREEN
`$vet`	Run baseline security and dependency review	audit and CVE records	`security_status = GREEN
`$vibe`	Review developer and user experience implications	DX/UX outcome record	`experience_status = GREEN
`$build`	Unlock bounded build planning	build-ready decision	`build_status = READY`

Gate Model

Meta-Architect is intentionally fail-closed.

Status	Meaning
`CLEAR`	enough input exists to proceed
`APPROVED`	the architecture lane produced an acceptable first-pass blueprint
`VERIFIED`	live evidence was grounded through approved GitMCP sources
`PARTIAL`	evidence is configured but live proof is incomplete or unavailable
`GREEN`	the current baseline review passed
`RED`	the lane is blocked or failed
`WAIVED`	the lane was intentionally waived with a recorded reason
`LOCKED`	downstream work is not allowed yet
`READY`	the next gated step is allowed

[!CAUTION] $build must stay locked until the upstream release state in .ma/release.json satisfies the gate contract. Meta-Architect is designed to stop on blockers rather than silently continue.

Release and Packaging

Meta-Architect has two related but different distribution surfaces.

Surface	Purpose	Produced by
npm package	public package containing CLI, docs, scripts, and canonical skills	`npm publish` or `npm pack`
skills bundle	narrower tarball containing `skills/` only	`npm run skills:pack`

Required packaging commands:

npm run skills:manifest
npm run skills:validate
npm run skills:pack
npm run skills:install -- --path ./dist/installed-skills
npm run pack:inspect

Pre-publish rules:

skills/index.json must be current
npm run skills:validate must pass
dist/meta-architect-skills.tgz must exist
npm pack --dry-run must show only intended public files
docs must match real CLI and release behavior

[!CAUTION] Do not claim npm, GitHub release, or any other publish channel until that channel has actually succeeded. Release documentation must match reality, not intent.

Package Surface

Included	`bin/`, `skills/`, `docs/`, `scripts/`, `index.js`, `README.md`, `LICENSE`
Excluded	`.ma/` runtime state, logs, caches, and temp install outputs

Repository Structure

Path	Responsibility
`.codex/`	runtime prompts, hooks, and repo guidance
`skills/`	canonical public skill contracts
`plugins/meta-architect/`	plugin-oriented distribution surface
`docs/`	installation, publishing, and release documentation
`missions/`	reproducible scenario-driven workflows
`mcp/`	GitMCP endpoint and collection configuration
`scripts/`	validation, packing, and install helpers
`sprint/`	human-readable phased workflow documents

Documentation

Surface	Purpose
Getting Started	end-to-end local onboarding
Skills Reference	trigger-by-trigger contract guide
Skills Publishing	source-to-package pipeline
MCP Setup	evidence endpoint policy
Plugin README	plugin distribution surface
Collaborative Whiteboard Mission	concrete scenario walkthrough
Release Spec	release and gate policy
Release Readiness	QA evidence for the `v0.1.0` line

Release Hygiene

[!WARNING] Runtime .ma logs, state, tmp, and cache files must not be shipped. Public docs must match actual package behavior. Publish statements must match reality. Skill contracts must stay aligned across canonical and plugin-facing copies.