DEV Community

Cover image for Meta-Architect - Quality gates and evidence verification for AI coding agents
JustineDevs
JustineDevs

Posted on

Meta-Architect - Quality gates and evidence verification for AI coding agents

#ai #programming #opensource #productivity

Overview

Meta-Architect is an open-source workflow layer for AI coding agents.

It does not write your application for you.

It controls how your agent moves from an idea to build-ready work.

The system treats planning, evidence, logic, security, experience, and implementation as separate concerns.

Each concern has a gate.

A failed gate blocks the next stage.

The Problem

AI coding agents produce fast output.

They also produce unsupported claims.

Common examples:

  • An agent recommends a package without checking the upstream repository.
  • An agent creates an architecture plan without recording trade-offs.
  • An agent says tests passed without fresh execution evidence.
  • An agent marks a feature as complete while security review never happened.
  • An agent treats private notes as proof.

These failures share one issue.

The workflow lacks enforced authority boundaries.

An agent writes the plan, validates the plan, and declares the plan complete. Nothing separates those actions.

Meta-Architect separates them.

What Meta-Architect Is

Meta-Architect is a workflow governor.

You install it as a skills and plugin package in an AI-agent host.

You describe a project goal.

$maestro reads the current state and routes work through gated lanes.

Flow 1

The system does not treat every agent response as approval.

Each lane owns one decision type.

The Core Model

Meta-Architect uses a staged workflow.

Flow 2

The workflow state looks like this:

Idea:          CLEAR
Architecture:  APPROVED
Evidence:      VERIFIED
Logic:         GREEN
Security:      GREEN
Experience:    GREEN
Build:         LOCKED
Enter fullscreen mode Exit fullscreen mode

Build unlocks only when every required upstream state passes.

If security_status = RED
Then build_status = LOCKED

If evidence_status = MISSING
Then build_status = LOCKED

If all required gates pass
Then build_status = READY
Enter fullscreen mode Exit fullscreen mode

This creates a fail-closed workflow.

The system preserves missing proof.

It does not replace missing proof with a confident summary.

The 11 Skills

Meta-Architect exposes 11 public skills.

Flow 3

The design separates coordination, approval, and support.

                $maestro
                    |
      +-------------+-------------+
      |                           |
Gated approval lanes         Helper skills
      |                           |
Change release state        Produce receipts
      |                           |
Can unlock next gate        Cannot unlock gates
Enter fullscreen mode Exit fullscreen mode

$maestro: Workflow Coordination

$maestro is the entry point.

You provide a project goal.

$maestro I want to build a multi-tenant analytics API for logistics customers
Enter fullscreen mode Exit fullscreen mode

It checks project state.

It selects the next safe lane.

It reports blockers.

It does not bypass gates.

Example:

Current state:
- Architecture: approved
- Evidence: partial
- Logic: pending
- Security: pending
- Build: locked

Next safe action:
$sage

Reason:
The project has an architecture decision.
The stack claims still need verified upstream evidence.
Enter fullscreen mode Exit fullscreen mode

This removes a common AI-agent failure.

You no longer need to remember which review step comes next.

The Six Gated Lanes

$arch: Architecture Gate

$arch defines what you want to build and why.

It records:

  • Problem framing
  • System components
  • Data model
  • Deployment target
  • Constraints
  • Risks
  • Trade-offs
  • Architecture decision

Output:

architecture_status = APPROVED
Enter fullscreen mode Exit fullscreen mode

Example decision record:

Decision:
Use a modular monolith for the first release.

Reason:
The team needs one deployment unit.
The product needs clear domain boundaries.
Microservices would add operational overhead before demand exists.

Trade-off:
Independent service scaling comes later.
Enter fullscreen mode Exit fullscreen mode

$arch does not prove a dependency exists.

That belongs to $sage.

$sage: Evidence Gate

$sage verifies major technical claims.

It uses GitMCP and MCP sources.

It separates discovery from proof.

Discovery source
      |
      v
Candidate package or pattern
      |
      v
Exact upstream repository mapping
      |
      v
Official documentation verification
      |
      v
Evidence grade
Enter fullscreen mode Exit fullscreen mode

