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.
GEARS Format (current notation): Five patterns — Ubiquitous "The shall " for system-wide always active requirements; Event-driven "When the shall " for trigger-response requirements; State-driven "While the shall " for conditional behavior; Where (capability gate) "Where , the shall " for capability-conditioned behavior; Event-detected (replaces the deprecated conditional modality) "When , the shall " for failure-mode handling. Unified compound clause: [Where ...][While ...][When ...] The <subject> shall <behavior> — any subset of the three modifiers may chain. The <subject> is generalized — any noun (system, component, service, agent, function, artifact). See the canonical authoring guide at .claude/skills/moai-workflow-spec/SKILL.md § "GEARS Format".
EARS Format (legacy reference, 6-month backward-compat — expires 2026-11-22): Five patterns Ubiquitous / Event-driven (WHEN/THEN) / State-driven (WHILE) / Unwanted (SHALL NOT) / Optional (WHERE possible). The 88 pre-v3 SPECs continue to use EARS; the lint engine emits a LegacyEARSKeyword warning on residual deprecated conditional modality in NEW SPECs (warning non-strict, error under moai spec lint --strict). For NEW SPECs, use GEARS. See modules/spec-ears-format.md (legacy reference, deprecated — see GEARS Format guide).
Token Budget: SPEC takes 30K, DDD takes 180K, Docs takes 40K, Total is 250K.
Key Practice: Execute /clear after Phase 1 to initialize context.
Detailed Reference: modules/spec-first-ddd.md
3. Delegation Patterns - Agent Orchestration
Purpose: Task delegation to specialized agents, avoiding direct execution.
Core Principle: MoAI must delegate all work through Agent() to specialized agents. Direct execution bypasses specialization, quality gates, and token optimization. Proper delegation improves task success rate by 40 percent and enables parallel execution.
Delegation Syntax: MoAI delegates via natural language — "Use the {agent} subagent to {task}" — carrying full context, constraints, and rationale. The orchestrator never passes a subagent_type code literal; it spawns Agent() (or Agent(general-purpose) for domain work) with a prose prompt.
Three Patterns:
Sequential for dependencies: Use the manager-spec subagent to author the SPEC, then the manager-develop subagent to implement it with the SPEC as context.
Parallel for independent work: Spawn multiple Agent(general-purpose) teammates in one turn — e.g. one with backend instructions and one with frontend instructions — when the work is independent.
Conditional for analysis-based: Use the Explore subagent for read-only diagnosis, then route the result to the appropriate retained agent (manager-develop for fixes, sync-auditor for quality scoring) based on the findings.
Agent Selection: Simple tasks with 1 file use 1-2 agents sequential. Medium tasks with 3-5 files use 2-3 agents sequential. Complex tasks with 10+ files use 5+ agents mixed. Domain-specific work (backend / frontend / security / performance / refactoring) is handled in run-phase by manager-develop, or by a per-spawn Agent(general-purpose) with a domain whitelist per .claude/rules/moai/workflow/archived-agent-rejection.md.
Purpose: Efficient 200K token budget through strategic context management.
Budget Allocation:
SPEC Phase takes 30K tokens. Strategy is to load requirements only and execute /clear after completion. Specification phase requires minimal context for requirement analysis. Saves 45-50K tokens for implementation phase.
DDD Phase takes 180K tokens. Strategy is selective file loading, load only implementation-relevant files. Implementation requires deep context but not full codebase. Enables 70 percent larger implementations within budget.
Docs Phase takes 40K tokens. Strategy is result caching and template reuse. Documentation builds on completed work artifacts. Reduces redundant file reads by 60 percent.
Total Budget is 250K tokens across all phases. Phase separation with context reset between phases provides clean context boundaries and prevents token bloat. Enables 2-3x larger projects within same budget.
Token Saving Strategies:
Phase Separation: Execute /clear between phases, after /moai plan to save 45-50K, when context exceeds 150K, after 50+ messages.
Selective Loading: Load only necessary files.
Context Optimization: Target 20-30K tokens.
Model Selection: Sonnet for quality, Haiku for speed and cost with 70% cheaper rates for 60-70% total savings.
Detailed Reference: modules/token-optimization.md
5. Progressive Disclosure - Content Architecture
Purpose: Three-tier knowledge delivery balancing value with depth.
Three Levels:
Quick Reference Level: 30 seconds time investment, core principles and essential concepts, approximately 1,000 tokens. Rapid value delivery for time-constrained users. Users gain 80 percent understanding in 5 percent of time.
Implementation Level: 5 minutes time investment, workflows, practical examples, integration patterns, approximately 3,000 tokens. Bridges concept to execution with actionable guidance. Enables immediate productive work without deep expertise.
Advanced Level: 10+ minutes time investment, deep technical dives, edge cases, optimization techniques, approximately 5,000 tokens. Provides mastery-level knowledge for complex scenarios. Reduces escalations by 70 percent through comprehensive coverage.
SKILL.md Structure (maximum 500 lines): Quick Reference section, Implementation Guide section, Advanced Patterns section, Works Well With section.
Module Architecture: SKILL.md as entry point with cross-references, modules directory for deep dives with unlimited size, examples.md for working samples, reference.md for external links.
File Splitting when exceeding 500 lines: SKILL.md contains Quick at 80-120 lines, Implementation at 180-250 lines, Advanced at 80-140 lines, References at 10-20 lines. Overflow content goes to modules/topic.md.
Standard Structure: Create .claude/skills/skill-name/ directory containing SKILL.md as core file under 500 lines, modules directory for extended content with unlimited size including patterns.md, examples.md for working samples, reference.md for external links, scripts directory for utilities (optional), templates directory (optional).
File Principles: SKILL.md stays under 500 lines with progressive disclosure and cross-references. modules directory is topic-focused with no limits and self-contained content. examples.md is copy-paste ready with comments. reference.md contains API docs and resources.
Cross-Reference Syntax: Reference modules as Details in modules/patterns.md, reference examples as Examples in examples.md#auth, reference external docs as External in reference.md#api.
Discovery Flow: SKILL.md to Topic to modules/topic.md to Deep dive.
Detailed Reference: modules/modular-system.md
Advanced Implementation
Advanced patterns including cross-module integration, quality validation, and error handling are available in the detailed module references.
Token-Optimized Delegation: Parallel execution with context reset
Progressive Agent Workflows: Escalation patterns
Quality Validation: Pre/Post execution validation
Error Handling: Delegation failure recovery
Detailed Reference: references/examples.md for working code samples
Works Well With
Agents: builder-harness for generating agents/skills/harnesses with foundation principles, manager-spec for plan-phase authoring, manager-develop for run-phase implementation, manager-docs for sync-phase documentation, sync-auditor for independent TRUST 5 quality scoring, super-advisor for on-demand high-reasoning consultation.
Skills: moai-foundation-cc for Claude Code authoring (skills, agents, plugins, hooks), moai-workflow-spec for GEARS format specification (current; EARS retained as legacy reference), moai-workflow-ddd for ANALYZE-PRESERVE-IMPROVE execution, moai-workflow-tdd for RED-GREEN-REFACTOR cycles, moai-foundation-quality for TRUST 5 validation orchestration, moai-foundation-thinking for strategic reasoning and Adaptive Thinking via the ultrathink keyword.
Tools: AskUserQuestion for direct user interaction and clarification needs.
Commands: /moai plan for SPEC-First Phase 1, /moai run for DDD Phase 2, /moai sync for Documentation Phase 3, /moai feedback for continuous improvement, /clear for token management.
Foundation Modules (Extended Documentation): modules/agents-reference.md for the 11-agent retained catalog (10 MoAI-custom + 1 Anthropic built-in Explore), modules/commands-reference.md for 6 core commands workflow, modules/execution-rules.md for security, Git strategy, and compliance. For migration of references to the 12 archived agents (manager-strategy, manager-quality, manager-brain, manager-project, claude-code-guide, researcher, and the 6 expert-* agents), see .claude/rules/moai/workflow/archived-agent-rejection.md.
Quick Decision Guide
New Agent: Primary principle is TRUST 5 and Delegation. Supporting principles are Token Optimization and Modular.
New Skill: Primary principle is Progressive and Modular. Supporting principles are TRUST 5 and Token Optimization.
Workflow: Primary principle is Delegation Patterns. Supporting principles are SPEC-First and Token Optimization.
Quality: Primary principle is TRUST 5 Framework. Supporting principle is SPEC-First DDD.
Budget: Primary principle is Token Optimization. Supporting principles are Progressive and Modular.
Docs: Primary principle is Progressive and Modular. Supporting principle is Token Optimization.
Progressive disclosure levels configured in skill frontmatter
Token Budget (absorbed from moai-foundation-context)
Context window optimization, /clear strategy, session state persistence, and multi-agent handoff patterns.
Context Window Targets
See .claude/rules/moai/workflow/context-window-management.md § Context Window Targets for the authoritative per-model-class /clear threshold table (1M/GLM = 50%, 200K/256K = 90%). Do not restate thresholds here (SSOT).
Phase Token Allocation
Phase
Budget
Strategy
/moai plan
30,000
Load requirements only, /clear after completion
/moai run
180,000
Selective file loading, on-demand skill loading
/moai sync
40,000
Result caching, reduced redundant reads
/clear Strategy
Mandatory /clear points:
After /moai plan completion (before /moai run)
When context exceeds 150,000 tokens (Sonnet/standard)
Before major phase transitions
Never use /clear when: In the middle of an agent task, when session state has not been persisted.
Session State Persistence
Before /clear, persist in-flight state to .moai/specs/<SPEC-ID>/progress.md:
Current task status (completed, in-progress, blocked)
File modification summary
Next action required
Resume message for paste-back after /clear
Resume message format:
Wave <N> 이어서 진행. SPEC-<ID>부터 <approach>.
progress.md: .moai/specs/<ID>/progress.md
다음 단계: <command>.
Multi-Agent Handoff
When delegating to a sub-agent near context ceiling:
Summarize findings in progress.md before Agent() call
Pass only necessary context in spawn prompt (avoid full file dumps)
Sub-agent result contributes to parent context on return — factor this in
If parent context > 120,000 tokens after return, save and /clear
