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

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

@@ -0,0 +1,209 @@
+# moai-foundation-claude Reference
+
+## API Reference
+
+### Skill Definition API
+
+Frontmatter Fields:
+- `name` (required): Skill identifier in kebab-case, max 64 characters
+- `description` (required): One-line description, max 1024 characters
+- `version`: Semantic version (e.g., "2.0.0")
+- `tools`: Comma-separated list of allowed tools
+- `modularized`: Boolean indicating modular file structure
+- `category`: Skill category (foundation, domain, workflow, library, integration)
+- `tags`: Array of searchable keywords
+- `aliases`: Alternative names for skill invocation
+
+### Sub-agent Delegation API
+
+Task Invocation:
+- `Task(subagent_type, prompt)`: Invoke specialized sub-agent
+- `Task(subagent_type, prompt, context)`: Invoke with context from previous task
+- Returns structured result object for chaining
+
+Available Sub-agent Types:
+- `spec-builder`: EARS format specification generation
+- `tdd-implementer`: RED-GREEN-REFACTOR TDD execution
+- `backend-expert`: Backend architecture and API development
+- `frontend-expert`: Frontend UI implementation
+- `security-expert`: Security analysis and validation
+- `docs-manager`: Technical documentation generation
+- `quality-gate`: TRUST 5 validation
+- `agent-factory`: Create new sub-agents
+- `skill-factory`: Create compliant skills
+
+### Command Parameter API
+
+Parameter Types:
+- `$1`, `$2`, `$3`: Positional arguments
+- `$ARGUMENTS`: All arguments as single string
+- `@filename`: File content injection
+
+Command Location:
+- Personal: `~/.claude/commands/`
+- Project: `.claude/commands/`
+
+---
+
+## Configuration Options
+
+### Settings Hierarchy
+
+Priority Order (highest to lowest):
+1. Enterprise settings (`/etc/claude/settings.json`)
+2. User settings (`~/.claude/settings.json`)
+3. Project settings (`.claude/settings.json`)
+4. Local settings (`.claude/settings.local.json`)
+
+### Tool Permissions
+
+Permission Levels:
+- `Read, Grep, Glob`: Read-only access for analysis
+- `Read, Write, Edit, Grep, Glob`: Full file manipulation
+- `Bash`: System command execution (requires explicit grant)
+- `WebFetch, WebSearch`: External web access
+
+### Memory Configuration
+
+Memory File Locations:
+- Enterprise: `/etc/claude/CLAUDE.md`
+- User: `~/.claude/CLAUDE.md`
+- Project: `./CLAUDE.md` or `.claude/CLAUDE.md`
+
+Memory Import Syntax:
+```markdown
+@import path/to/file.md
+```
+
+---
+
+## Integration Patterns
+
+### Command-Agent-Skill Orchestration
+
+Sequential Pattern:
+1. Command receives user input with `$ARGUMENTS`
+2. Command loads relevant Skills via `Skill("skill-name")`
+3. Command delegates to sub-agent via `Task(subagent_type, prompt)`
+4. Sub-agent executes with loaded skill context
+5. Result returned to command for presentation
+
+Parallel Pattern:
+- Multiple independent `Task()` calls execute concurrently
+- Results aggregated after all complete
+- Use when tasks have no dependencies
+
+### Hook Integration
+
+PreToolUse Hooks:
+- Execute before any tool invocation
+- Can block or modify tool execution
+- Use for validation, logging, security checks
+
+PostToolUse Hooks:
+- Execute after tool completion
+- Can process or modify results
+- Use for backup, audit, notification
+
+Hook Configuration (settings.json):
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "ToolName",
+        "hooks": [{"type": "command", "command": "hook-script"}]
+      }
+    ]
+  }
+}
+```
+
+### MCP Server Integration
+
+Context7 Integration:
+- Use for real-time documentation lookup
+- Two-step pattern: resolve library ID, then fetch docs
+- Supports token-limited responses
+
+MCP Tool Invocation:
+- Tools prefixed with `mcp__` for MCP-provided capabilities
+- Server configuration in settings.json
+
+---
+
+## Troubleshooting
+
+### Skill Not Loading
+
+Symptoms: Skill not recognized, missing context
+
+Solutions:
+1. Verify file location (`~/.claude/skills/` or `.claude/skills/`)
+2. Check SKILL.md frontmatter syntax (valid YAML)
+3. Confirm name follows kebab-case, max 64 chars
+4. Verify file size under 500 lines
+
+### Sub-agent Delegation Failures
+
+Symptoms: Task() returns error, incomplete results
+
+Solutions:
+1. Verify subagent_type is valid
+2. Check prompt clarity and specificity
+3. Ensure required context is provided
+4. Review token budget (each Task() gets 200K)
+
+### Hook Not Executing
+
+Symptoms: PreToolUse/PostToolUse not triggering
+
+Solutions:
+1. Check matcher pattern matches tool name exactly
+2. Verify hook script exists and is executable
+3. Review settings.json syntax
+4. Check command permissions
+
+### Memory File Issues
+
+Symptoms: CLAUDE.md content not applied
+
+Solutions:
+1. Verify file location in correct hierarchy
+2. Check file encoding (UTF-8 required)
+3. Review @import paths (relative to file)
+4. Ensure file permissions allow reading
+
+---
+
+## External Resources
+
+### Official Documentation
+
+- [Claude Code Skills Guide](https://docs.anthropic.com/claude-code/skills)
+- [Sub-agents Documentation](https://docs.anthropic.com/claude-code/agents)
+- [Custom Commands Reference](https://docs.anthropic.com/claude-code/commands)
+- [Hooks System Guide](https://docs.anthropic.com/claude-code/hooks)
+- [Memory Management](https://docs.anthropic.com/claude-code/memory)
+- [Settings Configuration](https://docs.anthropic.com/claude-code/settings)
+- [IAM and Permissions](https://docs.anthropic.com/claude-code/iam)
+
+### Best Practices
+
+- Keep SKILL.md under 500 lines
+- Use progressive disclosure (Quick, Implementation, Advanced)
+- Apply least-privilege tool permissions
+- Document trigger scenarios in description
+- Include working examples for each pattern
+
+### Related Skills
+
+- `moai-foundation-core`: Core execution patterns and SPEC workflow
+- `moai-foundation-context`: Token budget and session management
+- `moai-workflow-project`: Project initialization and configuration
+- `moai-docs-generation`: Documentation automation
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-06

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

@@ -0,0 +1,221 @@
+---
+name: moai-foundation-context
+aliases: [moai-foundation-context]
+description: Enterprise context and session management with token budget optimization and state persistence
+version: 3.1.0
+modularized: false
+user-invocable: false
+category: foundation
+tags:
+  [
+    "foundation",
+    "context",
+    "session",
+    "token-optimization",
+    "state-management",
+    "multi-agent",
+  ]
+updated: 2026-01-11
+status: "active"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+replaces: moai-core-context-budget, moai-core-session-state
+---
+
+## Quick Reference
+
+Enterprise Context and Session Management - Unified context optimization and session state management for Claude Code with 200K token budget management, session persistence, and multi-agent handoff protocols.
+
+Core Capabilities:
+
+- 200K token budget allocation and monitoring
+- Session state tracking with persistence
+- Context-aware token optimization
+- Multi-agent handoff protocols
+- Progressive disclosure and memory management
+- Session forking for parallel exploration
+
+When to Use:
+
+- Session initialization and cleanup
+- Long-running workflows exceeding 10 minutes
+- Multi-agent orchestration
+- Context window approaching limits exceeding 150K tokens
+- Model switches between Haiku and Sonnet
+- Workflow phase transitions
+
+Key Principles:
+
+Avoid Last 20%: Performance degrades in final fifth of context window.
+
+Aggressive Clearing: Execute /clear every 1-3 messages for SPEC workflows.
+
+Lean Memory Files: Keep each file under 500 lines.
+
+Disable Unused MCPs: Minimize tool definition overhead.
+
+Quality Over Quantity: 10% relevant context beats 90% noise.
+
+---
+
+## Implementation Guide
+
+### Features
+
+- Intelligent context window management for Claude Code sessions
+- Progressive file loading with priority-based caching
+- Token budget tracking and optimization alerts
+- Selective context preservation across /clear boundaries
+- MCP integration context persistence
+
+### When to Use
+
+- Managing large codebases exceeding 150K token limits
+- Optimizing token usage in long-running development sessions
+- Preserving critical context across session resets
+- Coordinating multi-agent workflows with shared context
+- Debugging context-related issues in Claude Code
+
+### Core Patterns
+
+Pattern 1 - Progressive File Loading:
+
+Load files by priority tiers. Tier 1 includes CLAUDE.md and config.json which are always loaded. Tier 2 includes current SPEC and implementation files. Tier 3 includes related modules and dependencies. Tier 4 includes reference documentation loaded on-demand.
+
+Pattern 2 - Context Checkpointing:
+
+Monitor token usage with warning at 150K and critical at 180K. Identify essential context to preserve. Execute /clear to reset session. Reload Tier 1 and Tier 2 files automatically. Resume work with preserved context.
+
+Pattern 3 - MCP Context Continuity:
+
+Preserve MCP agent context across /clear by storing the agent_id. After /clear, context is restored through fresh MCP agent initialization.
+
+## Core Patterns Detail
+
+### Pattern 1: Token Budget Management
+
+Concept: Strategic allocation and monitoring of 200K token context window.
+
+Budget Breakdown: System Prompt and Instructions take approximately 15K tokens at 7.5%, including CLAUDE.md at 8K, Command definitions at 4K, and Skill metadata at 3K. Active Conversation takes approximately 80K tokens at 40%, including Recent messages at 50K, Context cache at 20K, and Active references at 10K. Reference Context with Progressive Disclosure takes approximately 50K at 25%, including Project structure at 15K, Related Skills at 20K, and Tool definitions at 15K. Reserve for Emergency Recovery takes approximately 55K tokens at 27.5%, including Session state snapshot at 10K, TAGs and cross-references at 15K, Error recovery context at 20K, and Free buffer at 10K.
+
+Monitoring Thresholds: When usage exceeds 85%, trigger emergency compression and execute clear command. When usage exceeds 75%, defer non-critical context and warn user of approaching limit. When usage exceeds 60%, track context growth patterns.
+
+Use Case: Prevent context overflow in long-running SPEC-First workflows.
+
+### Pattern 2: Aggressive /clear Strategy
+
+Concept: Proactive context clearing at strategic checkpoints to maintain efficiency.
+
+Mandatory /clear Points: After /moai:1-plan completion to save 45-50K tokens. When context exceeds 150K tokens to prevent overflow. When conversation exceeds 50 messages to remove stale history. Before major phase transitions for clean slate. During model switches for Haiku to Sonnet handoffs.
+
+Use Case: Maximize token efficiency across SPEC-Run-Sync cycles.
+
+### Pattern 3: Session State Persistence
+
+Concept: Maintain session continuity across interruptions with state snapshots.
+
+Session State Layers: L1 is the Context-Aware Layer for Claude 4.5+ with token budget tracking, context window position, auto-summarization triggers, and model-specific optimizations. L2 is Active Context for current task, variables, and scope. L3 is Session History for recent actions and decisions. L4 is Project State for SPEC progress and milestones. L5 is User Context for preferences, language, and expertise. L6 is System State for tools, permissions, and environment.
+
+Use Case: Resume long-running tasks after interruptions without context loss.
+
+### Pattern 4: Multi-Agent Handoff Protocols
+
+Concept: Seamless context transfer between agents with minimal token overhead.
+
+Handoff Package Contents: Include handoff_id, from_agent, to_agent, session_context with session_id, model, context_position, available_tokens, and user_language, task_context with spec_id, current_phase, completed_steps, and next_step, and recovery_info with last_checkpoint, recovery_tokens_reserved, and session_fork_available.
+
+Handoff Validation: Check token budget with minimum 30K available buffer. Verify agent compatibility. Trigger context compression if needed.
+
+Use Case: Efficient Plan to Run to Sync workflow execution.
+
+### Pattern 5: Progressive Disclosure and Memory Optimization
+
+Concept: Load context progressively based on relevance and need.
+
+Progressive Summarization: Extract key sentences to compress 50K to 15K at target ratio of 0.3. Add pointers to original content for reference. Store original in session archive for recovery. Result saves approximately 35K tokens.
+
+Context Tagging: Avoid high token cost phrases like "The user configuration from the previous 20 messages..." and use efficient references like "Refer to @CONFIG-001 for user preferences".
+
+Use Case: Maintain context continuity while minimizing token overhead.
+
+---
+
+## Advanced Documentation
+
+For detailed patterns and implementation strategies:
+
+- modules/token-budget-allocation.md - Budget breakdown, allocation strategies, monitoring thresholds
+- modules/session-state-management.md - State layers, persistence, resumption patterns
+- modules/context-optimization.md - Progressive disclosure, summarization, memory management
+- modules/handoff-protocols.md - Inter-agent communication, package format, validation
+- modules/memory-mcp-optimization.md - Memory file structure, MCP server configuration
+- modules/reference.md - API reference, troubleshooting, best practices
+
+---
+
+## Best Practices
+
+Recommended Practices:
+
+- Execute /clear immediately after SPEC creation
+- Monitor token usage and plan accordingly
+- Use context-aware token budget tracking
+- Create checkpoints before major operations
+- Apply progressive summarization for long workflows
+- Enable session persistence for recovery
+- Use session forking for parallel exploration
+- Keep memory files under 500 lines each
+- Disable unused MCP servers to reduce overhead
+
+Required Practices:
+
+Maintain bounded context history with regular clearing cycles. Unbounded context accumulation degrades performance and increases token costs exponentially. This prevents context overflow, maintains consistent response quality, and reduces token waste by 60-70%.
+
+Respond to token budget warnings immediately when usage exceeds 150K tokens. Operating in the final 20% of context window causes significant performance degradation.
+
+Execute state validation checks during session recovery operations. Invalid state can cause workflow failures and data loss in multi-step processes.
+
+Persist session identifiers before any context clearing operations. Session IDs are the only reliable mechanism for resuming interrupted workflows.
+
+Execute context compression or clearing when usage reaches 85% threshold. This maintains 55K token emergency reserve and prevents forced interruptions.
+
+---
+
+## Works Well With
+
+- moai-cc-memory - Memory management and context persistence
+- moai-cc-configuration - Session configuration and preferences
+- moai-core-workflow - Workflow state persistence and recovery
+- moai-cc-agents - Agent state management across sessions
+- moai-foundation-trust - Quality gate integration
+
+---
+
+## Workflow Integration
+
+Session Initialization: Initialize token budget with Pattern 1, load session state with Pattern 3, setup progressive disclosure with Pattern 5, configure handoff protocols with Pattern 4.
+
+SPEC-First Workflow: Execute /moai:1-plan, then mandatory /clear to save 45-50K tokens, then /moai:2-run SPEC-XXX, then multi-agent handoffs with Pattern 4, then /moai:3-sync SPEC-XXX, then session state persistence with Pattern 3.
+
+Context Monitoring: Continuously track token usage with Pattern 1, apply progressive disclosure with Pattern 5, execute /clear at thresholds with Pattern 2, validate handoffs with Pattern 4.
+
+---
+
+## Success Metrics
+
+- Token Efficiency: 60-70% reduction through aggressive clearing
+- Context Overhead: Less than 15K tokens for system/skill metadata
+- Handoff Success Rate: Greater than 95% with validation
+- Session Recovery: Less than 5 seconds with state persistence
+- Memory Optimization: Less than 500 lines per memory file
+
+---
+
+Status: Production Ready (Enterprise)
+Modular Architecture: SKILL.md + 6 modules
+Integration: Plan-Run-Sync workflow optimized
+Generated with: MoAI-ADK Skill Factory