moai-adk 0.8.2__tar.gz → 0.9.0__tar.gz

{moai_adk-0.8.2 → moai_adk-0.9.0}/.gitignore

@@ -68,7 +68,18 @@ logs/
 *.tmp
 *.temp
 
+
+
+
 .claudeignore
 
 # Project Plans (internal tracking, not versioned)
 CURSOR_INTEGRATION_PLAN.md
+
+
+# MoAI internal directories (not versioned)
+.moai/analysis/
+.moai/reports/
+.moai/scripts/
+.moai/cache/
+

{moai_adk-0.8.2 → moai_adk-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.8.2
+Version: 0.9.0
 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
@@ -255,7 +255,7 @@ my-project/
 │   │       ├── 1-plan.md           # SPEC authoring
 │   │       ├── 2-run.md            # TDD implementation
 │   │       └── 3-sync.md           # Documentation sync
-│   ├── skills/                     # 58 Claude Skills
+│   ├── skills/                     # 55+ Claude Skills
 │   │   ├── moai-foundation-*       # 6 Foundation tier
 │   │   ├── moai-essentials-*       # 4 Essentials tier
 │   │   ├── moai-alfred-*           # 7 Alfred tier
@@ -388,30 +388,70 @@ cat README.md
 
 MoAI-ADK's AI coordination is powered by **Alfred**, the MoAI SuperAgent. Alfred's behavior and decision-making are guided by a set of **internal configuration documents** in the `.claude/` directory.
 
-### 4-Document Structure
+### 4-Document Structure (Progressive Disclosure Pattern)
 
-When you run MoAI-ADK, Alfred loads configuration from **4 coordinated documents** (stored in your `.claude/` directory):
+When you run MoAI-ADK, Alfred loads configuration from **4 coordinated documents** (stored in your `.claude/` directory). This layered approach follows **Progressive Disclosure** — each document adds context only when needed:
 
-| Document                   | Size  | Purpose                                                                                                          | When Alfred Reads It                                          |
-| -------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| **CLAUDE.md**              | ~7kb  | Alfred's identity, core directives, project metadata                                                             | At session start (bootstrap)                                  |
-| **CLAUDE-AGENTS-GUIDE.md** | ~14kb | Sub-agent roster (19 members), Skills distribution (55 packs), team structure                                    | When selecting which agent to invoke                          |
-| **CLAUDE-RULES.md**        | ~17kb | Decision-making rules (Skill invocation, Interactive Questions, TAG validation), commit templates, TRUST 5 gates | During each decision point (e.g., when to ask user questions) |
-| **CLAUDE-PRACTICES.md**    | ~8kb  | Practical workflows, context engineering (JIT retrieval), on-demand agent patterns, real examples                | During implementation phase                                   |
+#### Layer 1: Bootstrap (Always Loaded)
+
+| Document | Size | Purpose | Single Responsibility |
+|----------|------|---------|----------------------|
+| **CLAUDE.md** | ~7kb | Alfred's identity, directives, project metadata, language settings | **Project-specific guidance** (your team's working playbook) |
+
+#### Layers 2-4: Just-In-Time (JIT) Loading
+
+| Document | Size | Purpose | Triggered When |
+|----------|------|---------|----------------|
+| **CLAUDE-AGENTS-GUIDE.md** | ~14kb | Sub-agent roster (19 members), Skills map (55 packs), selection criteria | Deciding which agent to invoke (e.g., `/alfred:2-run` → need tdd-implementer) |
+| **CLAUDE-RULES.md** | ~17kb | Decision rules: Skill invocation, Interactive Questions, TAG validation, TRUST gates, commit templates | At decision points (e.g., "Should I ask user?", "Which Skill applies?") |
+| **CLAUDE-PRACTICES.md** | ~8kb | Real-world workflows, context engineering (JIT retrieval), agent collaboration patterns, code examples | During implementation phase (e.g., executing `/alfred:2-run` RED→GREEN→REFACTOR) |
+
+### How Progressive Disclosure Works
+
+**Example: You run `/alfred:2-run AUTH-001`**
+
+```
+Session Start
+    ↓ Load CLAUDE.md (7kb)
+    ├─ Alfred knows: project context, language settings, core directives
+    ↓ User invokes /alfred:2-run
+    ├─ Load CLAUDE-AGENTS-GUIDE.md (14kb)
+    ├─ Alfred decides: "I need tdd-implementer agent"
+    ├─ Load CLAUDE-RULES.md (17kb)
+    ├─ Alfred checks: "TDD rules? TEST before CODE? TRUST gates?"
+    ├─ Load CLAUDE-PRACTICES.md (8kb)
+    ├─ Alfred references: "RED → GREEN → REFACTOR pattern"
+    ↓ Implementation complete
+    └─ Context cleaned up (only CLAUDE.md remains for next task)
+```
+
+**Result**:
+- ✅ Session boots fast (only 7kb initial load)
+- ✅ Context stays clean (7kb → 7kb+14kb → 7kb+14kb+17kb as needed)
+- ✅ Each document has single responsibility (easier to maintain)
+- ✅ Developers know exactly where to find/modify specific guidance
 
 ### Why This Structure Matters
 
