AAA - Architecture Agent Assembly

Multi-agent architecture design system for Claude Code. Given a description of an agentic system, AAA produces a complete, internally consistent, cross-referenced architecture package that development teams can implement without making architectural decisions.

Quick Start

npx aaa-cc

Follow the interactive prompts to select install location and model profile, then:

cd your-project
claude
/AAA:new-system "automated PR code review pipeline with 6 agents"

Installation

Interactive (recommended)

npx aaa-cc

Prompts for:

Model profile - quality, balanced, or budget
Install location - global (~/.claude/) or local (./.claude/)
Statusline - replace existing or keep

Non-interactive

# Install globally with default (balanced) profile
npx aaa-cc --global

# Install globally with quality profile
npx aaa-cc --global --profile quality

# Install locally (current project only)
npx aaa-cc --local

# Install with budget profile
npx aaa-cc --global --profile budget

# Custom config directory
npx aaa-cc --global --config-dir ~/.claude-work

CLI Flags

Flag	Description
`-g, --global`	Install to `~/.claude/` (all projects)
`-l, --local`	Install to `./.claude/` (this project)
`--profile <name>`	Set model profile: `quality`, `balanced`, `budget`
`--force-statusline`	Replace existing statusline configuration
`-c, --config-dir <path>`	Custom config directory
`-u, --uninstall`	Remove AAA (requires `--global` or `--local`)
`-h, --help`	Show help

Uninstall

npx aaa-cc --global --uninstall
npx aaa-cc --local --uninstall

Model Profiles

Control which Claude model each agent uses. Select during install or change later in ~/.claude/aaa-runtime/config.json.

Agent	quality	balanced	budget
discuss-system	opus	opus	sonnet
arch-roadmapper	opus	opus	sonnet
context-engineer	opus	opus	sonnet
arch-researcher	sonnet	sonnet	haiku
arch-planner	sonnet	sonnet	haiku
arch-executor	sonnet	sonnet	sonnet
arch-verifier	sonnet	sonnet	haiku
schema-designer	sonnet	sonnet	haiku
failure-analyst	sonnet	sonnet	haiku
arch-checker	haiku	haiku	haiku
arch-integrator	haiku	haiku	haiku

quality/balanced: Opus for intake, roadmapping, and context engineering. Sonnet for execution and verification. Haiku for checking and integration.
budget: Sonnet for high-value agents (intake, executor, roadmapper, context). Haiku for everything else.

Commands

Command	Description
`/AAA:new-system`	Start a new architecture project. Spawns structured intake to extract system domain, actors, constraints, scale. Produces `.arch/CONTEXT.md`.
`/AAA:plan-phase`	Plan a design phase. Spawns researcher, roadmapper, planner, and checker. Produces `PLAN.md` with tasks and wave assignments.
`/AAA:execute-phase`	Execute a planned phase. Spawns executor agents for each task in wave order. Produces design artifacts (agent specs, schemas, topology).
`/AAA:verify-phase`	Verify a completed phase. Runs 4-level verification (exists, substantive, cross-referenced, consistent). Produces `VERIFICATION.md`.
`/AAA:progress`	Show current project state, phase position, accumulated decisions, and blockers.
`/AAA:resume`	Resume from last checkpoint after context reset. Reads `.arch/STATE.md` to determine next action.

Typical Workflow

/AAA:new-system "your system description"
  -> Structured intake conversation
  -> .arch/CONTEXT.md produced

/AAA:plan-phase --phase 1
  -> Research, roadmap, plan, review loop
  -> PLAN.md produced

/AAA:execute-phase --phase 1
  -> Executor writes design documents per plan
  -> Agent specs, event schemas, etc.

/AAA:verify-phase --phase 1
  -> 4-level verification
  -> VERIFICATION.md, INTEGRATION-REPORT.md

(repeat for phases 2-5)

Agents

AAA uses 11 specialized agents, each with a defined role, upstream inputs, downstream consumers, and structured returns.

Agent	Role
discuss-system	Structured intake. Conducts conversation with human architect to extract domain, actors, non-goals, constraints, scale, locked decisions.
arch-researcher	Researches architecture patterns, technology constraints, and domain-specific practices for the target system.
arch-roadmapper	Derives design phases from system intent using research. Produces phase count, goals, success criteria, dependency graph.
arch-planner	Decomposes roadmap phases into concrete tasks with wave assignments and dependencies.
arch-checker	Reviews plans for consistency, completeness, naming conventions. Catches vague language.
arch-executor	Writes design documents for phase tasks. Produces agent specs, event schemas, topology diagrams, context flows, failure modes.
arch-verifier	Multi-level verification: Level 1 (Exists), Level 2 (Substantive), Level 3 (Cross-Referenced), Level 4 (Consistent).
arch-integrator	Cross-phase consistency checks. Verifies agents mentioned in topology exist in design.
context-engineer	Designs context engineering strategy for target system agents. Context flows, sliding windows, handoff protocols.
schema-designer	Designs event, command, and data type schemas with type safety enforcement.
failure-analyst	Analyzes failure modes per agent. Documents triggers, manifestations, severity, recovery procedures.

