moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/settings.json

@@ -1,23 +1,86 @@
 {
-  "env": {
-    "MOAI_RUNTIME": "python",
-    "MOAI_AUTO_ROUTING": "true",
-    "MOAI_PERFORMANCE_MONITORING": "true",
-    "PYTHON_ENV": "{{PROJECT_MODE}}"
-  },
+  "companyAnnouncements": [
+    "Start with a plan: Write down what you want to build first to avoid confusion (/alfred:1-plan)",
+    "✅ 5 promises: Test-first + Easy-to-read code + Clean organization + Secure + Trackable",
+    "Task list: Continuous progress tracking ensures nothing gets missed",
+    "Language separation: We communicate in your language, computers understand in English",
+    "Everything connected: Plan→Test→Code→Docs are all linked together",
+    "⚡ Parallel processing: Independent tasks can be handled simultaneously",
+    "Tools first: Find the right tools before starting any work",
+    "Step by step: What you want→Plan→Execute→Report results",
+    "Auto-generated lists: Planning automatically creates task lists",
+    "❓ Ask when confused: If something isn't clear, just ask right away",
+    "🧪 Automatic quality checks: Code automatically verified against 5 core principles",
+    "Multi-language support: Automatic validation for Python, JavaScript, and more",
+    "⚡ Never stops: Can continue even when tools are unavailable",
+    "Flexible approach: Choose between team collaboration or individual work as needed",
+    "🧹 Auto cleanup: Automatically removes unnecessary items when work is complete",
+    "⚡ Quick updates: New versions detected in 3 seconds, only fetch what's needed",
+    "On-demand loading: Only loads current tools to save memory",
+    "Complete history: All steps from planning to code are recorded for easy reference",
+    "Bug reporting: File bug reports to GitHub in 30 seconds",
+    "🩺 Health check: Use 'moai-adk doctor' to instantly check current status",
+    "Safe updates: Use 'moai-adk update' to safely add new features",
+    "🧹 When work is done: Use '/clear' to clean up conversation for the next task"
+  ],
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "uv run {{HOOK_PROJECT_DIR}}/.claude/hooks/alfred/session_start__show_project_info.py",
+            "type": "command",
+            "description": "Display project info and language configuration at session start"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "hooks": [
           {
-            "command": "uv run .claude/hooks/alfred/alfred_hooks.py PreToolUse",
-            "type": "command"
+            "command": "uv run {{HOOK_PROJECT_DIR}}/.claude/hooks/alfred/pre_tool__auto_checkpoint.py",
+            "type": "command",
+            "description": "Create automatic checkpoint before file modifications"
           }
         ],
         "matcher": "Edit|Write|MultiEdit"
       }
     ],
-    "PostToolUse": []
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "command": "uv run {{HOOK_PROJECT_DIR}}/.claude/hooks/alfred/user_prompt__jit_load_docs.py",
+            "type": "command",
+            "description": "Load documentation on-demand based on user intent"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "command": "uv run {{HOOK_PROJECT_DIR}}/.claude/hooks/alfred/session_end__cleanup.py",
+            "type": "command",
+            "description": "Clean up session state and temporary files"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "command": "uv run {{HOOK_PROJECT_DIR}}/.claude/hooks/alfred/post_tool__log_changes.py",
+            "type": "command",
+            "description": "Log file changes for audit and tracking"
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      }
+    ]
   },
   "permissions": {
     "defaultMode": "default",
@@ -35,7 +98,14 @@
       "WebSearch",
       "BashOutput",
       "KillShell",
-      "Bash(git:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git branch:*)",
+      "Bash(git show:*)",
+      "Bash(git remote:*)",
+      "Bash(git tag:*)",
+      "Bash(git config:*)",
       "Bash(rg:*)",
       "Bash(ls:*)",
       "Bash(echo:*)",
@@ -54,7 +124,6 @@
       "Bash(gh pr create:*)",
       "Bash(gh pr view:*)",
       "Bash(gh pr list:*)",
-      "Bash(gh pr merge:*)",
       "Bash(gh repo view:*)",
       "Bash(gh issue:*)",
       "Bash(mkdir:*)",
@@ -68,8 +137,15 @@
       "Bash(uniq:*)"
     ],
     "ask": [
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
       "Bash(git push:*)",
       "Bash(git merge:*)",
+      "Bash(git checkout:*)",
+      "Bash(git rebase:*)",
+      "Bash(git reset:*)",
+      "Bash(git stash:*)",
+      "Bash(git revert:*)",
       "Bash(gh pr merge:*)",
       "Bash(uv add:*)",
       "Bash(uv remove:*)",
@@ -98,7 +174,13 @@
       "Bash(mkfs:*)",
       "Bash(fdisk:*)",
       "Bash(reboot:*)",
-      "Bash(shutdown:*)"
+      "Bash(shutdown:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git rebase -i:*)"
     ]
