This section is for developers who want to take MoAI-ADK apart and see how it works inside. Once you are comfortable with the basic workflow (plan → run → sync), this is where you can see how the harness is actually assembled.

Info
The documents in this section cover mainly the third of v3.0’s three core values — Tokenomics (Token Economics), Agentic Loop Engineering, and the Agentic Harness — namely the implementation details of the harness. The secret to making agents write good code is not the model, but the design of the environment around the model.

How the Harness Is Assembled

The MoAI-ADK harness operates as seven components arranged in layers. The further down you go, the more dynamic the layer.

flowchart TD
    CLAUDE["CLAUDE.md
Project constitution"] --> SETTINGS["settings.json
Permissions and environment"]
    CLAUDE --> RULES[".claude/rules/
Conditional rules"]

    SETTINGS --> HOOKS["Hooks
Event automation"]
    SETTINGS --> MCP["MCP servers
External tool connections"]

    RULES --> SKILLS["Skills
Expertise modules"]
    SKILLS --> AGENTS["Agents
Specialist agents"]

    AGENTS --> BUILDERS["Builder Agents
Extension generators"]

If CLAUDE.md is the project’s constitution, settings.json is the permission boundary, hooks are the deterministic control points, and skills and agents are the hands doing the actual work. And Builder Agents can regenerate this entire structure — a recursive architecture where the harness builds the harness.

Cost — Tokenomics

Topic	Description
Tokenomics Overview	The paradox of unit prices falling 98% while costs rise 320%, and the answer
Token Budget	Token Circuit Breaker · verify-diet · context diet
No-Haiku 3-Tier	The DeepSWE-leaderboard rationale and the 3-tier policy
Profile Matrix	The single profile axis of 11 agents × `{model, effort}` across 33 cells
statusline	An always-on dashboard for context usage, cache hit rate, and rate limits

Self-improvement — Agentic Loop Engineering

Topic	Description
Self-Evolving System	The 4-tier learning ladder (observation → heuristic → rule → auto-update)
Autonomous Loops	The condition-declared and diagnostic-driven loops of `/moai goal` and `/moai loop`
Decision Memory	The observation system that learns user choices
ultracode Workflows	Dynamic workflow orchestration (multi-agent fan-out)

Quality-control — Agentic Harness

Topic	Description
Skill Guide	The skill system that gives AI specialized expertise
Agent Guide	The system of specialized AI task performers
Builder Agents Guide	Creating skills, agents, commands, and plugins
Harness v4 Builder	Generate a project-specific harness from a single natural-language sentence
Harness Profiles and Evaluation System	3-level verification depth + 4-dimension scoring
Catalog System	The 3-tier manifest and slim init

Control and Automation

Topic	Description
Hooks Guide	Event-driven automation scripts
Hooks Reference	The list of hooks MoAI-ADK ships
settings.json Guide	Managing Claude Code global settings
config Sections	Reference for the `.moai/config/sections/*.yaml` settings
CLAUDE.md Guide	The project instruction file system
@MX Tags	Inline annotations between agents for context, invariant contracts, and danger zones
Security Notes	The permission stack and sandboxing

Info
Each document can be read independently. If you want a systematic understanding of the whole architecture, however, we recommend the order Skill Guide → Agent Guide → Builder Agents — the flow from knowledge modules to performers, and from performers to generators, mirrors the recursive structure of the harness itself.

Advanced Topics

How the Harness Is Assembled

Table of Contents

Cost — Tokenomics

Self-improvement — Agentic Loop Engineering

Quality-control — Agentic Harness

Control and Automation