moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-jit-docs-enhanced/SKILL.md

@@ -0,0 +1,460 @@
+---
+name: moai-jit-docs-enhanced
+version: 1.0.0
+created: 2025-11-05
+updated: 2025-11-05
+status: active
+description: Enhanced Just-In-Time document loading system that intelligently discovers, loads, and caches relevant documentation based on user intent and project context. Use when users need specific documentation, when working with new technologies, when answering domain-specific questions, or when context indicates documentation gaps.
+keywords: [jit-loading, documentation, context-aware, intelligent-caching, domain-knowledge, tech-docs]
+allowed-tools:
+  - Read
+  - Glob
+  - WebFetch
+  - WebSearch
+---
+
+# Enhanced JIT Documentation Loader
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Alfred (Knowledge Management) |
+| Auto-load | When documentation gaps detected |
+| Purpose | Intelligent, context-aware document loading |
+
+---
+
+## What It Does
+
+Advanced Just-In-Time documentation loading system that intelligently discovers, retrieves, and caches relevant documentation based on user intent, project context, and knowledge gaps. Enhances Alfred's capabilities by bringing in the right documentation at the right time.
+
+**Core capabilities**:
+- ✅ Intent-based document discovery
+- ✅ Context-aware loading strategies
+- ✅ Intelligent caching and retrieval
+- ✅ Multi-source documentation aggregation
+- ✅ Domain-specific knowledge integration
+- ✅ Real-time web research for latest information
+- ✅ Documentation quality assessment
+- ✅ Automatic relevance ranking
+
+---
+
+## When to Use
+
+- ✅ When user questions indicate knowledge gaps
+- ✅ When working with unfamiliar technologies or frameworks
+- ✅ When domain-specific expertise is needed
+- ✅ When answering technical questions with precision
+- ✅ When implementing new features or patterns
+- ✅ When troubleshooting complex issues
+- ✅ When best practices guidance is required
+
+---
+
+## Intent Detection Patterns
+
+### 1. Question-Based Triggers
+```python
+# User asks specific questions
+"how do I implement JWT in FastAPI?"
+"What's the best way to handle database migrations?"
+"How does React useEffect work exactly?"
+"What are the security implications of JWT?"
+
+# Trigger: Load relevant documentation
+Skill("moai-jit-docs-enhanced")
+# → Loads FastAPI JWT authentication docs
+# → Loads database migration best practices
+# → Loads React hooks documentation
+# → Loads JWT security analysis
+```
+
+### 2. Technology-Specific Triggers
+```python
+# Technology keywords detected
+"FastAPI", "React", "PostgreSQL", "Docker", "Kubernetes"
+"pytest", "TypeScript", "GraphQL", "Redis", "NGINX"
+
+# Trigger: Load technology-specific documentation
+Skill("moai-jit-docs-enhanced")
+# → Loads official docs, tutorials, best practices
+```
+
+### 3. Domain-Specific Triggers
+```python
+# Domain keywords detected
+"authentication", "authorization", "security", "performance"
+"database", "api", "frontend", "backend", "devops"
+
+# Trigger: Load domain expertise documentation
+Skill("moai-jit-docs-enhanced")
+# → Loads domain-specific patterns and guidelines
+```
+
+### 4. Pattern-Based Triggers
+```python
+# Implementation patterns
+"implement", "create", "build", "design", "architecture"
+"best practices", "optimization", "troubleshooting", "debugging"
+
+# Trigger: Load implementation guidance
+Skill("moai-jit-docs-enhanced")
+# → Loads implementation patterns and examples
+```
+
+---
+
+## Documentation Sources
+
+### 1. Local Project Documentation
+```bash
+# Primary sources (highest priority)
+.moai/docs/                    # Project-specific docs
+.moai/specs/                   # Requirements and specifications
+README.md                      # General project information
+CHANGELOG.md                   # Version history
+docs/                          # Comprehensive documentation
+```
+
+### 2. Official Documentation
+```python
+# Technology-specific official sources
+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/"
+}
+```
+
+### 3. Community Resources
+```python
+# High-quality community resources
+community_resources = {
+    "Stack Overflow": "Highly-voted answers",
+    "GitHub Discussions": "Official project discussions",
+    "Dev.to": "Tutorial articles",
+    "Medium": "Technical deep-dives"
+}
+```
+
+### 4. Real-Time Web Research
+```python
+# Dynamic content for latest information
+def get_latest_info(query):
+    return WebSearch(f"{query} best practices 2024 2025")
+```
+
+---
+
+## Loading Strategies
+
+### 1. Intent Analysis
+```python
+def analyze_user_intent(user_input, context):
+    """Determine what documentation is needed"""
+    intent = {
+        "technologies": extract_technologies(user_input),
+        "domains": extract_domains(user_input),
+        "question_type": classify_question(user_input),
+        "complexity": assess_complexity(user_input),
+        "urgency": determine_urgency(user_input)
+    }
+    return intent
+```
+
+### 2. Source Prioritization
+```python
+def prioritize_documentation_sources(intent):
+    """Rank sources based on intent and context"""
+    priorities = []
+
+    # 1. Local project docs (always first)
+    if has_local_docs():
+        priorities.append(("local", 1.0))
+
+    # 2. Official docs (high authority)
+    for tech in intent["technologies"]:
+        if official_docs.get(tech):
+            priorities.append(("official", 0.9))
+
+    # 3. Community resources (practical examples)
+    if intent["question_type"] == "implementation":
+        priorities.append(("community", 0.7))
+
+    # 4. Web research (latest info)
+    if intent["urgency"] == "latest":
+        priorities.append(("web", 0.8))
+
+    return sorted(priorities, key=lambda x: x[1], reverse=True)
+```
+
+### 3. Intelligent Caching
+```python
+class DocumentationCache:
+    """Smart caching system for documentation"""
+
+    def __init__(self):
+        self.cache = {}
+        self.relevance_scores = {}
+        self.access_times = {}
+
+    def get(self, key, context):
+        """Get cached documentation if still relevant"""
+        if key in self.cache:
+            # Check relevance based on context
+            if self.is_relevant(key, context):
+                self.update_access_time(key)
+                return self.cache[key]
+            else:
+                # Remove outdated content
+                self.remove(key)
+        return None
+
+    def store(self, key, content, relevance_score):
+        """Store documentation with relevance score"""
+        self.cache[key] = content
+        self.relevance_scores[key] = relevance_score
+        self.access_times[key] = datetime.now()
+```
+
+---
+
+## Quality Assessment
+
+### 1. Content Quality Metrics
+```python
+def assess_documentation_quality(content):
+    """Evaluate documentation quality"""
+    quality_score = 0.0
+
+    # Authority (30%)
+    if is_official_source(content):
+        quality_score += 0.3
+    elif is_reputable_community(content):
+        quality_score += 0.2
+
+    # Recency (25%)
+    if is_recent(content, months=6):
+        quality_score += 0.25
+    elif is_recent(content, months=12):
+        quality_score += 0.15
+
+    # Completeness (25%)
+    if has_examples(content):
+        quality_score += 0.1
+    if has_code_samples(content):
+        quality_score += 0.1
+    if has_explanations(content):
+        quality_score += 0.05
+
+    # Relevance (20%)
+    relevance = calculate_relevance(content, user_context)
+    quality_score += relevance * 0.2
+
+    return min(quality_score, 1.0)
+```
+
+### 2. Relevance Ranking
+```python
+def rank_documentation_results(results, user_context):
+    """Rank documentation by relevance to user context"""
+    ranked_results = []
+
+    for result in results:
+        relevance_score = calculate_relevance(result, user_context)
+        quality_score = assess_documentation_quality(result)
+
+        # Combined score: 70% relevance, 30% quality
+        combined_score = (relevance_score * 0.7) + (quality_score * 0.3)
+
+        ranked_results.append({
+            "content": result,
+            "relevance": relevance_score,
+            "quality": quality_score,
+            "combined": combined_score
+        })
+
+    return sorted(ranked_results, key=lambda x: x["combined"], reverse=True)
+```
+
+---
+
+## Integration Examples
+
+### Example 1: Authentication Implementation
+```python
+# User asks: "How do I implement JWT authentication in FastAPI?"
+
+# 1. Intent Analysis
+intent = {
+    "technologies": ["FastAPI", "JWT"],
+    "domains": ["authentication", "security"],
+    "question_type": "implementation",
+    "complexity": "medium"
+}
+
+# 2. Documentation Loading
+Skill("moai-jit-docs-enhanced")
+
+# 3. Loaded Documentation
+docs_loaded = [
+    "FastAPI Security - OAuth2 with JWT (Official)",
+    "JWT Best Practices for APIs (Community)",
+    "FastAPI JWT Implementation Tutorial (High-quality)",
+    "JWT Security Considerations (Latest research)"
+]
+
+# 4. Enhanced Response
+Alfred can now provide comprehensive, accurate guidance
+```
+
+### Example 2: Database Optimization
+```python
+# User asks: "My PostgreSQL queries are slow, how can I optimize them?"
+
+# 1. Intent Detection
+# Technologies: PostgreSQL
+# Domains: database, performance, optimization
+# Question Type: troubleshooting
+
+# 2. JIT Documentation Loading
+Skill("moai-jit-docs-enhanced")
+
+# 3. Loaded Resources
+performance_docs = [
+    "PostgreSQL Query Optimization Guide (Official)",
+    "EXPLAIN ANALYZE Best Practices (Community)",
+    "Database Indexing Strategies (Expert article)",
+    "PostgreSQL Performance Tuning (Latest version)"
+]
+
+# 4. Contextual Response
+Alfred provides specific, actionable optimization advice
+```
+
+### Example 3: New Technology Adoption
+```python
+# User wants to implement GraphQL in existing project
+
+# 1. Technology Detection
+# New technology: GraphQL
+# Context: Existing REST API project
+# Need: Migration guidance
+
+# 2. Comprehensive Documentation Loading
+Skill("moai-jit-docs-enhanced")
+
+# 3. Multi-Source Documentation
+graphql_docs = [
+    "GraphQL Official Documentation",
+    "Apollo Server Best Practices",
+    "REST to GraphQL Migration Guide",
+    "GraphQL Schema Design Patterns",
+    "Performance Optimization for GraphQL"
+]
+
+# 4. Strategic Guidance
+Alfred provides complete migration strategy
+```
+
+---
+
+## Performance Optimization
+
+### 1. Caching Strategy
+```python
+# Multi-level caching
+cache_levels = {
+    "session": {},      # Current session only
+    "project": {},     # Project-specific cache
+    "global": {}       # Cross-project cache
+}
+
+# Cache eviction policies
+def evict_old_cache():
+    """Remove outdated documentation"""
+    # Remove content older than 30 days
+    # Keep high-authority sources longer
+    # Prioritize frequently accessed content
+```
+
+### 2. Lazy Loading
+```python
+def load_documentation_on_demand():
+    """Load documentation only when needed"""
+    # Don't preload everything
+    # Load based on user interaction
+    # Cache for future use
+    pass
+```
+
+### 3. Batch Processing
+```python
+def batch_web_searches(queries):
+    """Combine multiple searches for efficiency"""
+    # Group similar queries
+    # Use WebSearch for multiple terms
+    # Process results in parallel
+    pass
+```
+
+---
+
+## Error Handling
+
+### 1. Network Failures
+```python
+if web_search_fails():
+    # Fall back to cached content
+    # Use local documentation
+    # Provide partial results
+```
+
+### 2. Content Quality Issues
+```python
+if content_quality_low():
+    # Try alternative sources
+    # Indicate uncertainty
+    # Request user clarification
+```
+
+### 3. Relevance Mismatches
+```python
+if relevance_score < threshold:
+    # Refine search query
+    # Ask user for clarification
+    # Broaden search scope
+```
+
+---
+
+## Usage Statistics and Learning
+
+### 1. Track Effectiveness
+```python
+def track_documentation_usage(doc_id, user_feedback):
+    """Learn which documentation is most helpful"""
+    stats[doc_id] = {
+        "usage_count": stats[doc_id]["usage_count"] + 1,
+        "helpful_votes": stats[doc_id]["helpful_votes"] + user_feedback,
+        "contexts": stats[doc_id]["contexts"].append(current_context)
+    }
+```
+
+### 2. Improve Source Selection
+```python
+def improve_source_ranking():
+    """Learn which sources work best for different contexts"""
+    # Analyze usage patterns
+    # Adjust source priorities
+    # Personalize recommendations
+```
+
+---
+
+**End of Skill** | Intelligent documentation loading for enhanced context and accuracy

