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

moai_adk/templates/.claude/skills/moai-domain-web-api/SKILL.md

@@ -1,97 +1,123 @@
 ---
-
 name: moai-domain-web-api
-description: REST API and GraphQL design patterns with authentication, versioning, and OpenAPI documentation. Use when working on web API contracts scenarios.
+version: 2.0.0
+created: 2025-10-22
+updated: 2025-10-22
+status: active
+description: REST API and GraphQL design with OpenAPI 3.1, authentication, versioning, and rate limiting.
+keywords: ['rest', 'graphql', 'openapi', 'api-design', 'authentication']
 allowed-tools:
   - Read
   - Bash
 ---
 
-# Web API Expert
+# Domain Web Api Skill
 
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Bash (terminal) |
-| Auto-load | On demand for API delivery |
-| Trigger cues | REST/GraphQL design, contract testing, versioning, integration hardening. |
-| Tier | 4 |
-
-## What it does
-
-Provides expertise in designing and implementing RESTful APIs and GraphQL services, including authentication mechanisms (JWT, OAuth2), API versioning strategies, and OpenAPI documentation.
-
-## When to use
-
-- Engages when designing or validating web APIs and their lifecycle controls.
-- “API design”, “REST API pattern”, “GraphQL schema”, “JWT authentication”
-- Automatically invoked when working with API projects
-- Web API SPEC implementation (`/alfred:2-run`)
-
-## How it works
-
-**REST API Design**:
-- **RESTful principles**: Resource-based URLs, HTTP verbs (GET, POST, PUT, DELETE)
-- **Status codes**: Proper use of 2xx, 4xx, 5xx codes
-- **HATEOAS**: Hypermedia links in responses
-- **Pagination**: Cursor-based or offset-based
-
-**GraphQL Design**:
-- **Schema definition**: Types, queries, mutations, subscriptions
-- **Resolver implementation**: Data fetching logic
-- **N+1 problem**: DataLoader for batching
-- **Schema stitching**: Federated GraphQL
-
-**Authentication & Authorization**:
-- **JWT (JSON Web Token)**: Stateless authentication
-- **OAuth2**: Authorization framework (flows: authorization code, client credentials)
-- **API keys**: Simple authentication
-- **RBAC/ABAC**: Role/Attribute-based access control
-
-**API Versioning**:
-- **URL versioning**: /v1/users, /v2/users
-- **Header versioning**: Accept: application/vnd.api.v2+json
-- **Deprecation strategy**: Sunset header
-
-**Documentation**:
-- **OpenAPI (Swagger)**: API specification
-- **API documentation**: Auto-generated docs
-- **Postman collections**: Request examples
-
-## Examples
-```bash
-$ uvicorn app.main:app --reload
-$ newman run postman_collection.json
-```
+| **Skill Name** | moai-domain-web-api |
+| **Version** | 2.0.0 (2025-10-22) |
+| **Allowed tools** | Read (read_file), Bash (terminal) |
+| **Auto-load** | On demand when keywords detected |
+| **Tier** | Domain |
+
+---
+
+## What It Does
+
+REST API and GraphQL design with OpenAPI 3.1, authentication, versioning, and rate limiting.
+
+**Key capabilities**:
+- ✅ Best practices enforcement for domain 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 |
+|------|---------|---------|--------|
+| **OpenAPI** | 3.1.0 | Primary | ✅ Current |
+| **Postman** | 11.21.0 | Primary | ✅ Current |
+| **Swagger UI** | 5.18.2 | Primary | ✅ Current |
+
+---
 
 ## Inputs
-- Domain-related design documents and user requirements.
-- Project technology stack and operational constraints.
+
+- Language-specific source directories
+- Configuration files
+- Test suites and sample data
 
 ## Outputs
-- Domain-specific architecture or implementation guidelines.
-- Recommended list of associated sub-agents/skills.
+
+- Test/lint execution plan
+- TRUST 5 review checkpoints
+- Migration guidance
 
 ## Failure Modes
