Our System

What Is AiAgentArchitect?

The Problem

Designing agentic systems is hard: vague requirements, no standard structure, and every implementation looks different. You know Claude Code can build multi-agent systems — but where do you start? How do you structure files? How do you know if you chose the right entity types?

Most teams end up with one of two outcomes:

• Everything in CLAUDE.md — a single file that grows to thousands of lines, loads every session, and becomes impossible to maintain
• Unstructured agents — files with no naming conventions, no clear boundaries, and no way to know what belongs where

Both work for simple cases. Both collapse as complexity grows.

The Solution

AiAgentArchitect is an open-source framework that solves this with a guided pipeline — from raw idea to production-ready .md files — using a strict entity-based architecture and built-in QA scoring.

It's not a wrapper around Claude Code. It's a design system that produces the files Claude Code reads. Think of it as an architect that designs the building, where Claude Code is the construction site.

The 3-Step Pipeline

AiAgentArchitect operates through three structured steps:

Each step has a checkpoint where you approve, adjust, or regenerate before proceeding. Nothing is generated without your explicit approval.

Entity Architecture

10 Entity Types

Every system built by AiAgentArchitect uses exactly 10 entity types. This isn't arbitrary — each type exists because it solves a specific design problem that can't be solved by any other type.

Naming Conventions

Every entity file follows strict naming rules that make systems self-documenting:

• Prefix — identifies the entity type at a glance (age-spe-, wor-, rul-, etc.)
• Kebab-case — no spaces, no uppercase: age-spe-email-classifier.md
• Name limit — max 64 characters in frontmatter name field
• Description limit — max 250 characters, following the "what + when" pattern

The "what + when" description pattern ensures agents are discoverable:

Claude Code Mapping

This is the most important section for understanding this guide. AiAgentArchitect's 10 entity types map to Claude Code's directory structure — but the mapping isn't always 1:1. Understanding where entities land and why prevents confusion.

Claude Code Native Structure

Out of the box, Claude Code recognizes this structure:

.claude/
├── commands/          ← slash commands (/name)
├── agents/            ← subagent definitions
├── skills/            ← reusable capability packages
└── settings.json      ← hooks, permissions

That's it. Claude Code natively knows about commands, agents, skills, and settings. There's no built-in concept of "Workflows", "Rules files", "Knowledge Bases", "Resources", "Scripts", or "Hooks as .md files".

AiAgentArchitect Mapping

AiAgentArchitect extends this structure by placing its 10 entity types into the directories Claude Code can read:

.claude/
├── commands/                ← wor-*.md (workflows) + com-*.md (commands)
├── agents/                  ← age-spe-*.md (specialists) + age-sup-*.md (supervisors)
├── skills/                  ← ski-*/SKILL.md
├── rules/                   ← rul-*.md (standalone rule files)
├── knowledge-base/          ← kno-*.md (reference material)
├── resources/               ← res-*.md (support documents)
├── scripts/                 ← scp-*.sh / scp-*.py (executables)
├── hooks/                   ← hok-*.md (hook documentation)
├── settings.json            ← hook config + permissions
└── settings.local.json      ← CC-exclusive permission overrides

The full entity mapping

Why This Mapping?

Three design decisions deserve explanation:

1. Why do Workflows live in commands/?

Claude Code has no native "workflow" concept. The closest mechanism is a command — a file in .claude/commands/ that becomes a slash command. AiAgentArchitect uses this mechanism to make Workflows invocable: you type /wor-content-pipeline and the orchestration starts. The wor- prefix is what distinguishes a workflow from a simple command (com-) — not the directory.

2. Why do Rules, KBs, Resources, etc. have their own directories?

Claude Code doesn't require these directories. But Claude can read any file on disk with the Read tool. By organizing reference content into typed directories (rules/, knowledge-base/, resources/), agents know exactly where to look — and humans can navigate the system at a glance. The convention is the configuration.

3. Why prefixes instead of just directories?

Because some entity types share directories. In commands/, you'll find both wor-* and com-*. In agents/, you'll find both age-spe-* and age-sup-*. The prefix is what tells you — and the system — what role each file plays. Without prefixes, a file listing in commands/ would be ambiguous.

Benefits

What You Get

Every system generated by AiAgentArchitect includes:

Built-in QA

Every session runs a three-role quality cycle automatically:

• Auditor — verifies rule compliance after each approved checkpoint. Reads rules from disk. Never modifies anything.
• Evaluator — scores each phase on four dimensions: Completeness (30%), Quality (30%), Compliance (25%), Efficiency (15%).
• Optimizer — reads the complete audit history, detects patterns, and generates prioritized improvement proposals. Never applies them automatically.

QA output is appended to qa-report.md — append-only, never overwritten. The cycle is non-blocking: it accumulates evidence without stopping execution.

Iteration Modes

Once a system is exported, iterate without starting from scratch:

Each iteration creates a git branch (e.g., iter/0.2.0-add-email-skill). When ready, merge to main and tag the version. Full reversibility, zero risk to the working system.