---
name: moai-library-toon
description: TOON Format Specialist - YAML-based token-efficient agent/workflow definitions inspired by BMAD Method patterns
version: 4.0.0
modularized: true
last_updated: 2025-12-01
compliance_score: 95
auto_trigger_keywords:
  - toon
  - agent-yaml
  - workflow-yaml
  - bmad
  - token-efficient
  - agent-definition
---

## Quick Reference (30 seconds)

**TOON v4.0** = YAML-based hierarchical format inspired by BMAD Method

TOON (Token-Optimized Object Notation) adopts BMAD's clean YAML patterns for agent and workflow definitions. This provides 40-60% token reduction while maintaining full expressiveness.

**Key Insight**: BMAD's `*.agent.yaml` and `workflow.yaml` ARE the optimal token-efficient format.

**Core Benefits**:
- 40-60% token reduction vs JSON
- Clean hierarchical YAML structure
- Runtime variable substitution (`{project-root}`, `{config_source}:key`)
- Human-readable and LLM-parseable
- Proven in BMAD Method v6 (650+ files, 25+ agents)

---

## TOON Agent Definition Pattern (BMAD-Style)

### 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"
```

---

## TOON Workflow Definition Pattern (BMAD-Style)

### 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
```

---

## TOON Configuration Pattern

### 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"
```

---

## Token Efficiency Analysis

### 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%** |

---

## Migration from Legacy TOON

### 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.

---

## Implementation Modules

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

---

## Works Well With

**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

---

## BMAD Method Attribution

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