docs: comprehensive AGENTS.md and documentation review (#234)

2026-04-30 13:51:15 +08:00 · 2026-02-01 02:02:36 +00:00
parent 7397cfe48f
commit b5acd0defd
16 changed files with 475 additions and 299 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,21 +1,23 @@
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # oh-my-claudecode

 Multi-agent orchestration system for Claude Code CLI, providing intelligent delegation, parallel execution, and IDE-like capabilities through LSP/AST integration.

-**Version:** 3.7.7
+**Version:** 3.8.14
 **Purpose:** Transform Claude Code into a conductor of specialized AI agents
 **Inspired by:** oh-my-zsh / oh-my-opencode

 ## Purpose

 oh-my-claudecode enhances Claude Code with:
- **32 specialized agents** across 8 domains with 3-tier model routing (Haiku/Sonnet/Opus)
- **LSP tools** for IDE-like code intelligence (hover, go-to-definition, references, diagnostics)
- **AST tools** for structural code search and transformation via ast-grep
- **Execution modes**: autopilot, ultrawork, ralph-loop, ultrapilot, swarm, pipeline, ecomode
- **Skills system** for reusable workflows and automation
+
+- **32 specialized agents** across multiple domains with 3-tier model routing (Haiku/Sonnet/Opus)
+- **37 skills** for workflow automation and specialized behaviors
+- **31 hooks** for event-driven execution modes and enhancements
+- **15 custom tools** including 12 LSP, 2 AST, and Python REPL
+- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline, ecomode
+- **MCP integration** with plugin-scoped tool discovery and skill loading

 ## Key Files

@@ -24,20 +26,24 @@ oh-my-claudecode enhances Claude Code with:
 | `package.json` | Project dependencies and npm scripts |
 | `tsconfig.json` | TypeScript configuration |
 | `CHANGELOG.md` | Version history and release notes |
-| `CLAUDE.md` | Main orchestration instructions (loaded by Claude Code) |
+| `docs/CLAUDE.md` | End-user orchestration instructions (installed to user projects) |
 | `src/index.ts` | Main entry point - exports `createSisyphusSession()` |
+| `.mcp.json` | MCP server configuration for plugin discovery |
+| `.claude-plugin/plugin.json` | Claude Code plugin manifest |

 ## Subdirectories

-| Directory | Purpose |
-|-----------|---------|
-| `src/` | TypeScript source code - core library (see `src/AGENTS.md`) |
-| `agents/` | Markdown prompt templates for 32 agents |
-| `skills/` | 32 skill definitions for workflows |
-| `scripts/` | Build scripts, utilities, and automation |
-| `docs/` | User documentation and guides |
-| `templates/` | Hook and rule templates |
-| `benchmark/` | Performance testing framework |
+| Directory | Purpose | Related AGENTS.md |
+|-----------|---------|-------------------|
+| `src/` | TypeScript source code - core library | `src/AGENTS.md` |
+| `agents/` | Markdown prompt templates for 32 agents (see `agents/templates/` for guidelines) | - |
+| `skills/` | 37 skill definitions for workflows | `skills/AGENTS.md` |
+| `commands/` | 31 slash command definitions (mirrors skills) | - |
+| `scripts/` | Build scripts, utilities, and automation | - |
+| `docs/` | User documentation and guides | `docs/AGENTS.md` |
+| `templates/` | Hook and rule templates (coding-style, testing, security, performance, git-workflow) | - |
+| `benchmark/` | Performance testing framework | - |
+| `bridge/` | Pre-bundled MCP server for plugin distribution | - |

 ## For AI Agents

@@ -54,25 +60,93 @@ oh-my-claudecode enhances Claude Code with:
   | Docs | `writer` | haiku |
   | Security | `security-reviewer` / `security-reviewer-low` | opus/haiku |
   | Build errors | `build-fixer` / `build-fixer-low` | sonnet/haiku |
+   | Testing | `qa-tester` / `qa-tester-high` | sonnet/opus |
+   | Code review | `code-reviewer` / `code-reviewer-low` | opus/haiku |
+   | TDD | `tdd-guide` / `tdd-guide-low` | sonnet/haiku |
+   | Data analysis | `scientist` / `scientist-low` / `scientist-high` | sonnet/haiku/opus |

-2. **LSP/AST Tools** (v3.7.5+): Use IDE-like tools for code intelligence:
+2. **LSP/AST Tools**: Use IDE-like tools for code intelligence:
   - `lsp_hover` - Type info and documentation at position
   - `lsp_goto_definition` - Jump to symbol definition
   - `lsp_find_references` - Find all usages across codebase
   - `lsp_document_symbols` - Get file outline
   - `lsp_workspace_symbols` - Search symbols across workspace
   - `lsp_diagnostics` - Get errors/warnings for single file
-   - `lsp_diagnostics_directory` - **Project-wide type checking** (uses tsc or LSP)
+   - `lsp_diagnostics_directory` - Project-wide type checking (uses tsc or LSP)
   - `lsp_rename` - Preview refactoring across files
   - `lsp_code_actions` - Get available quick fixes
   - `ast_grep_search` - Structural code search with patterns
   - `ast_grep_replace` - AST-aware code transformation
+   - `python_repl` - Execute Python code for data analysis

 3. **Model Routing**: Match model tier to task complexity:
   - **Haiku** (LOW): Simple lookups, trivial fixes, fast searches
   - **Sonnet** (MEDIUM): Standard implementation, moderate reasoning
   - **Opus** (HIGH): Complex reasoning, architecture, debugging

+### Modification Checklist
+
+#### Cross-File Dependencies
+
+| If you modify... | Also check/update... |
+|------------------|---------------------|
+| `agents/*.md` | `src/agents/definitions.ts`, `src/agents/index.ts`, `docs/REFERENCE.md` |
+| `skills/*/SKILL.md` | `commands/*.md` (mirror), `scripts/build-skill-bridge.mjs` |
+| `commands/*.md` | `skills/*/SKILL.md` (mirror) |
+| `src/hooks/*` | `src/hooks/index.ts`, `src/hooks/bridge.ts`, related skill/command |
+| Agent prompt | Tiered variants (`-low`, `-medium`, `-high`) |
+| Tool definition | `src/tools/index.ts`, `src/mcp/omc-tools-server.ts`, `docs/REFERENCE.md` |
+| `src/hud/*` | `commands/hud.md`, `skills/hud/SKILL.md` |
+| `src/mcp/*` | `docs/REFERENCE.md` (MCP Tools section) |
+| Agent tool assignments | `docs/CLAUDE.md` (Agent Tool Matrix) |
+| `templates/rules/*` | `src/hooks/rules-injector/` if pattern changes |
+| New execution mode | `src/hooks/*/`, `skills/*/SKILL.md`, `commands/*.md` (all three) |
+
+#### Documentation Updates (docs/)
+
+| If you change... | Update this docs/ file |
+|------------------|----------------------|
+| Agent count or agent list | `docs/REFERENCE.md` (Agents section) |
+| Skill count or skill list | `docs/REFERENCE.md` (Skills section) |
+| Hook count or hook list | `docs/REFERENCE.md` (Hooks System section) |
+| Magic keywords | `docs/REFERENCE.md` (Magic Keywords section) |
+| Architecture or skill composition | `docs/ARCHITECTURE.md` |
+| Internal API or feature | `docs/FEATURES.md` |
+| Breaking changes | `docs/MIGRATION.md` |
+| Tiered agent design | `docs/TIERED_AGENTS_V2.md` |
+| Compatibility requirements | `docs/COMPATIBILITY.md` |
+| CLAUDE.md content | `docs/CLAUDE.md` (end-user instructions) |
+
+#### Skills ↔ Commands Relationship
+
+- `skills/` contains skill implementations with full prompts
+- `commands/` contains slash command definitions that invoke skills
+- Both should be kept in sync for the same functionality
+
+#### AGENTS.md Update Requirements
+
+When you modify files in these locations, update the corresponding AGENTS.md:
+
+| If you change... | Update this AGENTS.md |
+|------------------|----------------------|
+| Root project structure, new features | `/AGENTS.md` (this file) |
+| `src/**/*.ts` structure or new modules | `src/AGENTS.md` |
+| `agents/*.md` files | `src/agents/AGENTS.md` (implementation details) |
+| `skills/*/` directories | `skills/AGENTS.md` |
+| `src/hooks/*/` directories | `src/hooks/AGENTS.md` |
+| `src/tools/**/*.ts` | `src/tools/AGENTS.md` |
+| `src/features/*/` modules | `src/features/AGENTS.md` |
+| `src/tools/lsp/` | `src/tools/lsp/AGENTS.md` |
+| `src/tools/diagnostics/` | `src/tools/diagnostics/AGENTS.md` |
+| `src/agents/*.ts` | `src/agents/AGENTS.md` |
+
+#### What to Update
+
+- Update version number when releasing
+- Update feature descriptions when functionality changes
+- Update file/directory tables when structure changes
+- Keep "Generated" date as original, update "Updated" date
+
 ### Testing Requirements

 ```bash
@@ -91,7 +165,7 @@ const session = createSisyphusSession();

 // Agent registration
 import { getAgentDefinitions } from './agents/definitions';
-const agents = getAgentDefinitions(); // Returns all 32 agents
+const agents = getAgentDefinitions();

 // Tool access
 import { allCustomTools, lspTools, astTools } from './tools';
@@ -106,7 +180,7 @@ import { allCustomTools, lspTools, astTools } from './tools';
 │                  oh-my-claudecode (OMC)                     │
 │  ┌─────────────┬─────────────┬─────────────┬─────────────┐  │
 │  │   Skills    │   Agents    │    Tools    │   Hooks     │  │
-│  │ (32 skills) │ (32 agents) │(LSP/AST/REPL)│ (30+ hooks)│  │
+│  │ (37 skills) │ (32 agents) │(LSP/AST/REPL)│ (31 hooks)  │  │
 │  └─────────────┴─────────────┴─────────────┴─────────────┘  │
 │  ┌─────────────────────────────────────────────────────────┐│
 │  │              Features Layer                             ││
@@ -119,6 +193,7 @@ import { allCustomTools, lspTools, astTools } from './tools';
 ## Agent Summary (32 Total)

 ### Base Agents (12)
+
 | Agent | Model | Purpose |
 |-------|-------|---------|
 | architect | opus | Architecture, debugging, root cause analysis |
@@ -134,10 +209,22 @@ import { allCustomTools, lspTools, astTools } from './tools';
 | qa-tester | sonnet | Interactive CLI/service testing |
 | scientist | sonnet | Data analysis, hypothesis testing |

-### Tiered Variants (20)
- `*-low` (Haiku): architect-low, executor-low, researcher-low, designer-low, scientist-low, explore (base), security-reviewer-low, build-fixer-low, tdd-guide-low, code-reviewer-low
- `*-medium` (Sonnet): architect-medium, explore-medium
- `*-high` (Opus): executor-high, designer-high, explore-high, qa-tester-high, scientist-high, security-reviewer, code-reviewer
+### Specialized Agents (4)
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| security-reviewer | opus | Security vulnerability detection and audits |
+| build-fixer | sonnet | Build/type error resolution (multi-language) |
+| tdd-guide | sonnet | Test-driven development workflow |
+| code-reviewer | opus | Expert code review and quality assessment |
+
+### Tiered Variants (16)
+
+| Tier | Agents |
+|------|--------|
+| **LOW** (Haiku) | `architect-low`, `executor-low`, `researcher-low`, `designer-low`, `scientist-low`, `security-reviewer-low`, `build-fixer-low`, `tdd-guide-low`, `code-reviewer-low` (9) |
+| **MEDIUM** (Sonnet) | `architect-medium`, `explore-medium` (2) |
+| **HIGH** (Opus) | `executor-high`, `designer-high`, `explore-high`, `qa-tester-high`, `scientist-high` (5) |

 ## Execution Modes

@@ -151,13 +238,14 @@ import { allCustomTools, lspTools, astTools } from './tools';
 | pipeline | "pipeline" | Sequential agent chaining with data passing |
 | ecomode | "eco", "efficient", "budget" | Token-efficient parallel execution |

-## Skills (32)
+## Skills (37)

 Key skills: `autopilot`, `ultrawork`, `ralph`, `ultrapilot`, `plan`, `ralplan`, `deepsearch`, `deepinit`, `frontend-ui-ux`, `git-master`, `tdd`, `security-review`, `code-review`, `research`, `analyze`, `swarm`, `pipeline`, `ecomode`, `cancel`, `learner`, `note`, `hud`, `doctor`, `omc-setup`, `mcp-setup`, `build-fix`, `ultraqa`

-## LSP/AST Tools (v3.7.5+)
+## LSP/AST Tools
+
+### LSP Tools

-### LSP Tools (12)
 ```typescript
 // IDE-like code intelligence via Language Server Protocol
 lsp_hover              // Type info at position
@@ -174,16 +262,21 @@ lsp_code_actions       // Available refactorings/fixes
 lsp_code_action_resolve // Get action details
 ```

-**Supported Languages**: TypeScript, Python, Rust, Go, C/C++, Java, JSON, HTML, CSS, YAML
+#### Supported Languages
+
+TypeScript, Python, Rust, Go, C/C++, Java, JSON, HTML, CSS, YAML
+
+### AST Tools

-### AST Tools (2)
 ```typescript
 // Structural code search/transform via ast-grep
 ast_grep_search   // Pattern matching with meta-variables ($NAME, $$$ARGS)
 ast_grep_replace  // AST-aware code transformation (dry-run by default)
 ```

-**Supported Languages**: JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML
+#### Supported Languages
+
+JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML

 ## State Files

@@ -197,6 +290,7 @@ ast_grep_replace  // AST-aware code transformation (dry-run by default)
 ## Dependencies

 ### Runtime
+
 | Package | Purpose |
 |---------|---------|
 | `@anthropic-ai/claude-agent-sdk` | Claude Code integration |
@@ -208,6 +302,7 @@ ast_grep_replace  // AST-aware code transformation (dry-run by default)
 | `commander` | CLI parsing |

 ### Development
+
 | Package | Purpose |
 |---------|---------|
 | `typescript` | Type system |
@@ -226,9 +321,10 @@ npm run lint            # ESLint
 npm run sync-metadata   # Sync agent/skill metadata
 ```

-## Hook System (30+)
+## Hook System (31)

 Key hooks in `src/hooks/`:
+
 - `autopilot/` - Full autonomous execution
 - `ralph/` - Persistence until verified
 - `ultrawork/` - Parallel execution
@@ -241,7 +337,7 @@ Key hooks in `src/hooks/`:

 ## Configuration

-Settings in `~/.claude/settings.local.json` or `.omc-config.json`:
+Settings in `~/.claude/.omc-config.json`:

 ```json
 {
--- a/README.md
+++ b/README.md
@@ -1,7 +1,3 @@
-
-
-
-
 # oh-my-claudecode

 [![npm version](https://img.shields.io/npm/v/oh-my-claude-sisyphus?color=cb3837)](https://www.npmjs.com/package/oh-my-claude-sisyphus)
@@ -16,8 +12,6 @@

 [Get Started](#quick-start) • [Documentation](https://yeachan-heo.github.io/oh-my-claudecode-website) • [Migration Guide](docs/MIGRATION.md)

-</div>
-
 ---

 ## Quick Start
@@ -40,14 +34,12 @@ autopilot: build a REST API for managing tasks

 That's it. Everything else is automatic.

-
 <h1 align="center">Your Claude Just Have been Steroided.</h1>

 <p align="center">
  <img src="assets/omc-character.jpg" alt="oh-my-claudecode" width="400" />
 </p>

-
 ---

 ## Why oh-my-claudecode?
@@ -70,17 +62,21 @@ Multiple strategies for different use cases - from fully autonomous builds to to
 | Mode | Speed | Use For |
 |------|-------|---------|
 | **Autopilot** | Fast | Full autonomous workflows |
+| **Ultrawork** | Parallel | Maximum parallelism for any task |
+| **Ralph** | Persistent | Tasks that must complete fully |
 | **Ultrapilot** | 3-5x faster | Multi-component systems |
 | **Ecomode** | Fast + 30-50% cheaper | Budget-conscious projects |
 | **Swarm** | Coordinated | Parallel independent tasks |
 | **Pipeline** | Sequential | Multi-stage processing |

 ### Intelligent Orchestration
+
 - **32 specialized agents** for architecture, research, design, testing, data science
 - **Smart model routing** - Haiku for simple tasks, Opus for complex reasoning
 - **Automatic delegation** - Right agent for the job, every time

 ### Developer Experience
+
 - **Magic keywords** - `ralph`, `ulw`, `eco`, `plan` for explicit control
 - **HUD statusline** - Real-time orchestration metrics in your status bar
 - **Skill learning** - Extract reusable patterns from your sessions
@@ -101,6 +97,7 @@ Optional shortcuts for power users. Natural language works fine without them.
 | `ulw` | Maximum parallelism | `ulw fix all errors` |
 | `eco` | Token-efficient execution | `eco: migrate database` |
 | `plan` | Planning interview | `plan the API` |
+| `ralplan` | Iterative planning consensus | `ralplan this feature` |

 **ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords.

@@ -162,15 +159,16 @@ If Oh-My-ClaudeCode helps your workflow, consider sponsoring:

 [![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-❤️-red?style=for-the-badge&logo=github)](https://github.com/sponsors/Yeachan-Heo)

-**Why sponsor?**
+### Why sponsor?
+
 - Keep development active
 - Priority support for sponsors
 - Influence roadmap & features
 - Help maintain free & open source

-**Other ways to help:**
+### Other ways to help
+
 - ⭐ Star the repo
 - 🐛 Report bugs
 - 💡 Suggest features
 - 📝 Contribute code
-
--- a/agents/AGENTS.md
+++ b/agents/AGENTS.md
@@ -1,144 +0,0 @@
-<!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
-
-# agents (Prompt Templates)
-
-Markdown prompt templates for all 32 agents in oh-my-claudecode.
-
-## Purpose
-
-This directory contains the prompt templates that define agent behavior. Each file is a markdown document with YAML frontmatter for metadata, loaded dynamically by `src/agents/definitions.ts`.
-
-## Key Files
-
-| File | Agent | Model | Purpose |
-|------|-------|-------|---------|
-| `architect.md` | architect | opus | Architecture, debugging, root cause analysis |
-| `architect-medium.md` | architect-medium | sonnet | Moderate analysis tasks |
-| `architect-low.md` | architect-low | haiku | Quick code questions |
-| `executor.md` | executor | sonnet | Focused task implementation |
-| `executor-high.md` | executor-high | opus | Complex multi-file changes |
-| `executor-low.md` | executor-low | haiku | Simple single-file tasks |
-| `explore.md` | explore | haiku | Fast codebase search |
-| `explore-medium.md` | explore-medium | sonnet | Thorough search with reasoning |
-| `explore-high.md` | explore-high | opus | Architectural discovery |
-| `designer.md` | designer | sonnet | UI/UX, component design |
-| `designer-high.md` | designer-high | opus | Complex UI architecture |
-| `designer-low.md` | designer-low | haiku | Simple styling tweaks |
-| `researcher.md` | researcher | sonnet | Documentation research |
-| `researcher-low.md` | researcher-low | haiku | Quick doc lookups |
-| `writer.md` | writer | haiku | Technical documentation |
-| `vision.md` | vision | sonnet | Image/screenshot analysis |
-| `critic.md` | critic | opus | Critical plan review |
-| `analyst.md` | analyst | opus | Pre-planning requirements |
-| `planner.md` | planner | opus | Strategic planning |
-| `qa-tester.md` | qa-tester | sonnet | Interactive CLI testing |
-| `qa-tester-high.md` | qa-tester-high | opus | Production-ready QA |
-| `scientist.md` | scientist | sonnet | Data analysis |
-| `scientist-high.md` | scientist-high | opus | Complex ML/research |
-| `scientist-low.md` | scientist-low | haiku | Quick data inspection |
-| `security-reviewer.md` | security-reviewer | opus | Security audits |
-| `security-reviewer-low.md` | security-reviewer-low | haiku | Quick security scans |
-| `build-fixer.md` | build-fixer | sonnet | Build error resolution |
-| `build-fixer-low.md` | build-fixer-low | haiku | Simple type errors |
-| `tdd-guide.md` | tdd-guide | sonnet | TDD workflow |
-| `tdd-guide-low.md` | tdd-guide-low | haiku | Test suggestions |
-| `code-reviewer.md` | code-reviewer | opus | Expert code review |
-| `code-reviewer-low.md` | code-reviewer-low | haiku | Quick code checks |
-
-## For AI Agents
-
-### Working In This Directory
-
-#### Prompt Template Format
-
-Each file follows this structure:
-```markdown
---
-name: agent-name
-description: Brief description of what this agent does
-model: opus | sonnet | haiku
-tools: [Read, Glob, Grep, ...]
---
-
-# Agent Name
-
-## Role
-What this agent is and its expertise.
-
-## Instructions
-Detailed instructions for how the agent should behave.
-
-## Constraints
-What the agent should NOT do.
-
-## Output Format
-How results should be formatted.
-```
-
-#### Creating a New Agent Prompt
-
-1. Create `new-agent.md` with YAML frontmatter
-2. Define clear role, instructions, and constraints
-3. Reference in `src/agents/definitions.ts`
-
-#### Tiered Variants
-
-For model routing, create variants with complexity-appropriate instructions:
-
-| Tier | File Suffix | Instructions Focus |
-|------|-------------|-------------------|
-| LOW (Haiku) | `-low.md` | Quick, simple tasks, minimal reasoning |
-| MEDIUM (Sonnet) | Base file or `-medium.md` | Standard complexity |
-| HIGH (Opus) | `-high.md` | Complex reasoning, deep analysis |
-
-### Common Patterns
-
-**Frontmatter parsing** (in `definitions.ts`):
-```typescript
-function loadAgentPrompt(agentName: string): string {
-  const content = readFileSync(`agents/${agentName}.md`, 'utf-8');
-  const match = content.match(/^---[\s\S]*?---\s*([\s\S]*)$/);
-  return match ? match[1].trim() : content.trim();
-}
-```
-
-**Tool assignment by agent type:**
- Read-only: `[Read, Glob, Grep]`
- Analysis: `[Read, Glob, Grep, WebSearch, WebFetch]`
- Execution: `[Read, Glob, Grep, Edit, Write, Bash, TodoWrite]`
- Data: `[Read, Glob, Grep, Bash, python_repl]`
-
-### Testing Requirements
-
-Agent prompts are tested via integration tests that spawn agents and verify behavior.
-
-## Dependencies
-
-### Internal
- Loaded by `src/agents/definitions.ts`
- Referenced by skill definitions in `skills/`
-
-### External
-None - pure markdown files.
-
-## Agent Categories
-
-| Category | Agents | Common Tools |
-|----------|--------|--------------|
-| Analysis | architect, architect-medium, architect-low | Read, Glob, Grep, lsp_diagnostics |
-| Execution | executor, executor-low, executor-high | Read, Glob, Grep, Edit, Write, Bash, lsp_diagnostics |
-| Search | explore, explore-medium, explore-high | Read, Glob, Grep, ast_grep_search, lsp_document_symbols, lsp_workspace_symbols |
-| Research | researcher, researcher-low | WebSearch, WebFetch |
-| Frontend | designer, designer-low, designer-high | Edit, Write, Bash |
-| Docs | writer | Edit, Write |
-| Visual | vision | Read, Glob, Grep |
-| Planning | planner, analyst, critic | Read, Glob, Grep |
-| Testing | qa-tester, qa-tester-high | Bash, Read, Grep, Glob, TodoWrite, lsp_diagnostics |
-| Security | security-reviewer, security-reviewer-low | Read, Grep, Bash |
-| Build | build-fixer, build-fixer-low | Read, Glob, Grep, Edit, Write, Bash, lsp_diagnostics, lsp_diagnostics_directory |
-| TDD | tdd-guide, tdd-guide-low | Read, Grep, Glob, Bash, lsp_diagnostics |
-| Review | code-reviewer, code-reviewer-low | Read, Grep, Glob, Bash, lsp_diagnostics |
-| Data | scientist, scientist-low, scientist-high | Read, Glob, Grep, Bash, python_repl |
-
-<!-- MANUAL: -->
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -0,0 +1,100 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-01-31 | Updated: 2026-01-31 -->
+
+# docs
+
+User documentation and technical guides for oh-my-claudecode.
+
+## Purpose
+
+This directory contains documentation for end-users and developers:
+
+- **End-user guides**: How to use oh-my-claudecode features
+- **Technical reference**: Architecture, compatibility, migration
+- **Design documents**: Feature design specifications
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `CLAUDE.md` | End-user orchestration instructions (installed to user projects) |
+| `FEATURES.md` | Developer API reference for internal features |
+| `REFERENCE.md` | API reference and configuration options |
+| `ARCHITECTURE.md` | System architecture overview |
+| `MIGRATION.md` | Version migration guides |
+| `COMPATIBILITY.md` | Compatibility matrix and requirements |
+| `TIERED_AGENTS_V2.md` | Model routing and tiered agent design |
+| `DELEGATION-ENFORCER.md` | Delegation protocol documentation |
+| `SYNC-SYSTEM.md` | State synchronization system |
+| `ANALYTICS-SYSTEM.md` | Analytics collection documentation |
+| `LOCAL_PLUGIN_INSTALL.md` | Plugin installation guide |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `design/` | Feature design specifications |
+
+## For AI Agents
+
+### Working In This Directory
+
+1. **End-User Focus**: CLAUDE.md is installed to user projects - write for end-users, not developers
+2. **Keep Links Accessible**: Use raw GitHub URLs for links in CLAUDE.md (agents can't navigate GitHub UI)
+3. **Version Consistency**: Update version numbers across all docs when releasing
+
+### When to Update Each File
+
+| Trigger | File to Update |
+|---------|---------------|
+| Agent count or list changes | `REFERENCE.md` (Agents section) |
+| Skill count or list changes | `REFERENCE.md` (Skills section) |
+| Hook count or list changes | `REFERENCE.md` (Hooks System section) |
+| Magic keywords change | `REFERENCE.md` (Magic Keywords section) |
+| Agent tool assignments change | `CLAUDE.md` (Agent Tool Matrix) |
+| Skill composition or architecture changes | `ARCHITECTURE.md` |
+| New internal API or feature | `FEATURES.md` |
+| Breaking changes or migrations | `MIGRATION.md` |
+| Tiered agent design updates | `TIERED_AGENTS_V2.md` |
+| Platform or version support changes | `COMPATIBILITY.md` |
+| End-user instructions change | `CLAUDE.md` |
+| Major user-facing features | `../README.md` |
+
+### Testing Requirements
+
+- Verify markdown renders correctly
+- Check all internal links resolve
+- Validate code examples in documentation
+
+### Common Patterns
+
+#### Linking to Raw Content
+
+Use raw GitHub URLs for external accessibility:
+
+[Migration Guide](https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/MIGRATION.md)
+
+#### Version References
+
+Use consistent version heading format with blank line after heading:
+
+```markdown
+## v3.8.14 Changes
+
+- Feature A
+- Feature B
+```
+
+## Dependencies
+
+### Internal
+
+- References agents from `agents/`
+- References skills from `skills/`
+- References tools from `src/tools/`
+
+### External
+
+None - pure markdown files.
+
+<!-- MANUAL: -->
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -62,7 +62,7 @@ Skills: ultrawork + default + git-master
 | MEDIUM | Sonnet | Standard implementations |
 | HIGH | Opus | Complex reasoning, architecture |

-See [FEATURES.md](./FEATURES.md) for the complete agent roster.
+See [REFERENCE.md](./REFERENCE.md) for the complete agent roster.

 ### Delegation

@@ -118,13 +118,16 @@ Legacy locations are auto-migrated on read.

 ## Hooks

-oh-my-claudecode uses Claude Code's hooks system for lifecycle events:
+oh-my-claudecode includes 31 hooks in `src/hooks/` for lifecycle events:

- **conversationStart**: Initialize OMC, check for active modes
- **beforeRequest**: Task delegation, skill routing
- **afterResponse**: State updates, verification checks
+| Event | Purpose |
+|-------|---------|
+| `UserPromptSubmit` | Keyword detection, mode activation |
+| `Stop` | Continuation enforcement, session end |
+| `PreToolUse` | Permission validation |
+| `PostToolUse` | Error recovery, rules injection |

-Hooks are defined in `.claude/hooks/` and managed through the plugin system.
+See [REFERENCE.md](./REFERENCE.md) for the complete hooks list.

 ## Verification Protocol

@@ -143,6 +146,7 @@ Evidence must be fresh (within 5 minutes) and include actual command output.

 ## For More Details

- **API Reference**: See [FEATURES.md](./FEATURES.md)
+- **Complete Reference**: See [REFERENCE.md](./REFERENCE.md)
+- **Internal API**: See [FEATURES.md](./FEATURES.md)
 - **User Guide**: See [README.md](../README.md)
 - **Skills Reference**: See CLAUDE.md in your project
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -366,8 +366,6 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool.

 ### MCP Tools & Agent Capabilities

-*Source of truth: `src/agents/definitions.ts`*
-
 #### Tool Inventory

 | Tool | Category | Purpose | Assigned to Agents? |
@@ -717,4 +715,4 @@ Say "setup omc" or run `/oh-my-claudecode:omc-setup` to configure. After that, e

 ## Migration

-For migration guides from earlier versions, see [MIGRATION.md](./MIGRATION.md).
+For migration guides from earlier versions, see the [Migration Guide](https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/MIGRATION.md).
--- a/docs/DELEGATION-ENFORCER.md
+++ b/docs/DELEGATION-ENFORCER.md
@@ -277,6 +277,5 @@ No migration needed! The enforcer is backward compatible:

 ## Related

- [Model Routing](./MODEL-ROUTING.md) - Intelligent task complexity analysis
 - [Agent Definitions](./AGENTS.md) - Complete agent reference
- [Delegation Categories](./DELEGATION-CATEGORIES.md) - Semantic task grouping
+- [Features Reference](./FEATURES.md) - Model routing and delegation categories
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -7,7 +7,7 @@ This guide covers all migration paths for oh-my-claudecode. Find your current ve
 ## Table of Contents

 - [v3.5.3 → v3.5.5: Test Fixes & Cleanup](#v353--v355-test-fixes--cleanup)
- [v3.5.2 → v3.5.3: Skill Consolidation](#v35--v36-skill-consolidation)
+- [v3.5.2 → v3.5.3: Skill Consolidation](#v352--v353-skill-consolidation)
 - [v2.x → v3.0: Package Rename & Auto-Activation](#v2x--v30-package-rename--auto-activation)
 - [v3.0 → v3.1: Notepad Wisdom & Enhanced Features](#v30--v31-notepad-wisdom--enhanced-features)
 - [v3.x → v4.0: Major Architecture Overhaul](#v3x--v40-major-architecture-overhaul)
--- a/docs/REFERENCE.md
+++ b/docs/REFERENCE.md
@@ -227,6 +227,9 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool.
 | `git-master` | Git expert for atomic commits and history | (silent activation) |
 | `tdd` | TDD enforcement: test-first development | `/oh-my-claudecode:tdd` |
 | `learner` | Extract reusable skill from session | `/oh-my-claudecode:learner` |
+| `build-fix` | Fix build and TypeScript errors | `/oh-my-claudecode:build-fix` |
+| `code-review` | Comprehensive code review | `/oh-my-claudecode:code-review` |
+| `security-review` | Security vulnerability detection | `/oh-my-claudecode:security-review` |

 ### Utility Skills

@@ -286,7 +289,20 @@ All skills are available as slash commands with the prefix `/oh-my-claudecode:`.

 ## Hooks System

-Oh-my-claudecode includes 19 lifecycle hooks that enhance Claude Code's behavior.
+Oh-my-claudecode includes 31 lifecycle hooks that enhance Claude Code's behavior.
+
+### Execution Mode Hooks
+
+| Hook | Description |
+|------|-------------|
+| `autopilot` | Full autonomous execution from idea to working code |
+| `ultrawork` | Maximum parallel agent execution |
+| `ralph` | Persistence until verified complete |
+| `ultrapilot` | Parallel autopilot with file ownership |
+| `ultraqa` | QA cycling until goal met |
+| `swarm` | Coordinated multi-agent with SQLite task claiming |
+| `mode-registry` | Tracks active execution mode (incl. ecomode) |
+| `persistent-mode` | Maintains mode state across sessions |

 ### Core Hooks

@@ -295,18 +311,18 @@ Oh-my-claudecode includes 19 lifecycle hooks that enhance Claude Code's behavior
 | `rules-injector` | Dynamic rules injection with YAML frontmatter parsing |
 | `omc-orchestrator` | Enforces orchestrator behavior and delegation |
 | `auto-slash-command` | Automatic slash command detection and execution |
-| `keyword-detector` | Magic keyword detection (ultrawork, search, analyze) |
-| `ralph-loop` | Self-referential development loop management |
+| `keyword-detector` | Magic keyword detection (ultrawork, ralph, etc.) |
 | `todo-continuation` | Ensures todo list completion |
-| `notepad` | Compaction-resilient memory system with three-tier storage |
+| `notepad` | Compaction-resilient memory system |
+| `learner` | Skill extraction from conversations |

 ### Context & Recovery

 | Hook | Description |
 |------|-------------|
-| `context-window-limit-recovery` | Token limit error handling and recovery |
+| `recovery` | Edit error, session, and context window recovery |
 | `preemptive-compaction` | Context usage monitoring to prevent limits |
-| `session-recovery` | Session state recovery on crashes |
+| `pre-compact` | Pre-compaction processing |
 | `directory-readme-injector` | README context injection |

 ### Quality & Validation
@@ -316,16 +332,20 @@ Oh-my-claudecode includes 19 lifecycle hooks that enhance Claude Code's behavior
 | `comment-checker` | BDD detection and directive filtering |
 | `thinking-block-validator` | Extended thinking validation |
 | `empty-message-sanitizer` | Empty message handling |
-| `edit-error-recovery` | Automatic recovery from edit errors |
-| `post-tool-use` | Remember tag auto-capture to notepad system |
+| `permission-handler` | Permission requests and validation |
+| `think-mode` | Extended thinking detection |

-### Environment & Notifications
+### Coordination & Environment

 | Hook | Description |
 |------|-------------|
+| `subagent-tracker` | Tracks spawned sub-agents |
+| `session-end` | Session termination handling |
 | `non-interactive-env` | CI/non-interactive environment handling |
 | `agent-usage-reminder` | Reminder to use specialized agents |
 | `background-notification` | Background task completion notifications |
+| `plugin-patterns` | Plugin pattern detection |
+| `setup` | Initial setup and configuration |

 ---

--- a/docs/SYNC-SYSTEM.md
+++ b/docs/SYNC-SYSTEM.md
@@ -523,6 +523,4 @@ Potential improvements:

 ## Related

- [Release Workflow](./RELEASE-WORKFLOW.md)
- [Version Management](./VERSIONING.md)
 - [CI/CD Pipeline](../.github/workflows/)
--- a/skills/AGENTS.md
+++ b/skills/AGENTS.md
@@ -1,9 +1,9 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # skills

-32 skill definitions for workflow automation and specialized behaviors.
+37 skill definitions for workflow automation and specialized behaviors.

 ## Purpose

@@ -15,62 +15,71 @@ Skills are reusable workflow templates that can be invoked via `/oh-my-claudecod
 ## Key Files

 ### Execution Mode Skills
+
 | File | Skill | Purpose |
-|------|-------|---------|
-| `autopilot.md` | autopilot | Full autonomous execution from idea to working code |
-| `ultrawork.md` | ultrawork | Maximum parallel agent execution |
-| `ralph.md` | ralph | Persistence until verified complete |
-| `ultrapilot.md` | ultrapilot | Parallel autopilot with file ownership |
-| `swarm.md` | swarm | N coordinated agents with task claiming |
-| `pipeline.md` | pipeline | Sequential agent chaining |
-| `ecomode.md` | ecomode | Token-efficient parallel execution |
-| `ultraqa.md` | ultraqa | QA cycling until goal met |
+|-----------|-------|---------|
+| `autopilot/SKILL.md` | autopilot | Full autonomous execution from idea to working code |
+| `ultrawork/SKILL.md` | ultrawork | Maximum parallel agent execution |
+| `ralph/SKILL.md` | ralph | Persistence until verified complete |
+| `ultrapilot/SKILL.md` | ultrapilot | Parallel autopilot with file ownership |
+| `swarm/SKILL.md` | swarm | N coordinated agents with task claiming |
+| `pipeline/SKILL.md` | pipeline | Sequential agent chaining |
+| `ecomode/SKILL.md` | ecomode | Token-efficient parallel execution |
+| `ultraqa/SKILL.md` | ultraqa | QA cycling until goal met |

 ### Planning Skills
+
 | File | Skill | Purpose |
-|------|-------|---------|
-| `plan.md` | plan | Strategic planning with interview workflow |
-| `ralplan.md` | ralplan | Iterative planning (Planner+Architect+Critic) |
-| `review.md` | review | Review plan with Critic |
-| `analyze.md` | analyze | Deep analysis and investigation |
-| `ralph-init.md` | ralph-init | Initialize PRD for structured ralph |
+|-----------|-------|---------|
+| `plan/SKILL.md` | plan | Strategic planning with interview workflow |
+| `ralplan/SKILL.md` | ralplan | Iterative planning (Planner+Architect+Critic) |
+| `review/SKILL.md` | review | Review plan with Critic |
+| `analyze/SKILL.md` | analyze | Deep analysis and investigation |
+| `ralph-init/SKILL.md` | ralph-init | Initialize PRD for structured ralph |

 ### Code Quality Skills
+
 | File | Skill | Purpose |
-|------|-------|---------|
-| `code-review.md` | code-review | Comprehensive code review |
-| `security-review.md` | security-review | Security vulnerability detection |
-| `tdd.md` | tdd | Test-driven development workflow |
-| `build-fix.md` | build-fix | Fix build and TypeScript errors |
+|-----------|-------|---------|
+| `code-review/SKILL.md` | code-review | Comprehensive code review |
+| `security-review/SKILL.md` | security-review | Security vulnerability detection |
+| `tdd/SKILL.md` | tdd | Test-driven development workflow |
+| `build-fix/SKILL.md` | build-fix | Fix build and TypeScript errors |

 ### Exploration Skills
+
 | File | Skill | Purpose |
-|------|-------|---------|
-| `deepsearch.md` | deepsearch | Thorough codebase search |
-| `deepinit.md` | deepinit | Generate hierarchical AGENTS.md |
-| `research.md` | research | Parallel scientist orchestration |
+|-----------|-------|---------|
+| `deepsearch/SKILL.md` | deepsearch | Thorough codebase search |
+| `deepinit/SKILL.md` | deepinit | Generate hierarchical AGENTS.md |
+| `research/SKILL.md` | research | Parallel scientist orchestration |

 ### Utility Skills
+
 | File | Skill | Purpose |
-|------|-------|---------|
-| `learner.md` | learner | Extract reusable skill from session |
-| `note.md` | note | Save notes for compaction resilience |
-| `cancel.md` | cancel | Cancel any active OMC mode |
-| `hud.md` | hud | Configure HUD display |
-| `doctor.md` | doctor | Diagnose installation issues |
-| `omc-setup.md` | omc-setup | One-time setup wizard |
-| `mcp-setup.md` | mcp-setup | Configure MCP servers |
-| `help.md` | help | Usage guide |
+|-----------|-------|---------|
+| `orchestrate/SKILL.md` | orchestrate | Core multi-agent orchestration (always active) |
+| `learner/SKILL.md` | learner | Extract reusable skill from session |
+| `note/SKILL.md` | note | Save notes for compaction resilience |
+| `cancel/SKILL.md` | cancel | Cancel any active OMC mode |
+| `hud/SKILL.md` | hud | Configure HUD display |
+| `doctor/SKILL.md` | doctor | Diagnose installation issues |
+| `omc-setup/SKILL.md` | omc-setup | One-time setup wizard |
+| `mcp-setup/SKILL.md` | mcp-setup | Configure MCP servers |
+| `help/SKILL.md` | help | Usage guide |
+| `learn-about-omc/SKILL.md` | learn-about-omc | Usage pattern analysis |
+| `skill/SKILL.md` | skill | Manage local skills |

 ### Domain Skills
+
 | File | Skill | Purpose |
-|------|-------|---------|
-| `frontend-ui-ux.md` | frontend-ui-ux | Designer-developer aesthetic |
-| `git-master.md` | git-master | Git expertise, atomic commits |
-| `project-session-manager.md` | psm | Isolated dev environments |
-| `writer-memory.md` | writer-memory | Agentic memory for writers |
-| `release.md` | release | Automated release workflow |
-| `local-skills-setup.md` | local-skills-setup | Manage local skills |
+|-----------|-------|---------|
+| `frontend-ui-ux/SKILL.md` | frontend-ui-ux | Designer-developer aesthetic |
+| `git-master/SKILL.md` | git-master | Git expertise, atomic commits |
+| `project-session-manager/SKILL.md` | psm | Isolated dev environments |
+| `writer-memory/SKILL.md` | writer-memory | Agentic memory for writers |
+| `release/SKILL.md` | release | Automated release workflow |
+| `local-skills-setup/SKILL.md` | local-skills-setup | Manage local skills |

 ## For AI Agents

@@ -121,10 +130,13 @@ Any configurable options.

 #### Creating a New Skill

-1. Create `new-skill.md` with YAML frontmatter
+1. Create `new-skill/SKILL.md` directory and file with YAML frontmatter
 2. Define purpose, workflow, and usage
 3. Add to skill registry (auto-detected from frontmatter)
 4. Optionally add activation triggers
+5. Create corresponding `commands/new-skill.md` file (mirror)
+6. Update `docs/REFERENCE.md` (Skills section, count)
+7. If execution mode skill, also create `src/hooks/new-skill/` hook

 ### Common Patterns

@@ -148,7 +160,10 @@ Any configurable options.

 ### Testing Requirements

-Skills are tested via integration tests that invoke skills and verify behavior.
+- Skills are verified via integration tests
+- Test skill invocation with `/oh-my-claudecode:skill-name`
+- Verify trigger keywords activate correct skill
+- For git-related skills, follow `templates/rules/git-workflow.md`

 ## Dependencies

--- a/src/AGENTS.md
+++ b/src/AGENTS.md
@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # src

@@ -8,9 +8,10 @@ TypeScript source code for oh-my-claudecode - the core library that powers multi
 ## Purpose

 This directory contains all TypeScript source code organized into modules:
+
 - **agents/** - 32 specialized AI agent definitions with tiered variants
- **tools/** - LSP/AST/REPL tools for IDE-like capabilities
- **hooks/** - 30+ event-driven behaviors for execution modes
+- **tools/** - 15 LSP/AST/REPL tools for IDE-like capabilities
+- **hooks/** - 31 event-driven behaviors for execution modes
 - **features/** - Core features (model routing, state management, verification)
 - **config/** - Configuration loading and validation
 - **commands/** - Command expansion utilities
@@ -28,8 +29,8 @@ This directory contains all TypeScript source code organized into modules:
 | Directory | Purpose |
 |-----------|---------|
 | `agents/` | 32 agent definitions with prompts and tools (see `agents/AGENTS.md`) |
-| `tools/` | LSP, AST, and Python REPL tools (see `tools/AGENTS.md`) |
-| `hooks/` | 30+ hooks for execution modes (see `hooks/AGENTS.md`) |
+| `tools/` | 15 LSP, AST, and Python REPL tools (see `tools/AGENTS.md`) |
+| `hooks/` | 31 hooks for execution modes (see `hooks/AGENTS.md`) |
 | `features/` | Core features like model routing, state (see `features/AGENTS.md`) |
 | `config/` | Configuration loading (`loader.ts`) |
 | `commands/` | Command expansion utilities |
@@ -58,11 +59,12 @@ This directory contains all TypeScript source code organized into modules:
   ```

 3. **Tool Registration**: Custom tools are registered in `tools/index.ts`:
+
   ```typescript
   export const allCustomTools = [
     ...lspTools,      // 12 LSP tools
     ...astTools,      // 2 AST tools
-     pythonReplTool    // 1 REPL tool
+     pythonReplTool    // 1 REPL tool (15 total)
   ];
   ```

@@ -72,39 +74,55 @@ This directory contains all TypeScript source code organized into modules:
     return {
       architect: architectAgent,
       executor: executorAgent,
-       // ... 30 more agents
+       // ... all 32 agents
     };
   }
   ```

 ### Testing Requirements

-```bash
-# From project root
-npm test                    # Run all tests
-npm run test:run            # Run once without watch
-npm run test:coverage       # With coverage report
-```
-
-Test files are in `__tests__/` with pattern `*.test.ts`.
+- Test files are in `__tests__/` with pattern `*.test.ts`
+- Run `npm test -- --grep "module-name"` for specific modules
+- Verify type safety with `npm run build` after changes
+- Use `lsp_diagnostics_directory` tool for project-wide type checking

 ### Common Patterns

-**Creating a new agent:**
+#### Creating a New Agent
+
 1. Add agent file in `agents/` (e.g., `new-agent.ts`)
 2. Export from `agents/index.ts`
 3. Add to `getAgentDefinitions()` in `agents/definitions.ts`
 4. Create prompt template in `/agents/new-agent.md`
+5. Update `docs/REFERENCE.md` (Agents section) with new agent
+
+#### Adding a New Hook

-**Adding a new hook:**
 1. Create directory in `hooks/` (e.g., `new-hook/`)
 2. Add `index.ts`, `types.ts`, `constants.ts`
 3. Export from `hooks/index.ts`
+4. Update `docs/REFERENCE.md` (Hooks System section) with new hook
+
+#### Adding a New Tool

-**Adding a new tool:**
 1. Create tool definition with Zod schema
 2. Add to appropriate tools file (`lsp-tools.ts`, `ast-tools.ts`)
 3. Export from `tools/index.ts`
+4. Update `docs/REFERENCE.md` if user-facing tool
+
+#### Adding a New Feature
+
+1. Create feature directory in `features/`
+2. Export from `features/index.ts`
+3. Update `docs/FEATURES.md` with API documentation
+
+#### TypeScript Conventions
+
+- Use strict mode (`noImplicitAny`, `strictNullChecks`)
+- Prefer interfaces over type aliases for public APIs
+- Use barrel exports (`index.ts`) for each module
+- File size: 200-400 lines typical, 800 max
+- Use Zod for runtime input validation (see `templates/rules/coding-style.md`)

 ## Dependencies

@@ -114,13 +132,8 @@ Test files are in `__tests__/` with pattern `*.test.ts`.
 - Loads skills from `/skills/*.md`

 ### External
-| Package | Used In | Purpose |
-|---------|---------|---------|
-| `zod` | tools, features | Runtime type validation |
-| `@ast-grep/napi` | tools/ast-tools.ts | AST parsing and searching |
-| `vscode-languageserver-protocol` | tools/lsp/ | LSP types |
-| `better-sqlite3` | hooks/swarm/ | Task coordination DB |
-| `chalk` | cli/, hud/ | Terminal colors |
+
+Key packages by module: `zod` (tools, features), `@ast-grep/napi` (tools/ast), `vscode-languageserver-protocol` (tools/lsp), `better-sqlite3` (hooks/swarm), `chalk` (cli, hud). See root AGENTS.md for full dependency list.

 ## Module Dependency Graph

--- a/src/agents/AGENTS.md
+++ b/src/agents/AGENTS.md
@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # agents

@@ -8,8 +8,10 @@
 ## Purpose

 This directory defines all agents available in oh-my-claudecode:
+
 - **12 base agents** with default model assignments
- **20 tiered variants** (LOW/MEDIUM/HIGH) for smart routing
+- **4 specialized agents** (security-reviewer, build-fixer, tdd-guide, code-reviewer)
+- **16 tiered variants** (LOW/MEDIUM/HIGH) for smart routing
 - Prompts loaded dynamically from `/agents/*.md` files
 - Tools assigned based on agent specialization

@@ -165,9 +167,38 @@ export const newAgentHigh: AgentConfig = {
 };
 ```

+### Modification Checklist
+
+#### When Adding a New Agent
+
+1. Create agent file (`src/agents/new-agent.ts`)
+2. Create prompt template (`agents/new-agent.md`)
+3. Add to `definitions.ts` (import + registry)
+4. Export from `index.ts`
+5. Update `docs/REFERENCE.md` (Agents section, count)
+6. Update `docs/CLAUDE.md` (Agent Selection Guide)
+7. Update root `/AGENTS.md` (Agent Summary if applicable)
+
+#### When Modifying an Agent
+
+1. Update agent file (`src/agents/*.ts`) if changing tools/model
+2. Update prompt template (`agents/*.md`) if changing behavior
+3. Update tiered variants (`-low`, `-medium`, `-high`) if applicable
+4. Update `docs/REFERENCE.md` if changing agent description/capabilities
+5. Update `docs/CLAUDE.md` (Agent Tool Matrix) if changing tool assignments
+
+#### When Removing an Agent
+
+1. Remove agent file from `src/agents/`
+2. Remove prompt template from `agents/`
+3. Remove from `definitions.ts` and `index.ts`
+4. Update agent counts in all documentation
+5. Check for skill/hook references to the removed agent
+
 ### Testing Requirements

 Agents are tested via integration tests:
+
 ```bash
 npm test -- --grep "agent"
 ```
--- a/src/features/AGENTS.md
+++ b/src/features/AGENTS.md
@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # features

@@ -127,9 +127,25 @@ const config = getCategoryConfig(category);
 // { tier: 'HIGH', temperature: 0.3, thinking: 'max' }
 ```

+### Modification Checklist
+
+#### When Adding a New Feature
+
+1. Create feature directory with `index.ts`, `types.ts`, `constants.ts`
+2. Export from `features/index.ts`
+3. Update `docs/FEATURES.md` with API documentation
+4. Update `docs/AGENTS.md` if architecture changes
+
+#### When Modifying State File Paths
+
+1. Update `state-manager/` for path standardization
+2. Consider migration logic for existing state files
+3. Document new paths in feature's README or AGENTS.md
+
 ### Common Patterns

-**Feature module structure:**
+#### Feature Module Structure
+
 ```
 feature-name/
 ├── index.ts     # Main exports
--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@@ -1,14 +1,14 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # hooks

-30+ event-driven hooks that power execution modes and behaviors.
+31 event-driven hooks that power execution modes and behaviors.

 ## Purpose

 Hooks intercept Claude Code events to enable:
- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline
+- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline (ecomode via mode-registry)
 - **Validation**: thinking blocks, empty messages, comments
 - **Recovery**: edit errors, session recovery, context window
 - **Enhancement**: rules injection, directory READMEs, notepad
@@ -19,6 +19,7 @@ Hooks intercept Claude Code events to enable:
 | File | Description |
 |------|-------------|
 | `index.ts` | Re-exports all hooks |
+| `bridge.ts` | Shell script entry point - `processHook()` routes events to handlers |

 ## Subdirectories

@@ -32,7 +33,8 @@ Hooks intercept Claude Code events to enable:
 | `ultrapilot/` | Parallel autopilot with file ownership | "ultrapilot" |
 | `swarm/` | N coordinated agents with task claiming | "swarm N agents" |
 | `ultraqa/` | QA cycling until goal met | test failures |
-| `mode-registry/` | Tracks active execution mode | internal |
+| `mode-registry/` | Tracks active execution mode (incl. ecomode) | internal |
+| `persistent-mode/` | Maintains mode state across sessions | internal |

 ### Validation Hooks

@@ -41,6 +43,7 @@ Hooks intercept Claude Code events to enable:
 | `thinking-block-validator/` | Validates thinking blocks in responses |
 | `empty-message-sanitizer/` | Handles empty/whitespace messages |
 | `comment-checker/` | Checks code comment quality |
+| `permission-handler/` | Handles permission requests and validation |

 ### Recovery Hooks

@@ -48,6 +51,7 @@ Hooks intercept Claude Code events to enable:
 |-----------|---------|
 | `recovery/` | Edit error recovery, session recovery |
 | `preemptive-compaction/` | Prevents context overflow |
+| `pre-compact/` | Pre-compaction processing |

 ### Enhancement Hooks

@@ -67,6 +71,7 @@ Hooks intercept Claude Code events to enable:
 | `think-mode/` | Extended thinking detection |
 | `auto-slash-command/` | Slash command expansion |
 | `non-interactive-env/` | Non-interactive environment detection |
+| `plugin-patterns/` | Plugin pattern detection |

 ### Coordination Hooks

@@ -74,6 +79,15 @@ Hooks intercept Claude Code events to enable:
 |-----------|---------|
 | `todo-continuation/` | Enforces task completion |
 | `omc-orchestrator/` | Orchestrator behavior |
+| `subagent-tracker/` | Tracks spawned sub-agents |
+| `session-end/` | Session termination handling |
+| `background-notification/` | Background task notifications |
+
+### Setup Hooks
+
+| Directory | Purpose |
+|-----------|---------|
+| `setup/` | Initial setup and configuration |

 ## For AI Agents

@@ -90,6 +104,14 @@ hook-name/
 └── *.ts         # Supporting modules
 ```

+#### When Adding a New Hook
+
+1. Create hook directory with `index.ts`, `types.ts`, `constants.ts`
+2. Export from `index.ts` (hook re-exports)
+3. Register handler in `bridge.ts` if needed
+4. Update `docs/REFERENCE.md` (Hooks System section) with new hook entry
+5. If execution mode hook, also create `skills/*/SKILL.md` and `commands/*.md`
+
 #### Hook Implementation

 ```typescript
@@ -145,7 +167,8 @@ export function createHook(config: HookConfig) {

 ### Common Patterns

-**State management:**
+#### State Management
+
 ```typescript
 import { readState, writeState } from '../features/state-manager';

@@ -154,7 +177,8 @@ state.phase = 'executing';
 writeState('autopilot-state', state);
 ```

-**Event handling:**
+#### Event Handling
+
 ```typescript
 // UserPromptSubmit - Before prompt is sent
 // Stop - Before session ends
@@ -164,13 +188,10 @@ writeState('autopilot-state', state);

 ### Testing Requirements

-```bash
-# Test specific hook
-npm test -- --grep "autopilot"
-
-# Test all hooks
-npm test -- --grep "hooks"
-```
+- Test specific hooks with `npm test -- --grep "hook-name"`
+- Test execution modes end-to-end with skill invocation
+- Verify state persistence in `.omc/state/`
+- For security hooks, follow `templates/rules/security.md` checklist

 ## Dependencies

--- a/src/tools/AGENTS.md
+++ b/src/tools/AGENTS.md
@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
+<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->

 # tools

@@ -127,6 +127,17 @@ The `lsp_diagnostics_directory` tool supports two strategies:

 **Recommendation**: Use `strategy: "auto"` (default) - it prefers `tsc` when available.

+### Modification Checklist
+
+#### When Adding a New Tool
+
+1. Define tool in appropriate file (`lsp-tools.ts`, `ast-tools.ts`, or new file)
+2. Export from `index.ts` (add to `allCustomTools`)
+3. Update `src/mcp/omc-tools-server.ts` if exposed via MCP
+4. Update `docs/REFERENCE.md` (MCP Tools section)
+5. Update agent tool assignments in `src/agents/definitions.ts` if needed
+6. Update `docs/CLAUDE.md` (Agent Tool Matrix) if assigned to agents
+
 ### Testing Requirements

 ```bash