-**For Developers**: These documents define how Alfred interprets your requirements and orchestrates development. Understanding them helps you:
+**For Developers**:
+1. **CLAUDE.md**: Your project's working guide (language, settings, directives)
+2. **CLAUDE-AGENTS-GUIDE.md**: "Who does what?" (agent selection logic)
+3. **CLAUDE-RULES.md**: "How do we decide?" (decision frameworks, gates)
+4. **CLAUDE-PRACTICES.md**: "Real examples" (practical patterns to follow)
 
-- Write clearer specifications that Alfred understands better
-- Know which agent/Skill will be invoked for your request
-- Understand decision points where Alfred might ask you questions
+Understanding this helps you:
+- Write clearer SPEC requirements that Alfred understands
+- Know which agent/Skill executes your request
+- Predict where Alfred might ask questions or apply TRUST verification
 
-**For AI**: Progressive disclosure means:
+**For AI (Context Efficiency)**:
+- **Phase 1** (Session Start): Minimal context footprint (7kb)
+- **Phase 2** (Planning): Load agent selection guide (total ~21kb)
+- **Phase 3** (Implementation): Load decision rules (~38kb)
+- **Phase 4** (Execution): Load practical patterns (~46kb)
+- **Between Tasks**: Unload unnecessary layers, keep CLAUDE.md active
 
-- **Session Start**: Load only CLAUDE.md (7kb) — minimal overhead
-- **On-Demand**: Load CLAUDE-AGENTS-GUIDE.md, CLAUDE-RULES.md, CLAUDE-PRACTICES.md only when needed
-- **Result**: Faster session boot, cleaner context, clear decision logic
+📚 **Learn More**: `.claude/CLAUDE.md` | `.claude/CLAUDE-AGENTS-GUIDE.md` | `.claude/CLAUDE-RULES.md` | `.claude/CLAUDE-PRACTICES.md`
 
 ### Example: What Happens When You Run `/alfred:2-run`
 
@@ -617,7 +657,7 @@ uv tool update
 
 ```bash
 # Reinstall specific version (e.g., 0.4.2)
-uv tool install moai-adk==0.4.2
+uv tool install moai-adk
 ```
 
 ### Verify After Update
@@ -873,19 +913,109 @@ moai-adk update --check
 
 ## Core Workflow (0 → 3)
 
-Alfred iteratively develops projects with four commands.
+Alfred iteratively develops projects with four commands, guided by the **4-Step Workflow Logic** for every user request.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    Start([User Request]) --> Init[0. Init<br/>/alfred:0-project]
-    Init --> Plan[1. Plan & SPEC<br/>/alfred:1-plan]
-    Plan --> Run[2. Run & TDD<br/>/alfred:2-run]
+    Start([User Request]) --> Intent[Step 1: Intent Understanding<br/>Clarify ambiguity if needed]
+    Intent --> Plan[Step 2: Plan Creation<br/>Decompose tasks + identify order]
+    Plan --> Execute[Step 3: Task Execution<br/>TodoWrite: pending → in_progress → completed]
+    Execute --> Report[Step 4: Report & Commit<br/>Document decisions + create git commits]
+    Report --> Init[0. Init<br/>/alfred:0-project]
+    Init --> PlanPhase[1. Plan & SPEC<br/>/alfred:1-plan]
+    PlanPhase --> Run[2. Run & TDD<br/>/alfred:2-run]
     Run --> Sync[3. Sync & Docs<br/>/alfred:3-sync]
