moai-adk 0.4.7__tar.gz → 0.4.10__tar.gz

{moai_adk-0.4.7 → moai_adk-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.4.7
+Version: 0.4.10
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -60,15 +60,16 @@ If you're **new to MoAI-ADK**, start with "What is MoAI-ADK?".
 If you want to **get started quickly**, jump straight to "5-Minute Quick Start".
 If you've **already installed it and want to understand the concepts**, we recommend "5 Key Concepts".
 
-| Question | Jump To |
-| --- | --- |
-| First time here—what is it? | [What is MoAI-ADK?](#what-is-moai-adk) |
-| How do I get started? | [5-Minute Quick Start](#5-minute-quick-start) |
-| What's the basic flow? | [Core Workflow (0 → 3)](#core-workflow-0--3) |
-| What do Plan/Run/Sync commands do? | [Command Cheat Sheet](#command-cheat-sheet) |
-| What are SPEC, TDD, TAG? | [5 Key Concepts](#5-key-concepts) |
-| Tell me about agents/Skills | [Sub-agents & Skills Overview](#sub-agents--skills-overview) |
-| Want to dive deeper? | [Additional Resources](#additional-resources) |
+| Question                           | Jump To                                                      |
+| ---------------------------------- | ------------------------------------------------------------ |
+| First time here—what is it?        | [What is MoAI-ADK?](#what-is-moai-adk)                       |
+| How do I get started?              | [5-Minute Quick Start](#5-minute-quick-start)                |
+| What's the basic flow?             | [Core Workflow (0 → 3)](#core-workflow-0--3)                 |
+| What do Plan/Run/Sync commands do? | [Command Cheat Sheet](#command-cheat-sheet)                  |
+| What are SPEC, TDD, TAG?           | [5 Key Concepts](#5-key-concepts)                            |
+| Tell me about agents/Skills        | [Sub-agents & Skills Overview](#sub-agents--skills-overview) |
+| I want a 4-week hands-on project   | [Second Practice: Mini Kanban Board](#second-practice-mini-kanban-board) |
+| Want to dive deeper?               | [Additional Resources](#additional-resources)                |
 
 ---
 
@@ -113,7 +114,7 @@ A single `/alfred:3-sync` command **synchronizes** all code, tests, and document
 Every piece of code, test, and documentation gets a `@TAG:ID`. When requirements change later, one command—`rg "@SPEC:AUTH-001"`—**finds all related tests, implementations, and docs**. You gain confidence during refactoring.
 
 **5️⃣ Alfred Remembers Context**
-19 AI agents (1 Alfred SuperAgent + 10 Core Sub-agents + 6 Zero-project Specialists + 2 Built-in Agents) collaborate to **remember** your project's structure, decision rationale, and work history. No need to repeat the same questions.
+A team of AI agents collaborate to **remember** your project's structure, decision rationale, and work history. No need to repeat the same questions.
 
 ### MoAI-ADK's 3 Core Promises
 
@@ -136,14 +137,14 @@ One `/alfred:3-sync` command auto-updates all documentation. README, CHANGELOG,
 
 Modern AI-powered development faces various challenges. MoAI-ADK **systematically solves** all these problems:
 
-| Concern | Traditional Approach Problem | MoAI-ADK Solution |
-| --- | --- | --- |
-| "Can't trust AI code" | Implementation without tests, unclear verification | Enforces SPEC → TEST → CODE order, guarantees 85%+ coverage |
-| "Repeating same explanations" | Context loss, unrecorded project history | Alfred remembers everything, 19 AI team members collaborate |
-| "Hard to write prompts" | Don't know how to write good prompts | `/alfred` commands provide standardized prompts automatically |
-| "Documentation always outdated" | Forget to update docs after code changes | `/alfred:3-sync` auto-syncs with one command |
-| "Don't know what changed where" | Hard to search code, unclear intent | @TAG chain connects SPEC → TEST → CODE → DOC |
-| "Team onboarding takes forever" | New members can't grasp code context | Reading SPEC makes intent immediately clear |
+| Concern                         | Traditional Approach Problem                       | MoAI-ADK Solution                                             |
+| ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| "Can't trust AI code"           | Implementation without tests, unclear verification | Enforces SPEC → TEST → CODE order, guarantees 85%+ coverage   |
+| "Repeating same explanations"   | Context loss, unrecorded project history           | Alfred remembers everything, 19 AI team members collaborate   |
+| "Hard to write prompts"         | Don't know how to write good prompts               | `/alfred` commands provide standardized prompts automatically |
+| "Documentation always outdated" | Forget to update docs after code changes           | `/alfred:3-sync` auto-syncs with one command                  |
+| "Don't know what changed where" | Hard to search code, unclear intent                | @TAG chain connects SPEC → TEST → CODE → DOC                  |
+| "Team onboarding takes forever" | New members can't grasp code context               | Reading SPEC makes intent immediately clear                   |
 
 ### Benefits You Can Experience Right Now
 
@@ -189,7 +190,7 @@ uv tool install moai-adk
 
 # Verify installation
 moai-adk --version
-# Output: MoAI-ADK v0.4.6
+# Output: MoAI-ADK v0.4.10
 ```
 
 Once installed, you can use the `moai-adk` command anywhere.
@@ -218,9 +219,9 @@ my-project/
 │   ├── specs/               # SPEC files
 │   └── reports/             # Analysis reports
 ├── .claude/                 # Claude Code automation
-│   ├── agents/              # 19-member AI team
+│   ├── agents/              # AI team
 │   ├── commands/            # /alfred commands
-│   ├── skills/              # 56 Claude Skills
+│   ├── skills/              # Claude Skills
 │   └── settings.json
 ├── src/                     # Implementation code
 ├── tests/                   # Test code
@@ -247,7 +248,7 @@ This command performs:
 
 1. **Collect Project Info**: "Project name?", "Goals?", "Main language?"
 2. **Auto-detect Tech Stack**: Automatically recognizes Python/JavaScript/Go, etc.
-3. **Deploy Skill Packs**: Prepares necessary Skills from the 56 available
+3. **Deploy Skill Packs**: Prepares necessary Skills for your project
 4. **Generate Initial Report**: Project structure, suggested next steps
 
 ### Step 5: Write First SPEC (about 1 minute)
@@ -435,12 +436,12 @@ graph TD
 
 ## Command Cheat Sheet
 
-| Command | What it does | Key Outputs |
-| --- | --- | --- |
-| `/alfred:0-project` | Collect project description, create config/docs, recommend Skills | `.moai/config.json`, `.moai/project/*`, initial report |
-| `/alfred:1-plan <description>` | Analyze requirements, draft SPEC, write Plan Board | `.moai/specs/SPEC-*/spec.md`, plan/acceptance docs, feature branch |
-| `/alfred:2-run <SPEC-ID>` | Execute TDD, test/implement/refactor, verify quality | `tests/`, `src/` implementation, quality report, TAG connection |
-| `/alfred:3-sync` | Sync docs/README/CHANGELOG, organize TAG/PR status | `docs/`, `.moai/reports/sync-report.md`, Ready PR |
+| Command                        | What it does                                                      | Key Outputs                                                        |
+| ------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `/alfred:0-project`            | Collect project description, create config/docs, recommend Skills | `.moai/config.json`, `.moai/project/*`, initial report             |
+| `/alfred:1-plan <description>` | Analyze requirements, draft SPEC, write Plan Board                | `.moai/specs/SPEC-*/spec.md`, plan/acceptance docs, feature branch |
+| `/alfred:2-run <SPEC-ID>`      | Execute TDD, test/implement/refactor, verify quality              | `tests/`, `src/` implementation, quality report, TAG connection    |
+| `/alfred:3-sync`               | Sync docs/README/CHANGELOG, organize TAG/PR status                | `docs/`, `.moai/reports/sync-report.md`, Ready PR                  |
 
 > ❗ All commands maintain **Phase 0 (optional) → Phase 1 → Phase 2 → Phase 3** cycle structure. Alfred automatically reports execution status and next-step suggestions.
 
@@ -598,13 +599,14 @@ rg '@TAG:AUTH-001' -n
 - **Zero-project Specialists**: Project initialization, language detection, etc. (6)
 - **Built-in Agents**: General questions, codebase exploration (2)
 
-**56 Claude Skills**:
+**55 Claude Skills**:
 - **Foundation** (6): TRUST/TAG/SPEC/Git/EARS principles
 - **Essentials** (4): Debugging, performance, refactoring, code review
-- **Alfred** (11): Workflow automation
+- **Alfred** (7): Workflow automation
 - **Domain** (10): Backend, frontend, security, etc.
-- **Language** (24): Python, JavaScript, Go, Rust, etc.
+- **Language** (18): Python, JavaScript, Go, Rust, Java, Kotlin, Swift, Dart, C/C#, Ruby, PHP, SQL, Shell, and more
 - **Ops** (1): Claude Code session management
+- **Other** (2): Skill factory, Spec authoring
 
 **How?** `/alfred:*` commands automatically activate the right expert team.
 
@@ -958,135 +960,252 @@ Result:
 
 ## Sub-agents & Skills Overview
 
-Alfred works by combining **19 agents** (1 SuperAgent + 10 Core Sub-agents + 6 0-project Sub-agents + 2 Built-in) with **56 Claude Skills**.
+Alfred works by combining multiple specialized agents with Claude Skills.
 
 ### Core Sub-agents (Plan → Run → Sync)
 
-| Sub-agent | Model | Role |
-| --- | --- | --- |
-| project-manager 📋 | Sonnet | Project initialization, metadata interviews |
-| spec-builder 🏗️ | Sonnet | Plan board, EARS SPEC authoring |
-| code-builder 💎 | Sonnet | Performs complete TDD with `implementation-planner` + `tdd-implementer` |
-| doc-syncer 📖 | Haiku | Living Doc, README, CHANGELOG sync |
-| tag-agent 🏷️ | Haiku | TAG inventory, orphan detection |
-| git-manager 🚀 | Haiku | GitFlow, Draft/Ready, Auto Merge |
-| debug-helper 🔍 | Sonnet | Failure analysis, fix-forward strategy |
-| trust-checker ✅ | Haiku | TRUST 5 quality gate |
-| quality-gate 🛡️ | Haiku | Coverage change and release blocker review |
-| cc-manager 🛠️ | Sonnet | Claude Code session optimization, Skill deployment |
+| Sub-agent         | Model  | Role                                                                    |
+| ----------------- | ------ | ----------------------------------------------------------------------- |
+| project-manager 📋 | Sonnet | Project initialization, metadata interviews                             |
+| spec-builder 🏗️    | Sonnet | Plan board, EARS SPEC authoring                                         |
+| code-builder 💎    | Sonnet | Performs complete TDD with `implementation-planner` + `tdd-implementer` |
+| doc-syncer 📖      | Haiku  | Living Doc, README, CHANGELOG sync                                      |
+| tag-agent 🏷️       | Haiku  | TAG inventory, orphan detection                                         |
+| git-manager 🚀     | Haiku  | GitFlow, Draft/Ready, Auto Merge                                        |
+| debug-helper 🔍    | Sonnet | Failure analysis, fix-forward strategy                                  |
+| trust-checker ✅   | Haiku  | TRUST 5 quality gate                                                    |
+| quality-gate 🛡️    | Haiku  | Coverage change and release blocker review                              |
+| cc-manager 🛠️      | Sonnet | Claude Code session optimization, Skill deployment                      |
 
 ### Skills (Progressive Disclosure - v0.4 New!)
 
-Alfred organizes **56 Claude Skills** in a 4-tier architecture using **Progressive Disclosure** to load Just-In-Time only when needed. Each Skill is a production-grade guide of 1,000+ lines stored in `.claude/skills/` directory.
+Alfred organizes Claude Skills in a 4-tier architecture using **Progressive Disclosure** to load Just-In-Time only when needed. Each Skill is a production-grade guide stored in `.claude/skills/` directory.
 
-#### Foundation Tier (6)
+#### Foundation Tier
 Core skills containing fundamental TRUST/TAG/SPEC/Git/EARS/Language principles
 
-| Skill | Description |
-| --- | --- |
+| Skill                   | Description                                                                        |
+| ----------------------- | ---------------------------------------------------------------------------------- |
 | `moai-foundation-trust` | TRUST 5-principles (Test 85%+, Readable, Unified, Secured, Trackable) verification |
-| `moai-foundation-tags` | @TAG markers scan and inventory generation (CODE-FIRST principle) |
-| `moai-foundation-specs` | SPEC YAML frontmatter (7 required fields) and HISTORY section validation |
-| `moai-foundation-ears` | EARS (Easy Approach to Requirements Syntax) requirements writing guide |
-| `moai-foundation-git` | Git workflow automation (branching, TDD commits, PR management) |
-| `moai-foundation-langs` | Project language/framework auto-detection (package.json, pyproject.toml, etc.) |
+| `moai-foundation-tags`  | @TAG markers scan and inventory generation (CODE-FIRST principle)                  |
+| `moai-foundation-specs` | SPEC YAML frontmatter validation and HISTORY section management                   |
+| `moai-foundation-ears`  | EARS (Easy Approach to Requirements Syntax) requirements writing guide             |
+| `moai-foundation-git`   | Git workflow automation (branching, TDD commits, PR management)                    |
+| `moai-foundation-langs` | Project language/framework auto-detection (package.json, pyproject.toml, etc.)     |
 
-#### Essentials Tier (4)
+#### Essentials Tier
 Core tools needed for daily development work
 
-| Skill | Description |
-| --- | --- |
-| `moai-essentials-debug` | Stack trace analysis, error pattern detection, quick diagnosis support |
-| `moai-essentials-perf` | Performance profiling, bottleneck detection, tuning strategies |
-| `moai-essentials-refactor` | Refactoring guide, design patterns, code improvement strategies |
-| `moai-essentials-review` | Automated code review, SOLID principles, code smell detection |
+| Skill                      | Description                                                            |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `moai-essentials-debug`    | Stack trace analysis, error pattern detection, quick diagnosis support |
+| `moai-essentials-perf`     | Performance profiling, bottleneck detection, tuning strategies         |
+| `moai-essentials-refactor` | Refactoring guide, design patterns, code improvement strategies        |
+| `moai-essentials-review`   | Automated code review, SOLID principles, code smell detection          |
 
-#### Alfred Tier (11)
+#### Alfred Tier
 MoAI-ADK internal workflow orchestration skills
 
-| Skill | Description |
-| --- | --- |
-| `moai-alfred-code-reviewer` | Automated code review with language-specific best practices, SOLID principles, improvement suggestions |
-| `moai-alfred-debugger-pro` | Stack trace analysis, error pattern detection, complex runtime error interpretation |
-| `moai-alfred-ears-authoring` | EARS syntax validation, 5 requirement pattern guide |
-| `moai-alfred-git-workflow` | MoAI-ADK conventions (feature branch, TDD commits, Draft PR) automation |
-| `moai-alfred-language-detection` | Project language/runtime detection, default test tool recommendations |
-| `moai-alfred-performance-optimizer` | Performance profiling, bottleneck detection, language-specific optimization |
-| `moai-alfred-refactoring-coach` | Refactoring guide, design patterns, step-by-step improvement plan |
-| `moai-alfred-spec-metadata-validation` | SPEC YAML frontmatter (7 fields) and HISTORY section consistency validation |
-| `moai-alfred-tag-scanning` | Complete @TAG marker scan and inventory generation (CODE-FIRST principle) |
-| `moai-alfred-trust-validation` | TRUST 5-principles compliance verification (Test 85%+, constraints, security, trackability) |
-| `moai-alfred-tui-survey` | Claude Code Tools AskUserQuestion TUI menu standardization |
-
-#### Domain Tier (10)
+| Skill                                  | Description                                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `moai-alfred-ears-authoring`           | EARS syntax validation and requirement pattern guidance                                                |
+| `moai-alfred-git-workflow`             | MoAI-ADK conventions (feature branch, TDD commits, Draft PR) automation                                |
+| `moai-alfred-language-detection`       | Project language/runtime detection and test tool recommendations                                       |
+| `moai-alfred-spec-metadata-validation` | SPEC YAML frontmatter and HISTORY section consistency validation                                       |
+| `moai-alfred-tag-scanning`             | Complete @TAG marker scan and inventory generation (CODE-FIRST principle)                              |
+| `moai-alfred-trust-validation`         | TRUST 5-principles compliance verification                                                             |
+| `moai-alfred-interactive-questions`    | Claude Code Tools AskUserQuestion TUI menu standardization                                             |
+
+#### Domain Tier
 Specialized domain expertise
 
-| Skill | Description |
-| --- | --- |
-| `moai-domain-backend` | Backend architecture, API design, scaling guide |
-| `moai-domain-cli-tool` | CLI tool development, argument parsing, POSIX compliance, user-friendly help messages |
-| `moai-domain-data-science` | Data analysis, visualization, statistical modeling, reproducible research workflows |
-| `moai-domain-database` | Database design, schema optimization, indexing strategies, migration management |
-| `moai-domain-devops` | CI/CD pipelines, Docker containerization, Kubernetes orchestration, IaC |
-| `moai-domain-frontend` | React/Vue/Angular development, state management, performance optimization, accessibility |
-| `moai-domain-ml` | Machine learning model training, evaluation, deployment, MLOps workflows |
-| `moai-domain-mobile-app` | Flutter/React Native development, state management, native integration |
-| `moai-domain-security` | OWASP Top 10, static analysis (SAST), dependency security, secrets management |
-| `moai-domain-web-api` | REST API, GraphQL design patterns, authentication, versioning, OpenAPI documentation |
-
-#### Language Tier (24)
+| Skill                      | Description                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `moai-domain-backend`      | Backend architecture, API design, scaling guide                                          |
+| `moai-domain-cli-tool`     | CLI tool development, argument parsing, POSIX compliance, user-friendly help messages    |
+| `moai-domain-data-science` | Data analysis, visualization, statistical modeling, reproducible research workflows      |
+| `moai-domain-database`     | Database design, schema optimization, indexing strategies, migration management          |
+| `moai-domain-devops`       | CI/CD pipelines, Docker containerization, Kubernetes orchestration, IaC                  |
+| `moai-domain-frontend`     | React/Vue/Angular development, state management, performance optimization, accessibility |
+| `moai-domain-ml`           | Machine learning model training, evaluation, deployment, MLOps workflows                 |
+| `moai-domain-mobile-app`   | Flutter/React Native development, state management, native integration                   |
+| `moai-domain-security`     | OWASP Top 10, static analysis (SAST), dependency security, secrets management            |
+| `moai-domain-web-api`      | REST API, GraphQL design patterns, authentication, versioning, OpenAPI documentation     |
+
+#### Language Tier
 Programming language-specific best practices
 
-| Skill | Description |
-| --- | --- |
-| `moai-lang-python` | pytest, mypy, ruff, black, uv package management |
-| `moai-lang-typescript` | Vitest, Biome, strict typing, npm/pnpm |
-| `moai-lang-javascript` | Jest, ESLint, Prettier, npm package management |
-| `moai-lang-go` | go test, golint, gofmt, standard library |
-| `moai-lang-rust` | cargo test, clippy, rustfmt, ownership/borrow checker |
-| `moai-lang-java` | JUnit, Maven/Gradle, Checkstyle, Spring Boot patterns |
-| `moai-lang-kotlin` | JUnit, Gradle, ktlint, coroutines, extension functions |
-| `moai-lang-swift` | XCTest, SwiftLint, iOS/macOS development patterns |
-| `moai-lang-dart` | flutter test, dart analyze, Flutter widget patterns |
-| `moai-lang-csharp` | xUnit, .NET tooling, LINQ, async/await patterns |
-| `moai-lang-cpp` | Google Test, clang-format, modern C++ (C++17/20) |
-| `moai-lang-c` | Unity test framework, cppcheck, Make build system |
-| `moai-lang-scala` | ScalaTest, sbt, functional programming patterns |
-| `moai-lang-ruby` | RSpec, RuboCop, Bundler, Rails patterns |
-| `moai-lang-php` | PHPUnit, Composer, PSR standards |
-| `moai-lang-sql` | Test frameworks, query optimization, migration management |
-| `moai-lang-shell` | bats, shellcheck, POSIX compliance |
-| `moai-lang-haskell` | HUnit, Stack/Cabal, pure functional programming |
-| `moai-lang-elixir` | ExUnit, Mix, OTP patterns |
-| `moai-lang-clojure` | clojure.test, Leiningen, immutable data structures |
-| `moai-lang-lua` | busted, luacheck, embedded scripting patterns |
-| `moai-lang-julia` | Test stdlib, Pkg manager, scientific computing patterns |
-| `moai-lang-r` | testthat, lintr, data analysis patterns |
-| `moai-lang-kotlin` | JUnit, Gradle, ktlint, coroutines, extension functions |
-
-#### Claude Code Ops (1)
+| Skill                  | Description                                               |
+| ---------------------- | --------------------------------------------------------- |
+| `moai-lang-python`     | pytest, mypy, ruff, black, uv package management          |
+| `moai-lang-typescript` | Vitest, Biome, strict typing, npm/pnpm                    |
+| `moai-lang-javascript` | Jest, ESLint, Prettier, npm package management            |
+| `moai-lang-go`         | go test, golint, gofmt, standard library                  |
+| `moai-lang-rust`       | cargo test, clippy, rustfmt, ownership/borrow checker     |
+| `moai-lang-java`       | JUnit, Maven/Gradle, Checkstyle, Spring Boot patterns     |
+| `moai-lang-kotlin`     | JUnit, Gradle, ktlint, coroutines, extension functions    |
+| `moai-lang-swift`      | XCTest, SwiftLint, iOS/macOS development patterns         |
+| `moai-lang-dart`       | flutter test, dart analyze, Flutter widget patterns       |
+| `moai-lang-csharp`     | xUnit, .NET tooling, LINQ, async/await patterns           |
+| `moai-lang-cpp`        | Google Test, clang-format, modern C++ (C++17/20)          |
+| `moai-lang-c`          | Unity test framework, cppcheck, Make build system         |
+| `moai-lang-scala`      | ScalaTest, sbt, functional programming patterns           |
+| `moai-lang-ruby`       | RSpec, RuboCop, Bundler, Rails patterns                   |
+| `moai-lang-php`        | PHPUnit, Composer, PSR standards                          |
+| `moai-lang-sql`        | Test frameworks, query optimization, migration management |
+| `moai-lang-shell`      | bats, shellcheck, POSIX compliance                        |
+| `moai-lang-r`          | testthat, lintr, data analysis patterns                   |
+
+#### Claude Code Ops
 Claude Code session management
 
-| Skill | Description |
-| --- | --- |
+| Skill              | Description                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------- |
 | `moai-claude-code` | Claude Code agents, commands, skills, plugins, settings scaffolding and monitoring |
 
-> **v0.4.6 New Feature**: 56 Claude Skills organized in 4-tier architecture (100% complete in v0.4.6). Each Skill loads via Progressive Disclosure only when needed to minimize context cost. Organized in Foundation → Essentials → Alfred → Domain/Language/Ops tiers, with all skills including 1,000+ lines of official documentation and 300+ executable TDD examples.
+> **v0.4.6 New Feature**: Claude Skills organized in 4-tier architecture (100% complete in v0.4.6). Each Skill loads via Progressive Disclosure only when needed to minimize context cost. Organized in Foundation → Essentials → Alfred → Domain/Language/Ops tiers, with all skills including production-grade documentation and executable TDD examples.
 
 ---
 
 ## AI Model Selection Guide
 
-| Scenario | Default Model | Why |
-| --- | --- | --- |
+| Scenario                                             | Default Model         | Why                                             |
+| ---------------------------------------------------- | --------------------- | ----------------------------------------------- |
 | Specifications, design, refactoring, problem solving | **Claude 4.5 Sonnet** | Strong in deep reasoning and structured writing |
-| Document sync, TAG checks, Git automation | **Claude 4.5 Haiku** | Strong in rapid iteration, string processing |
+| Document sync, TAG checks, Git automation            | **Claude 4.5 Haiku**  | Strong in rapid iteration, string processing    |
 
 - Start with Haiku for patterned tasks; switch to Sonnet when complex judgment is needed.
 - If you manually change models, noting "why switched" in logs helps collaboration.
 
 ---
 
+## Claude Code Hooks Guide
+
+MoAI-ADK provides 4 main **Claude Code Hooks** that seamlessly integrate with your development workflow. These hooks enable automatic checkpoints, JIT context loading, and session monitoring—all happening transparently in the background.
+
+### What Are Hooks?
+
+Hooks are **event-driven** scripts that trigger automatically at specific points in your Claude Code session. Think of them as safety guardrails and productivity boosters that work behind the scenes without interrupting your flow.
+
+### Installed Hooks
+
+#### 1. SessionStart (Session Initialization)
+
+**Triggers**: When you start a Claude Code session in your project
+**Purpose**: Display project status at a glance
+
+**What You See**:
+```
+🚀 MoAI-ADK Session Started
+   Language: Python
+   Branch: develop
+   Changes: 2 files
+   SPEC Progress: 12/25 (48%)
+```
+
+**Why It Matters**: Instantly understand your project's current state without running multiple commands.
+
+#### 2. PreToolUse (Before Tool Execution)
+
+**Triggers**: Before executing file edits, Bash commands, or MultiEdit operations
+**Purpose**: Detect risky operations and automatically create safety checkpoints
+
+**Protection Against**:
+- `rm -rf` (file deletion)
+- `git merge`, `git reset --hard` (Git dangerous operations)
+- Editing critical files (`CLAUDE.md`, `config.json`)
+- Mass edits (10+ files at once via MultiEdit)
+
+**What You See**:
+```
+🛡️ Checkpoint created: before-delete-20251023-143000
+   Operation: delete
+```
+
+**Why It Matters**: Prevents data loss from mistakes. You can always restore from the checkpoint if something goes wrong.
+
+#### 3. UserPromptSubmit (Prompt Input)
+
+**Triggers**: When you submit a prompt to Claude
+**Purpose**: JIT (Just-In-Time) context loading—automatically add relevant files
+
+**How It Works**:
+- You type: "Fix AUTH bug"
+- Hook scans for AUTH-related files
+- Auto-loads: SPEC, tests, implementation, docs related to AUTH
+- Claude receives full context without you manually specifying files
+
+**Why It Matters**: Saves time and ensures Claude has all the relevant context for your request.
+
+#### 4. SessionEnd (Session Cleanup)
+
+**Triggers**: When you close your Claude Code session
+**Purpose**: Cleanup tasks and state preservation
+
+**Why It Matters**: Ensures clean session transitions and proper state management.
+
+### Technical Details
+
+- **Location**: `.claude/hooks/alfred/`
+- **Environment Variable**: `$CLAUDE_PROJECT_DIR` (dynamically references project root)
+- **Performance**: Each hook executes in <100ms
+- **Logging**: Errors output to stderr (stdout reserved for JSON payloads)
+
+### How to Disable Hooks
+
+If you need to temporarily disable hooks, edit `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [],     // Disabled
+    "PreToolUse": [...]     // Still active
+  }
+}
+```
+
+### Troubleshooting
+
+**Problem: Hook doesn't execute**
+- ✅ Verify `.claude/settings.json` is properly configured
+- ✅ Check `uv` is installed: `which uv`
+- ✅ Ensure hook script has execute permissions: `chmod +x .claude/hooks/alfred/alfred_hooks.py`
+
+**Problem: Performance degradation**
+- ✅ Check if any hook exceeds 100ms execution time
+- ✅ Disable unnecessary hooks
+- ✅ Review error messages in stderr output
+
+**Problem: Too many checkpoints created**
+- ✅ Review PreToolUse trigger conditions
+- ✅ Adjust detection thresholds in `core/checkpoint.py` if needed
+
+### Installed Hooks (5 total)
+
+| Hook | Status | Feature |
+|------|--------|---------|
+| **SessionStart** | ✅ Active | Project status summary (language, Git, SPEC progress, checkpoints) |
+| **PreToolUse** | ✅ Active | Risk detection + auto checkpoint (critical-delete, delete, merge, script) |
+| **UserPromptSubmit** | ✅ Active | JIT context loading (auto-load related SPEC, tests, code, docs) |
+| **PostToolUse** | ✅ Active | Auto-run tests after code changes (9 languages: Python, TS, JS, Go, Rust, Java, Kotlin, Swift, Dart) |
+| **SessionEnd** | ✅ Active | Session cleanup and state saving |
+
+### Future Enhancements
+
+- **Notification**: Important event alerts (logging, notifications)
+- **Stop/SubagentStop**: Cleanup when agents terminate
+- Advanced security: `dd` commands, supply chain checks
+
+### Learn More
+
+- Comprehensive analysis: `.moai/reports/hooks-analysis-and-implementation.md`
+- PostToolUse implementation: `.moai/reports/phase3-posttool-implementation-complete.md`
+- Security enhancements: `.moai/reports/security-enhancement-critical-delete.md`
+- Hook implementation: `.claude/hooks/alfred/`
+- Hook tests: `tests/hooks/`
+
+---
+
 ## Frequently Asked Questions (FAQ)
 
 - **Q. Can I install on an existing project?**
@@ -1102,40 +1221,310 @@ Claude Code session management
 
 ## v0.4 Series Updates (New!)
 
-| Version | Key Features | Date |
-| --- | --- | --- |
-| **v0.4.6** | 🎉 Complete Skills v2.0 (56/56 100%) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
-| **v0.4.5** | ✅ CI/CD fixes + Multi-language README + Deployment cleanup | 2025-10-22 |
-| **v0.4.4** | Korean language support | 2025-10-21 |
-| **v0.4.3** | Interactive question tool (TUI menu) | 2025-10-21 |
-| **v0.4.1** | Skills localization | 2025-10-21 |
-| **v0.4.0** | **56 Claude Skills** + 19-member AI team + 4-stage workflow | 2025-10-21 |
+| Version    | Key Features                                                                         | Date       |
+| ---------- | ------------------------------------------------------------------------------------ | ---------- |
+| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config | 2025-10-23 |
+| **v0.4.9** | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)        | 2025-10-23 |
+| **v0.4.8** | 🚀 Release automation + PyPI deployment + Skills refinement                          | 2025-10-23 |
+| **v0.4.7** | 📖 Korean language optimization + SPEC-First principle documentation                 | 2025-10-22 |
+| **v0.4.6** | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
+| **v0.4.5** | ✅ CI/CD fixes + Multi-language README + Deployment cleanup                           | 2025-10-22 |
 
-> 📦 **Install Now**: `pip install moai-adk==0.4.6` or `uv tool install moai-adk==0.4.6`
+> 📦 **Install Now**: `pip install moai-adk==0.4.10` or `uv tool install moai-adk==0.4.10`
+
+---
+
+##
+
+## Second Practice: Mini Kanban Board
+
+This section goes beyond the first Todo API example and outlines a full 4-week full‑stack project.
+
+Let’s build a Mini Kanban Board web application designed to help you master MoAI‑ADK end‑to‑end. This project lets you experience every step of SPEC‑First TDD.
+
+### Project Overview
+
+- Backend: FastAPI + Pydantic v2 + uv + WebSocket (Python)
+- Frontend: React 19 + TypeScript 5.9 + Vite + Zustand + TanStack Query
+- Real-time: Multi‑client sync over WebSocket
+- Storage: Local filesystem (.moai/specs/)
+- DevOps: Docker Compose + GitHub Actions CI/CD + Playwright E2E
+
+### 4‑Week Timeline
+
+```mermaid
+gantt
+    title Mini Kanban Board — 4‑week plan
+    dateFormat YYYY-MM-DD
+
+    section Phase 1: Backend Basics
+    CH07: Define SPEC-001~004           :active, ch07-spec, 2025-11-03, 1d
+    CH07: Implement SpecScanner (TDD)   :active, ch07-impl, 2025-11-04, 1d
+
+    section Phase 2: Backend Advanced
+    CH08: Implement REST API            :active, ch08-api, 2025-11-05, 1d
+    CH08: WebSocket + File Watch        :active, ch08-ws, 2025-11-06, 1d
+
+    section Phase 3: Frontend Basics
+    CH09: React init + SPEC-009~012     :active, ch09-spec, 2025-11-10, 1d
+    CH09: Kanban Board (TDD)            :active, ch09-impl, 2025-11-11, 1d
+
+    section Phase 4: Advanced + Deploy
+    CH10: E2E + CI/CD                   :active, ch10-e2e, 2025-11-12, 1d
+    CH10: Docker Compose + Optimize     :active, ch10-deploy, 2025-11-13, 1d
+```
+
+### 16‑SPEC Roadmap
+
+| Phase | SPEC ID | Title | Stack | Est. | Status |
+|------|---------|-------|-------|------|--------|
+| Backend Basics | SPEC-001 | SPEC file scanner | FastAPI + pathlib + YAML | 1h | 📋 |
+|  | SPEC-002 | YAML metadata parser | Pydantic v2 validation | 1h | 📋 |
+|  | SPEC-003 | GET /api/specs (list) | FastAPI router | 0.5h | 📋 |
+|  | SPEC-004 | GET /api/specs/{id} (detail) | FastAPI router | 0.5h | 📋 |
+| Backend Advanced | SPEC-005 | PATCH /api/specs/{id}/status | FastAPI + update | 1h | 📋 |
+|  | SPEC-006 | GET /api/specs/summary | Aggregation | 0.5h | 📋 |
+|  | SPEC-007 | File watcher | watchdog + async | 1h | 📋 |
+|  | SPEC-008 | WebSocket events | FastAPI WebSocket | 1.5h | 📋 |
+| Frontend Basics | SPEC-009 | Kanban layout | React + CSS Grid | 1.5h | 📋 |
+|  | SPEC-010 | SPEC card component | React + TypeScript | 1h | 📋 |
+|  | SPEC-011 | TanStack Query integration | useQuery + useMutation | 1.5h | 📋 |
+|  | SPEC-012 | Drag & Drop | React Beautiful DnD | 1.5h | 📋 |
+| Advanced + Deploy | SPEC-013 | E2E automated tests | Playwright | 1.5h | 📋 |
+|  | SPEC-014 | GitHub Actions CI/CD | Test + Release | 1h | 📋 |
+|  | SPEC-015 | Docker Compose deploy | Multi‑container | 1h | 📋 |
+|  | SPEC-016 | Performance + extensions | Caching + WS tuning | 1.5h | 📋 |
+|  |  | Overall |  | 20h |  |
+
+### System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                Mini Kanban Board — Architecture              │
+└─────────────────────────────────────────────────────────────┘
+
+┌──────────────────────┐         ┌────────────────────────┐
+│   📱 Frontend        │         │   🖥️ Backend Server    │
+│  (React 19 + Vite)   │◄───────►│ (FastAPI + Pydantic)   │
+│                      │  REST   │                        │
+│ ┌──────────────────┐ │ API +   │ ┌──────────────────┐   │
+│ │ DashboardHeader  │ │WebSocket│ │ GET /api/specs   │   │
+│ ├──────────────────┤ │         │ ├──────────────────┤   │
+│ │ KanbanBoard      │ │         │ │ PATCH /api/specs/{id}││
+│ │ ┌──────────────┐ │ │         │ │ /status          │   │
+│ │ │ Column: Draft│ │ │         │ ├──────────────────┤   │
+│ │ │ Column: Active││ │         │ │ WebSocket        │   │
+│ │ │ Column: Done │ │ │         │ │ /ws              │   │
+│ │ └──────────────┘ │ │         │ │                  │   │
+│ ├──────────────────┤ │         │ ├──────────────────┤   │
+│ │ SpecCard (DnD)   │ │         │ │ SpecScanner      │   │
+│ ├──────────────────┤ │         │ │ (.moai/specs/)   │   │
+│ │ SearchBar        │ │         │ ├──────────────────┤   │
+│ └──────────────────┘ │         │ │ YAML Parser      │   │
+│                      │         │ │ (Pydantic v2)    │   │
+│ Zustand Store:       │         │ └──────────────────┘   │
+│ • filterStore        │         │                        │
+│ • uiStore            │         │ File System:           │
+│                      │         │ .moai/specs/           │
+│ TanStack Query:      │         │ SPEC-001/              │
+│ • useQuery           │         │ SPEC-002/              │
+│ • useMutation        │         │ ...                    │
+└──────────────────────┘         └────────────────────────┘
+         │                                    │
+         │            WebSocket               │
+         └────────────────────────────────────┘
+              (Real-time Sync)
+```
+
+### Phase Details
+
+#### Phase 1: Backend Basics (SPEC-001~004)
+
+Goal: Build the core data scanning service with FastAPI + Pydantic v2 + uv
+
+```bash
+# 1) Initialize project
+/alfred:0-project
+# → creates .moai/, backend/, frontend/
+# → configures .moai/config.json
+
+# 2) Write SPECs (SPEC-001~004)
+/alfred:1-plan
+# → SPEC-001: SPEC file scanner
+# → SPEC-002: YAML metadata parser
+# → SPEC-003: GET /api/specs endpoint
+# → SPEC-004: GET /api/specs/{id} endpoint
+
+# 3) TDD (RED → GREEN → REFACTOR)
+/alfred:2-run SPEC-001
+/alfred:2-run SPEC-002
+/alfred:2-run SPEC-003
+/alfred:2-run SPEC-004
+```
+
+Key Concepts:
+- FastAPI project structure
+- Pydantic v2 validation
+- YAML front matter parsing
+- Dependency Injection
+- First TDD cycle completed
+
+#### Phase 2: Backend Advanced (SPEC-005~008)
+
+Goal: Implement file watching and WebSocket real-time events
+
+```bash
+# REST endpoints
+/alfred:2-run SPEC-005  # PATCH /api/specs/{id}/status
+/alfred:2-run SPEC-006  # GET /api/specs/summary
+
+# WebSocket + File Watcher
+/alfred:2-run SPEC-007  # File watching (watchdog)
+/alfred:2-run SPEC-008  # WebSocket broadcast
+
+# TRUST 5 verification
+/alfred:3-sync          # verify all principles
+```
+
+Key Concepts:
+- File system monitoring (watchdog)
+- FastAPI WebSocket endpoint
+- Async event broadcast
+- Automated TRUST 5 verification
+
+#### Phase 3: Frontend Basics (SPEC-009~012)
+
+Goal: Build Kanban UI with React 19 + TypeScript + Vite
+
+```bash
+# Initialize React + Vite
+cd frontend
+npm create vite@latest . -- --template react-ts
+
+# TanStack Query + Zustand
+npm install @tanstack/react-query zustand
+
+# SPECs
+/alfred:1-plan SPEC-009  # layout
+/alfred:1-plan SPEC-010  # card component
+/alfred:1-plan SPEC-011  # TanStack Query integration
+/alfred:1-plan SPEC-012  # drag & drop
+
+# TDD
+/alfred:2-run SPEC-009
+/alfred:2-run SPEC-010
+/alfred:2-run SPEC-011
+/alfred:2-run SPEC-012
+```
+
+Key Concepts:
+- React 19 Hooks (useState, useEffect, useContext)
+- TypeScript 5.9 strict typing
+- TanStack Query (useQuery, useMutation)
+- Zustand state management
+- React Beautiful DnD drag & drop
+
+#### Phase 4: Advanced + Deploy (SPEC-013~016)
+
+Goal: E2E tests, CI/CD, Docker deployment, performance optimization
+
+```bash
+# E2E tests (Playwright)
+/alfred:2-run SPEC-013
+
+# GitHub Actions CI/CD
+/alfred:2-run SPEC-014
+
+# Docker Compose deploy
+/alfred:2-run SPEC-015
+
+# Performance optimization
+/alfred:2-run SPEC-016
+```
+
+Key Concepts:
+- Playwright E2E automation
+- GitHub Actions workflows
+- Docker multi-stage builds
+- Production performance tuning
+
+### Quick Start Guide
+
+#### Step 1: Initialize project
+
+```bash
+# Install MoAI-ADK
+pip install moai-adk==0.4.6
+
+# Create project
+mkdir mini-kanban-board && cd mini-kanban-board
+git init
+
+# Initialize with Alfred
+/alfred:0-project
+```
+
+#### Step 2: Write SPECs
+
+```bash
+# Start planning
+/alfred:1-plan
+
+# Answer prompts:
+# - Project name: Mini Kanban Board
+# - Tech stack: FastAPI + React 19
+# - Duration: 4-week practice project
+```
+
+#### Step 3: Start TDD
+
+```bash
+# Phase 1 (Backend basics)
+/alfred:2-run SPEC-001  # first TDD cycle
+
+# Phase 2 (Backend advanced)
+/alfred:2-run SPEC-005
+/alfred:2-run SPEC-006
+/alfred:2-run SPEC-007
+/alfred:2-run SPEC-008
+
+# Phase 3 (Frontend basics)
+cd frontend
+/alfred:2-run SPEC-009
+/alfred:2-run SPEC-010
+/alfred:2-run SPEC-011
+/alfred:2-run SPEC-012
+
+# Phase 4 (Advanced + deploy)
+/alfred:2-run SPEC-013
+/alfred:2-run SPEC-014
+/alfred:2-run SPEC-015
+/alfred:2-run SPEC-016
+```
 
 ---
 
 ## Additional Resources
 
-| Purpose | Resource |
-| --- | --- |
-| Skills detailed structure | `.claude/skills/` directory (56 Skills) |
-| Sub-agent details | `.claude/agents/alfred/` directory |
-| Workflow guide | `.claude/commands/alfred/` (0-3 commands) |
-| Development guidelines | `.moai/memory/development-guide.md`, `.moai/memory/spec-metadata.md` |
-| Release notes | GitHub Releases: https://github.com/modu-ai/moai-adk/releases |
+| Purpose                   | Resource                                                             |
+| ------------------------- | -------------------------------------------------------------------- |
+| Skills detailed structure | `.claude/skills/` directory (56 Skills)                              |
+| Sub-agent details         | `.claude/agents/alfred/` directory                                   |
+| Workflow guide            | `.claude/commands/alfred/` (0-3 commands)                            |
+| Development guidelines    | `.moai/memory/development-guide.md`, `.moai/memory/spec-metadata.md` |
+| Release notes             | GitHub Releases: https://github.com/modu-ai/moai-adk/releases        |
 
 ---
 
 ## Community & Support
 
-| Channel | Link |
-| --- | --- |
-| **GitHub Repository** | https://github.com/modu-ai/moai-adk |
-| **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues |
-| **PyPI Package** | https://pypi.org/project/moai-adk/ (Latest: v0.4.6) |
-| **Latest Release** | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.6 |
-| **Documentation** | See `.moai/`, `.claude/`, `docs/` within project |
+| Channel                  | Link                                                    |
+| ------------------------ | ------------------------------------------------------- |
+| **GitHub Repository**    | https://github.com/modu-ai/moai-adk                     |
+| **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues              |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.6)     |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.6 |
+| **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project        |
 
 ---
 
@@ -1155,8 +1544,11 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 
 ---
 
-**MoAI-ADK v0.4.6** — SPEC-First TDD with AI SuperAgent & Complete Skills v2.0
+**MoAI-ADK v0.4.10** — SPEC-First TDD with AI SuperAgent & Complete Skills v2.0
 - 📦 PyPI: https://pypi.org/project/moai-adk/
 - 🏠 GitHub: https://github.com/modu-ai/moai-adk
 - 📝 License: MIT
-- ⭐ Skills: 56/56 Complete (100% Production-Ready)
+- ⭐ Skills: 55+ Production-Ready Guides
+- ✅ Tests: 468/468 Passing (86% coverage)
+
+---