Evidence grades:

VERIFIED
Exact upstream mapping exists.
Primary sources confirm the claim.

PARTIAL
A candidate exists.
The required proof is incomplete.

MISSING
No trusted source supports the claim.
Enter fullscreen mode Exit fullscreen mode

Example:

Claim:
The selected SDK supports server-side token refresh.

Result:
PARTIAL

Reason:
The repository exists.
The official documentation does not confirm server-side refresh behavior.
Enter fullscreen mode Exit fullscreen mode

The build stays locked until critical evidence reaches an acceptable state.

$flow: Logic Gate

$flow reviews behavior and state transitions.

It looks for problems such as:

  • Missing error states
  • Invalid transition paths
  • Retry loops without exit conditions
  • Race conditions
  • Inconsistent ownership rules
  • Unhandled failure outcomes

Example state flow:

Order created
      |
      v
Payment pending
      |
      +------------------+
      |                  |
      v                  v
Payment paid        Payment failed
      |                  |
      v                  v
Fulfillment queued  Order cancelled
Enter fullscreen mode Exit fullscreen mode

$flow asks whether every state has a valid next state.

Output:

logic_status = GREEN
Enter fullscreen mode Exit fullscreen mode

or:

logic_status = RED
Enter fullscreen mode Exit fullscreen mode

$vet: Security Gate

$vet reviews security and trust boundaries.

It covers:

  • Identity and session boundaries
  • Authorization and tenancy
  • Secret handling
  • Dependency risk
  • Supply-chain exposure
  • Input validation
  • Output exposure
  • Abuse cases
  • Operational failure modes

Example:

Finding:
Tenant ID comes from a request body field.

Risk:
A user could supply another tenant ID.

Required fix:
Derive tenant identity from the authenticated session.
Enter fullscreen mode Exit fullscreen mode

Higher-risk changes can trigger an adversarial hardening pass.

The result returns structured findings.

It does not silently change gate state.

$vibe: Experience Gate

$vibe reviews developer and user experience.

It checks:

  • Setup friction
  • Naming clarity
  • Error messages
  • Documentation flow
  • User expectations
  • Developer workflow cost
  • Onboarding gaps

Example:

Problem:
The install guide requires users to know MCP configuration before first use.

Outcome:
RED

Required change:
Provide a bootstrap path with starter configuration and explicit status output.
Enter fullscreen mode Exit fullscreen mode

Output:

experience_status = GREEN
Enter fullscreen mode Exit fullscreen mode

or:

experience_status = RED
Enter fullscreen mode Exit fullscreen mode

$build: Build Readiness Gate

$build does not mean “generate all the code.”

It identifies the narrowest safe implementation slice.

It checks upstream gates first.

Architecture approved?
Evidence verified?
Logic green?
Security green?
Experience green or waived?
Enter fullscreen mode Exit fullscreen mode

If required conditions fail:

build_status = LOCKED
Enter fullscreen mode Exit fullscreen mode

If required conditions pass:

build_status = READY
Enter fullscreen mode Exit fullscreen mode

Then it creates a bounded implementation plan.

.ma/plans/build.md
Enter fullscreen mode Exit fullscreen mode

Helper Skills Do Not Approve Work

Meta-Architect includes four helper skills.

$align
$diagnose
$tdd
$cleanup
Enter fullscreen mode Exit fullscreen mode

They support the workflow.

They do not own release-state transitions.

$align
- Tightens terminology
- Reduces ambiguity
- Improves scope clarity

$diagnose
- Breaks a blocker into hypotheses
- Suggests next probes
- Helps isolate failures

$tdd
- Builds regression-first or test-first scaffolding
- Locks expected behavior

$cleanup
- Removes unnecessary output
- Simplifies documentation
- Preserves behavior while reducing noise
Enter fullscreen mode Exit fullscreen mode

The boundary matters.

A useful helper result is not an approval.

Helper receipt exists
        |
        v
Gate remains unchanged
        |
        v
Owning lane reviews the result
        |
        v
Only the owning lane changes status
Enter fullscreen mode Exit fullscreen mode

Context Is Not Evidence

