moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-core/modules/commands-reference.md

@@ -0,0 +1,432 @@
+# Commands Reference - MoAI-ADK Core Commands
+
+Purpose: Complete reference for MoAI-ADK's 6 core commands used in SPEC-First TDD workflow.
+
+Last Updated: 2025-11-25
+Version: 2.0.0
+
+---
+
+## Quick Reference (30 seconds)
+
+MoAI-ADK provides 6 core commands for SPEC-First TDD execution:
+
+| Command            | Purpose                | Phase         |
+| ------------------ | ---------------------- | ------------- |
+| `/moai:0-project`  | Project initialization | Setup         |
+| `/moai:1-plan`     | SPEC generation        | Planning      |
+| `/moai:2-run`      | TDD implementation     | Development   |
+| `/moai:3-sync`     | Documentation sync     | Documentation |
+| `/moai:9-feedback` | Feedback collection    | Improvement   |
+| `/moai:99-release` | Production deployment  | Release       |
+
+Required Workflow:
+```
+1. /moai:0-project # Initialize
+2. /moai:1-plan "description" # Generate SPEC
+3. /clear # Clear context (REQUIRED)
+4. /moai:2-run SPEC-001 # Implement
+5. /moai:3-sync SPEC-001 # Document
+6. /moai:9-feedback # Improve
+```
+
+Critical Rule: Execute `/clear` after `/moai:1-plan` (saves 45-50K tokens)
+
+---
+
+## Implementation Guide (5 minutes)
+
+### `/moai:0-project` - Project Initialization
+
+Purpose: Initialize project structure and generate configuration
+
+Agent Delegation: `workflow-project`
+
+Usage:
+```bash
+/moai:0-project
+/moai:0-project --with-git
+```
+
+What It Does:
+1. Creates `.moai/` directory structure
+2. Generates `config.json` with default settings
+3. Initializes Git repository (if `--with-git` flag provided)
+4. Sets up MoAI-ADK workflows
+
+Output:
+- `.moai/` directory
+- `.moai/config/config.yaml`
+- `.moai/memory/` (empty, ready for session state)
+- `.moai/logs/` (empty, ready for logging)
+
+Next Step: Ready for SPEC generation via `/moai:1-plan`
+
+Example:
+```
+User: /moai:0-project
+Alfred: Project initialized successfully.
+ - .moai/config/config.yaml created
+ - Git workflow set to 'manual' mode
+ Ready for SPEC generation.
+```
+
+---
+
+### `/moai:1-plan` - SPEC Generation
+
+Purpose: Generate SPEC document in EARS format
+
+Agent Delegation: `workflow-spec`
+
+Usage:
+```bash
+/moai:1-plan "Implement user authentication endpoint (JWT)"
+/moai:1-plan "Add dark mode toggle to settings page"
+```
+
+What It Does:
+1. Analyzes user request
+2. Generates EARS format SPEC document
+3. Creates `.moai/specs/SPEC-XXX/` directory
+4. Saves `spec.md` with requirements
+
+EARS Format (5 sections):
+- WHEN (trigger conditions)
+- IF (preconditions)
+- THE SYSTEM SHALL (functional requirements)
+- WHERE (constraints)
+- UBIQUITOUS (quality requirements)
+
+Output:
+- `.moai/specs/SPEC-001/spec.md` (EARS document)
+- SPEC ID assigned (auto-incremented)
+
+CRITICAL: Execute `/clear` immediately after completion
+- Saves 45-50K tokens
+- Prepares clean context for implementation
+
+Example:
+```
+User: /moai:1-plan "Implement user authentication endpoint (JWT)"
+Alfred: SPEC-001 generated successfully.
+ Location: .moai/specs/SPEC-001/spec.md
+
+ IMPORTANT: Execute /clear now to free 45-50K tokens.
+```
+
+---
+
+### `/moai:2-run` - TDD Implementation
+
+Purpose: Execute RED-GREEN-REFACTOR cycle
+
+Agent Delegation: `workflow-tdd`
+
+Usage:
+```bash
+/moai:2-run SPEC-001
+/moai:2-run SPEC-002
+```
+
+What It Does:
+1. Reads SPEC document
+2. Executes TDD cycle in 3 phases:
+ - RED: Write failing tests
+ - GREEN: Implement minimal code to pass tests
+ - REFACTOR: Optimize and clean up code
+3. Validates TRUST 5 quality gates
+4. Generates implementation report
+
+TDD Process:
+```
+Phase 1 (RED):
+ - Write failing tests for each requirement
+ - Run tests → ALL FAIL (expected)
+
+Phase 2 (GREEN):
+ - Implement minimal code to pass tests
+ - Run tests → ALL PASS
+
+Phase 3 (REFACTOR):
+ - Optimize code structure
+ - Improve readability
+ - Remove duplication
+ - Run tests → ALL PASS (maintained)
+```
+
+Output:
+- Implemented code (in source directories)
+- Test files (in test directories)
+- Quality report (TRUST 5 validation)
+
+Requirement: Test coverage ≥ 85% (TRUST 5)
+
+Example:
+```
+User: /moai:2-run SPEC-001
+Alfred: TDD implementation cycle started for SPEC-001.
+
+ RED: 12 failing tests written
+ GREEN: Implementation complete, all tests passing
+ REFACTOR: Code optimized
+
+ Test Coverage: 92% ( meets 85% threshold)
+ TRUST 5: All gates passed
+```
+
+---
+
+### `/moai:3-sync` - Documentation Synchronization
+
+Purpose: Auto-generate API documentation and project artifacts
+
+Agent Delegation: `workflow-docs`
+
+Usage:
+```bash
+/moai:3-sync SPEC-001
+/moai:3-sync SPEC-002
+```
+
+What It Does:
+1. Reads implemented code
+2. Generates API documentation (OpenAPI format)
+3. Creates architecture diagrams
+4. Produces project completion report
+
+Output:
+- API documentation (OpenAPI/Swagger format)
+- Architecture diagrams (Mermaid)
+- `.moai/docs/SPEC-001/` directory
+- Project report
+
+Example:
+```
+User: /moai:3-sync SPEC-001
+Alfred: Documentation synchronized for SPEC-001.
+
+ Generated:
+ - API documentation: .moai/docs/SPEC-001/api.yaml
+ - Architecture diagram: .moai/docs/SPEC-001/architecture.md
+ - Completion report: .moai/docs/SPEC-001/report.md
+```
+
+---
+
+### `/moai:9-feedback` - Improvement Feedback Collection
+
+Purpose: Error analysis and improvement suggestions
+
+Agent Delegation: `core-quality`
+
+Usage:
+```bash
+/moai:9-feedback
+/moai:9-feedback --analyze SPEC-001
+```
+
+What It Does:
+1. Analyzes errors encountered during workflow
+2. Collects improvement suggestions
+3. Reports to MoAI-ADK development team
+4. Proposes error recovery strategies
+
+Use Cases:
+- Errors: When errors occur during any workflow phase
+- Improvements: When MoAI-ADK enhancements are identified
+- Analysis: Post-implementation review
+
+Example:
+```
+User: /moai:9-feedback
+Alfred: Collecting feedback for recent session.
+
+ Errors: 2 permission issues detected
+ Improvements: 1 token optimization suggestion
+
+ Feedback submitted to MoAI-ADK development team.
+```
+
+---
+
+### `/moai:99-release` - Production Deployment
+
+Purpose: Production deployment workflow
+
+Agent Delegation: `infra-devops`
+
+Usage:
+```bash
+/moai:99-release
+```
+
+What It Does:
+1. Validates all TRUST 5 quality gates
+2. Runs full test suite
+3. Builds production artifacts
+4. Deploys to production environment
+
+Note: This command is local-only and NOT synchronized to the package template. It's for local development and testing.
+
+---
+
+## Advanced Implementation (10+ minutes)
+
+### Context Initialization Rules
+
+Rule 1: Execute `/clear` AFTER `/moai:1-plan` (mandatory)
+- SPEC generation uses 45-50K tokens
+- `/clear` frees this context for implementation phase
+- Prevents context overflow
+
+Rule 2: Execute `/clear` when context > 150K tokens
+- Monitor context usage via `/context` command
+- Prevents token limit exceeded errors
+
+Rule 3: Execute `/clear` after 50+ conversation messages
+- Accumulated context from conversation history
+- Reset for fresh context
+
+Why `/clear` is critical:
+```
+Without /clear:
+ SPEC generation: 50K tokens
+ Implementation: 100K tokens
+ Total: 150K tokens (approaching 200K limit)
+
+With /clear:
+ SPEC generation: 50K tokens
+ /clear: 0K tokens (reset)
+ Implementation: 100K tokens
+ Total: 100K tokens (50K budget remaining)
+```
+
+---
+
+### Command Delegation Patterns
+
+Each command delegates to a specific agent:
+
+| Command            | Agent              | Agent Type              |
+| ------------------ | ------------------ | ----------------------- |
+| `/moai:0-project`  | `workflow-project` | Tier 1 (Always Active)  |
+| `/moai:1-plan`     | `workflow-spec`    | Tier 1 (Always Active)  |
+| `/moai:2-run`      | `workflow-tdd`     | Tier 1 (Always Active)  |
+| `/moai:3-sync`     | `workflow-docs`    | Tier 1 (Always Active)  |
+| `/moai:9-feedback` | `core-quality`     | Tier 2 (Auto-triggered) |
+| `/moai:99-release` | `infra-devops`     | Tier 3 (Lazy-loaded)    |
+
+Delegation Flow:
+```
+User executes command
+ ↓
+Alfred receives command
+ ↓
+Command processor agent invoked
+ ↓
+Agent executes workflow
+ ↓
+Results reported to user
+```
+
+---
+
+### Token Budget by Command
+
+| Command        | Average Tokens | Phase Budget                          |
+| -------------- | -------------- | ------------------------------------- |
+| `/moai:1-plan` | 45-50K         | Planning Phase (30K allocated)        |
+| `/moai:2-run`  | 80-100K        | Implementation Phase (180K allocated) |
+| `/moai:3-sync` | 20-25K         | Documentation Phase (40K allocated)   |
+| Total          | 145-175K       | 250K per feature                      |
+
+Optimization:
+- Use Haiku 4.5 for `/moai:2-run` (fast, cost-effective)
+- Use Sonnet 4.5 for `/moai:1-plan` (high-quality SPEC)
+- Execute `/clear` between phases (critical)
+
+---
+
+### Error Handling
+
+Common Errors:
+
+| Error                     | Command                | Solution                                    |
+| ------------------------- | ---------------------- | ------------------------------------------- |
+| "Project not initialized" | `/moai:1-plan`         | Run `/moai:0-project` first                 |
+| "SPEC not found"          | `/moai:2-run SPEC-999` | Verify SPEC ID exists                       |
+| "Token limit exceeded"    | Any                    | Execute `/clear` immediately                |
+| "Test coverage < 85%"     | `/moai:2-run`          | `core-quality` auto-generates missing tests |
+
+Recovery Pattern:
+```bash
+# Error: Token limit exceeded
+1. /clear # Reset context
+2. /moai:2-run SPEC-001 # Retry with clean context
+```
+
+---
+
+### Workflow Variations
+
+Standard Workflow (Full SPEC):
+```
+/moai:0-project → /moai:1-plan → /clear → /moai:2-run → /moai:3-sync
+```
+
+Quick Workflow (No SPEC for simple tasks):
+```
+/moai:0-project → Direct implementation (for 1-2 file changes)
+```
+
+Iterative Workflow (Multiple SPECs):
+```
+/moai:1-plan "Feature A" → /clear → /moai:2-run SPEC-001 → /moai:3-sync SPEC-001
+/moai:1-plan "Feature B" → /clear → /moai:2-run SPEC-002 → /moai:3-sync SPEC-002
+```
+
+---
+
+### Integration with Git Workflow
+
+Commands automatically integrate with Git based on `config.json` settings:
+
+Manual Mode (Local Git):
+- `/moai:1-plan`: Prompts for branch creation
+- `/moai:2-run`: Auto-commits to local branch
+- No auto-push
+
+Personal Mode (GitHub Individual):
+- `/moai:1-plan`: Auto-creates feature branch + auto-push
+- `/moai:2-run`: Auto-commits + auto-push
+- `/moai:3-sync`: Suggests PR creation (user choice)
+
+Team Mode (GitHub Team):
+- `/moai:1-plan`: Auto-creates feature branch + Draft PR
+- `/moai:2-run`: Auto-commits + auto-push
+- `/moai:3-sync`: Prepares PR for team review
+
+---
+
+## Works Well With
+
+Skills:
+- [moai-foundation-core](../SKILL.md) - Parent skill
+- [moai-foundation-context](../../moai-foundation-context/SKILL.md) - Token budget management
+
+Other Modules:
+- [spec-first-tdd.md](spec-first-tdd.md) - Detailed SPEC-First TDD process
+- [token-optimization.md](token-optimization.md) - /clear execution strategies
+- [agents-reference.md](agents-reference.md) - Agent catalog
+
+Agents:
+- [workflow-project](agents-reference.md#tier-1-command-processors) - `/moai:0-project`
+- [workflow-spec](agents-reference.md#tier-1-command-processors) - `/moai:1-plan`
+- [workflow-tdd](agents-reference.md#tier-1-command-processors) - `/moai:2-run`
+- [workflow-docs](agents-reference.md#tier-1-command-processors) - `/moai:3-sync`
+
+---
+
+Maintained by: MoAI-ADK Team
+Status: Production Ready

moai_adk/templates/.claude/skills/moai-foundation-core/modules/delegation-advanced.md

@@ -0,0 +1,279 @@
+# Delegation Advanced Patterns
+
+Purpose: Error handling, recovery strategies, and hybrid delegation patterns for complex workflows.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [delegation-patterns.md](delegation-patterns.md)
+
+---
+
+## Error Handling and Recovery
+
+### Resilient Delegation Pattern
+
+```python
+from typing import Optional
+import asyncio
+
+class ResilientDelegation:
+    """Handle delegation failures with retry and fallback."""
+
+    def __init__(self):
+        self.max_retries = 3
+        self.retry_delay = 5  # seconds
+
+    async def delegate_with_retry(
+        self,
+        agent_type: str,
+        prompt: str,
+        context: dict,
+        fallback_agent: Optional[str] = None
+    ):
+        """Delegate with automatic retry and fallback."""
+
+        for attempt in range(self.max_retries):
+            try:
+                result = await Task(
+                    subagent_type=agent_type,
+                    prompt=prompt,
+                    context=context
+                )
+                return result
+
+            except AgentExecutionError as e:
+                if attempt < self.max_retries - 1:
+                    delay = self.retry_delay * (2 ** attempt)
+                    await asyncio.sleep(delay)
+                    continue
+
+                if fallback_agent:
+                    return await self._fallback_delegation(
+                        fallback_agent, prompt, context, original_error=e
+                    )
+
+                raise
+
+            except ContextTooLargeError as e:
+                compressed_context = self._compress_context(context)
+                return await Task(
+                    subagent_type=agent_type,
+                    prompt=prompt,
+                    context=compressed_context
+                )
+
+    async def _fallback_delegation(
+        self,
+        fallback_agent: str,
+        prompt: str,
+        context: dict,
+        original_error: Exception
+    ):
+        """Execute fallback delegation."""
+        fallback_context = {
+            **context,
+            "original_error": str(original_error),
+            "fallback_mode": True
+        }
+
+        return await Task(
+            subagent_type=fallback_agent,
+            prompt=f"[FALLBACK] {prompt}",
+            context=fallback_context
+        )
+```
+
+Usage:
+```python
+delegator = ResilientDelegation()
+
+result = await delegator.delegate_with_retry(
+    agent_type="code-backend",
+    prompt="Implement complex feature",
+    context=large_context,
+    fallback_agent="support-debug"
+)
+```
+
+---
+
+## Hybrid Delegation Patterns
+
+### Sequential + Parallel Combination
+
+```python
+async def hybrid_workflow(spec_id: str):
+    """Combine sequential and parallel patterns."""
+
+    # Phase 1: Sequential (SPEC → Design)
+    spec = await Task(
+        subagent_type="workflow-spec",
+        prompt=f"Generate SPEC {spec_id}"
+    )
+
+    design = await Task(
+        subagent_type="api-designer",
+        prompt="Design API",
+        context={"spec_id": spec.id}
+    )
+
+    execute_clear()
+
+    # Phase 2: Parallel (Implementation)
+    impl_results = await Promise.all([
+        Task(
+            subagent_type="code-backend",
+            prompt="Backend",
+            context={"spec_id": spec.id, "api": design}
+        ),
+        Task(
+            subagent_type="code-frontend",
+            prompt="Frontend",
+            context={"spec_id": spec.id, "api": design}
+        ),
+        Task(
+            subagent_type="data-database",
+            prompt="Database",
+            context={"spec_id": spec.id, "api": design}
+        )
+    ])
+
+    backend, frontend, database = impl_results
+
+    # Phase 3: Sequential (Testing → QA)
+    tests = await Task(
+        subagent_type="core-quality",
+        prompt="Integration tests",
+        context={
+            "spec_id": spec.id,
+            "backend": backend.summary,
+            "frontend": frontend.summary,
+            "database": database.summary
+        }
+    )
+
+    qa = await Task(
+        subagent_type="core-quality",
+        prompt="Quality validation",
+        context={
+            "spec_id": spec.id,
+            "tests": tests.results,
+            "coverage": tests.coverage
+        }
+    )
+
+    return {
+        "spec": spec,
+        "design": design,
+        "backend": backend,
+        "frontend": frontend,
+        "database": database,
+        "tests": tests,
+        "qa": qa
+    }
+```
+
+---
+
+### Conditional + Parallel Combination
+
+```python
+async def conditional_parallel_workflow(requests: list):
+    """Route multiple requests in parallel based on analysis."""
+
+    # Phase 1: Parallel analysis
+    analyses = await Promise.all([
+        Task(
+            subagent_type="plan",
+            prompt=f"Analyze request",
+            context={"request": req}
+        )
+        for req in requests
+    ])
+
+    # Phase 2: Conditional routing (grouped by type)
+    security_tasks = []
+    feature_tasks = []
+    bug_tasks = []
+
+    for analysis in analyses:
+        if analysis.category == "security":
+            security_tasks.append(
+                Task(
+                    subagent_type="security-expert",
+                    prompt="Handle security issue",
+                    context={"analysis": analysis}
+                )
+            )
+        elif analysis.category == "feature":
+            feature_tasks.append(
+                Task(
+                    subagent_type="code-backend",
+                    prompt="Implement feature",
+                    context={"analysis": analysis}
+                )
+            )
+        elif analysis.category == "bug":
+            bug_tasks.append(
+                Task(
+                    subagent_type="support-debug",
+                    prompt="Debug issue",
+                    context={"analysis": analysis}
+                )
+            )
+
+    # Phase 3: Parallel execution by category
+    results = await Promise.all([
+        *security_tasks,
+        *feature_tasks,
+        *bug_tasks
+    ])
+
+    return results
+```
+
+---
+
+## Context Compression Strategies
+
+```python
+class ContextCompressor:
+    """Compress context when exceeding limits."""
+
+    def compress_for_agent(self, context: dict, agent_type: str) -> dict:
+        """Compress context based on agent requirements."""
+
+        # Remove non-essential fields
+        essential_fields = self._get_essential_fields(agent_type)
+        compressed = {k: v for k, v in context.items() if k in essential_fields}
+
+        # Compress large text fields
+        for key, value in compressed.items():
+            if isinstance(value, str) and len(value) > 5000:
+                compressed[key] = self._summarize_text(value)
+
+            elif isinstance(value, list) and len(value) > 100:
+                compressed[key] = value[:50] + ["... (truncated)"] + value[-10:]
+
+        return compressed
+
+    def _summarize_text(self, text: str, max_length: int = 1000) -> str:
+        """Summarize long text to key points."""
+        paragraphs = text.split("\n\n")
+        if len(paragraphs) > 2:
+            summary = paragraphs[0] + "\n\n...\n\n" + paragraphs[-1]
+            return summary[:max_length] if len(summary) > max_length else summary
+        return text[:max_length]
+```
+
+---
+
+## Works Well With
+
+- [delegation-patterns.md](delegation-patterns.md) - Overview
+- [delegation-implementation.md](delegation-implementation.md) - Basic patterns
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06