git-meta-harness

Plug-and-play multi-agent orchestration framework for greenfield and in-progress projects → production software delivery, materializable on demand from a functional specification into any agentic CLI (Claude Code, Copilot, Codex, OpenCode, Devin, Hermes Agent, Cursor).

Version: 1.14.0 · License: MIT · Status: stable · 30 releases · Validation and test case: ✅ brenonaraujo/mandai-v2

What's new in the last 4 releases (jul/2026)

Version	Type	What it does
v1.14.0	FEATURE	Adaptive Meta-Harness (BIG, 4 ADRs) — `gmh adopt` (in-progress projects, detects stack + adapts), `gmh new --spec` (creates project + TODO from spec), `gmh doctor --json` (health score 0-100, 4 dimensions), `gmh metrics` (Prometheus dashboard + Slack alerts). 4 ADRs (0026-0029). `docs/ECOSYSTEM.md` maps 4 implementations (Stanford IRIS, SuperagenticAI, Towards AI, us).
v1.13.0	FEATURE	Feature flow enforcement — `sensor 13 feature-flow` (BLOCKING) + canonical comment templates + builder reads-all-comments rule. Prevents the team-manager from skipping `domain-expert`/`solutions-architect` on `type/feature` issues. ADR-0025.
v1.12.2	HOTFIX	`hermes -p` flag order — `agentic.Invocation()` now produces `hermes -p <profile> chat -q '<prompt>'` (the `-p` is a global flag, not a `chat` subcommand flag). ADR-0024.
v1.12.1	HOTFIX	Agent config preservation — `gmh agents sync` no longer erases `model.default`, `model.provider`, `agent.reasoning_effort` from profile `config.yaml`. Fixed `struct round-trip erasure` bug. ADR-0023.

See CHANGELOG.md for the full history (30 versions).

The concept in one paragraph

git-meta-harness is a framework that materializes a reliable multi-agent team + project + pipeline from a functional specification, with zero configuration effort from the user, using GitHub Issues + PRs + Actions as the native substrate. It is called "meta" because it is the harness of harnesses: the unit it delivers is not "one configured agent" but "one orchestrated team, with process, gates, and audit trail". The user pastes a spec into an agentic CLI; the team-manager decomposes the spec into routed issues, dispatches them to specialized personas, gates the work with 13 sensors + 28 invariants, and produces a PR ready for human validation. The user does not configure anything. Full vision: docs/CONCEPT.md. Comparison with SDD/SPDD: docs/COMPARISON.md. Origin story: docs/ORIGIN.md. GitHub integration: docs/PIPELINE.md. How this fits loop engineering (the dominant 2026 pattern for AI agents): docs/LOOP.md. How to start a project (where the spec lives, spec discovery, code graph): docs/HOWTO.md.

Visual overview

The full loop — from spec to release

flowchart LR
    H[("👤 Human")]
    SPEC["📜 docs/SPEC.md<br/>(functional spec)"]
    DISCOVER["🔍 Spec discovery?<br/>(if project exists,<br/>no spec)"]
    REVERSA["🤖 5-phase pipeline<br/>(Scout→Archaeologist<br/>→Architect→Writer→Reviewer)"]
    TM["🤖 team-manager<br/>(orchestrator)"]
    EPIC["📋 Issue-mãe #1<br/>(épico)"]
    SUB["📋 Sub-issues<br/>(type/*, domain/*)"]
    GH[("🗂️ GitHub<br/>Issues + PRs + Actions")]
    P["👥 8 personas<br/>(smart routing<br/>by type/*)"]
    CG["🔎 Code graph<br/>(optional)"]
    PR["📬 Pull Request"]
    QA["🔍 QA (13 sensors)"]
    HVAL["👤 Human validation<br/>(branch protection)"]
    REL["🏷️ Release<br/>(tagged)"]

    H -->|"paste spec OR<br/>describe OR<br/>request discovery"| SPEC
    SPEC -.->|"missing?"| DISCOVER
    DISCOVER --> REVERSA
    REVERSA -->|"writes spec"| SPEC
    SPEC -->|"read + decompose"| TM
    TM -->|"create"| EPIC
    EPIC -->|"decompose"| SUB
    SUB --> GH
    GH -->|"smart routing"| P
    P -.->|"optional"| CG
    P -->|"code + tests"| PR
    PR -->|"sensors"| QA
    QA -->|"9 green"| HVAL
    HVAL -->|"✅"| TM
    TM -->|"merge + tag"| REL
    REL --> GH

    classDef user fill:#fef3c7,stroke:#f59e0b,color:#92400e
    classDef tm fill:#fef3c7,stroke:#f59e0b,color:#92400e
    classDef data fill:#f3e8ff,stroke:#9333ea,color:#581c87
    classDef tools fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    class H,SPEC,HVAL user
    class TM,EPIC,SUB,REL tm
    class DISCOVER,REVERSA,P,PR,QA tools
    class CG data