Meta-Architect supports Obsidian vault integration.

Your notes become vault_context.

They help the agent understand your project.

They do not automatically prove a claim.

Obsidian note
      |
      v
vault_context
      |
      v
Planning input
      |
      v
No release authority
Enter fullscreen mode Exit fullscreen mode

For a note to support build evidence:

Vault note
      |
      v
Owning gate reviews the claim
      |
      v
Primary source attached
      |
      v
Evidence record created
      |
      v
Claim receives authority
Enter fullscreen mode Exit fullscreen mode

This avoids a common failure mode.

A polished internal note does not become production truth because it exists in Markdown.

Learning Loop

Meta-Architect records learnings.

It does not let every observation change future behavior.

A learning begins as a candidate.

Flow 4

A promoted learning needs:

  • Source
  • Evidence
  • Authority
  • Next verification path

This keeps memory from becoming an unreviewed policy engine.

Environment Awareness

Meta-Architect inspects the workspace for available capabilities.

It detects:

  • Existing local skills
  • MCP configuration
  • Plugin manifests
  • Available tools
  • Workspace paths
  • Host compatibility signals

It records discovered capabilities as context.

Available capability
      |
      v
Task relevance check
      |
      v
Selected by an owning lane
      |
      v
Execution with explicit authority
Enter fullscreen mode Exit fullscreen mode

Discovery does not trigger execution.

Discovery does not become build evidence.

Universal Plugin Broker

Meta-Architect supports 55 AI-agent hosts through a hybrid compatibility model.

The broker uses two paths.

Flow 5

This design keeps the Meta-Architect workflow contract portable.

Codex serves as the reference runtime.

The broker exports compatible context and plugin surfaces for other hosts.

Security and Data Boundaries

Meta-Architect includes several systems for risk control.

MCP Policy
- Defines allowed source behavior
- Validates runtime configuration

Exposure Catalog
- Records dependency and package risks
- Produces findings for review

Redaction Gateway
- Creates provider-bound redaction receipts
- Reduces sensitive context exposure

Quorum Review Engine
- Records review confidence
- Preserves minority reports

Workspace Virtualizer
- Produces bounded verification receipts
- Avoids unsafe workspace mutation

Code Graph Rehearse
- Identifies code touchpoints
- Rehearses changes without source mutation
Enter fullscreen mode Exit fullscreen mode

Ralph Execution Core

Ralph Execution Core starts after planning passes the required gates.

It converts an approved plan into story-sized work.

Approved build plan
      |
      v
Story contract
      |
      v
Implementation slice
      |
      v
Verification
      |
      v
Completion or blocker
Enter fullscreen mode Exit fullscreen mode

Each story has a bounded outcome.

finished
blocked
failed
cancelled
askuserQuestion
Enter fullscreen mode Exit fullscreen mode

A completion claim needs fresh verification evidence.

Installation

🧩 Quick start

AI agent installation prompt

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.
Enter fullscreen mode Exit fullscreen mode

OR

Claude code Marketplace 

/plugin marketplace add JustineDevs/meta-architect
/plugin install meta-architect@meta-architect
Enter fullscreen mode Exit fullscreen mode

Install into an AI vendor host

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
Enter fullscreen mode Exit fullscreen mode

Uninstall

Uninstall Meta-Architect: npm uninstall -g @jstn-sdk/ma
Uninstall Meta-Architect and Codex: npm uninstall -g @jstn-sdk/ma @openai/codex

Who Maintains It

Meta-Architect is created and maintained by JustineDevs.

The project is open source under the MIT license.

Repository: https://github.com/JustineDevs/meta-architect
Current release: v0.14.0

When You Should Use It

Use Meta-Architect when you want:

  • Explicit architecture decisions
  • Evidence-backed stack selection
  • Logic review before implementation
  • Security review before build work
  • Clear release blockers
  • Auditable AI-agent outputs
  • Project knowledge without treating notes as proof
  • Cross-host skill distribution
  • A bounded path from planning to execution

Skip Meta-Architect when you want unrestricted code generation with no enforced review process.

The system adds process. The process is the product.

Top comments (0)