MoAI Foundation Core

Foundational principles and architectural patterns that power MoAI-ADK's AI-driven development workflow.

Core Philosophy: Quality-first, test-driven, modular, and efficient AI development through proven patterns and automated workflows.

Quick Reference (30 seconds)

What is MoAI Foundation Core? Six essential principles that ensure quality, efficiency, and scalability in AI-powered development:

• TRUST 5 Framework - Quality gate system (Test-first, Readable, Unified, Secured, Trackable)

• SPEC-First TDD - Specification-driven test-driven development workflow

• Delegation Patterns - Task orchestration via specialized agents (never direct execution)

• Token Optimization - 200K budget management and context efficiency

• Progressive Disclosure - Three-tier knowledge delivery (Quick → Implementation → Advanced)

• Modular System - File splitting and reference architecture for scalability

Quick Access:

• Quality standards → TRUST 5 Module

• Development workflow → SPEC-First TDD Module

• Agent coordination → Delegation Patterns Module

• Budget management → Token Optimization Module

• Content structure → Progressive Disclosure Module

• File organization → Modular System Module

• Agent catalog → Agents Reference Module NEW

• Command reference → Commands Reference Module NEW

• Security & constraints → Execution Rules Module NEW

Use Cases:

• New agent creation with quality standards

• New skill development with structural guidelines

• Complex workflow orchestration

• Token budget planning and optimization

• Documentation architecture design

• Quality gate configuration

Implementation Guide (5 minutes)

1. TRUST 5 Framework - Quality Assurance System

Purpose: Automated quality gates ensuring code quality, security, and maintainability.

Five Pillars:

Pillar Requirement Validation Failure Action

Test-first ≥85% coverage pytest --cov Block merge, generate tests

Readable Clear naming ruff linter Warning, suggest refactor

Unified Consistent patterns black, isort Auto-format or warn

Secured OWASP compliance security-expert Block merge, review

Trackable Clear commits Git regex Suggest format

Integration Points:

• Pre-commit hooks → Automated validation

• CI/CD pipelines → Quality gate enforcement

• Agent workflows → core-quality validation

• Documentation → Quality metrics

Detailed Reference: TRUST 5 Framework Module

2. SPEC-First TDD - Development Workflow

Purpose: Specification-driven development ensuring clear requirements before implementation.

Three-Phase Workflow:

Phase 1: SPEC (/moai:1-plan) workflow-spec → EARS format Output: .moai/specs/SPEC-XXX/spec.md Execute /clear (saves 45-50K tokens)

Phase 2: TDD (/moai:2-run) RED: Failing tests GREEN: Passing code REFACTOR: Optimize Validate: ≥85% coverage

Phase 3: Docs (/moai:3-sync) API documentation Architecture diagrams Project reports

EARS Format:

• Ubiquitous: System-wide (always active)

• Event-driven: Trigger-based (when X, do Y)

• State-driven: Conditional (while X, do Y)

• Unwanted: Prohibited (shall not do X)

• Optional: Nice-to-have (where possible, do X)

Token Budget: SPEC 30K | TDD 180K | Docs 40K | Total 250K

Key Practice: Execute /clear after Phase 1 to initialize context.

Detailed Reference: SPEC-First TDD Module

3. Delegation Patterns - Agent Orchestration

Purpose: Task delegation to specialized agents, avoiding direct execution.

Core Principle: Alfred NEVER executes directly. All work via Task().

Delegation Syntax:

result = await Task( subagent_type="specialized_agent", prompt="Clear, specific task", context={"relevant": "data"} )

Three Patterns:

Sequential (dependencies):

design = Task(subagent_type="api-designer", prompt="Design API") code = Task(subagent_type="backend-expert", prompt="Implement", context={"design": design})

Parallel (independent):

results = await Promise.all([ Task(subagent_type="backend-expert", prompt="Backend"), Task(subagent_type="frontend-expert", prompt="Frontend") ])

Conditional (analysis-based):

analysis = Task(subagent_type="debug-helper", prompt="Analyze") if analysis.type == "security": Task(subagent_type="security-expert", prompt="Fix")

Agent Selection:

• Simple (1 file): 1-2 agents sequential

• Medium (3-5 files): 2-3 agents sequential

• Complex (10+ files): 5+ agents mixed

Detailed Reference: Delegation Patterns Module

4. Token Optimization - Budget Management

Purpose: Efficient 200K token budget through strategic context management.

Budget Allocation:

Phase Budget Strategy

SPEC 30K Load requirements only, /clear after

TDD 180K Selective file loading

Docs 40K Result caching, templates

Total 250K Phase separation

Token Saving Strategies:

• Phase Separation: /clear between phases

• After /moai:1-plan (saves 45-50K)

• When context > 150K

• After 50+ messages

Selective Loading: Load only necessary files

Context Optimization: 20-30K tokens target

Model Selection: Sonnet (quality) | Haiku (speed/cost)

Monitoring: /context command, track budget, suggest /clear

Cost Savings: Haiku 70% cheaper → 60-70% total savings

Detailed Reference: Token Optimization Module

5. Progressive Disclosure - Content Architecture

Purpose: Three-tier knowledge delivery balancing value with depth.

Three Levels:

Level Time Content Tokens

Quick Reference 30s Core principles 1,000

Implementation 5min Workflows, examples 3,000

Advanced 10+min Deep dives, edge cases 5,000

