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

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

@@ -68,18 +68,7 @@ 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.9.0 → moai_adk-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.9.0
+Version: 0.9.1
 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
@@ -388,70 +388,30 @@ 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 (Progressive Disclosure Pattern)
+### 4-Document Structure
 
-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:
+When you run MoAI-ADK, Alfred loads configuration from **4 coordinated documents** (stored in your `.claude/` directory):
 
-#### 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
+| 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                                   |
 
 ### Why This Structure Matters
 
-**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)
+**For Developers**: These documents define how Alfred interprets your requirements and orchestrates development. Understanding them helps you:
 
-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
+- 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
 
-**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
+**For AI**: Progressive disclosure means:
 
-📚 **Learn More**: `.claude/CLAUDE.md` | `.claude/CLAUDE-AGENTS-GUIDE.md` | `.claude/CLAUDE-RULES.md` | `.claude/CLAUDE-PRACTICES.md`
+- **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
 
 ### Example: What Happens When You Run `/alfred:2-run`
 
@@ -869,6 +829,40 @@ This issue has been **fixed** in v0.8.1+. If you're experiencing this:
 - Code now gracefully handles InvalidVersion exceptions
 - Added comprehensive unit tests for placeholder detection
 
+#### Problem: UV Tool Upgrade Shows "Nothing to upgrade" Despite New Version
+
+**Status**: Automatically fixed in v0.9.1+ with cache refresh retry
+
+**Symptoms:**
+- `moai-adk update` shows "Nothing to upgrade"
+- PyPI has a newer version available
+- Caused by stale UV cache metadata
+
+**Automatic Fix (v0.9.1+):**
+The system now automatically detects stale cache and retries:
+1. Detects "Nothing to upgrade" message
+2. Compares installed version vs PyPI latest version
+3. Clears UV cache: `uv cache clean moai-adk`
+4. Automatically retries upgrade
+5. Completes in a single command run
+
+**Manual Workaround (if needed):**
+```bash
+# Clear UV cache and retry
+uv cache clean moai-adk && moai-adk update
+```
+
+**Technical Details:**
+- Root cause: UV caches PyPI metadata that can become outdated
+- Detection: Compares version strings when "Nothing to upgrade" appears
+- Retry limit: Maximum 1 retry to prevent infinite loops
+- Timeout: 10 seconds for cache clear operation
+
+**References:**
+- SPEC: @SPEC:UPDATE-CACHE-FIX-001
+- Implementation: @CODE:UPDATE-CACHE-FIX-001-001, @CODE:UPDATE-CACHE-FIX-001-002, @CODE:UPDATE-CACHE-FIX-001-003
+- Tests: @TEST:UPDATE-CACHE-FIX-001
+
 ### Contributing Tests
 
 When adding new features, always include tests:
@@ -913,109 +907,19 @@ moai-adk update --check
 
 ## Core Workflow (0 → 3)
 
-Alfred iteratively develops projects with four commands, guided by the **4-Step Workflow Logic** for every user request.
+Alfred iteratively develops projects with four commands.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    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]
+    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]
     Run --> Sync[3. Sync & Docs<br/>/alfred:3-sync]
-    Sync --> PlanPhase
+    Sync --> Plan
     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)
@@ -1040,19 +944,18 @@ Step 4: Report → Create sync report, auto-close SPEC Issues, ready PR for merg
 - 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` | **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 |
+| 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        |
 
 > ❗ All commands maintain **Phase 0 (optional) → Phase 1 → Phase 2 → Phase 3** cycle structure. Alfred automatically reports execution status and next-step suggestions.
 >
@@ -1074,69 +977,6 @@ 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:**
@@ -1381,8 +1221,6 @@ 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)
@@ -1419,8 +1257,6 @@ 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
@@ -1447,36 +1283,6 @@ 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
@@ -1495,8 +1301,6 @@ 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
@@ -1542,8 +1346,6 @@ 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
@@ -1554,40 +1356,10 @@ rg '@TAG:AUTH-001' -n
 
 **Agent Composition**:
 
-#### 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
+- **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)
 
 **55 Claude Skills**:
 
@@ -2158,42 +1930,7 @@ 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. 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)
+#### 3. UserPromptSubmit (Prompt Input)
 
 **Triggers**: When you submit a prompt to Claude
 **Purpose**: JIT (Just-In-Time) context loading—automatically add relevant files
@@ -2207,7 +1944,7 @@ Or if tests fail:
 
 **Why It Matters**: Saves time and ensures Claude has all the relevant context for your request.
 
-#### 5. SessionEnd (Session Cleanup)
+#### 4. SessionEnd (Session Cleanup)
 
 **Triggers**: When you close your Claude Code session
 **Purpose**: Cleanup tasks and state preservation
@@ -2296,7 +2033,6 @@ 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 |