/moai-foundation-core

name: moai-foundation-core
description: >
  Provides MoAI-ADK foundational principles including TRUST 5 quality framework,
  SPEC-First DDD methodology, delegation patterns, progressive disclosure,
  agent catalog reference, and token budget management (absorbed from moai-foundation-context).
  Use when referencing TRUST 5 gates, SPEC workflow, or context window optimization.

when_to_use: >
  Use for MoAI-ADK foundations: the TRUST 5 quality framework, SPEC-First
  DDD methodology, delegation patterns, progressive disclosure,
  token/context-window budget management, GEARS/EARS formats, and session
  handoff.

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Grep, Glob
user-invocable: false
metadata:
  version: "3.0.0"
  category: "foundation"
  status: "active"
  updated: "2026-07-10"
  modularized: "true"
  tags: "foundation, core, orchestration, agents, commands, trust-5, spec-first-ddd, token-budget, context-window, session-state"
  related-skills: "moai-foundation-cc, moai-foundation-thinking"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

MoAI Foundation Core

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

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

Quick Reference

What is MoAI Foundation Core?

Six essential principles that ensure quality, efficiency, and scalability in AI-powered development:

1. TRUST 5 Framework - Quality gate system (Tested, Readable, Unified, Secured, Trackable) 2. SPEC-First DDD - Specification-driven domain-driven development workflow 3. Delegation Patterns - Task orchestration via specialized agents (never direct execution) 4. Token Optimization - 200K budget management and context efficiency 5. Progressive Disclosure - Three-tier knowledge delivery (Quick, Implementation, Advanced) 6. Modular System - File splitting and reference architecture for scalability

Quick Access:

• Quality standards in modules/trust-5-framework.md
• Development workflow in modules/spec-first-ddd.md
• Agent coordination in modules/delegation-patterns.md
• Budget management in modules/token-optimization.md
• Content structure in modules/progressive-disclosure.md
• File organization in modules/modular-system.md
• Agent catalog in modules/agents-reference.md
• Command reference in modules/commands-reference.md
• Security and constraints in modules/execution-rules.md

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

1. TRUST 5 Framework - Quality Assurance System

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

Five Pillars:

Tested Pillar: Maintain comprehensive test coverage with characterization tests ensuring behavior preservation. Execute the project's test runner with coverage (e.g. go test -cover, pytest --cov, cargo test, npm test -- --coverage). Block merge and generate missing tests on failure. Characterization tests capture current behavior for legacy code, while specification tests validate domain requirements for new code. High coverage ensures code reliability and reduces production defects, and preserves behavior during refactoring.

Readable Pillar: Use clear and descriptive naming conventions. Run the project's linter (e.g. golangci-lint, ruff, eslint, clippy). Issue warning and suggest refactoring improvements on failure. Clear naming improves code comprehension, team collaboration, and maintenance velocity.

Unified Pillar: Apply consistent formatting and import patterns. Run the project's formatter (e.g. gofmt, black, prettier, rustfmt). Auto-format code or issue warning on failure. Consistency eliminates style debates and merge conflicts and improves readability.

Secured Pillar: Comply with OWASP security standards. Surface security findings via the appropriate agent or reference skill (e.g. spawn a per-spawn general-purpose agent with security instructions, or load the moai-ref-owasp-checklist / moai-ref-llm-security reference). Block merge and require security review on failure. Security vulnerabilities create critical business and legal risks.

Trackable Pillar: Write clear and structured commit messages. Match Git commit message regex patterns (Conventional Commits). Suggest proper commit message format on failure. Clear history enables debugging, auditing, and collaboration.

Integration Points: Pre-commit hooks for automated validation, CI/CD pipelines for quality gate enforcement, Agent workflows for TRUST 5 validation (moai-foundation-quality orchestration), Documentation for quality metrics.

Detailed Reference: modules/trust-5-framework.md

---

2. SPEC-First DDD - Development Workflow

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

Three-Phase Workflow:

Phase 1 SPEC (/moai plan): workflow-spec generates GEARS format (primary; EARS retained as 6-month backward-compat legacy reference for the 88 pre-v3 SPECs). Output is .moai/specs/SPEC-XXX/spec.md. Execute /clear to save 45-50K tokens.

Phase 2 DDD (/moai run): ANALYZE for requirements, PRESERVE for existing behavior, IMPROVE for enhancement. Validate with at least 85% coverage.

Phase 3 Docs (/moai sync): API documentation, architecture diagrams, project reports.

GEARS Format (current notation): Five patterns — Ubiquitous "The <subject> shall <behavior>" for system-wide always active requirements; Event-driven "When <event> the <subject> shall <behavior>" for trigger-response requirements; State-driven "While <state> the <subject> shall <behavior>" for conditional behavior; Where (capability gate) "Where <capab