-- When the domain document does not exist or is ambiguous.
-- When the project strategy is unconfirmed and cannot be specified.
+
+- When required tools are not installed
+- When dependencies are missing
+- When test coverage falls below 85%
 
 ## Dependencies
-- `.moai/project/` document and latest technical briefing are required.
 
-## References
-- Microsoft. "REST API Design Guidelines." https://learn.microsoft.com/azure/architecture/best-practices/api-design (accessed 2025-03-29).
-- OpenAPI Initiative. "OpenAPI Specification." https://spec.openapis.org/oas/latest.html (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: Codified input/output and failure responses for domain skills.
 
-## 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 (API security validation)
-- backend-expert (server implementation)
-- security-expert (authentication patterns)
+---
 
 ## Best Practices
-- Record supporting documentation (version/link) for each domain decision.
-- Review performance, security, and operational requirements simultaneously at an early stage.
+
+✅ **DO**:
+- Follow domain 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-domain-web-api/examples.md

@@ -0,0 +1,29 @@
+# moai-domain-web-api - 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_

moai_adk/templates/.claude/skills/moai-domain-web-api/reference.md

@@ -0,0 +1,30 @@
+# moai-domain-web-api - CLI Reference
+
+_Last updated: 2025-10-22_
+
+## Quick Reference
+
+### Installation
+
+```bash
+# Installation commands
+```
+
+### Common Commands
+
+```bash
+# Test
+# Lint
+# Format
+# Build
+```
+
+## Tool Versions (2025-10-22)
+
+- **OpenAPI**: 3.1.0
+- **Postman**: 11.21.0
+- **Swagger UI**: 5.18.2
+
+---
+
+_For detailed usage, see SKILL.md_

moai_adk/templates/.claude/skills/moai-essentials-debug/SKILL.md

@@ -1,5 +1,4 @@
 ---
-
 name: moai-essentials-debug
 description: Advanced debugging with stack trace analysis, error pattern detection, and fix suggestions. Use when delivering quick diagnostic support for everyday issues.
 allowed-tools:
@@ -10,93 +9,295 @@ allowed-tools:
   - TodoWrite
 ---
 
-# Alfred Debugger Pro
+# MoAI Essentials Debug v2.1
 
 ## Skill Metadata
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Version | 2.1.0 |
+| Created | 2025-10-22 |
+| Last Updated | 2025-10-27 |
+| Language Coverage | 23 languages + containers + distributed systems |
+| Allowed tools | Read, Write, Edit, Bash, TodoWrite |
 | Auto-load | On demand during Run stage (debug-helper) |
-| Trigger cues | Runtime error triage, stack trace analysis, root cause investigation requests. |
+| Trigger cues | Runtime error triage, stack trace analysis, root cause investigation requests |
 
 ## What it does
 
-Advanced debugging support with stack trace analysis, common error pattern detection, and actionable fix suggestions.
+Comprehensive debugging support across all 23 MoAI-ADK languages with:
+- Language-specific debugger integration
+- Stack trace analysis and error pattern detection
+- Container and Kubernetes debugging
+- Distributed tracing with OpenTelemetry
+- Cloud debugger integration (AWS X-Ray, GCP Cloud Debugger)
+- Performance profiling with Prometheus
 
 ## When to use
 
