moai-adk 0.4.4__py3-none-any.whl → 0.4.7__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.md

@@ -14,12 +14,14 @@
 | --- | --- | --- | --- |
 | **Commands** | User ↔ Alfred | Workflow entry points that establish the Plan → Run → Sync cadence | `/alfred:0-project`, `/alfred:1-plan`, `/alfred:2-run`, `/alfred:3-sync` |
 | **Sub-agents** | Alfred | Deep reasoning and decision making for each phase | project-manager, spec-builder, code-builder pipeline, doc-syncer |
-| **Skills (44)** | Claude Skills | Reusable knowledge capsules loaded just-in-time | Foundation (TRUST/TAG/Git), Essentials (debug/refactor/review), Domain & Language packs |
-| **Hooks** | Runtime guardrails | Fast validation + JIT context hints (<100 ms) | SessionStart status card, PreToolUse destructive-command blocker |
+| **Skills (55)** | Claude Skills | Reusable knowledge capsules loaded just-in-time | Foundation (TRUST/TAG/Git), Essentials (debug/refactor/review), Alfred workflow, Domain & Language packs |
+| **Hooks** | Runtime guardrails | Fast validation + JIT context hints (<100 ms) | SessionStart status card, PreToolUse destructive-command blocker |
 
 ### Core Sub-agent Roster
 
 > Alfred + 10 core sub-agents + 6 zero-project specialists + 2 built-in Claude agents = **19-member team**
+>
+> **Note on Counting**: The "code-builder pipeline" is counted as 1 conceptual agent but implemented as 2 physical files (`implementation-planner` + `tdd-implementer`) for sequential RED → GREEN → REFACTOR execution. This maintains the 19-member team concept while acknowledging that 20 distinct agent files exist in `.claude/agents/alfred/`.
 
 | Sub-agent | Model | Phase | Responsibility | Trigger |
 | --- | --- | --- | --- | --- |
@@ -47,6 +49,8 @@ The **code-builder pipeline** runs two Sonnet specialists in sequence: **impleme
 | **feature-selector** 🎯 | Haiku | Skill pack recommendation | `/alfred:0-project` |
 | **template-optimizer** ⚙️ | Haiku | Template cleanup, migration helpers | `/alfred:0-project` |
 
+> **Implementation Note**: Zero-project specialists may be embedded within other agents (e.g., functionality within `project-manager`) or implemented as dedicated Skills (e.g., `moai-alfred-language-detection`). For example, `language-detector` functionality is provided by the `moai-alfred-language-detection` Skill during `/alfred:0-project` initialization.
+
 ### Built-in Claude Agents
 
 | Agent | Model | Specialty | Invocation |
@@ -107,9 +111,21 @@ User: "Where is JWT authentication implemented in this project?"
 - `medium`: moderate sweep (multiple locations + naming rules) — **recommended**
 - `very thorough`: exhaustive scan (full codebase analysis)
 
-### Claude Skills (44 packs)
+### Claude Skills (55 packs)
+
+Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive Disclosure: metadata is available at session start, full `SKILL.md` content loads when a sub-agent references it, and supporting templates stream only when required.
 
-Alfred relies on 44 Claude Skills grouped by tier. Skills load via Progressive Disclosure: metadata is available at session start, full `SKILL.md` content loads when a sub-agent references it, and supporting templates stream only when required.
+**Skills Distribution by Tier**:
+
+| Tier | Count | Purpose |
+| --- | --- | --- |
+| Foundation | 6 | Core TRUST/TAG/SPEC/Git/EARS/Lang principles |
+| Essentials | 4 | Debug/Perf/Refactor/Review workflows |
+| Alfred | 11 | Internal workflow orchestration |
+| Domain | 10 | Specialized domain expertise |
+| Language | 23 | Language-specific best practices |
+| Claude Code Ops | 1 | Session management |
+| **Total** | **55** | Complete knowledge capsule library |
 
 **Foundation Tier (6)**
 
@@ -131,6 +147,22 @@ Alfred relies on 44 Claude Skills grouped by tier. Skills load via Progressive D
 | `moai-essentials-refactor` | Refactoring patterns & code-smell remediation | `/alfred:2-run` |
 | `moai-essentials-review` | Code review checklist & quality feedback | `/alfred:3-sync` |
 
