moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-context/reference.md

@@ -0,0 +1,246 @@
+# moai-foundation-context Reference
+
+## API Reference
+
+### Token Budget Monitoring API
+
+Functions:
+- `monitor_token_budget(context_usage: int)`: Real-time usage monitoring
+- `get_usage_percent()`: Returns current usage as percentage (0-100)
+- `trigger_emergency_compression()`: Compress context when critical
+- `defer_non_critical_context()`: Move non-essential context to cache
+
+Thresholds:
+- 60%: Monitor and track growth patterns
+- 75%: Warning - start progressive disclosure
+- 85%: Critical - trigger emergency compression
+
+### Session State API
+
+Session State Structure:
+- `session_id`: Unique identifier (UUID v4)
+- `model`: Current model identifier
+- `created_at`: ISO 8601 timestamp
+- `context_window`: Token usage statistics
+- `persistence`: Recovery configuration
+- `work_state`: Current task state
+
+State Management Functions:
+- `create_session_snapshot()`: Capture current state
+- `restore_session_state(snapshot)`: Restore from snapshot
+- `validate_session_state(state)`: Verify state integrity
+
+### Handoff Protocol API
+
+Handoff Package Structure:
+- `handoff_id`: Unique transfer identifier
+- `from_agent`: Source agent type
+- `to_agent`: Destination agent type
+- `session_context`: Token and model information
+- `task_context`: Current work state
+- `recovery_info`: Checkpoint and fork data
+
+Validation Functions:
+- `validate_handoff(package)`: Verify package integrity
+- `can_agents_cooperate(from, to)`: Check compatibility
+
+---
+
+## Configuration Options
+
+### Token Budget Allocation
+
+Default Allocation (200K total):
+- System Prompt and Instructions: 15K tokens (7.5%)
+- Active Conversation: 80K tokens (40%)
+- Reference Context: 50K tokens (25%)
+- Reserve (Emergency): 55K tokens (27.5%)
+
+Customizable Settings:
+- `system_prompt_budget`: Override system allocation
+- `conversation_budget`: Override conversation allocation
+- `reference_budget`: Override reference allocation
+- `reserve_budget`: Override emergency reserve
+
+### Clear Execution Settings
+
+Mandatory Clear Points:
+- After `/moai:1-plan` completion
+- Context exceeds 150K tokens
+- Conversation exceeds 50 messages
+- Before major phase transitions
+- Model switches (Haiku to Sonnet)
+
+Configuration Options:
+- `auto_clear_enabled`: Enable automatic clearing
+- `clear_threshold_tokens`: Token threshold for auto-clear
+- `clear_threshold_messages`: Message count threshold
+- `preserve_on_clear`: Context types to preserve
+
+### Session Persistence Settings
+
+State Layers Configuration:
+- L1: Context-Aware Layer (model features)
+- L2: Active Context (current task)
+- L3: Session History (recent actions)
+- L4: Project State (SPEC progress)
+- L5: User Context (preferences)
+- L6: System State (tools, permissions)
+
+Persistence Options:
+- `auto_load_history`: Restore previous context
+- `context_preservation`: Preservation level
+- `cache_enabled`: Enable context caching
+
+---
+
+## Integration Patterns
+
+### Plan-Run-Sync Workflow Integration
+
+Workflow Sequence:
+1. `/moai:1-plan` execution
+2. `/clear` (mandatory - saves 45-50K tokens)
+3. `/moai:2-run SPEC-XXX`
+4. Multi-agent handoffs
+5. `/moai:3-sync SPEC-XXX`
+6. Session state persistence
+
+Token Savings:
+- Post-plan clear: 45-50K tokens saved
+- Progressive disclosure: 30-40% reduction
+- Handoff optimization: 15-20K per transfer
+
+### Multi-Agent Coordination
+
+Handoff Workflow:
+1. Source agent completes task phase
+2. Create handoff package with minimal context
+3. Validate handoff integrity
+4. Target agent receives and validates
+5. Target agent continues workflow
+
+Context Minimization:
+- Include only SPEC ID and key requirements
+- Limit architecture summary to 200 characters
+- Exclude background and reasoning
+- Transfer critical state only
+
+### Progressive Disclosure Integration
+
+Loading Tiers:
+- Tier 1: CLAUDE.md, config.json (always loaded)
+- Tier 2: Current SPEC and implementation files
+- Tier 3: Related modules and dependencies
+- Tier 4: Reference documentation (on-demand)
+
+Disclosure Triggers:
+- Explicit user request
+- Error recovery requirement
+- Complex implementation need
+- Documentation reference needed
+
+---
+
+## Troubleshooting
+
+### Context Overflow Issues
+
+Symptoms: Degraded performance, incomplete responses
+
+Solutions:
+1. Execute `/clear` immediately
+2. Reduce loaded context tiers
+3. Apply progressive summarization
+4. Split task across multiple sessions
+
+Prevention:
+- Monitor at 60% threshold
+- Clear after major milestones
+- Use aggressive clearing strategy
+
+### Session Recovery Failures
+
+Symptoms: Lost state after interruption
+
+Solutions:
+1. Verify session ID was persisted
+2. Check snapshot integrity
+3. Restore from most recent checkpoint
+4. Rebuild state from project files
+
+Prevention:
+- Create checkpoints before operations
+- Persist session ID before clearing
+- Enable auto-save for state snapshots
+
+### Handoff Validation Errors
+
+Symptoms: Agent transition failures
+
+Solutions:
+1. Verify available tokens exceed 30K
+2. Check agent compatibility
+3. Reduce handoff package size
+4. Trigger context compression before transfer
+
+Prevention:
+- Validate before creating package
+- Include only critical context
+- Reserve tokens for handoff overhead
+
+### Token Budget Exhaustion
+
+Symptoms: Forced interruptions, emergency behavior
+
+Solutions:
+1. Execute immediate `/clear`
+2. Resume with Tier 1 context only
+3. Load additional context incrementally
+4. Split remaining work across sessions
+
+Prevention:
+- Maintain 55K emergency reserve
+- Execute clear at 85% threshold
+- Apply progressive disclosure consistently
+
+---
+
+## External Resources
+
+### Related Documentation
+
+- Token Management Best Practices
+- Session State Architecture Guide
+- Multi-Agent Coordination Patterns
+- Context Optimization Strategies
+
+### Module Files
+
+Advanced Documentation:
+- `modules/token-budget-allocation.md`: Budget breakdown and strategies
+- `modules/session-state-management.md`: State layers and persistence
+- `modules/context-optimization.md`: Progressive disclosure and summarization
+- `modules/handoff-protocols.md`: Inter-agent communication
+- `modules/memory-mcp-optimization.md`: Memory file structure
+
+### Performance Metrics
+
+Target Metrics:
+- Token Efficiency: 60-70% reduction through clearing
+- Context Overhead: Less than 15K for system metadata
+- Handoff Success Rate: Greater than 95%
+- Session Recovery: Less than 5 seconds
+- Memory Files: Less than 500 lines each
+
+### Related Skills
+
+- `moai-foundation-claude`: Claude Code authoring and configuration
+- `moai-foundation-core`: Core execution patterns and SPEC workflow
+- `moai-workflow-project`: Project management and documentation
+- `moai-cc-memory`: Memory management and persistence
+
+---
+
+Version: 3.0.0
+Last Updated: 2025-12-06