-- Loads when users share stack traces or ask why a failure occurred.
-- “Resolve the error”, “What is the cause of this error?”, “Stack trace analysis”
-- Automatically invoked on runtime errors (via debug-helper sub-agent)
-- "Why not?", "Solving NullPointerException"
-
-## How it works
-
-**Stack Trace Analysis**:
-```python
-# Error example
-jwt.exceptions.ExpiredSignatureError: Signature has expired
-
-# Alfred Analysis
-📍 Error Location: src/auth/service.py:142
-🔍 Root Cause: JWT token has expired
-💡 Fix Suggestion:
-   1. Implement token refresh logic
-   2. Check expiration before validation
-   3. Handle ExpiredSignatureError gracefully
+- Runtime errors, exceptions, crashes
+- Stack trace analysis requests
+- "Why is this failing?", "Debug this error"
+- Container/K8s debugging scenarios
+- Distributed system tracing
+- Performance bottleneck investigation
+- Automatically invoked via debug-helper sub-agent
+
+---
+
+## Quick Reference: Debugger by Language
+
+### Systems Programming
+- **C/C++**: gdb 14.x, lldb 17.x, AddressSanitizer
+- **Rust**: rust-lldb, rust-gdb, RUST_BACKTRACE=1
+- **Go**: Delve 1.22.x, goroutine debugging
+
+### JVM Ecosystem
+- **Java**: jdb, IntelliJ IDEA, Remote JDWP
+- **Kotlin**: IntelliJ Kotlin Debugger, Coroutines debugger
+- **Scala**: IntelliJ Scala Plugin, sbt debug mode
+- **Clojure**: CIDER, Cursive, REPL-based debugging
+
+### Scripting Languages
+- **Python**: pdb, debugpy 1.8.0, pudb (TUI)
+- **Ruby**: debug gem (built-in), byebug, pry-byebug
+- **PHP**: Xdebug 3.3.x, phpdbg
+- **Lua**: ZeroBrane Studio, MobDebug
+- **Shell**: bash -x, set -x toggle
+
+### Web & Mobile
+- **JavaScript**: Chrome DevTools, node --inspect
+- **TypeScript**: Chrome DevTools with source maps, VS Code debugger
+- **Dart/Flutter**: Flutter DevTools, hot reload
+- **Swift**: LLDB (Xcode), Instruments profiling
+
+### Functional & Concurrency
+- **Haskell**: GHCi debugger, Debug.Trace
+- **Elixir**: IEx debugger, :observer.start()
+- **Julia**: Debugger.jl, Infiltrator.jl
+- **R**: browser(), debug(), RStudio debugger
+
+### Enterprise & Data
+- **C#**: Visual Studio Debugger, Rider, vsdbg
+- **SQL**: EXPLAIN ANALYZE, pg_stat_statements
+
+> **Complete debugger matrix with CLI commands**: See [reference.md](reference.md)
+
+---
+
+## Debugging Workflow (6-Step Process)
+
+### 1. Reproduce
+- [ ] Minimal reproducible example (MRE)
+- [ ] Consistent reproduction steps
+- [ ] Document environment (OS, language version, dependencies)
+
+### 2. Isolate
+- [ ] Binary search the code (comment out sections)
+- [ ] Check recent changes (git diff, git log)
+- [ ] Verify input data and edge cases
+
+### 3. Investigate
+- [ ] Read stack trace from bottom (entry point) to top (error site)
+- [ ] Add logging at key decision points
+- [ ] Use debugger breakpoints before error location
+- [ ] Check variable state in debugger
+
+### 4. Hypothesize
+- [ ] Form theory about root cause
+- [ ] Identify 2-3 most likely culprits
+- [ ] Design experiment to test hypothesis
+
+### 5. Fix
+- [ ] Implement minimal fix first
+- [ ] Add regression test (RED → GREEN)
+- [ ] Refactor if needed (REFACTOR stage)
+- [ ] Update documentation
+
+### 6. Verify
+- [ ] Run full test suite
+- [ ] Test edge cases explicitly
+- [ ] Verify fix in production-like environment
+- [ ] Monitor for recurrence
+
+---
+
+## Common Error Patterns by Language Category
+
+### Memory Safety
+- **C/C++**: Buffer overflow, use-after-free, memory leaks
+  - Tools: Valgrind, AddressSanitizer (`-fsanitize=address`)
+- **Rust**: Ownership violations (prevented at compile time)
+- **Go**: Goroutine leaks, improper channel usage
+
+### Null/Nil Handling
+- **Java**: NullPointerException → Use Optional<T>
+- **Kotlin**: NullPointerException → Leverage null safety (?.)
+- **TypeScript**: undefined access → Optional chaining (?.)
+- **Go**: Nil pointer → Early nil checks
+- **Rust**: Option<T> unwrap → Pattern matching
+
+### Type Errors
+- **Python**: TypeError, AttributeError → Type hints + mypy
+- **JavaScript**: Type coercion bugs → Use TypeScript
+- **Ruby**: NoMethodError → Duck typing checks
+
+### Concurrency Issues
+- **Go**: Data races → `go build -race`, proper channel usage
+- **Java**: ConcurrentModificationException → Use concurrent collections
+- **Rust**: Data races (prevented by borrow checker)
+- **Python**: GIL limitations → Use multiprocessing for CPU-bound tasks
+
+### Async/Await Pitfalls
+- **Python**: `RuntimeError: Event loop is closed` → Proper asyncio usage
+- **JavaScript**: Unhandled promise rejections → Always catch async errors
+- **Rust**: Send/Sync trait violations → Understand thread safety
+
+> **Detailed error pattern analysis**: See [examples.md](examples.md)
+
+---
+
+## Container & Kubernetes Debugging
+
+### Docker Debugging
+```bash
+# Attach to running container
+docker exec -it <container> /bin/sh
+
+# Debug with debugger ports exposed
+docker run -p 5005:5005 -e JAVA_TOOL_OPTIONS='-agentlib:jdwp=...' myapp
+
+# Python remote debugging
+docker run -p 5678:5678 -e DEBUGPY_ENABLE=true myapp
 ```
 
-**Common Error Patterns**:
-- `NullPointerException` → Optional usage, guard clauses
-- `IndexError` → Boundary checks
-- `KeyError` → `.get()` with defaults
-- `TypeError` → Type hints, input validation
-- `ConnectionError` → Retry logic, timeouts
-
-**Debugging Checklist**:
-- [ ] Reproducible?
-- [ ] Log messages?
-- [ ] Input data?
-- [ ] Recent changes?
-- [ ] Dependency versions?
-
-**Language-specific Tips**:
-- **Python**: Logging, type guards
-- **TypeScript**: Type guards, null checks
-- **Java**: Optional, try-with-resources
-
-## Examples
-```markdown
-- Checks the current diff and lists items that can be modified immediately.
-- Schedule follow-up tasks with TodoWrite.
+### Kubernetes Debugging
+```bash
+# Port-forward debugger port
+kubectl port-forward pod/myapp-pod 5005:5005
+
+# Exec into pod
+kubectl exec -it myapp-pod -- /bin/bash
+
+# Debug with ephemeral container (K8s 1.23+)
+kubectl debug -it myapp-pod --image=busybox --target=myapp
 ```
 
