moai-library-toon

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

# {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)

Example: MoAI Developer Agent

# 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

# 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

Example: MoAI TDD Workflow

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

# 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

# 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

# TOON YAML (45 tokens)
agent:
  metadata:
    name: expert-backend
    title: Backend Expert
  persona:
    role: Senior Engineer
    principles: |
      - TDD first
      - API-first design

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

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)

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