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

moai_adk/templates/.claude/skills/moai-workflow-jit-docs/reference.md

@@ -0,0 +1,307 @@
+# moai-workflow-jit-docs Reference
+
+## API Reference
+
+### Intent Analysis API
+
+Intent Detection Functions:
+- `analyze_user_intent(user_input, context)`: Determine documentation needs
+- `extract_technologies(user_input)`: Identify technology keywords
+- `extract_domains(user_input)`: Identify domain keywords
+- `classify_question(user_input)`: Categorize question type
+- `assess_complexity(user_input)`: Evaluate question complexity
+- `determine_urgency(user_input)`: Assess information urgency
+
+Intent Structure:
+```python
+{
+    "technologies": ["FastAPI", "JWT"],
+    "domains": ["authentication", "security"],
+    "question_type": "implementation",
+    "complexity": "medium",
+    "urgency": "standard"
+}
+```
+
+Question Types:
+- `implementation`: How to build/create something
+- `troubleshooting`: How to fix issues
+- `conceptual`: Understanding concepts
+- `best_practices`: Recommended approaches
+- `comparison`: Evaluating options
+
+### Source Prioritization API
+
+Priority Functions:
+- `prioritize_documentation_sources(intent)`: Rank sources by relevance
+- `has_local_docs()`: Check for project documentation
+- `get_official_docs(technology)`: Get official documentation URL
+- `calculate_relevance(content, context)`: Score content relevance
+
+Source Types and Weights:
+- `local`: Project documentation (priority 1.0)
+- `official`: Official documentation (priority 0.9)
+- `web`: Real-time web research (priority 0.8)
+- `community`: Community resources (priority 0.7)
+
+### Caching API
+
+DocumentationCache Class:
+- `get(key, context)`: Retrieve cached documentation
+- `store(key, content, relevance_score)`: Cache with relevance
+- `remove(key)`: Remove from cache
+- `is_relevant(key, context)`: Check current relevance
+- `update_access_time(key)`: Track access patterns
+
+Cache Levels:
+- `session`: Current session only
+- `project`: Project-specific persistent cache
+- `global`: Cross-project shared cache
+
+### Quality Assessment API
+
+Quality Functions:
+- `assess_documentation_quality(content)`: Evaluate content quality
+- `is_official_source(content)`: Check source authority
+- `is_recent(content, months)`: Check content age
+- `has_examples(content)`: Check for code examples
+- `has_explanations(content)`: Check for explanations
+
+Quality Scoring:
+- Authority: 30% (official sources preferred)
+- Recency: 25% (recent content preferred)
+- Completeness: 25% (examples and explanations)
+- Relevance: 20% (match to user context)
+
+---
+
+## Configuration Options
+
+### Source Configuration
+
+Local Documentation Paths:
+- `.moai/docs/`: Project-specific documentation
+- `.moai/specs/`: Requirements and specifications
+- `README.md`: General project information
+- `CHANGELOG.md`: Version history
+- `docs/`: Comprehensive documentation directory
+
+Official Documentation URLs:
+```python
+official_docs = {
+    "FastAPI": "https://fastapi.tiangolo.com/",
+    "React": "https://react.dev/",
+    "PostgreSQL": "https://www.postgresql.org/docs/",
+    "Docker": "https://docs.docker.com/",
+    "Kubernetes": "https://kubernetes.io/docs/",
+    "TypeScript": "https://www.typescriptlang.org/docs/"
+}
+```
+
+### Cache Configuration
+
+Cache Settings:
+- `cache_duration_days`: How long to keep cached content
+- `max_cache_size_mb`: Maximum cache size
+- `auto_cleanup_enabled`: Enable automatic cleanup
+- `relevance_threshold`: Minimum relevance to cache
+
+Eviction Policies:
+- Remove content older than 30 days
+- Keep high-authority sources longer
+- Prioritize frequently accessed content
+- Remove low-relevance content first
+
+### Intent Detection Settings
+
+Technology Keywords:
+- Frameworks: FastAPI, React, Vue, Django, Flask
+- Languages: Python, TypeScript, JavaScript, Go, Rust
+- Databases: PostgreSQL, MongoDB, Redis, MySQL
+- DevOps: Docker, Kubernetes, Terraform, AWS
+
+Domain Keywords:
+- Security: authentication, authorization, encryption
+- Performance: optimization, caching, scaling
+- Database: queries, migrations, indexing
+- API: endpoints, REST, GraphQL
+
+---
+
+## Integration Patterns
+
+### Question-Based Loading
+
+Trigger Pattern:
+1. User asks specific question
+2. Intent analysis identifies needs
+3. Sources prioritized by relevance
+4. Documentation loaded and cached
+5. Enhanced response generated
+
+Example Flow:
+```
+User: "How do I implement JWT in FastAPI?"
+
+1. Intent: {technologies: [FastAPI, JWT], domains: [auth]}
+2. Sources: [FastAPI docs, JWT best practices]
+3. Load: Official FastAPI security guide
+4. Cache: Store with high relevance score
+5. Response: Comprehensive JWT implementation guide
+```
+
+### Technology-Specific Loading
+
+Trigger Pattern:
+1. Technology keyword detected
+2. Official documentation identified
+3. Relevant sections loaded
+4. Community resources added
+5. Latest updates checked
+
+Technology Coverage:
+- Language-specific patterns and idioms
+- Framework configuration and usage
+- Library integration examples
+- Version-specific changes
+
+### Domain-Specific Loading
+
+Trigger Pattern:
+1. Domain keyword detected
+2. Domain expertise documentation loaded
+3. Best practices identified
+4. Common patterns extracted
+5. Troubleshooting guides added
+
+Domain Coverage:
+- Authentication and authorization patterns
+- Database optimization strategies
+- API design best practices
+- Performance tuning guides
+
+### Real-Time Web Research
+
+Trigger Pattern:
+1. Latest information needed
+2. WebSearch executed with current year
+3. Results quality-assessed
+4. High-quality content extracted
+5. Cached for future use
+
+Search Optimization:
+```python
+WebSearch(f"{query} best practices 2024 2025")
+```
+
+---
+
+## Troubleshooting
+
+### Documentation Not Loading
+
+Symptoms: Skill not activating, missing context
+
+Solutions:
+1. Verify intent detection triggered
+2. Check local documentation paths exist
+3. Confirm network connectivity for web sources
+4. Review cache for stale entries
+
+### Low Quality Results
+
+Symptoms: Irrelevant or outdated documentation
+
+Solutions:
+1. Adjust relevance threshold higher
+2. Clear cache to force fresh fetch
+3. Prioritize official sources
+4. Add year filter to web searches
+
+### Cache Issues
+
+Symptoms: Stale content, cache bloat
+
+Solutions:
+1. Clear session cache: Reset current session
+2. Clear project cache: Remove project-specific cache
+3. Reduce cache duration
+4. Lower max cache size
+
+### Intent Misdetection
+
+Symptoms: Wrong documentation loaded
+
+Solutions:
+1. User clarification requested
+2. Refine keyword extraction
+3. Adjust domain mappings
+4. Add technology aliases
+
+### Network Failures
+
+Symptoms: Web sources unavailable
+
+Solutions:
+1. Fall back to cached content
+2. Use local documentation
+3. Provide partial results with notice
+4. Retry with backoff
+
+---
+
+## External Resources
+
+### Documentation Sources
+
+Official Sources by Category:
+- Languages: Official language documentation
+- Frameworks: Framework official guides
+- Databases: Database documentation
+- Cloud: Provider documentation
+
+Community Resources:
+- Stack Overflow (highly-voted answers)
+- GitHub Discussions (official projects)
+- Dev.to (tutorial articles)
+- Medium (technical deep-dives)
+
+### Quality Indicators
+
+High-Quality Sources:
+- Official documentation (docs.*.com, *.io/docs)
+- GitHub repositories with high stars
+- Conference talks and official blogs
+- Books from recognized publishers
+
+Low-Quality Sources:
+- Outdated content (older than 2 years)
+- No code examples
+- Missing author attribution
+- Scraped or aggregated content
+
+### Related Skills
+
+- `moai-docs-generation`: Generate documentation
+- `moai-workflow-docs`: Documentation workflows
+- `moai-library-nextra`: Nextra documentation sites
+- `moai-foundation-context`: Token budget management
+
+### Performance Optimization
+
+Loading Strategies:
+- Lazy loading: Load only when needed
+- Batch processing: Combine related queries
+- Progressive disclosure: Load detail on demand
+- Intelligent caching: Predict future needs
+
+Metrics:
+- Cache hit rate target: Greater than 70%
+- Average load time: Less than 2 seconds
+- Relevance score threshold: 0.7 minimum
+- Quality score threshold: 0.6 minimum
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-06

