moai-adk 0.11.0__py3-none-any.whl → 0.11.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-skill-factory/templates/reference-template.md

@@ -0,0 +1,278 @@
+# Reference: [Skill Domain]
+
+Complete reference documentation for [Skill Name].
+
+---
+
+## API Reference
+
+### Function/Command 1: `function_name(param1, param2)`
+
+[Description of what this function does]
+
+**Parameters**:
+- `param1` (type): Description of parameter 1
+- `param2` (type): Description of parameter 2
+
+**Returns**:
+- Type: [Return type]
+- Description: [What is returned]
+
+**Example**:
+```python
+result = function_name("value1", "value2")
+print(result)
+# Output: [example output]
+```
+
+**Raises**:
+- `ErrorType`: When this error occurs
+- `AnotherError`: When that error occurs
+
+---
+
+### Function/Command 2: `another_function(arg1)`
+
+[Description]
+
+**Parameters**:
+- `arg1`: Description
+
+**Returns**: Description
+
+**Example**:
+```
+code example
+```
+
+---
+
+## Configuration
+
+### Configuration File Format
+
+```yaml
+# Example configuration
+key1: value1
+section:
+  nested_key: nested_value
+  list:
+    - item1
+    - item2
+```
+
+### Available Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | string | "default" | Description of option 1 |
+| `option2` | number | 10 | Description of option 2 |
+| `option3` | boolean | true | Description of option 3 |
+
+### Configuration Examples
+
+**Minimal Configuration**:
+```yaml
+required_option: value
+```
+
+**Production Configuration**:
+```yaml
+option1: production_value
+option2: 100
+option3: false
+section:
+  nested_value: production_specific
+```
+
+---
+
+## Data Models
+
+### Model 1: [Model Name]
+
+```
+Class/Type definition here
+Field 1: type - description
+Field 2: type - description
+Field 3: type - description
+```
+
+**Example**:
+```json
+{
+  "field1": "value",
+  "field2": 123,
+  "field3": true
+}
+```
+
+### Model 2: [Model Name]
+
+[Similar structure]
+
+---
+
+## Edge Cases & Limitations
+
+### Known Limitations
+
+1. **Limitation 1**
+   - Description
+   - Impact
+   - Workaround (if available)
+
+2. **Limitation 2**
+   - Description
+   - Impact
+   - Workaround
+
+### Boundary Conditions
+
+| Condition | Behavior | Handling |
+|-----------|----------|----------|
+| Empty input | Returns default | Validate before calling |
+| Maximum size exceeded | Throws error | Check size limits first |
+| Timeout | Operation fails | Set timeout threshold |
+
+### Workarounds
+
+**Workaround 1**: [For limitation 1]
+```
+Implementation workaround code
+```
+
+**Workaround 2**: [For limitation 2]
+```
+Implementation workaround code
+```
+
+---
+
+## Performance Considerations
+
+### Time Complexity
+
+- Operation 1: O(n) — Description
+- Operation 2: O(n log n) — Description
+- Operation 3: O(1) — Description
+
+### Space Complexity
+
+- Operation 1: O(n) — Description
+- Operation 2: O(1) — Description
+
+### Optimization Tips
+
+1. **Tip 1**: How to optimize performance in scenario 1
+2. **Tip 2**: How to optimize performance in scenario 2
+3. **Tip 3**: Caching strategy or batching approach
+
+### Benchmarks (if applicable)
+
+| Operation | Small (1K) | Medium (1M) | Large (1G) |
+|-----------|-----------|-----------|-----------|
+| Read | 10ms | 100ms | 1s |
+| Write | 20ms | 200ms | 2s |
+| Process | 50ms | 500ms | 5s |
+
+---
+
+## Error Handling
+
+### Common Errors
+
+**Error 1: [Error Name]**
+- Cause: [What causes this error]
+- Solution: [How to fix it]
+- Example:
+```
+Error message example
+```
+
+**Error 2: [Error Name]**
+- Cause: [What causes this error]
+- Solution: [How to fix it]
+
+### Error Codes
+
+| Code | Meaning | Recovery |
+|------|---------|----------|
+| 0 | Success | Continue |
+| 1 | General error | Check logs |
+| 2 | Invalid input | Validate input |
+| 3 | Resource not found | Check resource exists |
+
+---
+
+## Compatibility
+
+### Supported Versions
+
+- Framework/Language version X.Y+
+- Dependency 1 version A.B+
+- Dependency 2 version C.D+
+
+### Known Incompatibilities
+
+- Version X.Y is not supported due to [reason]
+- Older frameworks may have [limitation]
+
+---
+
+## Security Considerations
+
+### Input Validation
+
+- All user input must be [validated/sanitized]
+- Maximum length limits: [specify limits]
+- Allowed characters: [specify]
+
+### Secrets Management
+
+- Never hardcode secrets
+- Use environment variables
+- Validate API keys before use
+
+### Common Vulnerabilities to Avoid
+
+1. [Vulnerability 1] — How to prevent it
+2. [Vulnerability 2] — How to prevent it
+
+---
+
+## Glossary
+
+- **Term 1**: Definition with context
+- **Term 2**: Definition with context
+- **Term 3**: Definition with context
+- **Acronym 1**: What it stands for and means
+- **Acronym 2**: What it stands for and means
+
+---
+
+## Related Resources
+
+- [SKILL.md](SKILL.md) — Main framework and concepts
+- [examples.md](examples.md) — Real-world usage examples
+- [External resource](https://example.com) — External documentation
+
+---
+
+## Version & History
+
+**Current Version**: 0.1.0
+**Last Updated**: 2025-10-22
+
+### Changelog
+
+#### v0.1.0 (2025-10-22)
+- Initial reference documentation
+- API documentation added
+- Configuration options documented
+
+---
+
+**Status**: Active
+**Maintainer**: [Your Name]
+**Framework**: MoAI-ADK + Claude Code Skills

moai_adk/templates/.claude/skills/moai-skill-factory/templates/scripts-template.sh

@@ -0,0 +1,303 @@
+#!/bin/bash
+#
+# Script Template: [Script Purpose]
+# Description: [What this script does in one sentence]
+# Usage: ./script-name.sh [ARGS]
+#
+# This is a template for creating production-ready Bash scripts
+# with proper error handling, validation, and logging.
+#
+
+set -euo pipefail
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+# Script metadata
+SCRIPT_NAME="$(basename "$0")"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Color codes for output
+readonly RED='\033[0;31m'
+readonly GREEN='\033[0;32m'
+readonly YELLOW='\033[1;33m'
+readonly BLUE='\033[0;34m'
+readonly NC='\033[0m' # No Color
+
+# Configuration variables
+readonly LOG_LEVEL="${LOG_LEVEL:-INFO}"  # DEBUG, INFO, WARN, ERROR
+readonly MAX_RETRIES="${MAX_RETRIES:-3}"
+readonly RETRY_DELAY="${RETRY_DELAY:-2}"
+
+# ============================================================================
+# LOGGING FUNCTIONS
+# ============================================================================
+
+log_debug() {
+    [[ "$LOG_LEVEL" == "DEBUG" ]] && echo -e "${BLUE}[DEBUG]${NC} $*" >&2
+    return 0
+}
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $*"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}✓${NC} $*"
+}
+
+# ============================================================================
+# ERROR HANDLING
+# ============================================================================
+
+# Trap errors and clean up
+trap 'on_error $? $LINENO' ERR
+
+on_error() {
+    local exit_code=$1
+    local line_number=$2
+    log_error "Script failed with exit code $exit_code on line $line_number"
+    cleanup
+    exit "$exit_code"
+}
+
+# Trap signals for graceful shutdown
+trap 'on_interrupt' INT TERM
+
+on_interrupt() {
+    log_warn "Script interrupted"
+    cleanup
+    exit 130
+}
+
+cleanup() {
+    log_debug "Running cleanup..."
+    # Add cleanup operations here (e.g., remove temp files, close connections)
+    # Example:
+    # [[ -n "${TEMP_FILE:-}" ]] && rm -f "$TEMP_FILE"
+}
+
+# ============================================================================
+# VALIDATION FUNCTIONS
+# ============================================================================
+
+validate_arg() {
+    local arg_name=$1
+    local arg_value=$2
+
+    if [[ -z "$arg_value" ]]; then
+        log_error "Argument '$arg_name' is required but was not provided"
+        print_usage
+        exit 1
+    fi
+}
+
+validate_file() {
+    local file_path=$1
+
+    if [[ ! -f "$file_path" ]]; then
+        log_error "File not found: $file_path"
+        return 1
+    fi
+
+    if [[ ! -r "$file_path" ]]; then
+        log_error "File is not readable: $file_path"
+        return 1
+    fi
+
+    return 0
+}
+
+validate_directory() {
+    local dir_path=$1
+
+    if [[ ! -d "$dir_path" ]]; then
+        log_error "Directory not found: $dir_path"
+        return 1
+    fi
+
+    if [[ ! -w "$dir_path" ]]; then
+        log_error "Directory is not writable: $dir_path"
+        return 1
+    fi
+
+    return 0
+}
+
+validate_command() {
+    local cmd=$1
+
+    if ! command -v "$cmd" &> /dev/null; then
+        log_error "Required command not found: $cmd"
+        return 1
+    fi
+
+    return 0
+}
+
+# ============================================================================
+# RETRY LOGIC
+# ============================================================================
+
+retry() {
+    local max_attempts=$1
+    shift
+    local cmd=("$@")
+    local attempt=1
+
+    while [[ $attempt -le $max_attempts ]]; do
+        log_debug "Attempt $attempt of $max_attempts: ${cmd[*]}"
+
+        if "${cmd[@]}"; then
+            return 0
+        fi
+
+        if [[ $attempt -lt $max_attempts ]]; then
+            log_warn "Command failed, retrying in ${RETRY_DELAY}s..."
+            sleep "$RETRY_DELAY"
+        fi
+
+        ((attempt++))
+    done
+
+    log_error "Command failed after $max_attempts attempts: ${cmd[*]}"
+    return 1
+}
+
+# ============================================================================
+# MAIN FUNCTIONS
+# ============================================================================
+
+print_usage() {
+    cat << EOF
+Usage: $SCRIPT_NAME [OPTIONS] [ARGUMENTS]
+
+Description:
+  [Describe what this script does]
+
+Options:
+  -h, --help              Show this help message
+  -v, --verbose           Enable verbose (debug) output
+  -d, --dry-run           Show what would be done without doing it
+
+Arguments:
+  ARG1                    [Description of argument 1]
+  ARG2                    [Description of argument 2]
+
+Examples:
+  # Basic usage
+  $SCRIPT_NAME arg1 arg2
+
+  # With verbose output
+  $SCRIPT_NAME -v arg1 arg2
+
+  # Dry run to preview changes
+  $SCRIPT_NAME --dry-run arg1 arg2
+
+Exit Codes:
+  0   Success
+  1   General error
+  2   Invalid arguments
+  130 Interrupted by user
+
+Notes:
+  [Any additional notes about the script]
+
+See Also:
+  [Reference to related documentation or scripts]
+EOF
+}
+
+parse_args() {
+    local dry_run=false
+
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            -h | --help)
+                print_usage
+                exit 0
+                ;;
+            -v | --verbose)
+                export LOG_LEVEL="DEBUG"
+                log_debug "Debug mode enabled"
+                shift
+                ;;
+            -d | --dry-run)
+                dry_run=true
+                log_info "Dry run mode enabled"
+                shift
+                ;;
+            -*)
+                log_error "Unknown option: $1"
+                print_usage
+                exit 2
+                ;;
+            *)
+                # Positional arguments
+                break
+                ;;
+        esac
+    done
+
+    # Store remaining arguments
+    readonly ARGS=("$@")
+    readonly DRY_RUN=$dry_run
+
+    # Validate required arguments
+    if [[ ${#ARGS[@]} -lt 1 ]]; then
+        log_error "Missing required argument"
+        print_usage
+        exit 2
+    fi
+}
+
+main() {
+    log_info "Starting $SCRIPT_NAME"
+
+    # Validate prerequisites
+    validate_command "grep" || exit 1
+    validate_command "sed" || exit 1
+
+    # Extract arguments
+    local arg1="${ARGS[0]}"
+    local arg2="${ARGS[1]:-}"
+
+    log_debug "arg1: $arg1"
+    log_debug "arg2: $arg2"
+
+    # Validate arguments
+    validate_arg "arg1" "$arg1"
+
+    # Main logic here
+    if [[ "$DRY_RUN" == "true" ]]; then
+        log_info "[DRY RUN] Would process: $arg1"
+        return 0
+    fi
+
+    # Example: Do something with retries
+    retry "$MAX_RETRIES" \
+        grep -r "pattern" "$arg1"
+
+    # Success
+    log_success "Operation completed successfully"
+    return 0
+}
+
+# ============================================================================
+# ENTRY POINT
+# ============================================================================
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    parse_args "$@"
+    main
+fi

moai_adk/templates/.claude/skills/moai-spec-authoring/README.md

@@ -0,0 +1,137 @@
+# moai-spec-authoring Skill
+
+**Version**: 1.2.0
+**Created**: 2025-10-23
+**Updated**: 2025-10-29
+**Status**: Active
+**Tier**: Foundation
+
+## Overview
+
+Comprehensive guide for authoring SPEC documents in MoAI-ADK projects. Provides complete YAML metadata structure, EARS syntax patterns, version management strategies, and validation tools.
+
+## Key Features
+
+- **7 Required + 9 Optional Metadata Fields**: Complete reference with lifecycle examples
+- **5 Official EARS Patterns**: Ubiquitous, Event-driven, State-driven, Optional, Unwanted Behaviors
+- **Version Lifecycle**: Semantic versioning from draft to production
+- **TAG Integration**: @SPEC, @TEST, @CODE, @DOC chain management
+- **Validation Tools**: Pre-submission checklist and automation scripts
+- **Common Pitfalls**: Prevention strategies for 7 major issues
+
+## File Structure (Progressive Disclosure)
+
+```
+.claude/skills/moai-spec-authoring/
+├── SKILL.md          # Core overview + Quick Start (~500 words)
+├── reference.md      # Complete metadata reference + EARS syntax
+├── examples.md       # Real-world examples + patterns + troubleshooting
+├── examples/
+│   └── validate-spec.sh  # Automated SPEC validation script
+└── README.md         # This file
+```
+
+## Quick Links
+
+- **Quick Start**: [SKILL.md](./SKILL.md#quick-start-5-step-spec-creation)
+- **Metadata Reference**: [reference.md](./reference.md#complete-metadata-field-reference)
+- **EARS Syntax**: [reference.md](./reference.md#ears-requirement-syntax)
+- **Examples**: [examples.md](./examples.md#real-world-ears-examples)
+- **Troubleshooting**: [examples.md](./examples.md#troubleshooting)
+
+## Usage
+
+### Automatic Activation
+
+This Skill automatically loads when:
+- `/alfred:1-plan` command is executed
+- SPEC document creation is requested
+- Requirements clarification is discussed
+
+### Manual Reference
+
+Consult detailed sections for:
+- SPEC authoring best practices
+- Existing SPEC document validation
+- Metadata issue troubleshooting
+- EARS syntax pattern reference
+
+## Validation Command
+
+```bash
+# Validate SPEC metadata
+rg "^(id|version|status|created|updated|author|priority):" .moai/specs/SPEC-AUTH-001/spec.md
+
+# Check for duplicate IDs
+rg "@SPEC:AUTH-001" -n .moai/specs/
+
+# Scan entire TAG chain
+rg '@(SPEC|TEST|CODE|DOC):AUTH-001' -n
+
+# Use automated script
+./examples/validate-spec.sh .moai/specs/SPEC-AUTH-001
+```
+
+## Example SPEC Structure
+
+```markdown
+---
+id: AUTH-001
+version: 0.0.1
+status: draft
+created: 2025-10-29
+updated: 2025-10-29
+author: @YourHandle
+priority: high
+---
+
+# @SPEC:AUTH-001: JWT Authentication System
+
+## HISTORY
+### v0.0.1 (2025-10-29)
+- **INITIAL**: JWT authentication SPEC draft
+
+## Environment
+**Runtime**: Node.js 20.x
+
+## Assumptions
+1. User storage: PostgreSQL
+2. Secret management: Environment variables
+
+## Requirements
+
+### Ubiquitous Requirements
+**UR-001**: The system shall provide JWT-based authentication.
+
+### Event-driven Requirements
+**ER-001**: WHEN the user submits valid credentials, the system shall issue a JWT token.
+
+### State-driven Requirements
+**SR-001**: WHILE the user is in an authenticated state, the system shall permit access to protected resources.
+
+### Optional Features
+**OF-001**: WHERE multi-factor authentication is enabled, the system can require OTP verification.
+
+### Unwanted Behaviors
+**UB-001**: IF a token has expired, THEN the system shall deny access and return HTTP 401.
+```
+
+## Integration
+
+Works seamlessly with:
+- `spec-builder` agent - SPEC creation
+- `moai-foundation-ears` - EARS syntax patterns
+- `moai-foundation-specs` - Metadata validation
+- `moai-foundation-tags` - TAG system integration
+
+## Support
+
+For questions or issues:
+1. Refer to comprehensive documentation: `SKILL.md`, `reference.md`, `examples.md`
+2. Use `/alfred:1-plan` for guided SPEC creation
+3. Review existing SPECs in `.moai/specs/` for examples
+
+---
+
+**Maintained By**: MoAI-ADK Team
+**Last Updated**: 2025-10-29