moai-adk 0.3.13__py3-none-any.whl → 0.4.1__py3-none-any.whl

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

@@ -0,0 +1,97 @@
+---
+
+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.
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Web API Expert
+
+## 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
+```
+
+## Inputs
+- Domain-related design documents and user requirements.
+- Project technology stack and operational constraints.
+
+## Outputs
+- Domain-specific architecture or implementation guidelines.
+- Recommended list of associated sub-agents/skills.
+
+## Failure Modes
+- When the domain document does not exist or is ambiguous.
+- When the project strategy is unconfirmed and cannot be specified.
+
+## 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).
+
+## Changelog
+- 2025-03-29: Codified input/output and failure responses for domain skills.
+
+## Works well with
+
+- 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.

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

@@ -0,0 +1,102 @@
+---
+
+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:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# Alfred Debugger Pro
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Auto-load | On demand during Run stage (debug-helper) |
+| 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.
+
+## 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
+```
+
+**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.
+```
+
+## Inputs
+- A snapshot of the code/tests/documentation you are currently working on.
+- Ongoing agent status information.
+
+## Outputs
+- Immediately actionable checklists or improvement suggestions.
+- Recommendations on whether to take next steps or not.
+
+## 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.
+
+## 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).
+
+## Changelog
+- 2025-03-29: Overhauled input/output definitions for Essentials skills.
+
+## Works well with
+
+- 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.

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

@@ -0,0 +1,104 @@
+---
+
+name: moai-essentials-perf
+description: Performance optimization with profiling, bottleneck detection, and tuning strategies. Use when performing baseline performance reviews.
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# Alfred Performance Optimizer
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Auto-load | On demand during Run stage (performance triage) |
+| Trigger cues | Latency complaints, profiling requests, throughput bottleneck analysis. |
+
+## What it does
+
+Performance analysis and optimization with profiling tools, bottleneck detection, and language-specific optimization techniques.
+
+## When to use
+
+- Loads when diagnosing performance regressions or planning optimization work.
+- “Improve performance”, “Find slow parts”, “How to optimize?”
+- “Profiling”, “Bottleneck”, “Memory leak”
+
+## How it works
+
+**Profiling Tools**:
+- **Python**: cProfile, memory_profiler
+- **TypeScript**: Chrome DevTools, clinic.js
+- **Java**: JProfiler, VisualVM
+- **Go**: pprof
+- **Rust**: flamegraph, criterion
+
+**Common Performance Issues**:
+- **N+1 Query Problem**: Use eager loading/joins
+- **Inefficient Loop**: O(n²) → O(n) with Set/Map
+- **Memory Leak**: Remove event listeners, close connections
+
+**Optimization Checklist**:
+- [ ] Current performance benchmark
+- [ ] Bottleneck identification
+- [ ] Profiling data collected
+- [ ] Algorithm complexity improved (O(n²) → O(n))
+- [ ] Unnecessary operations removed
+- [ ] Caching applied
+- [ ] Async processing introduced
+- [ ] Post-optimization benchmark
+- [ ] Side effects checked
+
+**Language-specific Optimizations**:
+- **Python**: List comprehension, generators, @lru_cache
+- **TypeScript**: Memoization, lazy loading, code splitting
+- **Java**: Stream API, parallel processing
+- **Go**: Goroutines, buffered channels
+- **Rust**: Zero-cost abstractions, borrowing
+
+**Performance Targets**:
+- API response time: <200ms (P95)
+- Page load time: <2s
+- Memory usage: <512MB
+- CPU usage: <70%
+
+## Examples
+```markdown
+- Checks the current diff and lists items that can be modified immediately.
+- Schedule follow-up tasks with TodoWrite.
+```
+
+## Inputs
+- A snapshot of the code/tests/documentation you are currently working on.
+- Ongoing agent status information.
+
+## Outputs
+- Immediately actionable checklists or improvement suggestions.
+- Recommendations on whether to take next steps or not.
+
+## 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.
+
+## Dependencies
+- Mainly used in conjunction with `tdd-implementer`, `quality-gate`, etc.
+
+## References
+- Google SRE. "The Four Golden Signals." https://sre.google/sre-book/monitoring-distributed-systems/ (accessed 2025-03-29).
+- Dynatrace. "Application Performance Monitoring Best Practices." https://www.dynatrace.com/resources/ebooks/ (accessed 2025-03-29).
+
+## Changelog
+- 2025-03-29: Overhauled input/output definitions for Essentials skills.
+
+## Works well with
+
+- 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.

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

@@ -0,0 +1,96 @@
+---
+
+name: moai-essentials-refactor
+description: Refactoring guidance with design patterns and code improvement strategies. Use when planning incremental refactors with safety nets.
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# Alfred Refactoring Coach
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Auto-load | On demand during Run stage (refactor planning) |
+| Trigger cues | Refactoring plans, code smell cleanup, design pattern coaching. |
+
+## What it does
+
+Refactoring guidance with design pattern recommendations, code smell detection, and step-by-step improvement plans.
+
+## When to use
+
+- Loads when the user asks how to restructure code or apply design patterns.
+- “Help with refactoring”, “How can I improve this code?”, “Apply design patterns” 
+- “Code organization”, “Remove duplication”, “Separate functions”
+
+## How it works
+
+**Refactoring Techniques**:
+- **Extract Method**: Separate long methods
+- **Replace Conditional with Polymorphism**: Remove conditional statements
+- **Introduce Parameter Object**: Group parameters
+- **Extract Class**: Massive class separation
+
+**Design Pattern Recommendations**:
+- Complex object creation → **Builder Pattern**
+- Type-specific behavior → **Strategy Pattern**
+- Global state → **Singleton Pattern**
+- Incompatible interfaces → **Adapter Pattern**
+- Delayed object creation → **Factory Pattern**
+
+**3-Strike Rule**:
+```
+1st occurrence: Just implement
+2nd occurrence: Notice similarity (leave as-is)
+3rd occurrence: Pattern confirmed → Refactor! 🔧
+```
+
+**Refactoring Checklist**:
+- [ ] All tests passing before refactoring
+- [ ] Code smells identified
+- [ ] Refactoring goal clear
+- [ ] Change one thing at a time
+- [ ] Run tests after each change
+- [ ] Commit frequently
+
+## Examples
+```markdown
+- Checks the current diff and lists items that can be modified immediately.
+- Schedule follow-up tasks with TodoWrite.
+```
+
+## Inputs
+- A snapshot of the code/tests/documentation you are currently working on.
+- Ongoing agent status information.
+
+## Outputs
+- Immediately actionable checklists or improvement suggestions.
+- Recommendations on whether to take next steps or not.
+
+## 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.
+
+## Dependencies
+- Mainly used in conjunction with `tdd-implementer`, `quality-gate`, etc.
+
+## References
+- Fowler, Martin. "Refactoring: Improving the Design of Existing Code." Addison-Wesley, 2018.
+- IEEE Software. "Managing Technical Debt." IEEE Software, 2021.
+
+## Changelog
+- 2025-03-29: Overhauled input/output definitions for Essentials skills.
+
+## Works well with
+
+- moai-essentials-review
+
+## Best Practices
+- Record results, even for simple improvements, to increase traceability.
+- Clearly mark items that require human review to distinguish them from automation.

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

@@ -0,0 +1,112 @@
+---
+
+name: moai-essentials-review
+description: Automated code review with SOLID principles, code smells, and language-specific best practices. Use when preparing concise review checklists for code changes.
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# Alfred Code Reviewer
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Auto-load | On demand during Sync stage (review gate) |
+| Trigger cues | Code review requests, quality checklist preparation, merge readiness checks. |
+
+## What it does
+
+Automated code review with language-specific best practices, SOLID principles verification, and code smell detection.
+
+## When to use
+
+- Loads when someone asks for a code review or a pre-merge quality assessment.
+- “Please review the code”, “How can this code be improved?”, “Check the code quality”
+- Optionally invoked after `/alfred:3-sync`
+- Before merging PR
+
+## How it works
+
+**Code Constraints Check**:
+- File ≤300 LOC
+- Function ≤50 LOC
+- Parameters ≤5
+- Cyclomatic complexity ≤10
+
+**SOLID Principles**:
+- Single Responsibility
+- Open/Closed
+- Liskov Substitution
+- Interface Segregation
+- Dependency Inversion
+
+**Code Smell Detection**:
+- Long Method
+- Large Class
+- Duplicate Code
+- Dead Code
+- Magic Numbers
+
+**Language-specific Best Practices**:
+- Python: List comprehension, type hints, PEP 8
+- TypeScript: Strict typing, async/await, error handling
+- Java: Streams API, Optional, Design patterns
+
+**Review Report**:
+```markdown
+## Code Review Report
+
+### 🔴 Critical Issues (3)
+1. **src/auth/service.py:45** - Function too long (85 > 50 LOC)
+2. **src/api/handler.ts:120** - Missing error handling
+3. **src/db/repository.java:200** - Magic number
+
+### ⚠️ Warnings (5)
+1. **src/utils/helper.py:30** - Unused import
+
+### ✅ Good Practices Found
+- Test coverage: 92%
+- Consistent naming
+```
+
+## Examples
+```markdown
+- Checks the current diff and lists items that can be modified immediately.
+- Schedule follow-up tasks with TodoWrite.
+```
+
+## Inputs
+- A snapshot of the code/tests/documentation you are currently working on.
+- Ongoing agent status information.
+
+## Outputs
+- Immediately actionable checklists or improvement suggestions.
+- Recommendations on whether to take next steps or not.
+
+## 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.
+
+## Dependencies
+- Mainly used in conjunction with `tdd-implementer`, `quality-gate`, etc.
+
+## References
+- IEEE. "Recommended Practice for Software Reviews." IEEE 1028-2008.
+- Cisco. "Peer Review Best Practices." https://www.cisco.com/c/en/us/support/docs/optical/ons-15454-esc/15114-peer-review.html (accessed 2025-03-29).
+
+## Changelog
+- 2025-03-29: Overhauled input/output definitions for Essentials skills.
+
+## Works well with
+
+- moai-foundation-specs
+- 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.

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

@@ -0,0 +1,98 @@
+---
+
+name: moai-foundation-ears
+description: EARS requirement authoring guide (Ubiquitous/Event/State/Optional/Constraints). Use when teams need guidance on EARS requirements structure.
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# Alfred EARS Authoring Guide
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Auto-load | SessionStart (foundation bootstrap) |
+| Trigger cues | Requests to draft or refine EARS-style requirements, “write spec”, or “requirements format” cues. |
+
+## What it does
+
+EARS (Easy Approach to Requirements Syntax) authoring guide for writing clear, testable requirements using 5 statement patterns.
+
+## When to use
+
+- Activates whenever the user asks to draft structured requirements or mentions EARS syntax.
+- “Writing SPEC”, “Requirements summary”, “EARS syntax”
+- Automatically invoked by `/alfred:1-plan`
+- When writing or refining SPEC documents
+
+## How it works
+
+EARS provides 5 statement patterns for structured requirements:
+
+### 1. Ubiquitous (Basic Requirements)
+**Format**: The system must provide [function]
+**Example**: The system must provide user authentication function
+
+### 2. Event-driven (event-based)
+**Format**: WHEN If [condition], the system must [operate]
+**Example**: WHEN When the user logs in, the system must issue a JWT token
+
+### 3. State-driven
+**Format**: WHILE When in [state], the system must [operate]
+**Example**: WHILE When the user is authenticated, the system must allow access to protected resources
+
+### 4. Optional (Optional function)
+**Format**: If WHERE [condition], the system can [operate]
+**Example**: If WHERE refresh token is provided, the system can issue a new access token
+
+### 5. Constraints
+**Format**: IF [condition], the system SHOULD [constrain]
+**Example**: IF an invalid token is provided, the system SHOULD deny access
+
+## Writing Tips
+
+✅ Be specific and measurable
+✅ Avoid vague terms (“adequate”, “sufficient”, “fast”)
+✅ One requirement per statement
+✅ Make it testable
+
+## Examples
+```markdown
+- Scan standard documents and report missing sections.
+- Changed regulations are reflected in CLAUDE.md.
+```
+
+## Inputs
+- Project standard documents (e.g. `CLAUDE.md`, `.moai/config.json`).
+- Latest printouts from relevant sub-agents.
+
+## Outputs
+- Templates or policy summaries conforming to the MoAI-ADK standard.
+- Reusable rules/checklists.
+
+## Failure Modes
+- When required standard files are missing or have limited access rights.
+- When conflicting policies are detected and coordination is required.
+
+## Dependencies
+- There is great synergy when called together with cc-manager.
+
+## References
+- Mavin, A., et al. "Easy Approach to Requirements Syntax (EARS)." IEEE RE, 2009.
+- INCOSE. "Guide for Writing Requirements." INCOSE-TP-2010-006-02 (accessed 2025-03-29).
+
+## Changelog
+- 2025-03-29: Foundation skill templates have been enhanced to align with best practice structures.
+
+## Works well with
+
+- moai-foundation-specs
+
+## Best Practices
+- When changing standards, the reason for change and supporting documents are recorded.
+- Follow the single source principle and avoid modifying the same item in multiple places.

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

@@ -0,0 +1,90 @@
+---
+
+name: moai-foundation-git
+description: Git workflow automation (branching, TDD commits, PR management). Use when standardizing Git practices across the project.
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# Alfred Git Workflow
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
+| Auto-load | SessionStart (foundation bootstrap) |
+| Trigger cues | Branch creation, commit convention, PR readiness, and release gating requests. |
+
+## What it does
+
+Automates Git operations following MoAI-ADK conventions: branch creation, locale-based TDD commits, Draft PR creation, and PR Ready transition.
+
+## When to use
+
+- Activates when Git workflow automation is needed for branching, commits, or PR promotion.
+- “Create branch”, “Create PR”, “Create commit”
+- Automatically invoked by `/alfred:1-plan`, `/alfred:2-run`, `/alfred:3-sync`
+- Git workflow automation needed
+
+## How it works
+
+**1. Branch Creation**:
+```bash
+git checkout develop
+git checkout -b feature/SPEC-AUTH-001
+```
+
+**2. Locale-based TDD Commits**:
+- **Korean (ko)**: 🔴 RED: [Test Description]
+- **English (en)**: 🔴 RED: [Test description]
+- **Japanese (ja)**: 🔴 RED: [テスト説明]
+- **Chinese (zh)**: 🔴 RED: [测试说明]
+
+Configured via `.moai/config.json`:
+```json
+{"project": {"locale": "ko"}}
+```
+
+**3. Draft PR Creation**:
+Creates Draft PR with SPEC reference and test checklist.
+
+**4. PR Ready Transition** (via `/alfred:3-sync`):
+- Updates PR from Draft → Ready
+- Adds quality gate checklist
+- Verifies TRUST 5-principles
+
+## Examples
+```markdown
+- Scan standard documents and report missing sections.
+- Changed regulations are reflected in CLAUDE.md.
+```
+
+## Best Practices
+- When changing standards, the reason for change and supporting documents are recorded.
+- Follow the single source principle and avoid modifying the same item in multiple places.
+
+## Inputs
+- Project standard documents (e.g. `CLAUDE.md`, `.moai/config.json`).
+- Latest printouts from relevant sub-agents.
+
+## Outputs
+- Templates or policy summaries conforming to the MoAI-ADK standard.
+- Reusable rules/checklists.
+
+## Failure Modes
+- When required standard files are missing or have limited access rights.
+- When conflicting policies are detected and coordination is required.
+
+## Dependencies
+- There is great synergy when called together with cc-manager.
+
+## References
+- Vincent Driessen. "A successful Git branching model." https://nvie.com/posts/a-successful-git-branching-model/ (accessed 2025-03-29).
+- GitHub Docs. "GitHub Flow." https://docs.github.com/en/get-started/using-github/github-flow (accessed 2025-03-29).
+
+## Changelog
+- 2025-03-29: Foundation skill templates have been enhanced to align with best practice structures.