moai_adk/templates/.claude/skills/moai-workflow-loop/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: moai-workflow-loop
+description: Ralph Engine - Automated feedback loop with LSP diagnostics and AST-grep integration for continuous code quality improvement. Use when implementing error-driven development, automated fixing, or continuous quality validation workflows.
+version: 1.2.0
+category: workflow
+tags: ['lsp', 'ast-grep', 'feedback-loop', 'code-quality', 'automation', 'diagnostics', 'ralph']
+user-invocable: false
+updated: 2026-01-11
+status: active
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# Ralph Engine
+
+Automated feedback loop system integrating LSP diagnostics, AST-grep security scanning, and test validation for continuous code quality improvement.
+
+## Quick Reference
+
+Core Capabilities:
+
+- LSP Integration: Real-time diagnostics from language servers
+- AST-grep Scanning: Structural code analysis and security checks
+- Feedback Loop: Iterative error correction until completion conditions met
+- Hook System: PostToolUse and Stop hooks for seamless Claude Code integration
+
+Key Components:
+
+- post_tool__lsp_diagnostic.py: LSP diagnostics after Write/Edit operations
+- stop__loop_controller.py: Loop iteration control
+- ralph.yaml: Configuration settings
+
+Commands:
+
+- /moai:alfred: One-click Plan-Run-Sync automation
+- /moai:loop: Start feedback loop
+- /moai:fix: One-time auto-fix
+- /moai:cancel-loop: Stop active loop
+
+When to Use:
+
+- Implementing features with zero-error goal
+- Automated code quality improvement
+- Continuous integration workflows
+- Error-driven development patterns
+
+## Implementation Guide
+
+### Architecture Overview
+
+The Ralph Engine follows a layered architecture. User commands such as /moai:loop, /moai:fix, and /moai:alfred enter the Command Layer. The Command Layer invokes the Hook System, which contains the PostToolUse Hook for LSP diagnostics and the Stop Hook for loop control. The Hook System connects to Backend Services including the LSP Client (MoAILSPClient), AST-grep Scanner, and Test Runner. Backend Services feed into Completion Check which evaluates whether errors are zero, tests pass, and coverage is met. Based on the Completion Check result, the system either continues the loop or completes.
+
+### Configuration
+
+The ralph.yaml configuration file contains the following sections and settings.
+
+Under the ralph section, enabled controls whether Ralph is active (true by default).
+
+Under the lsp section, auto_start controls automatic language server startup (true by default), timeout_seconds sets the connection timeout (30 seconds default), and graceful_degradation enables fallback to linters when LSP unavailable (true by default).
+
+Under the ast_grep section, enabled controls AST-grep integration (true by default), security_scan enables security rule checking (true by default), and quality_scan enables code quality rule checking (true by default).
+
+Under the loop section, max_iterations sets the maximum loop iterations (10 by default), auto_fix controls automatic fix application (false by default requiring confirmation), and require_confirmation requires user approval before fixes (true by default).
+
+Under the completion subsection of loop, zero_errors requires no LSP or compiler errors (true by default), zero_warnings requires no warnings (false by default as optional), tests_pass requires all tests to pass (true by default), and coverage_threshold sets minimum coverage percentage (85 by default).
+
+Under the hooks section, post_tool_lsp has enabled (true by default) and severity_threshold (error by default). The stop_loop_controller has enabled set to true by default.
+
+### Hook Integration
+
+#### PostToolUse Hook
+
+The PostToolUse hook is triggered after Write and Edit operations. When invoked, Claude Code provides hook input containing the tool_name (such as Write) and tool_input containing the file_path and content.
+
+The hook processes diagnostics and returns hook output with hookSpecificOutput containing the hookEventName (PostToolUse) and additionalContext describing the diagnostic results. For example, the context might report LSP found 2 errors and 3 warnings in file.py, with specific error messages including line numbers.
+
+Exit code 0 indicates no action needed. Exit code 2 indicates attention needed due to errors found.
+
+#### Stop Hook for Loop Controller
+
+The Stop hook is triggered after each Claude response. The hook reads the loop state file located at .moai/cache/.moai_loop_state.json. This state contains active status (true or false), current iteration number, max_iterations limit, last_error_count from previous iteration, and completion_reason when finished.
+
+The hook returns output with hookSpecificOutput containing hookEventName (Stop) and additionalContext reporting loop status. For example, it might report Ralph Loop CONTINUE at Iteration 3 of 10 with 2 Errors, and next actions to fix the remaining errors.
+
+Exit code 0 indicates loop complete or inactive. Exit code 1 indicates continue loop with more work needed.
+
+### LSP Client Usage
+
+Initialize the MoAILSPClient from moai_adk.lsp.client with the project_root parameter set to the project directory path.
+
+To get diagnostics for a file, call the get_diagnostics method asynchronously with the file path.
+
+Process the returned diagnostics by iterating through each diagnostic object. Check the severity property against DiagnosticSeverity.ERROR to identify errors. Access the line number from diag.range.start.line and the message from diag.message.
+
+### Completion Conditions
+
+The loop completes when all enabled conditions are met.
+
+The zero_errors condition (default true) requires no LSP or compiler errors.
+
+The zero_warnings condition (default false) optionally requires no warnings.
+
+The tests_pass condition (default true) requires all tests to pass.
+
+The coverage_threshold condition (default 85) requires minimum coverage percentage.
+
+## Advanced Patterns
+
+### Custom Completion Conditions
+
+Extend the loop controller with custom conditions by implementing a check function. For example, create a function to count TODO comments in the codebase and return true only when the count reaches zero.
+
+### Integration with CI/CD
+
+For GitHub Actions integration, create a workflow step that runs Claude with the /moai:loop command and max-iterations flag. Set the MOAI_LOOP_ACTIVE environment variable to true to enable loop mode.
+
+### Graceful Degradation
+
+When LSP is unavailable, the system falls back to linter-based diagnostics using tools like ruff or eslint, then to compiler error detection, and finally to test failure detection.
+
+## Troubleshooting
+
+### Loop Not Starting
+
+Check that ralph.enabled is set to true in configuration. Verify MOAI_DISABLE_LOOP_CONTROLLER environment variable is not set. Ensure the state file location is writable.
+
+### LSP Diagnostics Missing
+
+Check LSP server configuration in .lsp.json file. Verify the language server is installed for your language. Check that MOAI_DISABLE_LSP_DIAGNOSTIC environment variable is not set.
+
+### Loop Stuck
+
+Review the max_iterations setting to ensure it allows sufficient iterations. Review completion conditions to verify they are achievable. Use /moai:cancel-loop command to reset the loop state.
+
+## Works Well With
+
+Skills:
+
+- moai-foundation-quality: TRUST 5 validation
+- moai-tool-ast-grep: Security scanning patterns
+- moai-workflow-testing: TDD integration
+- moai-lang-python: Python-specific patterns
+- moai-lang-typescript: TypeScript patterns
+
+Agents:
+
+- manager-tdd: TDD implementation
+- manager-quality: Quality validation
+- expert-debug: Complex debugging
+
+Commands:
+
+- /moai:2-run: TDD implementation
+- /moai:3-sync: Documentation sync
+
+## Reference
+
+### Environment Variables
+
+MOAI_DISABLE_LSP_DIAGNOSTIC disables the LSP hook when set.
+
+MOAI_DISABLE_LOOP_CONTROLLER disables the loop hook when set.
+
+MOAI_LOOP_ACTIVE indicates whether the loop is currently active.
+
+MOAI_LOOP_ITERATION contains the current iteration number.
+
+CLAUDE_PROJECT_DIR contains the project root path.
+
+### File Locations
+
+Configuration is stored at .moai/config/sections/ralph.yaml.
+
+Loop state is stored at .moai/cache/.moai_loop_state.json.
+
+The LSP hook is located at .claude/hooks/moai/post_tool__lsp_diagnostic.py.
+
+The loop hook is located at .claude/hooks/moai/stop__loop_controller.py.
+
+### Supported Languages
+
+LSP diagnostics are available for Python using pyright or pylsp, TypeScript and JavaScript using tsserver, Go using gopls, Rust using rust-analyzer, Java using jdtls, and additional languages via .lsp.json configuration.
+
+---
+
+Version: 1.2.0
+Last Updated: 2026-01-11
+Status: Active
+Integration: Claude Code Hooks, LSP Protocol, AST-grep
+Skill Name: moai-workflow-loop (formerly moai-ralph)