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

moai_adk/templates/.claude/skills/moai-claude-code/templates/skill-full.md

@@ -0,0 +1,496 @@
+---
+name: {skill-name}
+description: {Capability + trigger phrases (<=1024 chars, aim for <=200)}
+allowed-tools:                     # optional; remove if full tool access is acceptable
+  - Read
+  - Bash
+  - Write
+---
+
+# {Skill Title}
+
+> {One-sentence compelling summary of value proposition}
+
+---
+
+## 🎯 Purpose of this skill
+
+{Comprehensive explanation covering:
+- Problem statement and context
+- How this skill addresses the problem
+- Unique value proposition
+- Integration with broader workflows}
+
+**Problem**: {Detailed problem description with examples}
+**Solution**: {Comprehensive solution approach}
+**Impact**: {Measurable benefits and improvements}
+
+---
+
+## 🏗️ MoAI-ADK integration
+
+### Alfred auto-selection conditions
+
+Alfred automatically activates this skill under the following conditions:
+
+- {Specific automatic trigger condition 1 with context}
+- {Specific automatic trigger condition 2 with keywords}
+- {Specific automatic trigger condition 3 with workflow state}
+
+### Workflow location
+
+```
+/alfred:1-plan → /alfred:2-run → /alfred:3-sync
+                                        ↑
+Automatically activate this skill
+                                  ({when activated})
+```
+
+**Integration Point**:
+- **Phase**: {Which phase of MoAI-ADK workflow}
+- **Trigger**: {What triggers automatic invocation}
+- **Role**: {What this skill contributes to the workflow}
+
+---
+
+## 📋 Core features
+
+### 1. {Major Feature 1 Name}
+
+{Detailed multi-paragraph description of this feature}
+
+**How ​​to implement**:
+```{language}
+# {Implementation detail 1}
+{code-example-1}
+
+# {Implementation detail 2}
+{code-example-2}
+```
+
+**Output**:
+- **{Output 1}**: {Detailed description with format}
+- **{Output 2}**: {Description with validation criteria}
+- **{Output 3}**: {Description with usage notes}
+
+**verification**:
+```bash
+# {Verification method}
+{verification-command}
+```
+
+---
+
+### 2. {Major Feature 2 Name}
+
+{Comprehensive feature description}
+
+**Algorithm**:
+1. {Step 1 of algorithm}
+2. {Step 2 with details}
+3. {Step 3 and expected outcome}
+
+**Implementation example**:
+```{language}
+{detailed-code-example}
+```
+
+---
+
+### 3. {Major Feature 3 Name}
+
+{Feature description with use cases}
+
+**Use Scenario**:
+- **{Scenario A}**: {When and why to use}
+- **{Scenario B}**: {Alternative use case}
+
+---
+
+## 💡 Usage Pattern
+
+### Pattern 1: Manual call
+
+**Example User Request**:
+```
+"Please execute {skill-name}"
+"{natural-language-trigger-phrase}"
+```
+
+**Alfred Action**:
+1. {What Alfred does in step 1}
+2. {What Alfred does in step 2}
+3. {Final action and result}
+
+---
+
+### Pattern 2: Automatic activation
+
+**Trigger condition**: {When automatic activation occurs}
+
+**Alfred detection scenario**:
+```
+User: "{example-user-request}"
+→ Alfred Analysis: {how Alfred recognizes this needs the skill}
+→ Autoplay: {what happens automatically}
+→ Result: {what user receives}
+```
+
+---
+
+### Pattern 3: Command integration
+
+**Related command**: `/{command-name}`
+
+**Integrated Flow**:
+```
+Run /{command-name}
+  ↓
+{When skill is invoked during command}
+  ↓
+Automatically call this skill
+  ↓
+{What skill contributes}
+  ↓
+Continue command
+```
+
+---
+
+## ⚙️ Settings and configuration
+
+### Configuration file location
+
+Configure in `.moai/config.json`:
+
+```json
+{
+  "{skill-config-section}": {
+    "{option1}": {default-value},
+    "{option2}": {default-value},
+    "{option3}": {
+      "{sub-option1}": {value},
+      "{sub-option2}": {value}
+    }
+  }
+}
+```
+
+### Setting option details
+
+| Options     | Type   | default     | Required | Description                 |
+| ----------- | ------ | ----------- | -------- | --------------------------- |
+| `{option1}` | {type} | `{default}` | ✅/⚠️      | {Comprehensive description} |
+| `{option2}` | {type} | `{default}` | ⚠️        | {What this controls}        |
+| `{option3}` | {type} | `{default}` | ⚠️        | {Usage notes}               |
+
+### Environment variables (optional)
+
+```bash
+# {Environment variable 1}
+export {VAR_NAME_1}="{value}"
+
+# {Environment variable 2}
+export {VAR_NAME_2}="{value}"
+```
+
+---
+
+## 📁 Directory Structure
+
+```
+.claude/skills/{skill-name}/
+├── SKILL.md # Main skill definition (this file)
+├── reference.md # Detailed reference document
+├── examples.md # Collection of practical examples
+├── scripts/ # Utility script
+│   ├── {helper-1}.py
+│   └── {helper-2}.py
+└── templates/ # template file
+    ├── {template-1}.txt
+    └── {template-2}.json
+```
+
+### Additional file descriptions
+
+- **reference.md**: {What additional documentation it contains}
+- **examples.md**: {What examples are provided}
+- **scripts/**: {What utility scripts do}
+- **templates/**: {What templates are included}
+
+---
+
+## ✅ Verification Checklist
+
+### Validation before execution
+
+- [ ] {Pre-execution check 1}
+- [ ] {Pre-execution check 2}
+- [ ] {Pre-execution check 3}
+
+### Verify after execution
+
+- [ ] {Post-execution validation 1 with criteria}
+- [ ] {Post-execution validation 2 with expected state}
+- [ ] {Post-execution validation 3 with deliverable}
+- [ ] {Check MoAI-ADK workflow integration}
+
+### Verification command
+
+```bash
+# {Validation script 1}
+uv run .claude/skills/{skill-name}/scripts/validate.py
+
+# {Validation check 2}
+{verification-command}
+
+# {Integration test}
+{integration-test-command}
+```
+
+---
+
+## 🚨 Error handling
+
+### Error classification
+
+#### 1. {Error Category 1}
+
+**Symptom**: {How this error manifests}
+
+**cause**:
+- {Possible cause 1}
+- {Possible cause 2}
+
+**Solution**:
+```bash
+# {Solution step 1}
+{command-1}
+
+# {Solution step 2}
+{command-2}
+```
+
+---
+
+#### 2. {Error Category 2}
+
+**Symptom**: {Error description}
+
+**Debugging**:
+```bash
+# {How to debug}
+{debug-command}
+```
+
+**correction**:
+1. {Fix step 1}
+2. {Fix step 2}
+
+---
+
+### Logging and Debugging
+
+**Log Location**: `{log-file-path}`
+
+**Log level settings**:
+```bash
+# {How to enable debug logging}
+{logging-config-command}
+```
+
+**Check log**:
+```bash
+# {How to view logs}
+tail -f {log-file-path}
+```
+
+---
+
+## 🔗 Related agents/commands
+
+### Related commands
+
+- **/{command-1}** - {How this skill supports the command}
+- **/{command-2}** - {Integration point}
+
+### Associated Agent
+
+- **@agent-{agent-1}** - {How they work together}
+- **@agent-{agent-2}** - {Collaboration scenario}
+
+### Related skills
+
+- **{skill-1}** - {Complementary functionality}
+- **{skill-2}** - {When to use together}
+
+---
+
+## 📊 Performance and Metrics
+
+### Performance characteristics
+
+- **Execution time**: {Typical execution time}
+- **Memory usage**: {Expected memory usage}
+- **Disk I/O**: {File operations count}
+- **Network**: {External API calls if any}
+
+### Optimization tips
+
+1. **{Optimization 1}**: {How to improve performance}
+2. **{Optimization 2}**: {Configuration tweak}
+3. **{Optimization 3}**: {Best practice}
+
+---
+
+## 🎓 Best Practices
+
+### 1. {Practice Category 1}
+
+**Recommendation**:
+```{language}
+# {Good practice example}
+{recommended-code}
+```
+
+**What to avoid**:
+```{language}
+# {Anti-pattern example}
+{avoid-this-code}
+```
+
+**Reason**: {Why this is best practice}
+
+---
+
+### 2. {Practice Category 2}
+
+**Tip**: {Helpful tip}
+
+**example**:
+```bash
+{example-of-best-practice}
+```
+
+---
+
+### 3. {Practice Category 3}
+
+**Caution**: {Important consideration}
+
+---
+
+## 📖 Practical examples
+
+### Example 1: {Common Use Case}
+
+**Purpose**: {What this example demonstrates}
+
+**input**:
+```{format}
+{example-input}
+```
+
+**execution**:
+```bash
+{commands-to-run}
+```
+
+**output of power**:
+```{format}
+{example-output}
+```
+
+**Explanation**: {What happened and why}
+
+---
+
+### Example 2: {Advanced Use Case}
+
+**Purpose**: {Advanced scenario}
+
+**Scenario**: {Detailed scenario description}
+
+**avatar**:
+```{language}
+{implementation-code}
+```
+
+**Result**: {What you achieve}
+
+---
+
+### Example 3: {Edge Case}
+
+**Scenario**: {Unusual but important scenario}
+
+**How ​​to handle**: {How skill handles this}
+
+---
+
+## 🔧 Customization
+
+### Extension points
+
+Areas where you can customize this skill to fit your project:
+
+1. **{Extension Point 1}**
+- File: `{file-to-modify}`
+ - How to modify: {How to customize}
+
+2. **{Extension Point 2}**
+- Settings: `{config-key}`
+ - Options: {Available options}
+
+### Plugin system (advanced)
+
+```python
+# {How to create plugins for this skill}
+{plugin-example-code}
+```
+
+---
+
+## 📚 References
+
+### Official Documentation
+- **Claude Code Skills**: https://docs.claude.com/en/docs/claude-code/skills
+- **{Related Doc}**: {URL}
+
+### MoAI-ADK Resources
+- **Development Guide**: `.moai/memory/development-guide.md`
+- **SPEC Metadata**: `.moai/memory/spec-metadata.md`
+
+### Community
+- **GitHub Issues**: {Link}
+- **Discussion**: {Link}
+
+---
+
+## 🔄 Update log
+
+### v1.0.0 (Initial)
+- {Feature 1 introduced}
+- {Feature 2 implemented}
+- {Initial release notes}
+
+---
+
+**Template Level**: Full
+**Best For**: Production MoAI-ADK integration, enterprise workflows
+**Features**:
+- Alfred auto-selection
+- Workflow integration
+- Detailed settings
+- Verification automation
+- Error handling
+- Performance optimization
+
+**Directory Structure**: Full (SKILL.md + reference.md + examples.md + scripts/ + templates/)
+**Estimated Setup Time**: 45-60 minutes
+**Maintenance**: Regular updates as workflow evolves
+**Support**: Full MoAI-ADK integration support
+
+---
+
+This skill provides the highest level of automation in {domain}.