+> **Complete container debugging guide**: See [reference.md](reference.md)
+
+---
+
+## Distributed Tracing
+
+### OpenTelemetry 1.24.0+
+- Python: opentelemetry-api, opentelemetry-sdk
+- TypeScript: @opentelemetry/sdk-trace-node
+- Exporters: Jaeger, Zipkin, OTLP
+
+### Prometheus 2.48.x Integration
+- Metrics: Counter, Gauge, Histogram, Summary
+- Python: prometheus-client 0.19.0
+- Go: prometheus/client_golang
+
+### Cloud Debuggers
+- **AWS X-Ray**: aws-xray-sdk, auto-instrumentation
+- **GCP Cloud Debugger**: googleclouddebugger Python package
+
+> **Complete distributed tracing setup**: See [reference.md](reference.md)
+
+---
+
+## Stack Trace Analysis Quick Guide
+
+### Reading Stack Traces
+
+**Direction**: Bottom (entry point) → Top (error site)
+
+**Key information**:
+- 📍 **Location**: File and line number
+- 🔍 **Context**: Function name and arguments
+- 💡 **Error type**: Exception class or error message
+
+### Analysis Pattern
+
+1. **Identify error type**: What exception/error?
+2. **Locate error site**: Top of stack trace
+3. **Trace execution path**: Follow stack from bottom
+4. **Identify root cause**: Where did bad data/state originate?
+5. **Suggest fix**: 1-3 actionable options
+
+> **Language-specific stack trace examples**: See [examples.md](examples.md)
+
+---
+
+## Performance Profiling Integration
+
+### CPU Profiling
+- **Python**: cProfile, py-spy (production-safe)
+- **Go**: pprof, go test -cpuprofile
+- **Rust**: flamegraph crate
+- **Java**: Java Flight Recorder (JFR)
+
+### Memory Profiling
+- **Python**: memory_profiler, tracemalloc
+- **Go**: pprof memory profiling
+- **C/C++**: Valgrind massif
+- **Rust**: heaptrack
+
+> **Complete profiling guide**: See [reference.md](reference.md)
+
+---
+
 ## Inputs
