anna-arch 1.3.2

ANNA — AI-Native Node Architecture. Manifest-driven navigation system for AI coding agents.

Anyone who has built software with AI knows how it usually goes: the code grows quickly, turns into spaghetti, duplication creeps in everywhere, and things start breaking in unexpected places.

While looking for a solution, I realized that AI is being trained and pushed to write code the way a human would. But what's needed is a different approach — a set of instructions designed to be understood by both humans and AI. That's how ANNA was born.

ANNA represents your codebase as a dependency graph, with each node clearly described. An AI agent uses this representation to quickly understand the architecture and the relevant parts of the system, and only then dives into the specific section of code to execute changes with surgical precision. No wasted tokens, no unnecessary rewrites, no guesswork — just clean results.

The Problem

AI coding agents are powerful — but no agent sees the full architecture at once. Given a task, an agent needs time and tokens just to map out where to act — and the larger the project, the more of both it takes. It lists directories, opens files, traces imports, and by the time it starts coding, most of the context window is already spent. Worse: even then it only sees fragments. It doesn't know what a module is supposed to do, what it guarantees, or what it must never do.

The agent improvises. It duplicates logic that already exists elsewhere. It bypasses contracts it didn't know about. It fixes a bug in one place without realizing the same assumption is embedded in three others. It lacks architectural memory.

ANNA gives the agent that context upfront. Every node in the graph carries its intent, its public contract, and its constraints. Before touching a single line of code, the agent reads simple manifests — and already knows the architecture, the rules, and exactly where to operate.

How It Works

ANNA uses two core manifests: a global manifest that maps all nodes and their dependencies within a service, and a local manifest per file that describes its intent, public contract, and constraints. For microservice architectures, a system manifest (planned) will describe the services themselves and how they interconnect.

You:  "Add a DELETE /users/{id} endpoint"

Agent reads index.json (global manifest) → sees api.py → user_service.py
Agent reads user_service.py.json (local manifest) → sees get_user, create_user contracts
Agent writes code → adds delete_user → updates manifests

Total navigation: 2 file reads instead of 12.

Quick Start

pip install anna-arch
cd your-project
anna init

anna init scaffolds the complete .anna/ structure: manifests/, audit/ (15 automated integrity checks), QA agent skills, infrastructure manifest, .annaignore with sensible defaults, and the full spec (ANNA_RULES.md).

Then two steps remain:

1. Configure your agent's memory. Run anna agent-rules — it prints ready-to-paste instructions and a table of where to put them for each agent (Cursor, Claude Code, Windsurf, Copilot, etc.).

2. Ask your AI agent to generate the manifests:

Read .anna/ANNA_INIT.md and initialize ANNA for this project.

For projects with 30+ source files, initialization runs in batches across multiple chat sessions — this is built into the init document and tracked via a progress file.

After initialization, review what the agent created — check that index.json reflects your project topology, that node intents match the actual purpose of your files, and that dependencies are accurate. The manifests are plain JSON — easy to read and verify. Then run anna audit to verify integrity.

CLI Commands

Command	What it does
anna init	Scaffold .anna/ in the current project
anna audit	Run all integrity checks (same as python .anna/audit/run_all.py)
anna update	Upgrade framework files (audit checks, rules) to the installed version — your manifests, .annaignore, and configs are preserved
anna agent-rules	Print agent rules for your agent's config file

Manual setup (without pip)

Point your AI agent to the initialization document — it will handle everything:

Read ANNA_INIT.md and initialize ANNA for this project.

Your agent will create the .anna/manifests/ structure, copy audit/ into .anna/audit/, create .annaignore with sensible defaults, then analyze your codebase and generate all manifests.

To configure your agent's memory, copy the rules from ANNA_AGENT_RULES.md into your agent's rules configuration file. Place ANNA_RULES.md in your project's .anna/ folder — your agent will use it as the day-to-day operational reference.

Once set up, you can delete ANNA_INIT.md — it's only needed for the initial setup.

The READ → CODE → SYNC Cycle

Every task follows three mandatory phases:

┌─────────┐     ┌─────────┐     ┌─────────┐
│  READ   │ ──→ │  CODE   │ ──→ │  SYNC   │
│manifests│     │  write  │     │ update  │
│  first  │     │  code   │     │manifests│
└─────────┘     └─────────┘     └─────────┘

Phase	What happens
READ	Agent reads index.json → finds affected nodes → reads their local manifests → reads their code if necessary
CODE	Agent writes code following contracts and constraints from manifests
SYNC	Agent updates manifests to reflect code changes. Never skip.

Zero footprint. ANNA lives entirely inside the .anna/ folder and your agent's rules file. To remove ANNA completely, just delete .anna/ and remove ANNA's rules from your agent's config — the next chat session will have no memory of it.

Key Concepts