moai_adk/templates/.claude/skills/moai-domain-backend/SKILL.md

@@ -0,0 +1,99 @@
+---
+
+name: moai-domain-backend
+description: Provides backend architecture and scaling guidance; use when the project targets server-side APIs or infrastructure design decisions.
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Backend Expert
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Bash (terminal) |
+| Auto-load | On demand for backend architecture requests |
+| Trigger cues | Service layering, API orchestration, caching, background job design discussions. |
+| Tier | 4 |
+
+## What it does
+
+Provides expertise in backend server architecture, RESTful API design, caching strategies, database optimization, and horizontal/vertical scalability patterns.
+
+## When to use
+
+- Engages when backend or service-architecture questions come up.
+- “Backend architecture”, “API design”, “Caching strategy”, “Scalability”
+- Automatically invoked when working with backend projects
+- Backend SPEC implementation (`/alfred:2-run`)
+
+## How it works
+
+**Server Architecture**:
+- **Layered architecture**: Controller → Service → Repository
+- **Microservices**: Service decomposition, inter-service communication
+- **Monoliths**: When appropriate (team size, complexity)
+- **Serverless**: Functions as a Service (AWS Lambda, Cloud Functions)
+
+**API Design**:
+- **RESTful principles**: Resource-based, stateless
+- **GraphQL**: Schema-first design
+- **gRPC**: Protocol buffers for high performance
+- **WebSockets**: Real-time bidirectional communication
+
+**Caching Strategies**:
+- **Redis**: In-memory data store
+- **Memcached**: Distributed caching
+- **Cache invalidation**: TTL, cache-aside pattern
+- **CDN caching**: Static asset delivery
+
+**Database Optimization**:
+- **Connection pooling**: Reuse connections
+- **Query optimization**: EXPLAIN analysis
+- **Read replicas**: Horizontal scaling
+- **Sharding**: Data partitioning
+
+**Scalability Patterns**:
+- **Horizontal scaling**: Load balancing across instances
+- **Vertical scaling**: Increasing instance resources
+- **Async processing**: Message queues (RabbitMQ, Kafka)
+- **Rate limiting**: API throttling
+
+## Examples
+```bash
+$ make test-backend
+$ k6 run perf/api-smoke.js
+```
+
+## Inputs
+- Domain-specific 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
+- AWS. "AWS Well-Architected Framework." https://docs.aws.amazon.com/wellarchitected/latest/framework/ (accessed 2025-03-29).
+- Heroku. "The Twelve-Factor App." https://12factor.net/ (accessed 2025-03-29).
+
+## Changelog
+- 2025-03-29: Codified input/output and failure responses for domain skills.
+
+## Works well with
+
+- alfred-trust-validation (backend testing)
+- web-api-expert (API design)
+- database-expert (database optimization)
+
+## 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-domain-cli-tool/SKILL.md

