moai-adk 0.32.8__py3-none-any.whl → 0.41.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

@@ -1,19 +1,19 @@
 ---
-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
+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.4.0
+category: "foundation"
 modularized: true
-updated: 2025-12-03
-status: active
-tags:
- - foundation
- - core
- - orchestration
- - agents
- - commands
- - trust-5
- - spec-first-tdd
-allowed-tools: Read, Grep, Glob
+user-invocable: false
+tags: ['foundation', 'core', 'orchestration', 'agents', 'commands', 'trust-5', 'spec-first-tdd']
+updated: 2026-01-08
+status: "active"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
 ---
 
 # MoAI Foundation Core
@@ -342,86 +342,16 @@ Detailed Reference: [Modular System Module](modules/modular-system.md)
 
 ## Advanced Implementation (10+ minutes)
 
-### Cross-Module Integration
+Advanced patterns including cross-module integration, quality validation, and error handling are available in the detailed module references.
 
-TRUST 5 + SPEC-First TDD:
-```python
-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:
-```python
-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})
-```
+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
 
-Progressive Agent Workflows:
-```python
-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:
-```python
-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:
-```python
-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:
-```python
-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:
-```python
-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)
-```
+Detailed Reference: [examples.md](examples.md) for working code samples
 
 ---
 
@@ -439,9 +369,11 @@ 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
 
+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
@@ -458,41 +390,14 @@ Foundation Modules (Extended Documentation):
 
 ## Quick Decision Matrix
 
-New Agent Scenario:
-- Primary Principle: TRUST 5 Framework and Delegation Patterns
-- Supporting Principles: Token Optimization and Modular System
-- WHY: Agents require quality gates and proper task orchestration
-- IMPACT: Ensures reliable, maintainable agent implementations
-
-New Skill Scenario:
-- Primary Principle: Progressive Disclosure and Modular System
-- Supporting Principles: TRUST 5 Framework and Token Optimization
-- WHY: Skills balance immediate value with comprehensive depth
-- IMPACT: Maximizes learning efficiency and adoption rate
-
-Workflow Scenario:
-- Primary Principle: Delegation Patterns
-- Supporting Principles: SPEC-First TDD and Token Optimization
-- WHY: Complex workflows require proper task orchestration
-- IMPACT: Enables reliable multi-step process execution
-
-Quality Scenario:
-- Primary Principle: TRUST 5 Framework
-- Supporting Principles: SPEC-First TDD
-- WHY: Quality requires systematic validation at every phase
-- IMPACT: Reduces defects by 85+ percent through automated gates
-
-Budget Scenario:
-- Primary Principle: Token Optimization
-- Supporting Principles: Progressive Disclosure and Modular System
-- WHY: Efficient token usage enables larger project scope
-- IMPACT: Doubles effective project size within same budget
-
-Documentation Scenario:
-- Primary Principle: Progressive Disclosure and Modular System
-- Supporting Principles: Token Optimization
-- WHY: Documentation must serve diverse user needs efficiently
-- IMPACT: Reduces time-to-value by 70 percent across user segments
+| 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)
@@ -507,9 +412,3 @@ Module Deep Dives:
 
 Full Examples: [examples.md](examples.md)
 External Resources: [reference.md](reference.md)
-
----
-
-Version: 2.3.0
-Last Updated: 2025-12-03
-Status: Active (515 lines, enhanced with Claude 4 positive requirements and WHY/IMPACT)