-    Sync --> Plan
+    Sync --> PlanPhase
     Sync -.-> End([Release])
 ```
 
+### Alfred's 4-Step Workflow Logic
+
+Every user request follows this systematic process:
+
+#### Step 1: Intent Understanding
+- **Goal**: Clarify user intent before any action
+- **Action**: Evaluate request clarity
+  - **HIGH clarity**: Technical stack, requirements, scope all specified → Skip to Step 2
+  - **MEDIUM/LOW clarity**: Multiple interpretations possible → Invoke `AskUserQuestion`
+- **Outcome**: Clear, unambiguous intent confirmed with user
+
+#### Step 2: Plan Creation
+- **Goal**: Analyze tasks and identify execution strategy
+- **Action**: Invoke Plan Agent to:
+  - Decompose tasks into structured steps
+  - Identify dependencies between tasks
+  - Determine single vs parallel execution opportunities
+  - Estimate work scope and files affected
+- **Outcome**: Structured task breakdown for TodoWrite initialization
+
+#### Step 3: Task Execution
+- **Goal**: Execute tasks with transparent progress tracking
+- **Action**:
+  1. Initialize TodoWrite with all pending tasks
+  2. For each task:
+     - Update status: pending → **in_progress** (exactly ONE at a time)
+     - Execute task (call appropriate sub-agent or tool)
+     - Update status: in_progress → **completed** (immediately after)
+  3. Handle blockers: Keep task in_progress, create new blocking task
+- **Outcome**: All tasks completed with verified progress
+
+#### Step 4: Report & Commit
+- **Goal**: Document work and create git history
+- **Action**:
+  - **Report Generation**: ONLY if user explicitly requested
+    - ❌ Prohibited: Auto-generate reports without request
+    - ✅ Allowed: `.moai/docs/`, `.moai/reports/`, `.moai/specs/`
+  - **Git Commit**: ALWAYS create commits
+    - Call git-manager for all Git operations
+    - TDD commits: RED → GREEN → REFACTOR → DOCS
+    - Include Alfred co-authorship
+- **Outcome**: Complete audit trail with documented decisions
+
+### How 4-Step Workflow Maps to Phase 0-3 Commands
+
+The **4-Step Workflow Logic** is universal and applies to **every command execution**. Here's how it manifests in each Phase:
+
+#### Phase 0: Project Initialization (`/alfred:0-project`)
+```
+Step 1: Intent → Clarify project needs (language, framework, team structure)
+Step 2: Plan  → Design `.moai/` structure, detect tech stack
+Step 3: Run   → Initialize config, deploy Skills, set up project template
+Step 4: Report → Create product/structure/tech.md documentation
+```
+
+#### Phase 1: Planning (`/alfred:1-plan <description>`)
+```
+Step 1: Intent → Parse requirements, clarify SPEC scope
+Step 2: Plan  → Decompose into EARS statements, identify acceptance criteria
+Step 3: Run   → Write SPEC document, create Plan Board, generate GitHub Issue
+Step 4: Report → Create feature branch, commit SPEC with TAG
+```
+
+#### Phase 2: TDD Implementation (`/alfred:2-run <SPEC-ID>`)
+```
+Step 1: Intent → Understand SPEC requirements and test strategy
+Step 2: Plan  → Decompose SPEC into 3-step TDD cycle (RED/GREEN/REFACTOR)
+Step 3: Run   → Execute TDD: 🔴 RED test → 🟢 GREEN implementation → ♻️ REFACTOR quality
+Step 4: Report → Verify TRUST 5 gates, commit code with @TEST/@CODE TAGs
+```
+
+#### Phase 3: Sync & Docs (`/alfred:3-sync`)
+```
+Step 1: Intent → Understand what documentation needs synchronization
+Step 2: Plan  → Identify TAG chains, detect orphans, plan doc updates
+Step 3: Run   → Sync docs, validate TAGs, update README/CHANGELOG
+Step 4: Report → Create sync report, auto-close SPEC Issues, ready PR for merge
+```
+
+**Key Insight**: Each command (0, 1, 2, 3) follows the same **4-Step Logic**. This ensures:
+- ✅ Consistent decision-making across all phases
+- ✅ Clear progression: understand → plan → execute → document
+- ✅ Predictable workflow that teams can rely on
+
+---
+
 ### 0. INIT — Project Preparation
 
 - Questions about project introduction, target, language, mode (locale)
@@ -910,18 +1040,19 @@ graph TD
 - Sync Living Document, README, CHANGELOG, etc.
 - Validate TAG chain and recover orphan TAGs
 - Generate Sync Report, transition Draft → Ready for Review, support `--auto-merge` option
+- **Auto-close related SPEC Issues** (Closes #XX reference in commit message)
 
 ---
 
 ## 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                  |
-| `/alfred:9-feedback` | Interactively create GitHub Issues (type → title → description → priority) | GitHub Issue with auto labels, priority, URL        |
+| Command | What It Does | Key Outputs |
+|---------|-------------|------------|
+| `/alfred:0-project` | **Initialize project**: gather metadata, detect tech stack, deploy 55 Claude Skills, set up `.moai/` directory | `.moai/config.json`, `.moai/project/*`, `product/structure/tech.md` |
+| `/alfred:1-plan <desc>` | **Write SPEC** in EARS format, create Plan Board, auto-generate acceptance criteria, create feature branch | `.moai/specs/SPEC-*/spec.md`, plan board, acceptance criteria, GitHub Issue |
+| `/alfred:2-run <ID>` | **Execute TDD cycle**: 🔴 RED (failing test) → 🟢 GREEN (minimal implementation) → ♻️ REFACTOR (cleanup) → quality gates | `tests/`, `src/` with `@TEST:ID` and `@CODE:ID` tags, test report |
+| `/alfred:3-sync` | **Synchronize Living Docs**: sync README, docs, CHANGELOG; validate TAG chains; auto-close SPEC Issues on PR merge | `docs/`, `.moai/reports/`, `@DOC:ID` tags, Issue closed |
+| `/alfred:9-feedback` | **Create GitHub Issues** interactively (workflow: issue type → title → description → priority/labels) | GitHub Issue with proper labels, priority, auto-assignable |
 
 > ❗ All commands maintain **Phase 0 (optional) → Phase 1 → Phase 2 → Phase 3** cycle structure. Alfred automatically reports execution status and next-step suggestions.
 >
@@ -943,6 +1074,69 @@ When you create a SPEC document using `/alfred:1-plan` and push it to a feature
 4. **PR Comment** is added with a link to the created issue
 5. **Labels** are automatically applied based on priority (critical, high, medium, low)
 
+### Automatic Issue Closure & Lifecycle Synchronization
+
+When you complete implementation and run `/alfred:3-sync`, the system manages the complete SPEC-to-Issue lifecycle:
+
+#### Issue Lifecycle Stages
+
+| Stage | SPEC Status | GitHub Issue Status | Action |
+|-------|------------|-------------------|--------|
+| **1. Creation** | `draft` | `open` + `spec` label | SPEC created, Issue auto-created |
+| **2. Review** | `in-review` | `open` + `planning` label | Awaiting SPEC approval |
+| **3. Implementation** | `in-progress` | `open` + `in_progress` label | `/alfred:2-run` execution |
+| **4. Completion** | `completed` | Closing... | `/alfred:3-sync` adds `Closes #XX` |
+| **5. Release** | `stable` | `closed` ✅ | PR merges → Issue auto-closes |
+
+#### Auto-Close Workflow Detail
+
+When you run `/alfred:3-sync` to finalize implementation:
+
+1. **SPEC Issue Detection**: System scans SPEC document for GitHub Issue number
+2. **Status Validation**: Confirms SPEC status is `completed` or `stable`
+3. **Closes Reference Generation**: Automatically generates `Closes #XX` in commit message
+4. **Smart Linking**: Issues PR to SPEC Issue with correlation
+5. **Auto-Close on Merge**: When PR merges to main branch:
+   - GitHub reads `Closes #XX` reference in commit message
+   - Automatically transitions Issue to `closed` status
+   - SPEC Issue and GitHub Issue statuses now match
+
+**Complete Example Workflow:**
+```
+Day 1: Create SPEC
+├─ /alfred:1-plan "User Authentication"
+├─ SPEC-AUTH-001 created in .moai/specs/SPEC-AUTH-001/
+└─ GitHub Issue #45 auto-created (status: open)
+
+Day 2: Implement Feature
+├─ /alfred:2-run AUTH-001
+├─ 🔴 RED: Add failing test @TEST:AUTH-001
+├─ 🟢 GREEN: Implement minimal solution @CODE:AUTH-001
+├─ ♻️ REFACTOR: Improve quality per TRUST 5
+├─ GitHub Issue #45 status: open, developer assignment active
+
+Day 3: Finalize & Sync
+├─ /alfred:3-sync
+├─ SPEC status: draft → completed → stable
+├─ Commit message: "🔖 RELEASE: v0.8.3 ... Closes #45"
+├─ PR created with automatic Issue linking
+└─ PR merges to main → Issue #45 automatically closed ✅
+
+Result:
+- ✅ SPEC-AUTH-001 fully implemented
+- ✅ All tests passing (85%+ coverage)
+- ✅ Documentation synchronized
+- ✅ GitHub Issue #45 closed
+- ✅ Complete audit trail via git history
+```
+
+#### Benefits of Automatic Closure
+
+- **Single Source of Truth**: SPEC document status always matches GitHub Issue status
+- **No Manual Updates**: No need to manually close issues (GitHub does it automatically)
+- **Traceable History**: Complete record in git commits shows SPEC→Issue→Close chain
+- **Team Coordination**: Everyone sees status via GitHub, no separate tracking system needed
+
 ### What Gets Synchronized
 
 **From SPEC to GitHub Issue:**