-  }
-}
+  },
+  "spinnerTipsEnabled": true,
+  "outputStyle": "streaming"
+}

moai_adk/templates/.claude/skills/moai-alfred-agent-guide/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: moai-alfred-agent-guide
+description: "19-agent team structure, decision trees for agent selection, Haiku vs Sonnet model selection, and agent collaboration principles. Use when deciding which sub-agent to invoke, understanding team responsibilities, or learning multi-agent orchestration."
+allowed-tools: "Read, Glob, Grep"
+---
+
+## What It Does
+
+MoAI-ADK의 19개 Sub-agent 아키텍처, 어떤 agent를 선택할지 결정하는 트리, Haiku/Sonnet 모델 선택 기준을 정의합니다.
+
+## When to Use
+
+- ✅ 어떤 sub-agent를 invoke할지 불명확
+- ✅ Agent 책임 범위 학습
+- ✅ Haiku vs Sonnet 모델 선택 필요
+- ✅ Multi-agent 협업 패턴 이해
+
+## Agent Team at a Glance
+
+### 10 Core Sub-agents (Sonnet)
+- spec-builder: SPEC 작성
+- tdd-implementer: TDD 구현 (RED → GREEN → REFACTOR)
+- doc-syncer: 문서 동기화
+- implementation-planner: 구현 전략
+- debug-helper: 오류 분석
+- quality-gate: TRUST 5 검증
+- tag-agent: TAG 체인 검증
+- git-manager: Git 워크플로우
+- Explore: 코드베이스 탐색
+- Plan: 작업 계획
+
+### 4 Expert Agents (Sonnet - Proactively Triggered)
+- **backend-expert**: Backend 아키텍처, API 설계, 데이터베이스
+- **frontend-expert**: Frontend 아키텍처, 컴포넌트 설계, 상태 관리
+- **devops-expert**: DevOps 전략, 배포, 인프라
+- **ui-ux-expert**: UI/UX 설계, 접근성, 디자인 시스템 (Figma MCP)
+
+### 6 Specialist Agents (Haiku)
+- project-manager: 프로젝트 초기화
+- skill-factory: Skill 생성/최적화
+- cc-manager: Claude Code 설정
+- cc-hooks: Hook 시스템
+- cc-mcp-plugins: MCP 서버
+- trust-checker: TRUST 검증
+
+## Agent Selection Decision Tree
+
+```
+Task Type?
+├─ SPEC 작성/검증 → spec-builder
+├─ TDD 구현 → tdd-implementer
+├─ 문서 동기화 → doc-syncer
+├─ 구현 계획 → implementation-planner
+├─ 오류 분석 → debug-helper
+├─ 품질 검증 → quality-gate + Skill("moai-foundation-trust")
+├─ 코드베이스 탐색 → Explore
+├─ Git 워크플로우 → git-manager
+└─ 전체 프로젝트 계획 → Plan
+```
+
+## Model Selection
+
+- **Sonnet**: Complex reasoning (spec-builder, tdd-implementer, implementation-planner)
+- **Haiku**: Fast execution (project-manager, quality-gate, git-manager)
+
+---
+
+Learn more in `reference.md` for complete agent responsibilities, collaboration patterns, and advanced orchestration strategies.
+
+**Related Skills**: moai-alfred-rules, moai-alfred-practices

moai_adk/templates/.claude/skills/moai-alfred-agent-guide/examples.md