Concept	Description
Global Manifest	index.json — map of all nodes and dependencies of the project, or of an individual service (for microservice architectures)
Local Manifest	Per-node .json file — full contract, constraints, and invariants for one file
Node	One source file = one node = one local manifest
Node ID	File path with / → . and extension after : (e.g., backend.api:py)
Intent	What the file does (1–2 sentences) — stored in global manifest
Context	How the file fits into the architecture (1–3 sentences) — stored in local manifest
Contract	Public API: methods with typed inputs/outputs
Constraints	Prescriptive rules — "don't do X", "always do Y"
Invariants	Verifiable assertions — "X is always true in this code"
Dependencies	Which other nodes this file imports from
Broker	Node excluded from cycle detection (for bidirectional deps like WebSocket hubs)
Zero-Degree Rule	A file with no incoming AND no outgoing dependencies is NOT a node — it stays outside ANNA until connected
.annaignore	Glob-pattern file that excludes tests, migrations, build configs, and other non-architectural files from manifests
BUG-TO-CONSTRAINT	Every bug fix adds a constraint to the manifest, preventing the same error from recurring

File Structure

your-project/
├── .anna/
│   ├── manifests/
│   │   ├── index.json                 ← Global: all nodes + deps
│   │   ├── backend/
│   │   │   ├── main.py.json           ← Local: contract for main.py
│   │   │   └── services/
│   │   │       └── user_service.py.json
│   │   └── frontend/
│   │       └── src/
│   │           └── App.tsx.json
│   ├── audit/                         ← Integrity checks (run after SYNC)
│   ├── qa/                            ← QA agent framework
│   │   ├── QA AGENT.md                ← QA agent skill
│   │   ├── QA AGENT INIT.md           ← First-run scaffold skill
│   │   ├── config.json                ← Test credentials & timeouts (generated)
│   │   ├── schemas.py                 ← Report models (generated)
│   │   ├── reporter.py                ← Report renderer (generated)
│   │   └── reports/                   ← JSON + Markdown test reports
│   ├── infra/                         ← Infrastructure manifest
│   │   └── infra.json                 ← Deployment topology & secrets map
│   ├── .annaignore                    ← Files excluded from ANNA
│   └── ANNA_RULES.md                  ← Full specification
├── backend/
│   ├── main.py
│   └── services/
│       └── user_service.py
└── frontend/
    └── src/
        └── App.tsx

📖 Full specification: ANNA_RULES.md · 📂 Real-world example: examples/

Audit System

ANNA includes 15 automated integrity checks that run after every SYNC phase to catch manifest drift:

anna audit
# or directly:
python .anna/audit/run_all.py

Exit code 0 — all checks pass. Exit code 1 — errors found that must be fixed before ending the task.

The checks cover:

• Structural integrity — missing/orphan manifests, node ID consistency, required fields
• Graph validity — broken dependency refs, cycles (DAG enforcement), unreachable nodes
• Source sync — missing source files, .annaignore compliance
• Contract sync — every public function and parameter in code is reflected in manifests (0 errors AND 0 warnings)
• Duplicate detection — no duplicate node IDs in index.json or across local manifests

The runner auto-discovers all check_*.py modules in .anna/audit/, so adding a new check is as simple as creating a check_<name>.py file with a run() function.

📖 Full check catalog with remediation steps: ANNA_RULES.md §10

QA Framework

ANNA includes a QA agent framework that provides structured, manifest-driven testing.

The QA agent tests your application against ANNA manifests — every constraint becomes a test case, every invariant becomes an assertion. It produces dual-format reports: JSON (for AI consumption) and Markdown (for developers).

To set up QA for your project, point your agent to the initialization skill:

Read QA AGENT INIT.md and scaffold the QA infrastructure.

This creates config.json, schemas.py, reporter.py, and the reports/ directory — all tailored to your project. Once scaffolded, the QA AGENT skill handles test execution and reporting.

Infrastructure Manifest

The infra/ directory contains a single infra.json file — a complete map of your deployment topology: VPS, Docker services, networking, SSH access, CI/CD pipelines, environment variables, and deploy procedures.

This gives any agent (or new team member) instant context on how the system is deployed and operated, without reading Dockerfiles, CI configs, and wiki pages scattered across the project.

Fill it in once, keep it updated — the same way you maintain code manifests.

Why ANNA?

Without ANNA	With ANNA
Agent reads 10–15 files to understand structure	Agent reads 2 manifests and starts coding
No architectural memory between sessions	Manifests persist knowledge across agents and chats
Agent accidentally breaks contracts	Constraints and invariants prevent violations
Same bugs recur after fixes	BUG-TO-CONSTRAINT captures root causes permanently
"What does this file do?" — read 200 lines	"What does this file do?" — read intent (1–2 sentences)

Impact scales with project size — the larger the codebase, the greater the time and token savings.

Agent Support

ANNA works with any AI coding agent. Copy the universal rule file into your agent's config — run anna agent-rules, or use the file directly:

📄 ANNA_AGENT_RULES.md — ready-to-paste instructions with a table of where to copy for each agent.

Contributing

See CONTRIBUTING.md. ANNA is designed to evolve with the community.

License

MIT — use it everywhere, fork it, build on top.

---

⭐ Star this repo if ANNA helps your AI agent work smarter.