+**Alfred Tier (11)** — Internal workflow orchestration
+
+| Skill | Purpose | Auto-load |
+| --- | --- | --- |
+| `moai-alfred-code-reviewer` | Automated code quality review | `/alfred:3-sync` |
+| `moai-alfred-debugger-pro` | Advanced debugging strategies | `/alfred:2-run` failures |
+| `moai-alfred-ears-authoring` | EARS syntax validation & templates | `/alfred:1-plan` |
+| `moai-alfred-git-workflow` | GitFlow automation patterns | Plan/Run/Sync |
+| `moai-alfred-language-detection` | Stack detection & Skill preload | SessionStart, `/alfred:0-project` |
+| `moai-alfred-performance-optimizer` | Performance profiling & optimization | On demand |
+| `moai-alfred-refactoring-coach` | Refactoring guidance & patterns | `/alfred:2-run` |
+| `moai-alfred-spec-metadata-validation` | SPEC metadata policy enforcement | `/alfred:1-plan` |
+| `moai-alfred-tag-scanning` | TAG integrity & orphan detection | `/alfred:3-sync` |
+| `moai-alfred-trust-validation` | TRUST 5 principle verification | All phases |
+| `moai-alfred-tui-survey` | Interactive user surveys & menus | On demand |
+
 **Domain Tier (10)** — `moai-domain-backend`, `web-api`, `frontend`, `mobile-app`, `security`, `devops`, `database`, `data-science`, `ml`, `cli-tool`.
 
 **Language Tier (23)** — Python, TypeScript, Go, Rust, Java, Kotlin, Swift, Dart, C/C++, C#, Scala, Haskell, Elixir, Clojure, Lua, Ruby, PHP, JavaScript, SQL, Shell, Julia, R, plus supporting stacks.
@@ -163,16 +195,16 @@ Skills keep the core knowledge lightweight while allowing Alfred to assemble the
 
 Alfred commands follow a three-phase loop, with an optional bootstrap stage for `/alfred:0-project`.
 
-- **Phase 0 — Bootstrap (optional)**  
+- **Phase 0 — Bootstrap (optional)**
   Capture project metadata, create `.moai/config.json` and project docs, detect languages, and stage the recommended Skill packs.
 
-- **Phase 1 — Analyze & Plan**  
+- **Phase 1 — Analyze & Plan**
   Understand scope, constraints, and desired outputs; review existing context (files, specs, tests); outline the execution plan and surface risks.
 
-- **Phase 2 — Execute**  
+- **Phase 2 — Execute**
   Run the approved steps in order, log progress in the task thread, escalate blockers immediately with mitigation options, and record decisions.
 
-- **Phase 3 — Sync & Handoff**  
+- **Phase 3 — Sync & Handoff**
   Update docs, TAG inventory, and reports; verify quality gates; summarize outcomes; and suggest the next command or manual follow-up.
 
 ### Alfred's Next-Step Suggestion Principles
@@ -526,15 +558,15 @@ MoAI-ADK assigns every responsibility to a dedicated execution layer.
 - Examples: spec-builder, code-builder pipeline, doc-syncer, tag-agent, git-manager.
 - Communicate status, escalate blockers, and request Skills when additional knowledge is required.
 
-### Skills — Reusable knowledge capsules (44 packs)
+### Skills — Reusable knowledge capsules (55 packs)
 
 - <500-word playbooks stored under `.claude/skills/`.
 - Loaded via Progressive Disclosure only when relevant.
-- Provide standard templates, best practices, and checklists across Foundation, Essentials, Domain, Language, and Ops tiers.
+- Provide standard templates, best practices, and checklists across Foundation, Essentials, Alfred, Domain, Language, and Ops tiers.
 
 ### Hooks — Guardrails & just-in-time context
 
-- Lightweight (<100 ms) checks triggered by session events.
+- Lightweight (<100 ms) checks triggered by session events.
 - Block destructive commands, surface status cards, and seed context pointers.
 - Examples: SessionStart project summary, PreToolUse safety checks.