Build production-ready multi-agent systems in three structured steps.
Designing agentic systems is hard: vague requirements, no standard structure, and every implementation looks different. AiAgentArchitect solves this with a guided pipeline — from raw idea to ready-to-deploy .md files — using a strict entity-based architecture and built-in QA scoring.
AiAgentArchitect operates through a 3-step pipeline:
Step 1 — Process Discovery A specialist agent interviews you using BPM/BPA techniques. It reverse-engineers vague requests, detects hidden complexity, and produces an AS-IS diagram and a structured handoff to Step 2.
Step 2 — Architecture Design An architecture agent translates the discovered process into a Blueprint: the right entities, correct responsibilities, assigned intricacy levels, and a To-Be diagram.
Step 3 — Entity Implementation
An entity builder materializes the Blueprint into correctly formatted .md files, placed in the output directory and ready to use.
Every generated system follows this structure:
exports/{system-name}/
├── .agents/ # Google Antigravity (source of truth)
│ ├── workflows/ # Orchestrators + specialist agents
│ ├── skills/ # Reusable capability packages
│ ├── rules/ # Guardrails and compliance rules
│ ├── knowledge-base/ # Static documentation consulted on demand
│ ├── resources/ # Templates and support logic
│ ├── scripts/ # Procedural scripts (.md behavioral)
│ ├── hooks/ # Behavioral hook definitions
│ └── process-overview.md # Full system documentation
├── .claude/ # Claude Code (generated automatically)
│ ├── commands/ # Workflows converted to commands
│ ├── agents/ # Specialist agents
│ ├── skills/, rules/, ... # Direct copies
│ ├── scripts/ # Executable scripts (.sh/.py)
│ └── settings.json # Permissions + hooks configuration
├── .codex/ # OpenAI Codex (compiled from .agents/)
│ ├── agents/ # TOML agent definitions
│ ├── skills/, rules/, ... # Direct copies
│ ├── hooks/ # Hook docs + JSON fragments
│ ├── hooks.json # Merged hook configuration
│ └── config.toml # Codex configuration
├── CLAUDE.md # Root-level context for Claude Code
├── AGENTS.md # Root-level context for OpenAI Codex
├── VERSION # Semantic version (e.g. 0.1.0)
├── system-overview.md # Entity inventory + reading strategy
├── process-overview.md # Full system documentation
├── qa-report.md # QA audit trail
├── context-ledger/ # Session records (content git-ignored)
└── memory/ # Lightweight session snapshots (git-ignored)
Example: assistant-documentation-generator — generated entirely by AiAgentArchitect:
- 5 specialist agents (content analyzer, doc builder, auditor, evaluator, optimizer)
- 4 skills, 4 rules, 3 knowledge-base files, 1 resource
- Built-in QA Layer (Auditor + Evaluator + Optimizer)
- Exported to Google Antigravity, Claude Code, and OpenAI Codex
Once a system is exported, you can iterate on it without starting from scratch. Each iteration creates its own git branch for safe, reversible changes.
Export first (one-time setup):
bash scripts/export-system.sh my-systemThis initializes the system as an independent Git repo with version v0.1.0.
Iterate — use the iteration command to modify the system:
/com-iterate-system
Three modes are available:
| Mode | When | What Happens |
|---|---|---|
| PATCH | Fix or update specific entities | Entity builder edits in place → patch bump |
| REFACTOR | Reorganize architecture | Architecture designer produces delta blueprint → minor bump |
| EVOLVE | Add new capabilities | Mini-discovery → architecture → implementation → minor/major bump |
Each iteration creates a branch (iter/0.2.0-add-email-skill). When ready:
/com-publish-system
This merges to main, tags the version, and pushes to your remote.
Every session leaves a trace so you can resume exactly where you left off — on any project.
context-ledger/— full session records with step outputs and reasoning traces. One file per session (YYYY-MM-DD-HH-MM-{project}.md). Used by the workflow for exact state reconstruction.memory/— lightweight snapshots (~1–2 KB) for fast startup. Loaded at workflow start to restore project name, last checkpoint, and active state without reading the full ledger.
Both directories live at the project root (and at the root of every generated system), not inside .agents/ or .claude/, so they are accessible to both platforms. Their content is git-ignored; only the directories themselves are tracked.
When wor-agentic-architect starts and detects prior context for a project, it presents a resume summary and asks whether to continue, start a new session, or switch projects.
Every system is built from 10 entity types:
| Entity | Prefix | Role |
|---|---|---|
| Workflow | wor- |
Orchestrator — coordinates agents and steps |
| Agent Specialist | age-spe- |
Executes a specific domain of responsibility |
| Agent Supervisor | age-sup- |
Reviews or validates output from other agents |
| Skill | ski- |
Reusable capability package (tool, API, protocol) |
| Command | com- |
Direct action or saved procedure for frequent tasks |
| Rule | rul- |
Constraint that guarantees quality and consistency |
| Knowledge-base | kno- |
Static context consulted on demand |
| Resources | res- |
Support documents extending other entities |
| Script | scp- |
Executable automated procedure (validation, deploy) |
| Hook | hok- |
Event-driven trigger for automated actions |
- Google Antigravity — reads
.agents/structure - Claude Code — reads
.claude/structure (auto-synced) - OpenAI Codex — reads
.codex/structure (compiled from.agents/) - Python 3.10+ (for
build-codex.py) fswatch(optional, for real-time sync):brew install fswatch
Google Antigravity — type the slash command in the chat:
/wor-agentic-architect
Claude Code — same slash command from the command palette:
/wor-agentic-architect
OpenAI Codex — the workflows are compiled to TOML agents, invocable from the Codex terminal.
All three platforms run the same logic. Antigravity reads .agents/, Claude Code reads .claude/, Codex reads .codex/.
Pre-fill a template before starting to skip most questions:
exports/template/%Master - Docs/template-input-architect.md ← full systems
exports/template/%Master - Docs/template-input-express.md ← single entities
→ Full usage guide, stage walkthrough, and checkpoint reference: USAGE.md
AiAgentArchitect uses a triple-platform architecture: every entity lives in .agents/ (Google Antigravity, source of truth), .claude/ (Claude Code, bidirectional sync), and .codex/ (OpenAI Codex, one-way compilation).
.agents/ ← Source of truth (Google Antigravity)
.claude/ ← Auto-synced mirror (Claude Code)
.codex/ ← Compiled output (OpenAI Codex) — never edit directly
exports/ ← Output directory for generated systems
└── template/ ← Starter template for new systems
└── {system}/ ← Flat triple-platform structure (.agents/ + .claude/ + .codex/)
context-ledger/ ← Session records per project (content git-ignored)
memory/ ← Lightweight session snapshots (content git-ignored)
system-overview.md ← Full entity inventory for fast session startup
scripts/ ← sync-dual.sh, build-codex.py, and utilities
See DUAL-SYSTEM.md for full sync documentation.
Every session runs a three-role quality cycle automatically — no setup required.
- Auditor — verifies rule compliance after each approved checkpoint. Reads rules from disk at audit time. Never modifies anything.
- Evaluator — scores each phase on four dimensions: Completeness, Quality, Compliance, and Efficiency. Produces a weighted scorecard at process close.
- Optimizer — reads the complete audit and score history, detects recurring patterns, and generates prioritized improvement proposals. Never applies them automatically.
QA output is appended to a single qa-report.md at the root of the generated system. The cycle is non-blocking: it never stops execution, only accumulates evidence.
→ Full QA specification: QA-SYSTEM.md
- QA System — Audit, scoring, and optimization cycle
- Memory System — Cross-session quick-start snapshots
- Context Ledger System — Full session traceability
- Changelog System — Version history at two levels
- Repository System — Entity cross-reference index
- Branch & Publication System — Iteration lifecycle
Have an idea or found something to improve? Open an issue.