SKILL.md Structure (≤500 lines):

Quick Reference (30s)

Implementation Guide (5min)

Advanced Patterns (10+min)

Works Well With

Module Architecture:

• SKILL.md: Entry point, cross-references

• modules/: Deep dives, unlimited

• examples.md: Working samples

• reference.md: External links

File Splitting (when >500 lines):

SKILL.md (500 lines) Quick (80-120) Implementation (180-250) Advanced (80-140) References (10-20)

Overflow → modules/[topic].md

Detailed Reference: Progressive Disclosure Module

6. Modular System - File Organization

Purpose: Scalable file structure enabling unlimited content.

Standard Structure:

.claude/skills/skill-name/ SKILL.md # Core (≤500 lines) modules/ # Extended (unlimited) patterns.md examples.md # Working samples reference.md # External links scripts/ # Utilities (optional) templates/ # Templates (optional)

File Principles:

• SKILL.md: ≤500 lines, progressive disclosure, cross-references

• modules/: Topic-focused, no limits, self-contained

• examples.md: Copy-paste ready, commented

• reference.md: API docs, resources

Cross-Reference Syntax:

Details: Module Examples: Examples External: Reference

Discovery Flow: SKILL.md → Topic → modules/[topic].md → Deep dive

Detailed Reference: Modular System Module

Advanced Implementation (10+ minutes)

Cross-Module Integration

TRUST 5 + SPEC-First TDD:

spec = Task(subagent_type="workflow-spec", prompt="SPEC with TRUST 5") impl = Task(subagent_type="workflow-tdd", prompt="≥85% coverage", context={"spec": spec, "quality_gates": ["TRUST5"]}) validation = Task(subagent_type="core-quality", prompt="Validate TRUST 5", context={"implementation": impl})

Token-Optimized Delegation:

spec = Task(subagent_type="workflow-spec", prompt="Generate SPEC") execute_clear() # Save 45-50K results = await Promise.all([ Task(subagent_type="backend-expert", prompt="Backend", context={"spec_id": spec.id}), Task(subagent_type="frontend-expert", prompt="Frontend", context={"spec_id": spec.id}) ]) Task(subagent_type="workflow-docs", prompt="Docs", context={"results": results})

Progressive Agent Workflows:

quick = Task(subagent_type="debug-helper", prompt="Quick diagnosis") if quick.complexity == "high": detailed = Task(subagent_type="debug-helper", prompt="Detailed analysis") if detailed.requires_expert: expert = Task(subagent_type="security-expert", prompt="Deep dive")

Quality Validation

Pre-Execution:

def validate_execution_requirements(task, context): return all([ validate_security_clearance(task), validate_resource_availability(context), validate_quality_standards(task), validate_permission_compliance(task) ])

Post-Execution:

def validate_execution_results(result, task): validations = [ validate_output_quality(result), validate_security_compliance(result), validate_test_coverage(result), validate_documentation_completeness(result) ] if not all(validations): raise QualityGateError("Quality gate failures") return True

Error Handling

Delegation Failure:

try: result = Task(subagent_type="backend-expert", prompt="Complex task") except AgentExecutionError as e: analysis = Task(subagent_type="debug-helper", prompt=f"Analyze: {e}") if analysis.issue == "complexity": results = await Promise.all([ Task(subagent_type="backend-expert", prompt="Subtask 1"), Task(subagent_type="backend-expert", prompt="Subtask 2") ])

Token Budget Exceeded:

if token_usage > 150_000: execute_clear() context = {"spec_id": current_spec.id, "phase_results": summarize(previous_results)} Task(subagent_type="next-agent", prompt="Continue", context=context)

Works Well With

Agents:

• agent-factory - Create agents with foundation principles

• skill-factory - Generate skills with modular architecture

• core-quality - Automated TRUST 5 validation

• workflow-spec - EARS format specification

• workflow-tdd - RED-GREEN-REFACTOR execution

• workflow-docs - Documentation with progressive disclosure

Skills:

• moai-cc-claude-md - CLAUDE.md with foundation patterns

• moai-cc-configuration - Config with TRUST 5

• moai-cc-memory - Token optimization

• moai-core-ask-user-questions - User clarification

• moai-context7-integration - MCP integration

Commands:

• /moai:1-plan - SPEC-First Phase 1

• /moai:2-run - TDD Phase 2

• /moai:3-sync - Documentation Phase 3

• /moai:9-feedback - Continuous improvement

• /clear - Token management

Foundation Modules (Extended Documentation):

• Agents Reference - 26-agent catalog with 7-tier hierarchy

• Commands Reference - 6 core commands workflow

• Execution Rules - Security, Git strategy, compliance

Quick Decision Matrix

Scenario Primary Principle Supporting

New agent TRUST 5 + Delegation Token, modular

New skill Progressive + Modular TRUST 5, token

Workflow Delegation SPEC-First, token

Quality TRUST 5 SPEC-First

Budget Token Optimization Progressive, modular

Docs Progressive + Modular Token

Module Deep Dives:

• TRUST 5 Framework

• SPEC-First TDD

• Delegation Patterns

• Token Optimization

• Progressive Disclosure

• Modular System

• Agents Reference NEW

• Commands Reference NEW

• Execution Rules NEW

Full Examples: examples.md External Resources: reference.md

Version: 2.2.0 Last Updated: 2025-11-26 Status: Active (496 lines, within 500-line limit)