moai-adk 0.5.4__py3-none-any.whl → 0.5.8__py3-none-any.whl

moai_adk/templates/.github/ISSUE_TEMPLATE/spec.yml

@@ -0,0 +1,176 @@
+name: 📋 SPEC Document
+description: Create a new SPEC document for feature planning
+title: "[SPEC-] "
+labels: ["spec", "planning"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## 📋 SPEC Metadata
+
+        Fill out the SPEC details below. This will be synchronized with the SPEC document and GitHub Issue.
+
+  - type: input
+    id: spec-id
+    attributes:
+      label: SPEC ID
+      description: "Format: DOMAIN-###. Example: AUTH-001, API-DESIGN-001"
+      placeholder: "AUTH-001"
+    validations:
+      required: true
+
+  - type: input
+    id: spec-title
+    attributes:
+      label: SPEC Title
+      description: "Brief description of the specification"
+      placeholder: "JWT-based authentication system"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: "Feature priority level"
+      options:
+        - "critical"
+        - "high"
+        - "medium"
+        - "low"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      description: "SPEC category"
+      options:
+        - "API"
+        - "Backend"
+        - "Frontend"
+        - "Infrastructure"
+        - "Security"
+        - "Testing"
+        - "DevOps"
+        - "Documentation"
+        - "Performance"
+        - "Other"
+    validations:
+      required: true
+
+  - type: textarea
+    id: ubiquitous-requirements
+    attributes:
+      label: "Ubiquitous Requirements"
+      description: "Statements that apply universally to the system"
+      placeholder: |
+        - The system must provide JWT-based authentication
+        - The system must support token expiration
+      value: "### Ubiquitous\n"
+    validations:
+      required: true
+
+  - type: textarea
+    id: event-requirements
+    attributes:
+      label: "Event-driven Requirements (WHEN)"
+      description: "Event-triggered requirements in EARS format"
+      placeholder: |
+        - WHEN the user submits login credentials, the system must validate them against the database
+        - WHEN credentials are valid, the system must issue a JWT token with expiration
+      value: "### Event-driven (WHEN)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: state-requirements
+    attributes:
+      label: "State-driven Requirements (WHILE)"
+      description: "State-based requirements in EARS format"
+      placeholder: |
+        - WHILE the token is unexpired, the system must allow access to protected resources
+        - WHILE the user is logged in, the system must track the session
+      value: "### State-driven (WHILE)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: optional-requirements
+    attributes:
+      label: "Optional Requirements (WHERE)"
+      description: "Optional features and capabilities"
+      placeholder: |
+        - WHERE the user requests token refresh, the system can issue a new token
+        - WHERE OAuth2 is available, the system can support social login
+      value: "### Optional (WHERE)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: constraints
+    attributes:
+      label: "Constraints (IF)"
+      description: "System constraints and conditions"
+      placeholder: |
+        - IF the token has expired, the system must return 401 Unauthorized
+        - IF the password is incorrect, the system must reject the login attempt
+      value: "### Constraints (IF)\n"
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: "Acceptance Criteria (Given-When-Then)"
+      description: "At least 2-3 test scenarios"
+      placeholder: |
+        **Scenario 1: Successful Login**
+        - Given a user with valid credentials exists
+        - When the user submits their credentials
+        - Then the system returns a valid JWT token
+
+        **Scenario 2: Token Expiration**
+        - Given a user with an expired token
+        - When the user tries to access a protected resource
+        - Then the system returns a 401 Unauthorized response
+      value: "## Acceptance Criteria\n\n"
+    validations:
+      required: true
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: "Dependencies"
+      description: "Related SPECs, tasks, or blockers"
+      placeholder: |
+        - Related: SPEC-SECURITY-001
+        - Blocks: SPEC-API-DESIGN-001
+        - Depends on: SPEC-DATABASE-001
+    validations:
+      required: false
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: "Additional Notes"
+      description: "Technical notes, assumptions, or context"
+      placeholder: |
+        - Consider token refresh token rotation
+        - JWT payload should be minimal for performance
+        - Consider rate limiting on login attempts
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        ## 📚 Reference
+
+        - **SPEC Metadata Guide**: See `.moai/memory/spec-metadata.md`
+        - **EARS Syntax Guide**: See `.moai/memory/development-guide.md`
+        - **Acceptance Criteria**: Use Given-When-Then (Gherkin) format
+        - **@TAG System**: @SPEC, @TEST, @CODE, @DOC traceability

moai_adk/templates/.github/workflows/spec-issue-sync.yml

@@ -0,0 +1,167 @@
+name: 📋 SPEC Issue Sync
+
+on:
+  pull_request:
+    paths:
+      - '.moai/specs/SPEC-*/spec.md'
+    types: [opened, synchronize]
+
+permissions:
+  issues: write
+  pull-requests: write
+  contents: read
+
+jobs:
+  sync-spec-to-issue:
+    runs-on: ubuntu-latest
+    name: 🔄 Sync SPEC to GitHub Issue
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Find and parse SPEC file
+        id: spec
+        run: |
+          set -x  # Enable debug mode
+
+          # Debug: Show current directory and files
+          echo "=== Debug: Current directory ==="
+          pwd
+          ls -la
+
+          echo "=== Debug: Looking for .moai/specs ==="
+          ls -la .moai/ 2>&1 || echo ".moai/ directory not found"
+
+          # Find SPEC files in the PR
+          echo "=== Debug: Searching for SPEC files ==="
+          find . -name "spec.md" -type f 2>&1 || echo "find command failed"
+
+          spec_file=$(find .moai/specs -name "spec.md" -type f 2>&1 | head -1)
+          echo "Found spec_file: [$spec_file]"
+
+          if [ -z "$spec_file" ]; then
+            echo "⚠️  No SPEC file found in .moai/specs"
+            echo "Exiting gracefully (this is expected if no SPEC files changed)"
+            exit 0
+          fi
+
+          echo "✅ Found SPEC file: $spec_file"
+          echo "spec_file=$spec_file" >> $GITHUB_OUTPUT
+
+          # Extract YAML metadata using grep
+          spec_id=$(grep "^id:" "$spec_file" | sed 's/^id: *//' | tr -d ' "')
+          spec_version=$(grep "^version:" "$spec_file" | sed 's/^version: *//' | tr -d ' "')
+          spec_status=$(grep "^status:" "$spec_file" | sed 's/^status: *//' | tr -d ' "')
+          spec_priority=$(grep "^priority:" "$spec_file" | sed 's/^priority: *//' | tr -d ' "')
+
+          # Extract title from H1 heading
+          spec_title=$(grep "^# @SPEC:" "$spec_file" | sed 's/^# @SPEC:[^:]*: //')
+
+          echo "✅ Extracted SPEC metadata:"
+          echo "  ID: $spec_id"
+          echo "  Title: $spec_title"
+          echo "  Version: $spec_version"
+          echo "  Status: $spec_status"
+          echo "  Priority: $spec_priority"
+
+          echo "spec_id=$spec_id" >> $GITHUB_OUTPUT
+          echo "spec_version=$spec_version" >> $GITHUB_OUTPUT
+          echo "spec_status=$spec_status" >> $GITHUB_OUTPUT
+          echo "spec_priority=$spec_priority" >> $GITHUB_OUTPUT
+          echo "spec_title=$spec_title" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Issue
+        if: steps.spec.outputs.spec_id
+        id: create-issue
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          spec_id="${{ steps.spec.outputs.spec_id }}"
+          spec_version="${{ steps.spec.outputs.spec_version }}"
+          spec_title="${{ steps.spec.outputs.spec_title }}"
+          spec_status="${{ steps.spec.outputs.spec_status }}"
+          spec_priority="${{ steps.spec.outputs.spec_priority }}"
+          spec_file="${{ steps.spec.outputs.spec_file }}"
+
+          # Read SPEC content (skip YAML frontmatter: 9 lines + 1 blank = 10 lines total)
+          # Start reading from line 11
+          spec_content=$(tail -n +11 "$spec_file")
+
+          # Create issue body using GitHub Actions recommended pattern
+          # Reference: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+          {
+            echo "## SPEC Metadata"
+            echo ""
+            echo "| Field | Value |"
+            echo "|-------|-------|"
+            echo "| **ID** | $spec_id |"
+            echo "| **Version** | $spec_version |"
+            echo "| **Status** | $spec_status |"
+            echo "| **Priority** | $spec_priority |"
+            echo ""
+            echo "## SPEC Document"
+            echo ""
+            echo "$spec_content"
+            echo ""
+            echo "---"
+            echo ""
+            echo "📎 **Branch**: \`feature/$spec_id\`"
+            echo "🔗 **PR**: #${{ github.event.pull_request.number }}"
+            echo "📝 **Auto-synced**: This issue is automatically synchronized from the SPEC document"
+          } > /tmp/issue_body.txt
+
+          echo "📋 Creating GitHub Issue..."
+          echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
+          echo "  Body file: /tmp/issue_body.txt"
+          wc -l /tmp/issue_body.txt
+
+          # Create issue with labels using body-file
+          issue_output=$(gh issue create \
+            --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
+            --body-file /tmp/issue_body.txt \
+            --label "spec" \
+            --label "planning" \
+            --label "$spec_priority" 2>&1)
+
+          echo "$issue_output" | tee /tmp/issue_output.txt
+
+          # Extract issue number from output
+          issue_num=$(echo "$issue_output" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+' | head -1)
+
+          if [ -z "$issue_num" ]; then
+            echo "⚠️  Could not extract issue number from output"
+            echo "Full output:"
+            cat /tmp/issue_output.txt
+            exit 1
+          fi
+
+          echo "issue_number=$issue_num" >> $GITHUB_OUTPUT
+          echo "✅ Created issue #$issue_num"
+
+      - name: Add PR comment
+        if: steps.create-issue.outputs.issue_number
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          issue_num="${{ steps.create-issue.outputs.issue_number }}"
+          spec_id="${{ steps.spec.outputs.spec_id }}"
+          spec_title="${{ steps.spec.outputs.spec_title }}"
+
+          # Create PR comment body using same pattern
+          {
+            echo "✅ **SPEC GitHub Issue Created**"
+            echo ""
+            echo "This SPEC has been synchronized to GitHub Issue."
+            echo ""
+            echo "📋 **Issue**: [#$issue_num - SPEC-$spec_id: $spec_title](../issues/$issue_num)"
+            echo "🔗 **SPEC File**: \`.moai/specs/SPEC-$spec_id/spec.md\`"
+            echo ""
+            echo "The issue will be automatically updated as you modify the SPEC document."
+          } > /tmp/pr_comment.txt
+
+          gh pr comment ${{ github.event.pull_request.number }} --body-file /tmp/pr_comment.txt
+          echo "✅ Added PR comment linking to issue #$issue_num"

moai_adk/templates/.moai/config.json

@@ -56,13 +56,13 @@
     "current_stage": "initialized"
   },
   "project": {
-    "created_at": "{{CREATION_TIMESTAMP}}",
+    "name": "{{PROJECT_NAME}}",
     "description": "{{PROJECT_DESCRIPTION}}",
-    "initialized": true,
-    "locale": "en",
     "mode": "{{PROJECT_MODE}}",
-    "name": "{{PROJECT_NAME}}",
-    "moai_adk_version": "{{MOAI_VERSION}}",
+    "locale": "{{CONVERSATION_LANGUAGE}}",
+    "language": "{{CODEBASE_LANGUAGE}}",
+    "created_at": "{{CREATION_TIMESTAMP}}",
+    "initialized": true,
     "optimized": false
   },
   "tags": {

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