moai_adk/templates/.claude/skills/moai-lang-c/SKILL.md

@@ -1,100 +1,124 @@
 ---
-
 name: moai-lang-c
-description: C best practices with Unity test framework, cppcheck, and Make build system. Use when writing or reviewing C code in project workflows.
+version: 2.0.0
+created: 2025-10-22
+updated: 2025-10-22
+status: active
+description: C17/C23 best practices with Unity test framework, cppcheck, and Make/CMake build systems.
+keywords: ['c', 'unity', 'cppcheck', 'cmake', 'make']
 allowed-tools:
   - Read
   - Bash
 ---
 
-# C Expert
+# Lang C Skill
 
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Bash (terminal) |
-| Auto-load | On demand when language keywords are detected |
-| Trigger cues | C code discussions, framework guidance, or file extensions such as .c/.h. |
-| Tier | 3 |
-
-## What it does
-
-Provides C-specific expertise for TDD development, including Unity test framework, cppcheck static analysis, and Make build system for system programming.
-
-## When to use
-
-- Engages when the conversation references C work, frameworks, or files like .c/.h.
-- "Writing C tests", "Unity test framework", "Embedded C"
-- Automatically invoked when working with C projects
-- C SPEC implementation (`/alfred:2-run`)
-
-## How it works
-
-**TDD Framework**:
-- **Unity**: Lightweight C test framework
-- **CMock**: Mocking framework for C
-- **Ceedling**: Build automation for C
-- Test coverage with gcov
-
-**Build Tools**:
-- **Make**: Standard build automation
-- **CMake**: Modern build system
-- **GCC/Clang**: C compilers
-
-**Code Quality**:
-- **cppcheck**: Static code analysis
-- **Valgrind**: Memory leak detection
-- **splint**: Secure programming lint
-
-**C Patterns**:
-- **Opaque pointers**: Information hiding
-- **Function pointers**: Callback mechanisms
-- **Error codes**: Integer return values
-- **Manual memory management**: malloc/free discipline
-
-**Best Practices**:
-- File ≤300 LOC, function ≤50 LOC
-- Always check malloc return values
-- Free every malloc
-- Avoid buffer overflows (use strncpy, snprintf)
-- Use const for read-only parameters
-- Initialize all variables
-
-## Examples
-```bash
-make test && cppcheck src
-```
+| **Skill Name** | moai-lang-c |
+| **Version** | 2.0.0 (2025-10-22) |
+| **Allowed tools** | Read (read_file), Bash (terminal) |
+| **Auto-load** | On demand when keywords detected |
+| **Tier** | Language |
+
+---
+
+## What It Does
+
+C17/C23 best practices with Unity test framework, cppcheck, and Make/CMake build systems.
+
+**Key capabilities**:
+- ✅ Best practices enforcement for language domain
+- ✅ TRUST 5 principles integration
+- ✅ Latest tool versions (2025-10-22)
+- ✅ TDD workflow support
+
+---
+
+## When to Use
+
+**Automatic triggers**:
+- Related code discussions and file patterns
+- SPEC implementation (`/alfred:2-run`)
+- Code review requests
+
+**Manual invocation**:
+- Review code for TRUST 5 compliance
+- Design new features
+- Troubleshoot issues
+
+---
+
+## Tool Version Matrix (2025-10-22)
+
+| Tool | Version | Purpose | Status |
+|------|---------|---------|--------|
+| **GCC** | 14.2.0 | Primary | ✅ Current |
+| **Clang** | 19.1.7 | Primary | ✅ Current |
+| **cppcheck** | 2.16.0 | Primary | ✅ Current |
+| **CMake** | 3.31.0 | Primary | ✅ Current |
+
+---
 
 ## Inputs
