moai-library-toon

Standard Agent YAML Structure

```yaml

# {agent-name}.agent.yaml

agent:

metadata:

id: "{bmad_folder}/module/agents/{name}.md"

name: "Display Name"

title: "Agent Title"

icon: "emoji"

module: "module-code" # Optional: for module-scoped agents

persona:

role: "Expert Title"

identity: "Background, expertise, and approach description"

communication_style: "How the agent communicates with users"

principles: |

- Core principle 1

- Core principle 2

- Core principle 3

critical_actions: # MANDATORY steps on activation

- "FIRST: Read all context before any action"

- "SECOND: Validate inputs against requirements"

- "THIRD: Execute with full audit trail"

menu:

- trigger: command-name

workflow: "{project-root}/{bmad_folder}/module/workflows/workflow-name/workflow.yaml"

description: "What this command does"

- trigger: another-command

exec: "shell command to execute"

description: "Direct shell execution"

- trigger: load-template

tmpl: "{project-root}/{bmad_folder}/module/templates/template.md"

description: "Display template file"

```

Menu Command Types (6 Types)

| Type | Purpose | Example |

|------|---------|---------|

| workflow | Execute multi-step workflow | workflow: "{path}/workflow.yaml" |

| exec | Run shell command | exec: "npm test" |

| action | Perform named action | action: "validate_schema" |

| tmpl | Display template file | tmpl: "{path}/template.md" |

| data | Load data file | data: "{path}/data.json" |

| validate-workflow | Validate workflow structure | validate-workflow: "{path}/" |

Example: MoAI Developer Agent

```yaml

# expert-backend.agent.yaml

agent:

metadata:

id: ".claude/agents/moai/expert-backend.md"

name: expert-backend

title: Backend Expert Agent

icon: "🔧"

persona:

role: Senior Backend Engineer

identity: Expert in API design, database integration, and server architecture with deep knowledge of Python, TypeScript, and cloud platforms.

communication_style: "Technical and precise. References file paths and line numbers. Provides code examples."

principles: |

- Follow TRUST 5 quality standards

- Red-green-refactor TDD cycle

- API-first design approach

- Comprehensive error handling

- Performance-conscious implementation

critical_actions:

- "READ existing codebase structure before implementation"

- "VERIFY API contracts match SPEC requirements"

- "WRITE tests before implementation code"

- "VALIDATE all endpoints with integration tests"

menu:

- trigger: implement-api

workflow: "{project-root}/.claude/workflows/api-implementation/workflow.yaml"

description: "Implement API endpoints from SPEC"

- trigger: design-schema

workflow: "{project-root}/.claude/workflows/schema-design/workflow.yaml"

description: "Design database schema"

- trigger: run-tests

exec: "pytest tests/ -v --cov"

description: "Run backend test suite"

```

---

Standard Workflow YAML Structure

```yaml

# workflow.yaml

name: workflow-name

description: "What this workflow accomplishes"

author: "Author Name"

# Configuration references (runtime variable resolution)

config_source: "{project-root}/{bmad_folder}/module/config.yaml"

output_folder: "{config_source}:output_folder"

user_name: "{config_source}:user_name"

communication_language: "{config_source}:communication_language"

# Project context (glob pattern)

project_context: "**/project-context.md"

# Workflow components

installed_path: "{project-root}/{bmad_folder}/module/workflows/workflow-name"

instructions: "{installed_path}/instructions.md"

checklist: "{installed_path}/checklist.md"

# Workflow settings

standalone: true

web_bundle: false

```

Runtime Variable Substitution

| Variable | Source | Description |

|----------|--------|-------------|

| {project-root} | Auto-detect | Project root directory |

| {bmad_folder} | Config | Usually .claude or .bmad |

| {config_source}:key | YAML lookup | Read value from config file |

| {installed_path} | Computed | Current workflow directory |

| {date} | System | Current date (system-generated) |

Example: MoAI TDD Workflow

