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

moai_adk/templates/.github/workflows/swift-tag-validation.yml

@@ -0,0 +1,79 @@
+# @CODE:LDE-006-SWIFT | SPEC: SPEC-LANGUAGE-DETECTION-EXTENDED-001/spec.md
+# Swift TAG Validation Workflow
+# Validates Swift code with XCTest, SwiftLint, and Swift Package Manager
+
+name: Swift TAG Validation
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [main, develop, "feature/**"]
+
+jobs:
+  test:
+    name: 🧪 Swift Tests & Linting
+    runs-on: macos-latest  # Swift requires macOS runner
+
+    if: github.event.pull_request.draft == false || github.event_name == 'push'
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    strategy:
+      matrix:
+        swift-version: ['5.9', '5.10']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Swift
+        uses: swift-actions/setup-swift@v2
+        with:
+          swift-version: ${{ matrix.swift-version }}
+
+      - name: Detect project type
+        id: detect-project
+        run: |
+          if [ -f "Package.swift" ]; then
+            echo "type=spm" >> $GITHUB_OUTPUT
+            echo "Swift Package Manager project detected"
+          elif [ -n "$(find . -name '*.xcodeproj' -o -name '*.xcworkspace')" ]; then
+            echo "type=xcode" >> $GITHUB_OUTPUT
+            echo "Xcode project detected"
+          else
+            echo "No Swift project detected"
+            exit 1
+          fi
+
+      - name: Install SwiftLint
+        run: brew install swiftlint
+
+      - name: Run SwiftLint
+        run: swiftlint lint --strict
+
+      - name: Build with Swift Package Manager
+        if: steps.detect-project.outputs.type == 'spm'
+        run: swift build
+
+      - name: Run tests with Swift Package Manager
+        if: steps.detect-project.outputs.type == 'spm'
+        run: swift test --enable-code-coverage
+
+      - name: Generate coverage report (SPM)
+        if: steps.detect-project.outputs.type == 'spm' && always()
+        run: |
+          xcrun llvm-cov export -format="lcov" .build/debug/*.xctest/Contents/MacOS/* \
+            -instr-profile .build/debug/codecov/default.profdata > coverage.lcov
+
+      - name: Upload coverage artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: swift-coverage-${{ matrix.swift-version }}
+          path: coverage.lcov
+          retention-days: 30

moai_adk/templates/.moai/config.json

@@ -0,0 +1,113 @@
+{
+  "_meta": {
+    "@CODE:CONFIG-STRUCTURE-001": "@DOC:JSON-CONFIG-001",
+    "@SPEC:PROJECT-CONFIG-001": "@SPEC:MOAI-CONFIG-001"
+  },
+  "moai": {
+    "version": "{{MOAI_VERSION}}",
+    "update_check_frequency": "daily",
+    "version_check": {
+      "enabled": true,
+      "cache_ttl_hours": 24
+    }
+  },
+  "constitution": {
+    "enforce_tdd": true,
+    "principles": {
+      "simplicity": {
+        "max_projects": 5,
+        "notes": "Default recommendation. Adjust in .moai/config.json or via SPEC/ADR with documented rationale based on project size."
+      }
+    },
+    "require_tags": true,
+    "simplicity_threshold": 5,
+    "test_coverage_target": 85
+  },
+  "git_strategy": {
+    "personal": {
+      "auto_checkpoint": "event-driven",
+      "checkpoint_events": [
+        "delete",
+        "refactor",
+        "merge",
+        "script",
+        "critical-file"
+      ],
+      "checkpoint_type": "local-branch",
+      "max_checkpoints": 10,
+      "cleanup_days": 7,
+      "push_to_remote": false,
+      "auto_commit": true,
+      "branch_prefix": "feature/",
+      "develop_branch": "develop",
+      "main_branch": "main"
+    },
+    "team": {
+      "auto_pr": true,
+      "develop_branch": "develop",
+      "draft_pr": true,
+      "feature_prefix": "feature/SPEC-",
+      "main_branch": "main",
+      "use_gitflow": true
+    }
+  },
+  "pipeline": {
+    "available_commands": [
+      "/alfred:0-project",
+      "/alfred:1-plan",
+      "/alfred:2-run",
+      "/alfred:3-sync"
+    ],
+    "current_stage": "initialized"
+  },
+  "language": {
+    "conversation_language": "{{CONVERSATION_LANGUAGE}}",
+    "conversation_language_name": "{{CONVERSATION_LANGUAGE_NAME}}"
+  },
+  "project": {
+    "name": "{{PROJECT_NAME}}",
+    "description": "{{PROJECT_DESCRIPTION}}",
+    "mode": "{{PROJECT_MODE}}",
+    "locale": "{{CONVERSATION_LANGUAGE}}",
+    "language": "{{CODEBASE_LANGUAGE}}",
+    "created_at": "{{CREATION_TIMESTAMP}}",
+    "initialized": true,
+    "optimized": false
+  },
+  "tags": {
+    "auto_sync": true,
+    "storage_type": "code_scan",
+    "categories": [
+      "REQ",
+      "DESIGN",
+      "TASK",
+      "TEST",
+      "FEATURE",
+      "API",
+      "UI",
+      "DATA"
+    ],
+    "code_scan_policy": {
+      "no_intermediate_cache": true,
+      "realtime_validation": true,
+      "scan_tools": [
+        "rg",
+        "grep"
+      ],
+      "scan_command": "rg '@TAG' -n",
+      "philosophy": "The source of truth for TAGs lives in the code itself"
+    }
+  },
+  "github": {
+    "@CODE:GITHUB-CONFIG-001": "@DOC:GITHUB-TEMPLATES-001",
+    "templates": {
+      "enable_trust_5": true,
+      "enable_tag_system": true,
+      "enable_alfred_commands": true,
+      "spec_directory": ".moai/specs",
+      "docs_directory": ".moai/docs",
+      "test_directory": "tests",
+      "notes": "Configure GitHub templates for project customization. When enable_* flags are false, corresponding MoAI-specific sections are omitted from templates."
+    }
+  }
+}

moai_adk/templates/.moai/memory/CLAUDE-AGENTS-GUIDE.md

@@ -0,0 +1,208 @@
+# CLAUDE-AGENTS-GUIDE.md
+
+> MoAI-ADK Agent Architecture & Decision Guide
+
+---
+
+## For Alfred: Why This Document Matters
+
+When Alfred reads this document:
+
+1. Upon receiving a new task - Decide "Which Sub-agent should I invoke?"
+2. When complex tasks are required - Determine sequence and collaboration patterns among multiple agents
+3. When reviewing team structure - Verify responsibility scope of each agent
+
+Alfred's Decision Making:
+
+- "Should this task be handled by spec-builder or code-builder?"
+- "When should I invoke the Explore agent and when should I not?"
+- "Is the Haiku model sufficient for this task, or do I need Sonnet?"
+
+After reading this document:
+
+- Clearly understand the responsibility scope of 19 Sub-agents
+- Grasp how 55 Skills are organized by tier
+- Master Agent collaboration principles (Command Precedence, Single Responsibility, etc.)
+- Learn Haiku vs Sonnet model selection criteria
+
+---
+
+→ Related Documents:
+
+- [For Alfred's decision-making rules, see CLAUDE-RULES.md](./CLAUDE-RULES.md#skill-invocation-rules)
+- [For actual Agent invocation examples, see CLAUDE-PRACTICES.md](./CLAUDE-PRACTICES.md#practical-workflow-examples)
+
+---
+
+## 4-Layer Architecture
+
+| Layer           | Owner              | Purpose                                                            | Examples                                                                                                 |
+| --------------- | ------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **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 (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                      |
+| ---------------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------- | ---------------------------- |
+| **project-manager** 📋       | Sonnet | Init        | Project bootstrap, metadata interview, mode selection                                          | `/alfred:0-project`          |
+| **spec-builder** 🏗️          | Sonnet | Plan        | Plan board consolidation, EARS-based SPEC authoring                                            | `/alfred:1-plan`             |
+| **code-builder pipeline** 💎 | Sonnet | Run         | Phase 1 `implementation-planner` → Phase 2 `tdd-implementer` to execute RED → GREEN → REFACTOR | `/alfred:2-run`              |
+| **doc-syncer** 📖            | Haiku  | Sync        | Living documentation, README/CHANGELOG updates                                                 | `/alfred:3-sync`             |
+| **tag-agent** 🏷️             | Haiku  | Sync        | TAG inventory, orphan detection, chain repair                                                  | `@agent-tag-agent`           |
+| **git-manager** 🚀           | Haiku  | Plan · Sync | GitFlow automation, Draft→Ready PR, auto-merge policy                                          | `@agent-git-manager`         |
+| **debug-helper** 🔍          | Sonnet | Run         | Failure diagnosis, fix-forward guidance                                                        | `@agent-debug-helper`        |
+| **trust-checker** ✅         | Haiku  | All phases  | TRUST 5 principle enforcement and risk flags                                                   | `@agent-trust-checker`       |
+| **quality-gate** 🛡️          | Haiku  | Sync        | Coverage delta review, release gate validation                                                 | Auto during `/alfred:3-sync` |
+| **cc-manager** 🛠️            | Sonnet | Ops         | Claude Code session tuning, Skill lifecycle management                                         | `@agent-cc-manager`          |
+
+The **code-builder pipeline** runs two Sonnet specialists in sequence: **implementation-planner** (strategy, libraries, TAG design) followed by **tdd-implementer** (RED → GREEN → REFACTOR execution).
+
+---
+
+## Zero-project Specialists
+
+| Sub-agent                  | Model  | Focus                                                       | Trigger                         |
+| -------------------------- | ------ | ----------------------------------------------------------- | ------------------------------- |
+| **language-detector** 🔍   | Haiku  | Stack detection, language matrix                            | Auto during `/alfred:0-project` |
+| **backup-merger** 📦       | Sonnet | Backup restore, checkpoint diff                             | `@agent-backup-merger`          |
+| **project-interviewer** 💬 | Sonnet | Requirement interviews, persona capture                     | `/alfred:0-project` Q&A         |
+| **document-generator** 📝  | Haiku  | Project docs seed (`product.md`, `structure.md`, `tech.md`) | `/alfred:0-project`             |
+| **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       |
+| ------------------- | ------ | --------------------------------------------- | ---------------- |
+| **Explore** 🔍      | Haiku  | Repository-wide search & architecture mapping | `@agent-Explore` |
+| **general-purpose** | Sonnet | General assistance                            | Automatic        |
+
+### Explore Agent Guide
+
+The **Explore** agent excels at navigating large codebases.
+
+**Use cases**:
+
+- ✅ **Code analysis** (understand complex implementations, trace dependencies, study architecture)
+- ✅ Search for specific keywords or patterns (e.g., "API endpoints", "authentication logic")
+- ✅ Locate files (e.g., `src/components/**/*.tsx`)
+- ✅ Understand codebase structure (e.g., "explain the project architecture")
+- ✅ Search across many files (Glob + Grep patterns)
+
+**Recommend Explore when**:
+
+- 🔍 You need to understand a complex structure
+- 🔍 The implementation spans multiple files
+- 🔍 You want the end-to-end flow of a feature
+- 🔍 Dependency relationships must be analyzed
+- 🔍 You're planning a refactor and need impact analysis
+
+**Usage**: Use `Task(subagent_type="Explore", ...)` for deep codebase analysis. Declare `thoroughness: quick|medium|very thorough` in the prompt.
+
+**Examples**:
+
+- Deep analysis: "Analyze TemplateProcessor class and its dependencies" (thoroughness: very thorough)
+- Domain search: "Find all AUTH-related files in SPEC/tests/src/docs" (thoroughness: medium)
+- Natural language: "Where is JWT authentication implemented?" → Alfred auto-delegates
+
+---
+
+## 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.
+
+**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)**: `moai-foundation-trust`, `moai-foundation-tags`, `moai-foundation-specs`, `moai-foundation-ears`, `moai-foundation-git`, `moai-foundation-langs` (TRUST/TAG/SPEC/EARS/Git/language detection)
+
+**Essentials Tier (4)**: `moai-essentials-debug`, `moai-essentials-perf`, `moai-essentials-refactor`, `moai-essentials-review` (Debug/Perf/Refactor/Review workflows)
+
+**Alfred Tier (11)**: `moai-alfred-code-reviewer`, `moai-alfred-debugger-pro`, `moai-alfred-ears-authoring`, `moai-alfred-git-workflow`, `moai-alfred-language-detection`, `moai-alfred-performance-optimizer`, `moai-alfred-refactoring-coach`, `moai-alfred-spec-metadata-validation`, `moai-alfred-tag-scanning`, `moai-alfred-trust-validation`, `moai-alfred-interactive-questions` (code review, debugging, EARS, Git, language detection, performance, refactoring, metadata, TAG scanning, trust validation, interactive questions)
+
+**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.
+
+**Claude Code Ops (1)** — `moai-claude-code` manages session settings, output styles, and Skill deployment.
+
+Skills keep the core knowledge lightweight while allowing Alfred to assemble the right expertise for each request.
+
+---
+
+## Agent Collaboration Principles
+
+- **Command precedence**: Command instructions outrank agent guidelines; follow the command if conflicts occur.
+- **Single responsibility**: Each agent handles only its specialty.
+- **Zero overlapping ownership**: When unsure, hand off to the agent with the most direct expertise.
+- **Confidence reporting**: Always share confidence levels and identified risks when completing a task.
+- **Escalation path**: When blocked, escalate to Alfred with context, attempted steps, and suggested next actions.
+
+---
+
+## Model Selection Guide
+
+| Model                 | Primary use cases                                                    | Representative sub-agents                                                              | Why it fits                                                    |
+| --------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Claude 4.5 Haiku**  | Documentation sync, TAG inventory, Git automation, rule-based checks | doc-syncer, tag-agent, git-manager, trust-checker, quality-gate, Explore               | Fast, deterministic output for patterned or string-heavy work  |
+| **Claude 4.5 Sonnet** | Planning, implementation, troubleshooting, session ops               | Alfred, project-manager, spec-builder, code-builder pipeline, debug-helper, cc-manager | Deep reasoning, multi-step synthesis, creative problem solving |
+
+**Guidelines**:
+
+- Default to **Haiku** when the task is pattern-driven or requires rapid iteration; escalate to **Sonnet** for novel design, architecture, or ambiguous problem solving.
+- Record any manual model switch in the task notes (who, why, expected benefit).
+- Combine both models when needed: e.g., Sonnet plans a refactor, Haiku formats and validates the resulting docs.
+
+---
+
+## Agent Selection Decision Tree
+
+| Situation                   | Recommended Agent         | Reason                                                                                                 |
+| --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Need codebase understanding | **Explore**               | Specialized in rapid analysis of large projects. Understand entire structure with Glob + Grep patterns |
+| Write SPEC for new feature  | **spec-builder**          | Expert in EARS syntax + SPEC structure. Auto-manage YAML metadata + HISTORY                            |
+| Analyze bug causes          | **debug-helper**          | Expert in stack trace + error pattern analysis. Recommends fix-forward vs rollback                     |
+| Code implementation (TDD)   | **code-builder pipeline** | Automates RED → GREEN → REFACTOR. Sequential execution of implementation-planner + tdd-implementer     |
+| Need document sync          | **doc-syncer**            | Automates Living Documents. Generates README + CHANGELOG, verifies TAG chain                           |
+| Git/PR management           | **git-manager**           | Automates GitFlow + Draft→Ready. Creates feature branches + PRs                                        |
+| Version release             | **git-manager**           | Automates releases. Generates CHANGELOG + creates tags + merges PR                                     |
+| Verify TAG integrity        | **tag-agent**             | Specializes in TAG chain verification. Detects orphan TAGs + recommends fixes                          |
+| Verify code quality         | **trust-checker**         | Verifies TRUST 5 principles. Checks Test/Readable/Unified/Secured/Trackable                            |
+| Verify release gate         | **quality-gate**          | Coverage delta + security scan. Final verification before release                                      |
+| Project initialization      | **project-manager**       | Metadata interview + mode selection. Dedicated to `/alfred:0-project`                                  |
+| Claude Code session mgmt    | **cc-manager**            | Skill lifecycle + output style management. Specialized in session tuning                               |
+
+---
+
+**Usage Examples**:
+
+- "User requests 'Add login feature'" → **spec-builder** (Write SPEC) → **code-builder pipeline** (Implement) → **doc-syncer** (Document)
+- "Tests are failing" → **debug-helper** (Analyze cause) → **code-builder pipeline** (Fix) → **trust-checker** (Re-verify quality)
+- "Prepare for release" → **quality-gate** (Final verification) → **git-manager** (PR merge + tag)
+
+---
+
+**Last Updated**: 2025-10-27
+**Document Version**: v1.0.0