@@ -1187,6 +1381,8 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 - ✅ SPEC-based test cases (what to test is already defined)
 - ✅ When requirements change, track all affected code with `@SPEC:ID` TAG
 
+📚 **Learn More**: `.moai/specs/` | [EARS Syntax Guide](./CLAUDE-RULES.md#ears-syntax) | [SPEC Examples](./CLAUDE-PRACTICES.md#spec-examples)
+
 ---
 
 ### Key Concept 2: TDD (Test-Driven Development)
@@ -1223,6 +1419,8 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 - ✅ Refactoring confidence (always verifiable with tests)
 - ✅ Clear Git history (trace RED → GREEN → REFACTOR process)
 
+📚 **Learn More**: [TDD Workflow](./CLAUDE-PRACTICES.md#tdd-workflow) | [Test Examples](./CLAUDE-PRACTICES.md#test-examples) | [Quality Gates](./CLAUDE-RULES.md#trust-5-principles)
+
 ---
 
 ### Key Concept 3: @TAG System
@@ -1249,6 +1447,36 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 - USER-001, USER-002...
 - Once assigned, **never change**
 
+**Advanced TAG Usage: Multi-Component TAGs**
+
+For complex features with multiple components, use sub-tags:
+
+```
+@SPEC:AUTH-001 (complete requirements)
+    ↓
+@TEST:AUTH-001 (test suite)
+├─ @TEST:AUTH-001:login (login flow tests)
+├─ @TEST:AUTH-001:token (token refresh tests)
+└─ @TEST:AUTH-001:session (session management tests)
+    ↓
+@CODE:AUTH-001 (implementation)
+├─ @CODE:AUTH-001:service (authentication service)
+├─ @CODE:AUTH-001:model (User/Token models)
+├─ @CODE:AUTH-001:middleware (auth middleware)
+└─ @CODE:AUTH-001:repository (database access layer)
+    ↓
+@DOC:AUTH-001 (documentation)
+├─ @DOC:AUTH-001:api (API documentation)
+└─ @DOC:AUTH-001:guide (integration guide)
+```
+
+**Component TAG Rules**:
+- Format: `@TAG:ID` or `@TAG:ID:component`
+- Component names are optional but **highly recommended** for clarity
+- All components share the same ID (never change ID once assigned)
+- When querying: `rg '@TAG:AUTH-001' -n` finds all components
+- Helps organize large features without creating new IDs
+
 **How to Use?** When requirements change:
 
 ```bash
@@ -1267,6 +1495,8 @@ rg '@TAG:AUTH-001' -n
 - ✅ Instantly identify all affected code during refactoring
 - ✅ Code remains understandable 3 months later (trace TAG → SPEC)
 
+📚 **Learn More**: [TAG System Guide](./CLAUDE-RULES.md#tag-system) | [TAG Validation](./CLAUDE-PRACTICES.md#tag-validation) | [Orphan Detection](./CLAUDE-RULES.md#orphan-tag-detection)
+
 ---
 
 ### Key Concept 4: TRUST 5 Principles
@@ -1312,6 +1542,8 @@ rg '@TAG:AUTH-001' -n
 - ✅ Entire team develops with same standards
 - ✅ Fewer bugs, prevent security vulnerabilities in advance
 
+📚 **Learn More**: [TRUST 5 Validation](./CLAUDE-RULES.md#trust-5-principles) | [Quality Gates](./CLAUDE-RULES.md#quality-gates) | [Security Best Practices](./CLAUDE-RULES.md#security-guidelines)
+
 ---
 
 ### Key Concept 5: Alfred SuperAgent
@@ -1322,10 +1554,40 @@ rg '@TAG:AUTH-001' -n
 
 **Agent Composition**:
 
-- **Alfred SuperAgent**: Overall orchestration (1)
-- **Core Sub-agents**: Specialized tasks like SPEC writing, TDD implementation, documentation sync (10)
-- **Zero-project Specialists**: Project initialization, language detection, etc. (6)
-- **Built-in Agents**: General questions, codebase exploration (2)
+#### 1. Alfred SuperAgent (1)
+- **🎩 Alfred**: Overall orchestration, workflow management, team coordination
+
+#### 2. Core Sub-agents (10)
+Specialized experts handling SPEC → TDD → SYNC pipeline:
+
+| Agent | Role | Responsibility |
+|-------|------|-----------------|
+| **📋 project-manager** | Project Initialization | Setup `.moai/` structure, tech stack detection, Skills deployment |
+| **🏗️ spec-builder** | SPEC Authoring | Write EARS-format specifications, acceptance criteria |
+| **💎 tdd-implementer** | TDD Implementation | RED → GREEN → REFACTOR cycle, test-first development |
+| **📖 doc-syncer** | Documentation Sync | Living docs, README sync, changelog management |
+| **🏷️ tag-agent** | TAG Validation | @TAG chain verification, orphan detection, traceability |
+| **🚀 git-manager** | Git Workflow | Branch management, commits, PR automation, releases |
+| **🔬 debug-helper** | Error Analysis | Stack trace parsing, error diagnosis, fix suggestions |
+| **✅ trust-checker** | TRUST Verification | Test coverage (85%+), code quality, security checks |
+| **🛠️ cc-manager** | Claude Code Config | Session settings, tool permissions, hook management |
+| **📊 implementation-planner** | Strategy Planning | Task decomposition, dependency analysis, parallelization |
+
+#### 3. Specialist Sub-agents (6)
+Domain-specific experts:
+
+- **Language Detection**: Auto-detect Python, TS, Go, Rust, Java from package config
+- **Skills Factory**: Research and integrate new Claude Skills
+- **Template Managers**: Project scaffolding, documentation templates
+- **Quality Gate**: Code review, linting, type checking orchestration
+- **Context Optimizer**: Memory management, JIT context loading
+- **Interactive Questions**: TUI-based user input for AskUserQuestion
+
+#### 4. Built-in Claude Agents (2)
+General-purpose capabilities:
+
+- **General Q&A**: Answer questions about coding, architecture, debugging
+- **Codebase Exploration**: Fast grep/glob searches, code pattern analysis
 
 **55 Claude Skills**:
 
@@ -1868,7 +2130,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
-**TAG Guard (New in v0.4.11)**:
+**TAG Guard**:
 Automatically detects missing @TAG annotations in changed files:
 
 - Scans staged, modified, and untracked files
@@ -1896,7 +2158,42 @@ Or when TAGs are missing:
 
 **Why It Matters**: Prevents data loss from mistakes and ensures @TAG traceability. You can always restore from the checkpoint if something goes wrong.
 
-#### 3. UserPromptSubmit (Prompt Input)
+#### 3. PostToolUse (After Tool Execution)
+
+**Triggers**: After executing file edits, code changes, or MultiEdit operations
+**Purpose**: Automatically run tests to verify changes didn't break anything
+
+**Auto-Test Execution**:
+
+Supported Languages (9 total):
+- 🐍 **Python**: `pytest` with coverage report
+- 📘 **TypeScript/JavaScript**: `Vitest` or `Jest`
+- 🐹 **Go**: `go test` with `-v` flag
+- 🦀 **Rust**: `cargo test` with `--all`
+- ☕ **Java**: `JUnit` via Maven/Gradle
+- 🎯 **Kotlin**: `JUnit` with Gradle
+- 🍎 **Swift**: `XCTest` via Xcode
+- 🎨 **Dart**: `flutter test`
+
+**What You See**:
+
+```
+✅ Tests passed (47 passed in 2.3s)
+   Coverage: 87% (improved from 84%)
+```
+
+Or if tests fail:
+
+```
+❌ Test failures detected
+   ├─ src/auth/service.test.ts:23
+   │  Expected token.length > 0
+   └─ Revert to previous version? (y/n)
+```
+
+**Why It Matters**: Instant feedback on code quality. Catches breaking changes immediately before you commit.
+
+#### 4. UserPromptSubmit (Prompt Input)
 
 **Triggers**: When you submit a prompt to Claude
 **Purpose**: JIT (Just-In-Time) context loading—automatically add relevant files
@@ -1910,7 +2207,7 @@ Or when TAGs are missing:
 
 **Why It Matters**: Saves time and ensures Claude has all the relevant context for your request.
 
-#### 4. SessionEnd (Session Cleanup)
+#### 5. SessionEnd (Session Cleanup)
 
 **Triggers**: When you close your Claude Code session
 **Purpose**: Cleanup tasks and state preservation
@@ -1999,15 +2296,17 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.8.3**  | 🔄 4-Step Workflow Logic (Intent → Plan → Execute → Report) + AI decision framework               | 2025-10-30 |
+| **v0.8.2**  | 📖 EARS terminology update: "Constraints" → "Unwanted Behaviors" for clarity                     | 2025-10-29 |
+| **v0.8.1**  | 🔄 Command rename: `/alfred:9-help` → `/alfred:9-feedback` + User feedback workflow improvements | 2025-10-28 |
+| **v0.8.0**  | 🏷️ @DOC TAG auto-generation system + SessionStart version check enhancement                      | 2025-10-27 |
+| **v0.7.0**  | 🌍 Complete language localization system (English, Korean, Japanese, Chinese, Spanish)           | 2025-10-26 |
+| **v0.6.3**  | ⚡ 3-Stage update workflow: 70-80% performance improvement via parallel operations               | 2025-10-25 |
+| **v0.6.0**  | 🏗️ Major architecture refactor + Enhanced SPEC metadata structure (7 required + 9 optional)      | 2025-10-24 |
 | **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
-| **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 |
 
-> 📦 **Install Now**: `uv tool install moai-adk==0.4.11` or `pip install moai-adk==0.4.11`
+> 📦 **Install Now**: `uv tool install moai-adk` or `pip install moai-adk`
 
 ---
 
@@ -2015,7 +2314,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Purpose                   | Resource                                                        |
 | ------------------------- | --------------------------------------------------------------- |
-| Skills detailed structure | `.claude/skills/` directory (58 Skills)                         |
+| Skills detailed structure | `.claude/skills/` directory (55+ Skills)                         |
 | Sub-agent details         | `.claude/agents/alfred/` directory (12 agents)                  |
 | Workflow guide            | `.claude/commands/alfred/` (4 commands: 0-project ~ 3-sync)     |
 | Documentation             | Coming soon (see `.moai/`, `.claude/`, `docs/` in your project) |
@@ -2029,8 +2328,8 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | ------------------------ | -------------------------------------------------------- |
 | **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.11)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/                       |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases             |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project         |
 
 ---
@@ -2039,7 +2338,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 > **"No CODE without SPEC"**
 
-MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 56 Claude Skills together guarantee:
+MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 55+ Claude Skills together guarantee:
 
 - ✅ **SPEC → TEST (TDD) → CODE → DOCS consistency**
 - ✅ **Complete history tracking with @TAG system**