```yaml

# .claude/workflows/tdd-implementation/workflow.yaml

name: tdd-implementation

description: "Execute RED-GREEN-REFACTOR cycle for SPEC implementation"

author: "MoAI-ADK"

# Configuration

config_source: "{project-root}/.moai/config/config.json"

test_coverage_target: "{config_source}:constitution.test_coverage_target"

enforce_tdd: "{config_source}:constitution.enforce_tdd"

# Project context

project_context: "**/CLAUDE.md"

spec_file: "{project-root}/.moai/specs/SPEC-{spec_id}/SPEC.md"

# Workflow components

installed_path: "{project-root}/.claude/workflows/tdd-implementation"

instructions: "{installed_path}/instructions.md"

checklist: "{installed_path}/checklist.md"

validation: "{installed_path}/validation-rules.md"

# Micro-file steps

steps:

- name: "Phase 1 - RED"

file: "{installed_path}/step-01-red.md"

checkpoint: true

- name: "Phase 2 - GREEN"

file: "{installed_path}/step-02-green.md"

checkpoint: true

- name: "Phase 3 - REFACTOR"

file: "{installed_path}/step-03-refactor.md"

checkpoint: false

standalone: true

web_bundle: false

```

---

Config YAML Structure

```yaml

# config.yaml

project:

name: "Project Name"

version: "1.0.0"

language: "python"

settings:

output_folder: ".moai/output"

user_name: "Developer"

communication_language: "ko"

document_output_language: "en"

constitution:

enforce_tdd: true

test_coverage_target: 90

agents:

enabled:

- expert-backend

- expert-frontend

- manager-tdd

default_model: "sonnet"

```

Variable Reference Syntax

```yaml

# In workflow.yaml, reference config values:

output_folder: "{config_source}:settings.output_folder"

test_target: "{config_source}:constitution.test_coverage_target"

# Nested key access with dot notation

user_lang: "{config_source}:settings.communication_language"

```

---

TOON YAML vs JSON Comparison

```yaml

# TOON YAML (45 tokens)

agent:

metadata:

name: expert-backend

title: Backend Expert

persona:

role: Senior Engineer

principles: |

- TDD first

- API-first design

```

```json

// JSON equivalent (78 tokens)

{

"agent": {

"metadata": {

"name": "expert-backend",

"title": "Backend Expert"

},

"persona": {

"role": "Senior Engineer",

"principles": ["TDD first", "API-first design"]

}

}

}

```

Token Savings: 42% reduction

Cumulative Savings per Agent

| Component | JSON Tokens | TOON YAML | Reduction |

|-----------|-------------|-----------|-----------|

| Metadata | 80 | 35 | 56% |

| Persona | 150 | 70 | 53% |

| Critical Actions | 100 | 50 | 50% |

| Menu (5 items) | 200 | 90 | 55% |

| Total | 530 | 245 | 54% |

---

Legacy TOON v2 (CSV-like)

```

# OLD FORMAT - DEPRECATED

scripts[N]{name,skill,lines,deps}:

script1.py,skill-a,200,2

script2.py,skill-b,300,3

```

New TOON v4 (YAML-based)

```yaml

# NEW FORMAT - RECOMMENDED

scripts:

- name: script1.py

skill: skill-a

lines: 200

deps: 2

- name: script2.py

skill: skill-b

lines: 300

deps: 3

```

Migration Note: CSV-like format is still valid for tabular data, but YAML is preferred for agent/workflow definitions.

---

For detailed patterns:

• Core Implementation: modules/core.md
• Advanced Patterns: modules/advanced-patterns.md
• BMAD Integration: modules/bmad-integration.md (NEW)

---

Agents:

• builder-workflow - UV script generation with TOON patterns
• builder-agent - Agent YAML creation
• builder-skill - Skill definition with TOON metadata

Skills:

• moai-foundation-core - Execution rules and delegation
• moai-foundation-claude - Claude Code configuration
• moai-lang-unified - Multi-language patterns

Commands:

• /moai:1-plan - SPEC generation with TOON metadata
• /moai:2-run - TDD execution with TOON workflows
• /moai:3-sync - Documentation with TOON configs

---

TOON v4.0 patterns are inspired by [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) v6.0.0-alpha.12:

• Agent YAML structure (*.agent.yaml)
• Workflow YAML structure (workflow.yaml)
• Runtime variable substitution patterns
• Menu command system (6 types)
• Configuration cascade pattern

Key Difference: MoAI uses Markdown directly (no XML compilation) while maintaining BMAD's clean YAML patterns.

---

Version: 4.0.0

Status: Active (BMAD YAML Patterns)

Last Updated: 2025-12-01