# AIWG Architecture Overview
> **Version**: 2026.5.0+
> **Audience**: Developers, technical leads, CISOs, anyone wanting a visual mental model of AIWG before reading the deeper guides
> **Status**: Mermaid versions inline; polished Gemini-rendered images in `architecture-overview/images/` (placeholders below — see [#1248](https://git.integrolabs.net/roctinam/aiwg/issues/1248) for the prompt set)
This document is the visual entry point for understanding what AIWG is, what it does at deploy time, what it does at runtime, and what's optional. Each section pairs a MermaidJS diagram (renders inline in markdown) with a placeholder for a polished Gemini-generated illustration (drop in `./architecture-overview/images/NN-name.png` and the markdown picks it up).
Deeper guides:
- [`docs/how-it-works.md`](how-it-works.md) — prose walkthrough of the same concepts
- [`docs/discovery-and-kernel-skills.md`](discovery-and-kernel-skills.md) — kernel-vs-standard skill model in depth
- [`docs/integrations/hermes-quickstart.md`](integrations/hermes-quickstart.md) — Hermes-specific integration
---
## 1. AIWG is a deploy-time tool — runtime-invisible
`aiwg use` runs once, copies plain-text files into the directories your AI platform reads, builds an artifact index, and exits. Nothing AIWG produces is a daemon, a service, or a network listener. Once the files land, your platform's native loader handles everything — AIWG can step out of the way.
```mermaid
flowchart LR
subgraph Source["AIWG framework source"]
direction TB
KERN[20 kernel skills
~15-25k tokens]
STD[~460 standard skills
read from $AIWG_ROOT]
AGENT[200+ agents]
RULES[60+ rules]
TPL[100+ templates]
end
CLI([aiwg use sdlc
--provider X]) --> DEPLOY
subgraph DEPLOY["Deploy step (one-shot)"]
direction TB
COPY[Copy kernel skills, agents,
rules to provider-native dirs]
INDEX[Build artifact index
~/.local/share/aiwg/index/]
CTX[Emit AIWG.md + AGENTS.md
at project root]
end
Source --> CLI
DEPLOY --> Project
subgraph Project["Your project (after deploy)"]
direction TB
PLAT[.claude/skills/
.codex/agents/
.warp/agents/ ...]
AIWGMD[AIWG.md / .hermes.md /
WARP.md / AGENTS.md]
ART[.aiwg/
requirements/
architecture/
...]
end
Project --> SESS
subgraph SESS["AI session (Claude / Codex / Hermes / etc.)"]
direction TB
NATIVE[Platform-native loader
reads provider dir]
DISC([Optional: aiwg discover
+ aiwg show])
end
classDef optional stroke-dasharray: 5 5,fill:#fef9e7
class DISC optional
class INDEX optional
```
---
## 2. The two-tier skill model — kernel vs standard
AIWG ships **480+ skills**. Platform context windows can't fit them all. So AIWG splits them: **20 kernel skills** are always loaded into the platform's flat skill listing; the remaining **~460 standard skills** stay at `$AIWG_ROOT` and reach the agent only when queried via the artifact index.
```mermaid
flowchart TB
subgraph KERNEL["Kernel tier — 20 skills, always loaded"]
direction LR
K1[9 framework quickrefs
sdlc / research / forensics /
marketing / media-curator /
security-eng / knowledge-base /
ops / aiwg-utils-quickref]
K2[10 self-maintenance ops
steward / aiwg-doctor / aiwg-refresh /
aiwg-status / aiwg-help / use /
aiwg-regenerate / aiwg-issue /
aiwg-pr / aiwg-mission]
end
subgraph STANDARD["Standard tier — ~460 skills, read from $AIWG_ROOT"]
direction LR
S1[SDLC workflows
intake-wizard, sdlc-accelerate,
flow-deploy-to-production,
address-issues, ...]
S2[Domain skills
media-curator, research-,
forensics-, marketing-, ...]
S3[Specialized
aiwg-orchestrate hermes-only,
per-provider regenerators, ...]
end
AGENT([AI session
natural-language request])
AGENT -->|Always sees| KERNEL
AGENT -.->|Optionally queries| INDEX[(aiwg index
artifact index)]
INDEX -.->|aiwg discover phrase| STANDARD
STANDARD -.->|aiwg show name| AGENT
classDef optional stroke-dasharray: 5 5,fill:#fef9e7
class INDEX optional
class STANDARD optional
```
See [`docs/discovery-and-kernel-skills.md`](discovery-and-kernel-skills.md) for the full kernel inventory, why no-copy is the default for standard skills, and the per-provider deployment paths.
---
## 3. The discover → show flow (the optional layer)
When the kernel skills don't directly answer a user request, the agent reaches into the standard tier via two RPC-style commands: `aiwg discover ""` ranks all 400+ artifacts by capability, then `aiwg show ` fetches the body. This flow is optional — agents can work entirely from the kernel surface for many requests — but when it's needed, the cost is bounded and the answer comes from the indexed ranking, not from a literal-string grep.
```mermaid
sequenceDiagram
participant User
participant Agent as AI session
participant CLI as aiwg CLI
participant Index as artifact index
(~/.local/share/aiwg/)
participant FS as $AIWG_ROOT
(framework source)
User->>Agent: "deploy this to production"
Note over Agent: Kernel skill aiwg-utils-quickref
doesn't match. Run discover.
Agent->>CLI: aiwg discover "deploy production"
CLI->>Index: rank artifacts by capability + triggers
Index-->>CLI: top 3 results with paths + scores
CLI-->>Agent: flow-deploy-to-production [0.51]
+ 2 alternatives
Agent->>CLI: aiwg show skill flow-deploy-to-production
CLI->>FS: read SKILL.md
FS-->>CLI: full skill body
CLI-->>Agent: SKILL.md content (instructions)
Agent->>User: Apply the skill's protocol
```
The **discover-first protocol** (Rule 1.5 in [`skill-discovery.md`](../agentic/code/addons/aiwg-utils/rules/skill-discovery.md)) makes this the mandatory first move for any query mentioning AIWG, a framework name, or a capability keyword — `Grep`/`Glob`/`Read` against provider artifact directories is forbidden until discover has been consulted in the session. See [issue #1249](https://git.integrolabs.net/roctinam/aiwg/issues/1249) for the rationale.
---
## 4. What's optional — Minimal vs Standard vs Full
Most AIWG users live happily in one of the first two tiers. The Full tier exists; it doesn't punish you for ignoring it.
```mermaid
flowchart TB
START{What do you want?}
START -->|"Just AI personas
and basic prompts"| MIN
START -->|"Plus structured
artifacts (SDLC, etc.)"| MID
START -->|"Plus self-maintaining
discovery + orchestration"| FULL
subgraph MIN["Minimal — agents only"]
direction TB
M1["aiwg use sdlc"]
M2[Deploys agents/rules/templates
to your provider dir]
M3[Use natural language
in the platform as normal]
M4[Index built but ignorable]
end
subgraph MID["Standard — agents + artifacts"]
direction TB
D1["aiwg use sdlc + create .aiwg/"]
D2[Use SDLC slash commands
or natural-language requests]
D3[Artifacts persist across sessions]
D4[Index queryable but optional]
end
subgraph FULL["Full — discovery + utilities"]
direction TB
F1["aiwg use all"]
F2[Agents query aiwg discover
for non-kernel skills]
F3[Optional utilities: ralph,
mc, daemon, mcp, schedule]
F4[Cross-session memory,
background orchestration]
end
MIN -.->|"upgrade anytime by
adding usage"| MID
MID -.->|"upgrade anytime by
using more commands"| FULL
```
The upgrade arrows go both ways. Nothing is forced. The opt-in utilities (Ralph for agent loops, Mission Control for background orchestration, Daemon for cross-session persistence, MCP for tool-host integration, Schedule for cron-style automation) only run when you invoke them.
---
## 5. The `.aiwg/` lifecycle
`.aiwg/` is your project's structured workspace — every SDLC phase has a home, the working scratch has a clearly disposable bin, and what you commit to git is your choice. AIWG manages the structure; you choose what's permanent.
```mermaid
flowchart LR
IDEA[Idea / project intent]
IDEA --> INTAKE
subgraph PHASES["SDLC phases — each writes to .aiwg/"]
direction TB
INTAKE[.aiwg/intake/]
REQ[.aiwg/requirements/]
ARCH[.aiwg/architecture/]
PLAN[.aiwg/planning/]
TEST[.aiwg/testing/]
SEC[.aiwg/security/]
DEPLOY[.aiwg/deployment/]
end
INTAKE --> REQ --> ARCH
ARCH --> PLAN
PLAN --> TEST
PLAN --> SEC
PLAN --> DEPLOY
PHASES --> WORK
WORK[.aiwg/working/
scratch — safe to delete]
PHASES --> REPORTS[.aiwg/reports/
auto-generated status]
PHASES --> ARCHIVE[.aiwg/archive/
versioned snapshots]
PHASES --> FRAME[.aiwg/frameworks/registry.json
which frameworks are deployed]
GIT([git repo])
PHASES -.->|"commit artifacts
(your choice)"| GIT
WORK -.->|"ignore"| GIT
classDef optional stroke-dasharray: 5 5,fill:#fef9e7
class WORK optional
class ARCHIVE optional
```
`.aiwg/working/` is explicitly ephemeral — safe to delete, typically `.gitignore`'d. Whether to commit the rest of `.aiwg/` is a team decision; many teams commit everything except `working/` and the optional `archive/` directory.
---
## 6. Hermes context-file priority (first-match-wins)
[Hermes Agent](https://github.com/NousResearch/hermes-agent) loads exactly **one** project-context file per turn, by priority. AIWG always emits `.hermes.md` (the priority-1 file), so `AGENTS.md` and `CLAUDE.md` remain valid for Claude Code, Codex, and other providers without interfering with Hermes.
```mermaid
flowchart TB
TURN([Hermes turn starts])
TURN --> CWD[Get cwd]
CWD --> WALK[Walk up to git root
looking for .hermes.md or HERMES.md]
WALK --> H{".hermes.md or
HERMES.md found?"}
H -->|Yes| HLOAD[Load .hermes.md
STOP — winner]
H -->|No| A{"AGENTS.md or
agents.md in cwd?"}
A -->|Yes| ALOAD[Load AGENTS.md
STOP — winner]
A -->|No| C{"CLAUDE.md or
claude.md in cwd?"}
C -->|Yes| CLOAD[Load CLAUDE.md
STOP — winner]
C -->|No| R{".cursorrules or
.cursor/rules/*.mdc?"}
R -->|Yes| RLOAD[Load .cursorrules
STOP — winner]
R -->|No| NONE[No project context loaded]
HLOAD --> CAP[Cap at 20,000 chars
head/tail truncate above]
ALOAD --> CAP
CLOAD --> CAP
RLOAD --> CAP
CAP --> PROMPT[Inject into system prompt
this turn]
NONE --> PROMPT
classDef winner fill:#d4edda
class HLOAD,ALOAD,CLOAD,RLOAD winner
```
Source: `agent/prompt_builder.py:1410-1436` in the Hermes Agent repo. See [`docs/integrations/hermes-quickstart.md`](integrations/hermes-quickstart.md) for the full integration walkthrough.
---
## 7. Multi-platform deploy — one source, ten targets
AIWG's parity model: write/configure once, deploy to whichever AI platforms your team uses. The source-of-truth tree (`agentic/code/`) translates to ten provider-native target conventions through `aiwg use --provider `.
```mermaid
flowchart LR
subgraph SOURCE["AIWG framework source ($AIWG_ROOT)"]
direction TB
AG[agents/
200+]
SK[skills/
400+]
CM[commands/
100+]
RL[rules/
60+]
BE[behaviors/
OpenClaw native]
end
CLI([aiwg use sdlc
--provider X])
SOURCE --> CLI
CLI --> CC[".claude/agents/
.claude/skills/
.claude/rules/"]
CLI --> CX[".codex/agents/
~/.codex/skills/
~/.codex/prompts/"]
CLI --> CP[".github/agents/
.github/skills/
.github/instructions/"]
CLI --> CR[".cursor/agents/
.cursor/skills/
.cursor/rules/"]
CLI --> WP[".warp/agents/
.warp/skills/
+ WARP.md aggregate"]
CLI --> WS[".windsurf/agents/
.windsurf/skills/
+ AGENTS.md"]
CLI --> FA[".factory/droids/
.factory/skills/
.factory/rules/"]
CLI --> OC[".opencode/agent/
.opencode/skill/
.opencode/rule/"]
CLI --> HE[".hermes.md + AGENTS.md
~/.hermes/skills/
MCP optional"]
CLI --> OW["~/.openclaw/agents/
~/.openclaw/skills/
~/.openclaw/behaviors/"]
classDef claude fill:#e8f4ff
classDef codex fill:#fef9e7
classDef hermes fill:#fde9d9
class CC claude
class CX,CP,CR,WP,WS,FA,OC,OW codex
class HE hermes
```
Switching platforms doesn't require redoing your team's agent/skill/rule investment — same source, different output convention. Hermes deploys files like the others (AGENTS.md + `.hermes.md` + `~/.hermes/skills/`) and is reached through the discover-first CLI; MCP is an optional global hook, not a requirement (validated v2026.5.13, #1527; modernization tracked in #1533).
---
## 8. Session reload after `aiwg use`
Every AI platform caches its agent/skill registry at session start. After `aiwg use`, a running session retains its old registry until the right invalidation step runs — and the right step is different per platform. `aiwg use` prints the correct step in its post-deploy "Session reload required" section so operators don't have to guess.
```mermaid
flowchart TB
DEPLOY([aiwg use completes
new files on disk])
DEPLOY --> Q{Was your AI session
already running?}
Q -->|No — fresh session| OK[Agents/skills load
on first turn ✓]
Q -->|Yes — running session| RELOAD{Which platform?}
RELOAD -->|Claude Code
Codex
Cursor
OpenCode
Factory
OpenClaw| RESTART[Restart the session
close + reopen]
RELOAD -->|Copilot
VS Code| WIN["Developer: Reload Window"]
RELOAD -->|Warp| TAB[Open a fresh Warp tab
WARP.md re-read on tab start]
RELOAD -->|Windsurf| WORK[Reload the workspace
AGENTS.md re-parsed]
RELOAD -->|Hermes| HCMD["/reload-skills
/reload-mcp
no restart needed"]
RESTART --> DONE[✓ New agents/skills visible]
WIN --> DONE
TAB --> DONE
WORK --> DONE
HCMD --> DONE
classDef good fill:#d4edda
classDef hermes fill:#fff3cd
class HCMD hermes
class DONE good
```
Hermes is the friendliest case — `/reload-skills` and `/reload-mcp` slash commands invalidate without a chat restart. Every other platform requires a session/window/tab reload, which is normal cache-invalidation behavior — not an AIWG-specific friction.
---
## Image generation status
Each diagram above has a polished image placeholder. Generation prompts (three aesthetic options — illustrated computing iconography, illustrated editorial, monospace-terminal) live on [issue #1248](https://git.integrolabs.net/roctinam/aiwg/issues/1248):
- [v4 (illustrated computing iconography — recommended)](https://git.integrolabs.net/roctinam/aiwg/issues/1248#issuecomment-41143)
- [v3 (monospace-terminal — for technical docs preferring that aesthetic)](https://git.integrolabs.net/roctinam/aiwg/issues/1248#issuecomment-41131)
- [v2 (illustrated editorial — for marketing/announcement copy)](https://git.integrolabs.net/roctinam/aiwg/issues/1248#issuecomment-41107)
All three sets share the 1-8 numbering. Generated images drop at `docs/architecture-overview/images/NN-name.png` and the placeholders above pick them up automatically.
---
## Related guides
- [`docs/how-it-works.md`](how-it-works.md) — the prose walkthrough of these same concepts
- [`docs/discovery-and-kernel-skills.md`](discovery-and-kernel-skills.md) — kernel/standard model in depth, verification steps
- [`docs/integrations/hermes-quickstart.md`](integrations/hermes-quickstart.md) — Hermes integration, capabilities catalog
- [`docs/cli-reference.md`](cli-reference.md) — complete CLI command reference
- [`.claude/rules/skill-discovery.md`](../agentic/code/addons/aiwg-utils/rules/skill-discovery.md) — the discover-first protocol (Rule 1.5)