moai_adk/templates/.claude/skills/moai-foundation-core/SKILL.md

@@ -0,0 +1,420 @@
+---
+name: moai-foundation-core
+description: MoAI-ADK's foundational principles - TRUST 5, SPEC-First TDD, delegation patterns, token optimization, progressive disclosure, modular architecture, agent catalog, command reference, and execution rules for building AI-powered development workflows
+version: 2.3.0
+modularized: true
+updated: 2025-12-03
+status: active
+tags:
+ - foundation
+ - core
+ - orchestration
+ - agents
+ - commands
+ - trust-5
+ - spec-first-tdd
+allowed-tools: Read, Grep, Glob
+---
+
+# 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:
+
+1. TRUST 5 Framework - Quality gate system (Test-first, Readable, Unified, Secured, Trackable)
+2. SPEC-First TDD - Specification-driven test-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 → [TRUST 5 Module](modules/trust-5-framework.md)
+- Development workflow → [SPEC-First TDD Module](modules/spec-first-tdd.md)
+- Agent coordination → [Delegation Patterns Module](modules/delegation-patterns.md)
+- Budget management → [Token Optimization Module](modules/token-optimization.md)
+- Content structure → [Progressive Disclosure Module](modules/progressive-disclosure.md)
+- File organization → [Modular System Module](modules/modular-system.md)
+- Agent catalog → [Agents Reference Module](modules/agents-reference.md) NEW
+- Command reference → [Commands Reference Module](modules/commands-reference.md) NEW
+- Security & constraints → [Execution Rules Module](modules/execution-rules.md) 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:
+
+Test-first Pillar:
+- Requirement: Maintain test coverage at or above 85 percent
+- Validation: Execute pytest with coverage reporting
+- Failure Action: Block merge and generate missing tests
+- WHY: High coverage ensures code reliability and reduces production defects
+- IMPACT: Catches bugs early, reduces debugging time by 60-70 percent
+
+Readable Pillar:
+- Requirement: Use clear and descriptive naming conventions
+- Validation: Execute ruff linter checks
+- Failure Action: Issue warning and suggest refactoring improvements
+- WHY: Clear naming improves code comprehension and team collaboration
+- IMPACT: Reduces onboarding time by 40 percent, improves maintenance velocity
+
+Unified Pillar:
+- Requirement: Apply consistent formatting and import patterns
+- Validation: Execute black formatter and isort checks
+- Failure Action: Auto-format code or issue warning
+- WHY: Consistency eliminates style debates and merge conflicts
+- IMPACT: Reduces code review time by 30 percent, improves readability
+
+Secured Pillar:
+- Requirement: Comply with OWASP security standards
+- Validation: Execute security-expert agent analysis
+- Failure Action: Block merge and require security review
+- WHY: Security vulnerabilities create critical business and legal risks
+- IMPACT: Prevents 95+ percent of common security vulnerabilities
+
+Trackable Pillar:
+- Requirement: Write clear and structured commit messages
+- Validation: Match Git commit message regex patterns
+- Failure Action: Suggest proper commit message format
+- WHY: Clear history enables debugging, auditing, and collaboration
+- IMPACT: Reduces issue investigation time by 50 percent
+
+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](modules/trust-5-framework.md)
+
+---
+
+### 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](modules/spec-first-tdd.md)
+
+---
+
+### 3. Delegation Patterns - Agent Orchestration
+
+Purpose: Task delegation to specialized agents, avoiding direct execution.
+
+Core Principle [HARD]: Alfred must delegate all work through Task() to specialized agents.
+
+WHY: Direct execution bypasses specialization, quality gates, and token optimization.
+IMPACT: Proper delegation improves task success rate by 40 percent and enables parallel execution.
+
+Delegation Syntax:
+```python
+result = await Task(
+ subagent_type="specialized_agent",
+ prompt="Clear, specific task",
+ context={"relevant": "data"}
+)
+```
+
+Three Patterns:
+
+Sequential (dependencies):
+```python
+design = Task(subagent_type="api-designer", prompt="Design API")
+code = Task(subagent_type="backend-expert", prompt="Implement", context={"design": design})
+```
+
+Parallel (independent):
+```python
+results = await Promise.all([
+ Task(subagent_type="backend-expert", prompt="Backend"),
+ Task(subagent_type="frontend-expert", prompt="Frontend")
+])
+```
+
+Conditional (analysis-based):
+```python
+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](modules/delegation-patterns.md)
+
+---
+
+### 4. Token Optimization - Budget Management
+
+Purpose: Efficient 200K token budget through strategic context management.
+
+Budget Allocation:
+
+SPEC Phase:
+- Token Budget: 30K tokens
+- Strategy: Load requirements only, execute /clear after completion
+- WHY: Specification phase requires minimal context for requirement analysis
+- IMPACT: Saves 45-50K tokens for implementation phase
+
+TDD Phase:
+- Token Budget: 180K tokens
+- Strategy: Selective file loading, load only implementation-relevant files
+- WHY: Implementation requires deep context but not full codebase
+- IMPACT: Enables 70 percent larger implementations within budget
+
+Docs Phase:
+- Token Budget: 40K tokens
+- Strategy: Result caching and template reuse
+- WHY: Documentation builds on completed work artifacts
+- IMPACT: Reduces redundant file reads by 60 percent
+
+Total Budget:
+- Combined Budget: 250K tokens across all phases
+- Strategy: Phase separation with context reset between phases
+- WHY: Clean context boundaries prevent token bloat
+- IMPACT: Enables 2-3x larger projects within same budget
+
+Token Saving Strategies:
+
+1. Phase Separation: /clear between phases
+ - After /moai:1-plan (saves 45-50K)
+ - When context > 150K
+ - After 50+ messages
+
+2. Selective Loading: Load only necessary files
+
+3. Context Optimization: 20-30K tokens target
+
+4. 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](modules/token-optimization.md)
+
+---
+
+### 5. Progressive Disclosure - Content Architecture
+
+Purpose: Three-tier knowledge delivery balancing value with depth.
+
+Three Levels:
+
+Quick Reference Level:
+- Time Investment: 30 seconds
+- Content: Core principles and essential concepts
+- Token Usage: Approximately 1,000 tokens
+- WHY: Rapid value delivery for time-constrained users
+- IMPACT: Users gain 80 percent understanding in 5 percent of time
+
+Implementation Level:
+- Time Investment: 5 minutes
+- Content: Workflows, practical examples, integration patterns
+- Token Usage: Approximately 3,000 tokens
+- WHY: Bridges concept to execution with actionable guidance
+- IMPACT: Enables immediate productive work without deep expertise
+
+Advanced Level:
+- Time Investment: 10+ minutes
+- Content: Deep technical dives, edge cases, optimization techniques
+- Token Usage: Approximately 5,000 tokens
+- WHY: Provides mastery-level knowledge for complex scenarios
+- IMPACT: Reduces escalations by 70 percent through comprehensive coverage
+
+SKILL.md Structure (≤500 lines):
+```markdown
+## 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](modules/progressive-disclosure.md)
+
+---
+
+### 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:
+
+1. SKILL.md: ≤500 lines, progressive disclosure, cross-references
+2. modules/: Topic-focused, no limits, self-contained
+3. examples.md: Copy-paste ready, commented
+4. reference.md: API docs, resources
+
+Cross-Reference Syntax:
+```markdown
+Details: [Module](modules/patterns.md)
+Examples: [Examples](examples.md#auth)
+External: [Reference](reference.md#api)
+```
+
+Discovery Flow: SKILL.md → Topic → modules/[topic].md → Deep dive
+
+Detailed Reference: [Modular System Module](modules/modular-system.md)
+
+---
+
+## Advanced Implementation (10+ minutes)
+
+Advanced patterns including cross-module integration, quality validation, and error handling are available in the detailed module references.
+
+Key Advanced Topics:
+- Cross-Module Integration: Combining TRUST 5 + SPEC-First TDD
+- 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: [examples.md](examples.md) for working code samples
+
+---
+
+## 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-context7-integration - MCP integration
+
+Tools:
+- AskUserQuestion - Use directly for all user interaction and clarification needs
+
+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](modules/agents-reference.md) - 26-agent catalog with 7-tier hierarchy
+- [Commands Reference](modules/commands-reference.md) - 6 core commands workflow
+- [Execution Rules](modules/execution-rules.md) - Security, Git strategy, compliance
+
+---
+
+## Quick Decision Matrix
+
+| Scenario | Primary Principle | Supporting Principles |
+|----------|------------------|----------------------|
+| New Agent | TRUST 5, Delegation | Token Opt, Modular |
+| New Skill | Progressive, Modular | TRUST 5, Token Opt |
+| Workflow | Delegation Patterns | SPEC-First, Token Opt |
+| Quality | TRUST 5 Framework | SPEC-First TDD |
+| Budget | Token Optimization | Progressive, Modular |
+| Docs | Progressive, Modular | Token Optimization |
+
+Module Deep Dives:
+- [TRUST 5 Framework](modules/trust-5-framework.md)
+- [SPEC-First TDD](modules/spec-first-tdd.md)
+- [Delegation Patterns](modules/delegation-patterns.md)
+- [Token Optimization](modules/token-optimization.md)
+- [Progressive Disclosure](modules/progressive-disclosure.md)
+- [Modular System](modules/modular-system.md)
+- [Agents Reference](modules/agents-reference.md) NEW
+- [Commands Reference](modules/commands-reference.md) NEW
+- [Execution Rules](modules/execution-rules.md) NEW
+
+Full Examples: [examples.md](examples.md)
+External Resources: [reference.md](reference.md)
+
+---
+
+Version: 2.4.0
+Last Updated: 2025-12-06
+Status: Active (optimized to <500 lines)