@@ -0,0 +1,95 @@
+---
+
+name: moai-domain-cli-tool
+description: CLI tool development with argument parsing, POSIX compliance, and user-friendly help messages. Use when working on command-line tooling scenarios.
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# CLI Tool Expert
+
+## Skill Metadata
+| Field | Value |
+| ----- | ----- |
+| Allowed tools | Read (read_file), Bash (terminal) |
+| Auto-load | On demand for CLI design requests |
+| Trigger cues | Command-line UX, packaging, distribution, and automation workflows. |
+| Tier | 4 |
+
+## What it does
+
+Provides expertise in developing command-line interface tools with proper argument parsing, POSIX compliance, intuitive help messages, and standard exit codes.
+
+## When to use
+
+- Engages when building or enhancing command-line tools.
+- “CLI tool development”, “command line parsing”, “POSIX compatibility”
+- Automatically invoked when working with CLI projects
+- CLI tool SPEC implementation (`/alfred:2-run`)
+
+## How it works
+
+**Argument Parsing**:
+- **Python**: argparse, click, typer
+- **Node.js**: commander, yargs, oclif
+- **Rust**: clap, structopt
+- **Go**: cobra, flag
+- **Subcommands**: git-style commands (tool add, tool remove)
+
+**POSIX Compliance**:
+- **Short options**: -h, -v
+- **Long options**: --help, --version
+- **Option arguments**: -o file, --output=file
+- **Standard streams**: stdin, stdout, stderr
+- **Exit codes**: 0 (success), 1-255 (errors)
+
+**User Experience**:
+- **Help messages**: Comprehensive usage documentation
+- **Auto-completion**: Shell completion (bash, zsh, fish)
+- **Progress indicators**: Spinners, progress bars
+- **Color output**: ANSI colors for readability
+- **Interactive prompts**: Confirmation dialogs
+
+**Configuration**:
+- **Config files**: YAML, JSON, TOML (e.g., ~/.toolrc)
+- **Environment variables**: Fallback configuration
+- **Precedence**: CLI args > env vars > config file > defaults
+
+## Examples
+```bash
+$ tool --help
+$ tool run --config config.yml
+```
+
+## Inputs
+- Domain-specific 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. "Command Line Interface Guidelines." https://learn.microsoft.com/windows/console/ (accessed 2025-03-29).
+- Python Packaging Authority. "Command-line Interface Guidelines." https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#entry-points (accessed 2025-03-29).
+
+## Changelog
+- 2025-03-29: Codified input/output and failure responses for domain skills.
+
+## Works well with
+
+- alfred-trust-validation (CLI testing)
+- shell-expert (shell integration)
+- python-expert/typescript-expert (implementation)
+
+## Best Practices
+- Record supporting documentation (version/link) for each domain decision.
+- Review performance, security, and operational requirements simultaneously at an early stage.