agentarch

README

agentarch

An open, versioned, verifiable standard for building AI agents.

Install it into any agent project, in any language, and every AI assistant working on that project — Claude Code, Gemini CLI, Cursor, Copilot, Codex, Grok, Kimi, Qwen Code, Windsurf, local models — follows the same architecture rules, from a single source of truth.

Status: pre-release, under active development. spec/1.0 is not frozen yet.

16 standards · 39 controls · 9 packs · 11 framework adapters · en and pt-BR.

---

The problem

Building a responsible AI agent today means assembling knowledge that lives in a dozen disconnected places: the OWASP Top 10 for LLM Applications, MITRE ATLAS, NIST AI RMF, ISO/IEC 42001, the OpenTelemetry GenAI semantic conventions, the prompt-injection literature, MCP security advisories, and whatever your framework happens to call a "tool" or a "guardrail".

None of it is executable. So every team reinvents its own conventions, the knowledge lives in one person's head, and nothing survives a change of framework, of assistant, or of team.

Meanwhile the AI assistant became the primary author of agent code — and it starts every session with no memory of what your team decided. Instruction files (AGENTS.md, CLAUDE.md, .cursor/rules) helped, but every tool reads a different file, all written by hand, all drifting apart within weeks.

What agentarch does

It answers three questions that have no standard answer today:

1. What must be declared for an agent to count as well-built — in machine-readable artifacts, not prose.
2. How that is verified automatically, in CI, without running the agent.
3. How every AI assistant picks up those rules from one source of truth.

Getting started

Install. Pick whichever fits your stack — the CLI is a single static binary, so nothing here pulls in a runtime you did not already have:

npx agentarch@latest init          # any project with Node
pipx install agentarch             # any project with Python
docker run --rm -v "$PWD:/work" ghcr.io/everton-baptista/agentarch check
go install github.com/Everton-baptista/agenteARQ/cmd/agentarch@latest

In CI, the composite action hides the language entirely:

- uses: Everton-baptista/agenteARQ/.github/actions/agentarch@v1
  with:
    command: check --profile standard

The npm and PyPI packages publish on the first tagged release; until then use go install or the container. Every artifact is signed with cosign and its checksum is verified before anything is unpacked — including by the action itself.

Then, in your project:

agentarch init --profile standard --jurisdictions EU,BR
agentarch blueprint

init writes an agentarch/ directory and generates the instruction file each assistant expects. blueprint asks what you are building and installs a complete, working project for it — manifest, prompt, tools, evals, threat model, CI, and code that runs:

What are you building?

  1. An agent that acts on my systems, with a human approving the dangerous part
  2. An agent that answers from my documents and cites its sources
  3. An agent that uses MCP servers I did not write
  4. Several agents working together without losing track of who may do what

Every blueprint passes the gate the moment it lands, so you start from something that works and edit it, rather than assembling one and finding out later what was missing. agentarch blueprint show <id> explains what each demonstrates.

Prefer to start empty?

agentarch new agent customer-triage

new agent scaffolds a manifest and a system prompt already hashed into each other.

validate will fail until you fill in the fields marked TODO, and that is deliberate. A manifest full of plausible defaults is worse than one that refuses to validate, because it looks finished. The two worth thinking about before the rest are out_of_scope — what the agent must refuse — and autonomy.level, which is a property of the deployment rather than of the model.

Once it validates:

agentarch check               # the release gate                 (exit 4 blocked, 5 waiver)
agentarch conformance         # L1 / L2 / L3, with an expiry
agentarch explain <control>   # why a rule exists and how to satisfy it

Commit the generated instruction files and run agentarch sync --check in CI, so a hand-edited CLAUDE.md fails the pull request instead of drifting quietly for six months. A ready-made workflow is in examples/01-rag-support-agent/.github/workflows/.

The rest of the surface

agentarch mcp audit --probe   # has a server changed its tool descriptions since review?
agentarch diff --base main    # which revalidation triggers fired (exit 6 with --strict)
agentarch aibom --out ai-bom.json
agentarch score               # maturity by dimension, declared vs proven
agentarch upgrade --dry-run   # what a newer standard would change

What it is not

Not a library. Not a runtime. It does not execute your agent and does not replace your framework. It has to work the same in Python, TypeScript, Go, Java and .NET — so it stays out of the execution path entirely.

---

How it is organized

Four layers, versioned and licensed separately, so that this can be a standard rather than just a tool:

Layer	What it is	Version	License
Spec	normative contracts: schemas, control and pack format, resolution algorithm, exit codes, shim rendering	spec/1.0	CC BY 4.0
Content	the standards, controls, official packs, templates, adapters	content/1.x	CC BY 4.0
Implementation	agentarch, the reference CLI, written in Go	cli/1.x	Apache-2.0
Governance	RFC process, conformance levels, versioning policy, registry	continuous	—

spec/conformance/ holds fixtures and expected outputs, so anyone can write a second implementation — in Rust, in TypeScript, inside an internal platform — and prove it correct.

Every rule exists twice

Once as prose you can read (content/standards/) and once as an executable control (content/packs/controls/), sharing an identifier. validate checks the correspondence in both directions: an undocumented control fails, and so does a documented rule that nothing verifies.

That is the core defense against becoming shelfware: prose without a verifiable consequence does not get into the standard. A rule that genuinely cannot be automated is admitted as check.kind: manual_attestation — an honest declaration, not a loophole.

Two things that are never negotiable

• A pack is data, never code. Checks are expressed in a restricted expression language specified in spec/normative/04-expression-language.md — no eval, no arbitrary calls. A governance standard that executes third-party code to verify governance does not hold up.
• The core is a fixed budget, not a list. What every assistant loads on every session is capped, and the build fails when it overflows. Adding an invariant means removing another — which makes "what is truly non-negotiable" a scarce, contested decision.

---

What is in the box

Standards	agent contract, prompt and context, tools, MCP, memory, multi-agent, human-in-the-loop, guardrails, security, privacy, evaluation, observability, resilience and cost, lifecycle, supply chain
Packs	core.agent, sec.owasp-llm, obs.otel, eval.baseline, reg.gdpr, reg.br-lgpd, reg.eu-ai-act, std.nist-ai-rmf, std.iso-42001
Adapters	LangGraph, OpenAI Agents SDK, Claude Agent SDK, Google ADK, Pydantic AI, LlamaIndex, CrewAI, Semantic Kernel, Agno, Vercel AI SDK, and no framework at all
Generated for	AGENTS.md, CLAUDE.md, GEMINI.md, QWEN.md, Cursor, Copilot, Windsurf, .mcp.json

Conformance

agentarch conformance --badge reports one of three levels:

Level	Means
L1 Declared	agents are described: manifest, named owner, explicit out-of-scope, declared autonomy and budget
L2 Enforced	the rules block: gate in CI, guardrails at all three points, least-privilege tools, MCP allowlist denying by default
L3 Proven	there is evidence: evals within their freshness window, red team executed, threat model reviewed, OTel with pinned semconv, AI-BOM

The badge expires. An L3 badge whose evals went stale drops to L2 on its own. Conformance that never decays is advertising.

---

Regulation is optional and pluggable

Standards never cite law. Legal obligations live in optional versioned packs — reg.eu-ai-act, reg.gdpr, reg.br-lgpd, std.iso-42001, std.nist-ai-rmf — each declaring its authority, its authority_status, and its review date. Your agent declares jurisdictions: ["EU", "BR"] and the applicable packs resolve automatically.

This is what lets a team in Berlin, São Paulo or Austin share the same core.

---

Language

English is normative. Translations declare the SHA-256 of the source they were made from, and validate flags them when they fall behind — a stale translation is worse than a missing one, because it lies with authority. Control IDs, schema fields and file names stay in English in every language, so error messages and searches remain interoperable across teams.

Shipping in v1: en, pt-BR.

---

Contributing

New controls, severity changes, new sync targets, schema changes and new official packs go through the RFC process in rfcs/. See CONTRIBUTING.md and GOVERNANCE.md.

No control is ever born blocking. Controls enter with enforced_from one minor ahead and run in warn mode until then, and no release makes an existing control stricter without a content major.

License

Code is Apache-2.0 (LICENSE). Spec and content are CC BY 4.0 (LICENSE-CONTENT) so they can be quoted, translated and reimplemented.

Documentation

Overview

Package agentarch carries the standard's payload — the content and spec trees — embedded into the binary.

The embed directives live at the module root because go:embed cannot reach outside its own package directory, and the payload must stay where humans edit it rather than being copied into the CLI's source tree.

Embedding is what lets `agentarch init` work offline and without network access. That is a deliberate constraint: a governance tool that phones home to fetch the rules it enforces is one outage away from being unusable, and one compromise away from being dangerous.

Index

• Variables

Variables

var Content embed.FS

all: is required. Without it go:embed silently skips anything beginning with a dot, and the blueprints ship a .github/workflows — so the CI gate never reached the project and a fresh install could not reach conformance L2. Silently, because an absent file looks like a choice.

var Spec embed.FS