Reading the diagram: the user provides a spec (4 paths in docs/HOWTO.md). The team-manager creates the issue-mãe (#1) itself from the spec (not the user), decomposes it into sub-issues, and dispatches each sub-issue to the right persona chain via smart routing. The personas ship code, optionally aided by a code graph for large codebases. QA runs 13 sensors on the PR. The human validates (enforced by branch protection). The release is tagged. Zero configuration by the human — they only provide the spec and validate.

The team — 8 personas + smart routing

flowchart TB
    TM["🤖 team-manager<br/>= orchestrator<br/>(always)"]

    subgraph FEAT["type/feature (full chain)"]
        F1[domain-expert-&lt;x&gt;] --> F2[solutions-architect]
        F2 --> F3[builder] --> F4[qa]
    end

    subgraph TECH["type/technical (no domain-expert)"]
        T1[solutions-architect] --> T2[builder] --> T3[qa]
    end

    subgraph INFRA["type/infra (no domain-expert, no builder)"]
        I1[solutions-architect] --> I2[devops-engineer] --> I3[qa]
    end

    subgraph BUG["type/bug (no domain-expert)"]
        B1[solutions-architect] --> B2[builder] --> B3[qa]
    end

    TM --> FEAT
    TM --> TECH
    TM --> INFRA
    TM --> BUG

    classDef always fill:#fef3c7,stroke:#f59e0b,color:#92400e
    class TM always

Reading the diagram: team-manager is always present. The type/* label on each issue picks one of the four paths. The personas inside each path run in sequence, never all at once.

GitHub as native substrate

flowchart LR
    subgraph META["git-meta-harness framework"]
        SPEC["📜 Functional spec"]
        SEED["🌱 Seed prompt"]
    end

    subgraph PROJ["Your project repo"]
        ISSUES["📋 Issues<br/>(type/*, domain/*)"]
        PRS["🔀 Pull Requests<br/>(1 issue = 1 PR)"]
        CI["⚙️ GitHub Actions<br/>(path-filtered CI)"]
        RELS["🏷️ Releases<br/>(tagged)"]
    end

    subgraph RUNTIMES["Agentic runtime (portable)"]
        H[Hermes profiles]
        C[Claude Code agents]
        X[Codex / OpenCode]
        CP[Copilot / Cursor]
    end

    SPEC --> SEED
    SEED -->|"materialize"| RUNTIMES
    RUNTIMES -->|"create + route"| ISSUES
    ISSUES -->|"produce"| PRS
    PRS -->|"gate by"| CI
    PRS -->|"human validates"| PRS
    CI -->|"on merge"| RELS

Reading the diagram: the spec is the input; the seed materializes the runtimes; the runtimes drive GitHub Issues; Issues produce PRs; PRs are gated by modular CI; merges become tagged Releases. No new platform is introduced.

What is this

git-meta-harness is a framework, not a product. It defines a complete orchestration layer for a team of AI agents that deliver software projects from a functional spec to a production release, with:

8 personas — team-manager, domain-expert (always specialized), solutions-architect, backend-engineer, frontend-engineer, quality-assurance, devops-engineer
13 sensors (00-13) — automated checks for static analysis, vulnerability, unit, contract, image scan, smoke, load, 12-factor, i18n, verify-after-build, decomposition safety, scope discipline, frontend polish, feature flow
5 stack files — Go 1.26.5 + Gin + GORM + PostgreSQL backend; Nuxt 4.5 + Pinia frontend; Prometheus + slog observability; distroless Docker; KISS/DRY code style
7 workflow docs — issue-lifecycle, branching, PR, snapshot-deploy, release, orchestration, loop-engineering
16+ templates — Dockerfile, docker-compose, CI workflow, .golangci.yml, .env.example, issue templates, PR description, 3 locales, 3 Nuxt UI templates (landing/dashboard/auth-form), 2 canonical comment templates (domain-expert + solutions-architect)
17 skills — github-pr-workflow, github-issues, github-code-review, tdd-go, openapi-spec-first, twelve-factor, i18n, code-graph, nuxt-ui-patterns, ux-design-best-practices, domain-refinement, pre-implementation-design, solution-scoping, frontend-public-skills, tailwind-only-patterns, visual-polish
28 invariants in AGENTS.md §8 — non-negotiable contracts
29 ADRs in contrib/design-decisions.md — every architectural decision documented
9+ scripts in harness/scripts/ — smoke-test, check-stack-versions, check-i18n, check-parallel-builders, check-scope-discipline, check-frontend-polish, check-feature-flow, plus bin/safe-commit-harness-sync.sh and scripts/visual/ (Playwright + Python companions)
gmh CLI (v1.13.0) — single static Go binary (gmh install/sync/update/doctor/agents)

It's designed to be dropped into any greenfield project and produce a consistent, auditable, CI-gated development loop with a real team structure (not a "single agent does everything" anti-pattern).

Why use it

Without meta-harness	With meta-harness
One agent does everything → drift	8 personas with explicit roles & interactions
No domain knowledge → generic AI	Specialized `domain-expert-<domain>` per project
No tests, no CI gates	13 sensors, 28 invariants, smoke test pre-flight
Stack drift (Go 1.22 vs 1.26)	`versions.md` + `check-stack-versions.sh`
CI runs everything every time	`dorny/paths-filter` → 5-10x faster PRs
Vendor lock-in (Claude Code only)	Multi-tool via `AGENTS.md` (Claude/Copilot/Codex/OpenCode/Devin/Hermes/Cursor)
No audit trail of decisions	ADRs + 28 invariants + per-issue briefings
No i18n → debt later	i18n first-class (en, pt-BR, es)
Team-manager skips domain/architect	Sensor 13 `feature-flow` BLOCKS in-progress without refinement+DoD
Builder receives only 1-paragraph desc	Builder reads ALL comments (refinement + DoD) before coding
UI shipped with hex colors / BEM	Sensor 12 `frontend-polish` BLOCKS (10 anti-patterns)
Profile config silently wiped on sync	gmh agents sync preserves model/agent (struct round-trip fix)
Team-manager invocations fail silently	agentic.Invocation validated live against `hermes --help`

Quickstart

1. Use as the seed for a new project

The framework is materialized into a target project via the meta-harness-seed.md prompt. Copy that file's content into your agentic CLI of choice:

# Claude Code
cat harness/seed/meta-harness-seed.md | claude

# Hermes Agent
hermes -p team-manager

# Generic
# Paste into any chat-based agent and let it install the harness
# into the current project.

The team-manager will:

Read the spec (your functional requirements).
Detect the domain (banking, retail, logistics, …).
Create specialized domain-expert-<domain> if needed.
Decompose the spec into issues with the right type/* and domain/* labels.
Dispatch to personas in parallel with explicit briefings.
Validate each sub-issue, run sensors, gate the PR.
Block the merge until you, the human, validate.

2. Use the `gmh` CLI (recommended for v1.6.0+)

The fastest way to adopt the meta-harness is the gmh CLI — a single static Go binary, installed with one command:

# Linux / macOS
curl -sSL https://raw.githubusercontent.com/brenonaraujo/git-meta-harness/main/cli/installer/install.sh | bash

# Windows PowerShell
iwr -useb https://raw.githubusercontent.com/brenonaraujo/git-meta-harness/main/cli/installer/install.ps1 | iex

Then in your project:

cd my-project

gmh install     # Install meta-harness
gmh doctor      # Health check (must be ✅)
gmh sync        # Update harness/ to latest version

See docs/CLI.md for the full manual.

3. Copy the harness manually (legacy)

# From your project root
git clone https://github.com/brenonaraujo/git-meta-harness.git /tmp/mh
cp -R /tmp/mh/harness ./harness
cp /tmp/mh/.github-workflows-ci.yml ./.github/workflows/ci.yml
cp /tmp/mh/.golangci.yml ./.golangci.yml
# ... adapt as needed

4. Verify it's healthy

./harness/scripts/smoke-test.sh .
./harness/scripts/check-stack-versions.sh --check-latest
# Both must report ✅ OK.

5. Publish a release (v1.6.0+)

After merging a feature branch:

git checkout main
git pull
git tag v0.1.0
git push origin v0.1.0
# CI builds backend + frontend (multi-arch: amd64 + arm64)
# Trivy scans, cosign signs, SBOMs generated
# Images pushed to ghcr.io/<owner>/<repo>/<service>:0.1.0
# GitHub Release auto-created with notes

# Pull and run anywhere
docker pull ghcr.io/<owner>/<repo>/backend:0.1.0

See docs/DEPLOY.md for ECS, EKS, Docker Swarm, and local deployment.

Architecture overview

The team (8 personas) and the 13 sensors

flowchart TB
    TM["🤖 team-manager<br/><i>orchestrator</i>"]

    subgraph PERSONAS["8 personas"]
        DE["🎯 domain-expert-&lt;x&gt;<br/><i>specialized per project</i>"]
        SA["📐 solutions-architect<br/><i>DoD, 12-factor, ADRs</i>"]
        BE["⚙️ backend-engineer<br/><i>Go · tests · local pre-flight</i>"]
        FE["🎨 frontend-engineer<br/><i>Nuxt · tests · local pre-flight</i>"]
        QA["🔍 quality-assurance<br/><i>runs the 13 sensors</i>"]
        DO["🚀 devops-engineer<br/><i>CI/CD · Docker · observability</i>"]
    end

    subgraph SENSORS["13 sensors (automated gates, v1.14.0+)"]
        S1["00 lint"]
        S2["01 vuln"]
        S3["02 unit"]
        S4["03 contract"]
        S5["04 image"]
        S6["05 smoke"]
        S7["06 load"]
        S8["07 12-factor"]
        S9["08 i18n"]
        S10["09 verify"]
        S11["10 decomposition"]
        S12["11 scope"]
        S13["12 polish"]
        S14["13 feature-flow"]
    end

    TM --> PERSONAS
    QA --> SENSORS
    TM -->|"smart routing by type/*"| PERSONAS

    classDef orchestrator fill:#fef3c7,stroke:#f59e0b,color:#92400e
    classDef persona fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef sensor fill:#f3e8ff,stroke:#9333ea,color:#581c87
    class TM orchestrator
    class DE,SA,BE,FE,QA,DO persona
    class S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,S11,S12,S13,S14 sensor

Reading the diagram: team-manager is the orchestrator. The 8 personas do the work. The QA persona runs the 13 sensors as automated gates. Smart routing (shown above in "The team" section) decides which personas run for which type/* issue.

Sensors (when each runs, what happens on fail)

flowchart LR
    subgraph S["Sensors (00-13)"]
        S00["00<br/>lint"]
        S01["01<br/>vuln"]
        S02["02<br/>unit"]
        S03["03<br/>contract"]
        S04["04<br/>image"]
        S05["05<br/>smoke"]
        S06["06<br/>load"]
        S07["07<br/>12-factor"]
        S08["08<br/>i18n"]
        S09["09<br/>verify"]
        S10["10<br/>decomp"]
        S11["11<br/>scope"]
        S12["12<br/>polish"]
        S13["13<br/>flow"]
    end

    S00 -->|"fails → blocks merge"| MERGE["❌ blocks merge"]
    S01 -->|"HIGH/CRITICAL → blocks merge<br/>(waiver possible)"| MERGE
    S02 -->|"< 80% coverage<br/>or test fail → blocks merge"| MERGE
    S03 -->|"OpenAPI diff breaks<br/>→ blocks merge"| MERGE
    S04 -->|"CRITICAL vuln<br/>→ blocks deploy"| MERGE
    S05 -->|"returns to builder<br/>with log"| MERGE
    S06 -->|"reports; blocks release"| MERGE
    S07 -->|"any factor missing<br/>→ blocks merge"| MERGE
    S08 -->|"i18n parity < 100%<br/>→ blocks merge"| MERGE
    S09 -->|"builder reports verde<br/>but team-manager re-runs<br/>→ block if mismatch"| MERGE
    S10 -->|"2+ builders in parallel<br/>without path-scope disjoint<br/>→ blocks"| MERGE
    S11 -->|"non-blocking<br/>(recommends shorten)"| WARN["⚠ recommends"]
    S12 -->|"hardcoded colors / BEM /<br/>emojis / a11y → blocks"| MERGE
    S13 -->|"type/feature without<br/>refined+ready+DoD<br/>→ blocks in-progress"| MERGE

    classDef blocking fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef warn fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef sensor fill:#f3e8ff,stroke:#9333ea,color:#581c87
    class MERGE blocking
    class WARN warn
    class S00,S01,S02,S03,S04,S05,S06,S07,S08,S09,S10,S11,S12,S13 sensor

Reading the diagram: every sensor has a clear fail action. 8 of the 9 block the merge; sensor 06 (load) blocks the release but not the merge. Sensor 04 (image) blocks the deploy.

CI workflow (modular with path filters)

flowchart TB
    PR[("📥 Pull Request<br/>or push to main")]
    CHANGES["🔍 changes<br/><i>dorny/paths-filter</i><br/>detects: backend, frontend,<br/>infra, docs, workflow, contracts"]
    TWELVE["🛡️ 12-factor<br/><i>always runs (security gate)</i>"]
    SUMMARY["📊 summary<br/><i>always runs (status report)</i>"]

    subgraph BE["Backend jobs (if backend changed)"]
        BEL["backend-lint"]
        BET["backend-test"]
        BEV["backend-vuln"]
        BEC["backend-contract"]
    end

    subgraph FE["Frontend jobs (if frontend changed)"]
        FEL["frontend-lint"]
        FET["frontend-test"]
        FEV["frontend-vuln"]
    end

    subgraph BUILD["Build + scan (if backend or frontend or infra changed)"]
        BB["build-backend<br/><i>cache scope=backend</i>"]
        FB["build-frontend<br/><i>cache scope=frontend</i>"]
    end

    I18N["🌐 i18n<br/><i>if backend or frontend or workflow changed</i>"]

    PR --> CHANGES
    CHANGES --> TWELVE
    CHANGES --> BE
    CHANGES --> FE
    CHANGES --> I18N
    CHANGES --> BUILD
    TWELVE --> SUMMARY
    BE --> SUMMARY
    FE --> SUMMARY
    I18N --> SUMMARY
    BUILD --> SUMMARY

    classDef gate fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef jobs fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef build fill:#fef3c7,stroke:#f59e0b,color:#92400e
    class TWELVE,SUMMARY gate
    class CHANGES,BEL,BET,BEV,BEC,FEL,FET,FEV,I18N jobs
    class BB,FB build

Reading the diagram: the changes job runs first and uses dorny/paths-filter to detect which components changed. Then only the relevant jobs run. 12-Factor and summary always run (security gates). Backend/Frontend cache uses scope=backend / scope=frontend so they don't invalidate each other. See docs/PIPELINE.md and ADR-0011 for the full design.

Multi-tool portability

The same harness/ directory works in any agentic tool. The AGENTS.md file is the universal contract; each tool has a small adapter in §9:

Tool	Adapter path	Validated?	Notes
Hermes Agent	`~/.hermes/profiles/<name>/SOUL.md`	✅ Yes (mandai-v2)	Per-persona profile, the only tool tested with the framework
Claude Code	`CLAUDE.md` + `.claude/agents/`	⏳ Adapter-only	Persona files → `.claude/agents/<name>.md`
GitHub Copilot	`.github/agents/` + `copilot-instructions.md`	⏳ Adapter-only
Codex CLI	`AGENTS.md` (root)	⏳ Adapter-only	Direct, no adapter needed
OpenCode	`AGENTS.md` (root)	⏳ Adapter-only	Direct, no adapter needed
Devin	`AGENTS.md` + `.devin/`	⏳ Adapter-only
Cursor	`.cursorrules`	⏳ Adapter-only	Generated from `AGENTS.md`

Important: as of v1.3.0, Hermes Agent is the only agentic tool that has been validated end-to-end with the framework (via the mandai-v2 validation case). The other tools have adapters only — the meta-harness is designed to be tool-agnostic, but full validation is pending for them. Adopters who use a different tool are encouraged to contribute their validation back to the project.

Validation and test case: mandai-v2

The framework was first validated end-to-end in brenonaraujo/mandai-v2 — a B2B2C community group buying marketplace (modeled on Meituan Select / Duoduo Maicai), built with Hermes Agent (the only tool tested with the framework so far).

Project profile (jul/2026):

~50 issues, ~10+ merged PRs, 4+ épicos concluídos (F1 auth/role, F2+F3 workspaces/products, F4+F5 ciclos/pedidos, F4+F5+ pix/payouts).
Stack: Go 1.26.5 + Gin + GORM + PostgreSQL + Nuxt 4 + UI v4 + Pinia + i18n (en/pt-BR/es).
27 releases do framework validadas em produção (v1.0.0 → v1.13.0).
3 lições aplicadas que viraram features do framework:
1. v1.6.5 — hermes profile <name> --prompt é inválido (corrigido pra hermes chat -p <name> -q ..., depois v1.12.2 confirmou a forma correta: hermes -p <name> chat -q ...).
2. v1.9.0 — Épico #12: 6 builders em paralelo causaram conflito UserRepository redeclarado → Decomposition Safety (path-scope + depends-on + sensor 10).
3. v1.11.0 — Épico F4+F5: domain-expert e solutions-architect viraram "blueprinter" (escreveram SQL/func names) → Scope Discipline (PILARES vs BLUEPRINTS + sensor 11 + skill solution-scoping).
4. v1.12.0 — PR #23 Redesign Landing: frontend-engineer entregou UI com hex hardcoded + BEM + emojis excessivos + zero npx skills → Frontend Public Skills + sensor 12 (cold-start polish).
5. v1.13.0 — Épico #48 F7+F8+F10: team-manager pulou domain-expert + architect, builders sem contexto → Feature flow enforcement (sensor 13 BLOQUEIA).
CI modular com dorny/paths-filter: PRs de typo/i18n-only rodam em ~30s (vs ~8 min do pipeline full).
6 personas especializadas: team-manager, domain-expert-mandai, backend-engineer, frontend-engineer, solutions-architect, quality-assurance, devops-engineer.

Key principles (extracted from `bootstrap.md`)

KISS, DRY, código limpo, ≤ 25/≤ 150.
TDD (Test-Driven Development) com table-driven tests + testify (backend) / Vitest (frontend). TDD é a metodologia (red-green-refactor); table-driven é o formato canônico (uma slice de cases cobrindo happy path + edge cases).
OpenAPI spec-first (never swag).
12-factor obrigatório (auditado pelo sensor 07).
i18n first-class (en, pt-BR, es).
Domain-expert sempre especializado (nunca genérico).
Smart routing por type/* no team-manager.
team-manager NÃO escreve código de feature (única linha vermelha).
Local pre-flight antes de PR (make lint && make test && make vuln).
Smoke test + check-stack-versions rodados antes de processar issues.
Stack pinada (sem latest) — fonte canônica stack/versions.md.
Distroless + UID 65532 (não nonroot:nonroot).
Bootstrap from a seed — cola o meta-harness-seed.md num agentic CLI e materializa o framework no projeto.

Project structure

git-meta-harness/
├── README.md                    # this file
├── CHANGELOG.md                 # version history (27 releases)
├── LICENSE                      # MIT
├── CONTRIBUTING.md              # how to contribute
├── VERSION                      # semver (1.13.0)
├── .github/
│   ├── ISSUE_TEMPLATE/          # bug, feature, tech-debt
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── CODEOWNERS
├── cli/                         # gmh CLI (Go static binary)
│   ├── cmd/                     # install, sync, update, doctor, agents
│   ├── internal/                # agentic, hermes, soul, skills, source
│   └── installer/               # install.sh, install.ps1
├── docs/                        # 9 docs (CONCEPT, HOWTO, LOOP, CLI, ...)
├── templates/                   # CI workflow, .golangci.yml
├── bin/                         # safe-commit-harness-sync.sh (v1.10.1+)
└── harness/
    ├── AGENTS.md                # multi-tool contract + 28 invariants
    ├── CLAUDE.md                # Claude Code adapter
    ├── bootstrap.md             # 13 princípios canônicos
    ├── smoke-test.md            # spec do smoke test
    ├── personas/                # 8 personas + examples/
    ├── sensors/                 # 14 sensors (00-13, v1.14.0: sensor 13 feature-flow documented)
    ├── workflow/                # 7 workflow docs (00-06)
    ├── stack/                   # backend, frontend, observability,
    │                            #   docker, code-style, versions
    ├── templates/               # 16+ templates (Dockerfile, ci.yml,
    │                            #   locales, nuxt-ui/, comments/)
    ├── skills/                  # 17 skills
    ├── contrib/                 # design-decisions.md (29 ADRs)
    ├── examples/                # domain-expert-* + README
    ├── seed/                    # meta-harness-seed.md
    └── scripts/                 # 9+ scripts (smoke-test, check-*, visual/)

Verification gates (pre-release)

# Smoke test (12 checks)
./harness/scripts/smoke-test.sh .

# Stack version consistency (offline + online)
./harness/scripts/check-stack-versions.sh --check-latest

Both must pass before any issue is processed. See smoke-test.md for the full spec.

Roadmap

v1.0.0 ✅ — First public release
v1.1.0 ✅ — Concept documentation
v1.2.0 ✅ — Mermaid diagrams
v1.3.0 ✅ — docs/LOOP.md
v1.4.0 ✅ — docs/HOWTO.md + code-graph skill
v1.5.0 ✅ — verify-after-build (sensor 09) + invariante 19
v1.6.0 ✅ — release pipeline (GHCR) + gmh CLI
v1.7.0 ✅ — UI/UX skills (nuxt-ui-patterns, ux-design-best-practices) + design cercas
v1.8.0 ✅ — skill domain-refinement + Cerca Técnica
v1.9.0 ✅ — Decomposition Safety (path-scope + depends-on + sensor 10)
v1.10.0 ✅ — Function limit 25→35 + skill pre-implementation-design
v1.10.1 ✅ — HOTFIX: bin/safe-commit-harness-sync.sh (no git add -A)
v1.10.2 ✅ — gmh agents sync writes config.yaml with skills.external_dirs
v1.10.3 ✅ — HOTFIX: gmh agents sync copies skills to each profile (UI count)
v1.11.0 ✅ — Scope Discipline (PILARES vs BLUEPRINTS) + sensor 11
v1.12.0 ✅ — Frontend Public Skills + Cold-Start Polish (sensor 12)
v1.12.1 ✅ — HOTFIX: gmh agents sync no longer erases model/agent config
v1.12.2 ✅ — HOTFIX: Hermes -p flag is global, not chat subcommand
v1.13.0 ✅ — Feature flow enforcement (sensor 13 + canonical comment templates)
v1.14.0 🔜 — Live tests for claude, codex, opencode (per ADR-0024)
v2.0.0 🔜 — Multi-repo orchestration (workspace of meta-harnesses)

Contributing

See CONTRIBUTING.md. For major changes, open an issue first to discuss what you'd like to change.

License

Acknowledgements

Built and validated with:

Hermes Agent — the agentic CLI used in the pilot
Claude Code, GitHub Copilot, Codex CLI, OpenCode, Devin, Cursor — multi-tool compatibility targets
golangci-lint v2, Trivy, dorny/paths-filter — the CI/CD substrate
distroless — the runtime substrate
Nuxt 4, Go 1.26, PostgreSQL 18 — the application stack

References (consolidated, v1.14.2+)

External sources cited in this project, in one place. The paper below is the academic origin of the "meta-harness" concept; the other repositories are sibling implementations of the same idea.

Paper (academic origin of "meta-harness")

Meta-Harness: End-to-End Optimization of Model Harnesses — Lee, Nair, Zhang, Lee, Khattab, Finn (Stanford IRIS Lab, 2026). The paper that named and operationalized the "meta-harness" concept via LLM proposer+verifier. arXiv:2603.28052.
- HTML v1 (full text) — recommended reading for the full architecture.
- Companion site: yoonholee.com/meta-harness.

Sibling implementations (complementary, not competitive)

Repo	Type	License	Notes
stanford-iris-lab/meta-harness	Research code (Python)	MIT	Reference code for the paper. 1.3k⭐ 127 forks.
SuperagenticAI/metaharness	Production code (Python)	Custom	v0.4.0 "Omnigent Backend" (jun/2026). 146⭐ 17 forks.
brenonaraujo/git-meta-harness	This project (Go CLI + Markdown)	MIT	Operational framework, multi-tool, GitHub-native.

Article (concept, governance + audit)

What Is Meta-Harness for AI Agents and Why Now? — Abhishek Pan, jul/2026. The "governance + audit + control plane" narrative. Paywalled after preview.

Validation case

brenonaraujo/mandai-v2 — the real pilot project. 50+ issues, 4+ epics, 5 lessons applied as framework features (Decomposition Safety v1.9.0, Scope Discipline v1.11.0, Frontend Polish v1.12.0, Feature Flow v1.13.0, Adaptive Harness v1.14.0).

Citation

If you cite this work, please cite the original Stanford IRIS paper:

@misc{lee2026metaharnessendtoendoptimizationmodel,
      title={Meta-Harness: End-to-End Optimization of Model Harnesses},
      author={Yoonho Lee and Roshen Nair and Qizheng Zhang and Kangwook Lee and Omar Khattab and Chelsea Finn},
      year={2026},
      eprint={2603.28052},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2603.28052},
}

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.github		.github
bin		bin
cli		cli
docs		docs
harness		harness
templates		templates
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION

Folders and files

Latest commit

History

Repository files navigation

git-meta-harness

What's new in the last 4 releases (jul/2026)

The concept in one paragraph

Visual overview

The full loop — from spec to release

The team — 8 personas + smart routing

GitHub as native substrate

What is this

Why use it

Quickstart

1. Use as the seed for a new project

2. Use the gmh CLI (recommended for v1.6.0+)

3. Copy the harness manually (legacy)

4. Verify it's healthy

5. Publish a release (v1.6.0+)

Architecture overview

The team (8 personas) and the 13 sensors

Sensors (when each runs, what happens on fail)

CI workflow (modular with path filters)

Multi-tool portability

Validation and test case: mandai-v2

Key principles (extracted from bootstrap.md)

Project structure

Verification gates (pre-release)

Roadmap

Contributing

License

Acknowledgements

References (consolidated, v1.14.2+)

Paper (academic origin of "meta-harness")

Sibling implementations (complementary, not competitive)

Article (concept, governance + audit)

Validation case

See also

Citation

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2. Use the `gmh` CLI (recommended for v1.6.0+)

Key principles (extracted from `bootstrap.md`)