@@ -0,0 +1,62 @@
+# Agent Selection Examples
+
+## Example 1: New Feature Request
+
+**User**: "Add two-factor authentication"
+
+**Decision Tree**:
+```
+Task = Feature Implementation
+  ↓
+Create SPEC first? → YES
+Invoke: spec-builder
+  ↓
+Write Tests? → YES
+Invoke: tdd-implementer
+  ↓
+Need Code Review? → YES
+Invoke: quality-gate + Skill("moai-foundation-trust")
+  ↓
+Update Documentation? → YES
+Invoke: doc-syncer
+```
+
+**Result**: Proper agent sequence avoids rework
+
+---
+
+## Example 2: Bug Fix Triage
+
+**Error**: "TypeError: undefined is not a function"
+
+**Agent Sequence**:
+1. Invoke: debug-helper
+   - Analyze stack trace
+   - Identify root cause
+2. Invoke: tdd-implementer
+   - Write regression test
+   - Fix implementation
+3. Invoke: git-manager
+   - Commit with @TAG
+
+---
+
+## Example 3: Large Codebase Exploration
+
+**Task**: "How is authentication implemented?"
+
+✅ Correct:
+```
+Invoke: Explore(prompt="Find auth flow, entry points, models")
+Result: Clear architecture map
+```
+
+❌ Wrong:
+```
+Manual grep for 20+ files
+Result: Bloated context, still confused
+```
+
+---
+
+Learn more in `reference.md` for complete decision tree and multi-agent patterns.

moai_adk/templates/.claude/skills/moai-alfred-agent-guide/reference.md

@@ -0,0 +1,242 @@
+# 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).
+
+---
+
+## Expert Agents (Proactively Triggered by SPEC Keywords)
+
+| Expert Agent            | Model  | Specialty                                                                           | Trigger Keywords                                                                                   | Trigger Source      |
+| ----------------------- | ------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
+| **backend-expert** 🔧   | Sonnet | Backend architecture, API design, database schema, microservices, authentication    | 'backend', 'api', 'server', 'database', 'microservice', 'deployment', 'authentication'            | implementation-planner |
+| **frontend-expert** 💻  | Sonnet | Frontend architecture, component design, state management, UI/UX implementation     | 'frontend', 'ui', 'page', 'component', 'client-side', 'browser', 'web interface'                  | implementation-planner |
+| **devops-expert** 🚀    | Sonnet | DevOps strategy, deployment automation, containerization, CI/CD, cloud infrastructure | 'deployment', 'docker', 'kubernetes', 'ci/cd', 'pipeline', 'infrastructure', 'railway', 'vercel', 'aws' | implementation-planner |
+| **ui-ux-expert** 🎨     | Sonnet | UI/UX design, accessibility (WCAG 2.1 AA/AAA), design systems, Figma MCP, design-to-code | 'design', 'ux', 'ui', 'accessibility', 'a11y', 'user experience', 'wireframe', 'prototype', 'design system', 'figma', 'user research', 'persona', 'journey map' | implementation-planner |
+
+### How Expert Agents Work
+
+1. **Automatic Keyword Detection**: When `implementation-planner` analyzes a SPEC, it scans for expert trigger keywords
+2. **Proactive Delegation**: If keywords match, `implementation-planner` automatically invokes the relevant expert agent(s)
+3. **Expert Consultation**: Each expert provides domain-specific architecture guidance, technology recommendations, and risk analysis
+4. **Integration**: Expert feedback is integrated into the implementation plan and tagged with `@EXPERT:DOMAIN` for traceability
+
+### Example: Full-Stack Authentication SPEC
+
+```
+SPEC Keywords: 'api', 'authentication', 'design', 'accessibility'
+
+→ Trigger backend-expert (for API & auth architecture)
+→ Trigger ui-ux-expert (for login UI & accessibility)
+
+Result:
+@SPEC:AUTH-001 | @EXPERT:BACKEND | @EXPERT:UIUX
+
+Implementation Plan includes:
+- Backend: JWT token strategy, rate limiting, audit logging
+- UI/UX: Accessible login form (WCAG 2.1 AA), error messaging
+```
+
+---
+
+## 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-ask-user-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