-- A snapshot of the code/tests/documentation you are currently working on.
-- Ongoing agent status information.
+- Stack traces, error messages, logs
+- Code context (relevant files)
+- Environment information (versions, config)
+- Reproduction steps
 
 ## Outputs
-- Immediately actionable checklists or improvement suggestions.
-- Recommendations on whether to take next steps or not.
+- Root cause analysis with evidence
+- Actionable fix suggestions (1-3 options)
+- Debugging checklist tailored to error type
+- Code snippets demonstrating fix
+
+---
 
 ## Failure Modes
-- If you cannot find the required files or test results.
-- When the scope of work is excessively large and cannot be resolved with simple support.
+- Insufficient stack trace or log information
+- Unable to reproduce error locally
+- Complex distributed system failures requiring multi-service tracing
+- Race conditions or timing-dependent bugs
 
-## Dependencies
-- Mainly used in conjunction with `tdd-implementer`, `quality-gate`, etc.
+---
 
-## References
-- Microsoft. "Debugging Techniques." https://learn.microsoft.com/visualstudio/debugger/ (accessed 2025-03-29).
-- JetBrains. "Debugging Code." https://www.jetbrains.com/help/idea/debugging-code.html (accessed 2025-03-29).
+## Dependencies
+- Works with: tdd-implementer, debug-helper, quality-gate
+- Requires: Language-specific debugger tools installed
+- Optional: OpenTelemetry, Prometheus, cloud debugger SDKs
 
-## Changelog
-- 2025-03-29: Overhauled input/output definitions for Essentials skills.
+---
 
-## Works well with
+## Related Skills
+- moai-essentials-refactor (clean up code after debugging)
+- moai-essentials-perf (performance bottleneck investigation)
+- moai-alfred-debugger-pro (advanced debugging strategies)
+- moai-foundation-trust (ensure debugging doesn't skip tests)
 
-- moai-essentials-refactor
+---
 
 ## Best Practices
-- Record results, even for simple improvements, to increase traceability.
-- Clearly mark items that require human review to distinguish them from automation.
+- Always create regression test after fixing bug (TDD cycle)
+- Log debugging insights in code comments with @TAG references
+- Use language-appropriate debugger (don't force Python workflow on Go)
+- Enable source maps for compiled/transpiled languages
+- Set up distributed tracing early in microservices projects
+- Use production-safe profilers (py-spy, async-profiler) in live systems
+- Document reproduction steps in issue tracker or SPEC HISTORY
+
+---
+
+**For complete 23-language debugger matrix**: [reference.md](reference.md)  
+**For language-specific debugging examples**: [examples.md](examples.md)
+
+---
+
+**End of Skill** | Refactored 2025-10-27