-- Language-specific source directories (e.g. `src/`, `app/`).
-- Language-specific build/test configuration files (e.g. `package.json`, `pyproject.toml`, `go.mod`).
-- Relevant test suites and sample data.
+
+- Language-specific source directories
+- Configuration files
+- Test suites and sample data
 
 ## Outputs
-- Test/lint execution plan tailored to the selected language.
-- List of key language idioms and review checkpoints.
+
+- Test/lint execution plan
+- TRUST 5 review checkpoints
+- Migration guidance
 
 ## Failure Modes
-- When the language runtime or package manager is not installed.
-- When the main language cannot be determined in a multilingual project.
+
+- When required tools are not installed
+- When dependencies are missing
+- When test coverage falls below 85%
 
 ## Dependencies
-- Access to the project file is required using the Read/Grep tool.
-- When used with `Skill("moai-foundation-langs")`, it is easy to share cross-language conventions.
 
-## References
-- ISO. "ISO/IEC 9899:2018 Programming Languages — C." (accessed 2025-03-29).
-- Cppcheck. "Cppcheck Manual." http://cppcheck.sourceforge.net/manual.pdf (accessed 2025-03-29).
+- Access to project files via Read/Bash tools
+- Integration with `moai-foundation-langs` for language detection
+- Integration with `moai-foundation-trust` for quality gates
+
+---
+
+## References (Latest Documentation)
+
+_Documentation links updated 2025-10-22_
+
+---
 
 ## Changelog
-- 2025-03-29: Input/output/failure response/reference information for each language has been specified.
 
-## Works well with
+- **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
+- **v1.0.0** (2025-03-29): Initial Skill release
+
+---
+
+## Works Well With
+
+- `moai-foundation-trust` (quality gates)
+- `moai-alfred-code-reviewer` (code review)
+- `moai-essentials-debug` (debugging support)
 
-- alfred-trust-validation (coverage verification)
-- alfred-code-reviewer (C-specific review)
-- alfred-debugger-pro (C debugging)
+---
 
 ## Best Practices
-- Enable automatic validation by matching your linter with the language's official style guide.
-- Fix test/build pipelines with reproducible commands in CI.
+
+✅ **DO**:
+- Follow language best practices
+- Use latest stable tool versions
+- Maintain test coverage ≥85%
+- Document all public APIs
+
+❌ **DON'T**:
+- Skip quality gates
+- Use deprecated tools
+- Ignore security warnings
+- Mix testing frameworks

moai_adk/templates/.claude/skills/moai-lang-c/examples.md

@@ -0,0 +1,29 @@
+# moai-lang-c - Working Examples
+
+_Last updated: 2025-10-22_
+
+## Example 1: Basic Setup
+
+```bash
+# Setup commands
+# ...
+```
+
+## Example 2: TDD Workflow
+
+```bash
+# RED: Write failing test
+# GREEN: Implement feature
+# REFACTOR: Improve code
+```
+
+## Example 3: Quality Gate
+
+```bash
+# Run quality checks
+# Verify coverage ≥85%
+```
+
+---
+
+_For more examples, see SKILL.md reference section_