Project Structure

AAA creates an .arch/ directory in your project:

.arch/
  CONTEXT.md              System intent (domain, actors, constraints)
  STATE.md                Project position and session continuity
  ROADMAP.md              Design phases with dependency graph
  RESEARCH.md             Architecture patterns and recommendations
  phases/
    01-context-and-schema-design/
      01-PLAN.md           Task decomposition
      01-SUMMARY.md        Phase completion summary
      design/
        agents/            Agent contract documents
        events/            Event/command schemas (YAML)
        topology/          Agent communication topology
        context-flows/     Per-agent context specifications
        failure-modes/     Failure catalogs per agent
        MANIFEST.md        Document index
        VERIFICATION.md    4-level verification results
        INTEGRATION-REPORT.md  Cross-phase consistency

Configuration

config.json

Located at ~/.claude/aaa-runtime/config.json:

{
  "model_profile": "balanced",
  "commit_docs": true,
  "parallelization": true,
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true
  },
  "model_profiles": {
    "quality": { ... },
    "balanced": { ... },
    "budget": { ... }
  }
}

model_profile: Active profile name
commit_docs: Auto-commit design documents
parallelization: Enable wave-based parallel execution
workflow.research: Enable research phase before planning
workflow.plan_check: Enable plan review loop with arch-checker
workflow.verifier: Enable verification after execution

Changing Profile After Install

Edit ~/.claude/aaa-runtime/config.json and change model_profile to quality, balanced, or budget.

CLI Utility

AAA includes arch-tools.js, a CLI utility for verification and validation:

# Frontmatter operations
node arch-tools.js frontmatter get <file> [--field key]
node arch-tools.js frontmatter set <file> --field k --value v

# Stub detection
node arch-tools.js detect-stubs <file>
node arch-tools.js detect-stubs --dir <directory>

# State management
node arch-tools.js state init --phase N --name <name>
node arch-tools.js state status

# Validation
node arch-tools.js validate-context <file>
node arch-tools.js validate-names <file>

# 4-level verification
node arch-tools.js verify level1 <file>
node arch-tools.js verify level2 <file> --type agent
node arch-tools.js verify level3 <file> --design-dir <dir>
node arch-tools.js verify level4 --design-dir <dir>
node arch-tools.js verify run <dir> --levels 1,2,3,4

Verification Levels

Level	Name	What It Checks
1	Exists	File exists at expected path
2	Substantive	Content is real, not stubs or placeholders
3	Cross-Referenced	All references to other documents resolve
4	Consistent	No circular dependencies, no orphaned agents, full graph connectivity

Hooks

AAA installs three lifecycle hooks:

Statusline: Shows AAA | profile | phase:status | context% in the Claude Code header
Update Check: Checks npm for newer aaa-cc version on session start
Context Monitor: Warns when context window usage is high, suggests /AAA:resume

What Gets Installed

~/.claude/
  commands/AAA/              6 slash commands
  agents/                    11 agent specifications
  aaa-runtime/          Runtime (bin, references, templates, config)
  hooks/                     3 lifecycle hooks (aaa-*.js)
  settings.json              Updated with hooks + statusline
  aaa-file-manifest.json     File hashes for modification detection

Local Modifications

If you customize any installed file, AAA detects the change on the next install/update:

Modified files are backed up to aaa-local-patches/
New version is installed
You're prompted to manually merge your changes back

Requirements

Ubuntu (Linux)
Node.js >= 18.0.0
Claude Code CLI

Name		Name	Last commit message	Last commit date
.planning		.planning
aaa-runtime		aaa-runtime
agents		agents
bin		bin
commands/AAA		commands/AAA
hooks		hooks
.gitignore		.gitignore
ARCHITECT-VISION.md		ARCHITECT-VISION.md
GSD-REPURPOSING-VISION.md		GSD-REPURPOSING-VISION.md
GSD-vs-AAA-tool-comparison.md		GSD-vs-AAA-tool-comparison.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
plugin.json		plugin.json
research-agentic-architecture-patterns.md		research-agentic-architecture-patterns.md

Navigation Menu

Repository files navigation

AAA - Architecture Agent Assembly

Quick Start

Installation

Interactive (recommended)

Non-interactive

CLI Flags

Uninstall

Model Profiles

Commands

Typical Workflow

Agents

Project Structure

Configuration

config.json

Changing Profile After Install

CLI Utility

Verification Levels

Hooks

What Gets Installed

Local Modifications

Requirements

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AAA - Architecture Agent Assembly

Quick Start

Installation

Interactive (recommended)

Non-interactive

CLI Flags

Uninstall

Model Profiles

Commands

Typical Workflow

Agents

Project Structure

Configuration

config.json

Changing Profile After Install

CLI Utility

Verification Levels

Hooks

What Gets Installed

Local Modifications

Requirements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages