@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/REFERENCE.md

@@ -1,19 +1,42 @@
-# 参考文档
+<!-- ultrapower v5.5.5 | updated: 2026-03-02 -->
 
-ultrapower 完整参考手册。快速入门请参阅 [README.md](../README.md)。
+# ultrapower Reference — v5.5.5
+
+Complete reference manual for ultrapower. For quick start see [README.md](../README.md).
 
 ---
 
-## 目录
+## Table of Contents
 
-- [Installation](#installation)
+- [Installation & Quick Start](#installation--quick-start)
 - [Configuration](#configuration)
-- [Agents (49 Total)](#agents-49-total)
-- [Skills (71 Total)](#skills-71-total)
-- [Slash Commands](#slash-commands)
-- [Hooks System](#hooks-system)
+- [Execution Modes](#execution-modes)
+- [Agents (49 total)](#agents-49-total)
+  - [Build/Analysis Lane (8)](#buildanalysis-lane-8)
+  - [Review Lane (6)](#review-lane-6)
+  - [Domain Specialists (16)](#domain-specialists-16)
+  - [Product Lane (4)](#product-lane-4)
+  - [Axiom Lane (14)](#axiom-lane-14)
+  - [Coordination (1)](#coordination-1)
+- [Skills (71 total)](#skills-71-total)
+  - [Workflow Skills](#workflow-skills)
+  - [Axiom Skills](#axiom-skills)
+  - [Superpowers Skills](#superpowers-skills)
+  - [Agent Shortcuts](#agent-shortcuts)
+  - [Utility Skills](#utility-skills)
+- [Custom Tools (35 total)](#custom-tools-35-total)
+  - [LSP Tools (12)](#lsp-tools-12)
+  - [AST Tools (2)](#ast-tools-2)
+  - [Python REPL (1)](#python-repl-1)
+  - [Notepad Tools (6)](#notepad-tools-6)
+  - [State Tools (5)](#state-tools-5)
+  - [Project Memory Tools (4)](#project-memory-tools-4)
+  - [Trace Tools (2)](#trace-tools-2)
+  - [Skills Tools (3)](#skills-tools-3)
+- [Hooks System (35 hooks)](#hooks-system-35-hooks)
+- [MCP Integration](#mcp-integration)
+- [Security & Safety Rules](#security--safety-rules)
 - [Magic Keywords](#magic-keywords)
-- [MCP Path Boundary Rules](#mcp-path-boundary-rules)
 - [Platform Support](#platform-support)
 - [Performance Monitoring](#performance-monitoring)
 - [Troubleshooting](#troubleshooting)
@@ -21,90 +44,109 @@ ultrapower 完整参考手册。快速入门请参阅 [README.md](../README.md)
 
 ---
 
-## Installation
+## Installation & Quick Start
 
-**仅支持 Claude Code Plugin 安装方式。** 其他安装方式（npm、bun、curl）已废弃，可能无法正常工作。
+**Only the Claude Code Plugin installation method is supported.** Other methods (npm, bun, curl) are deprecated and may not work correctly.
 
-### Claude Code Plugin（必须）
+### Claude Code Plugin (Required)
 
 ```bash
-# 第一步：添加插件市场
+# Step 1: Add the plugin marketplace
 /plugin marketplace add https://github.com/liangjie559567/ultrapower
 
-# 第二步：安装插件
+# Step 2: Install the plugin
 /plugin install omc@ultrapower
 ```
 
-此方式直接集成到 Claude Code 的插件系统，使用 Node.js hooks。
+This method integrates directly into Claude Code's plugin system using Node.js hooks.
+
+> **Note**: Direct global installation via npm/bun is **not supported**. The plugin system handles all installation and hook configuration automatically.
+
+### System Requirements
+
+- [Claude Code](https://docs.anthropic.com/claude-code) installed
+- One of:
+  - **Claude Max/Pro subscription** (recommended for personal use)
+  - **Anthropic API key** (`ANTHROPIC_API_KEY` environment variable)
 
-> **注意**：**不支持**直接通过 npm/bun 全局安装。插件系统会自动处理所有安装和 hook 配置。
+### Quick Start
 
-### 系统要求
+After installation, run the setup wizard:
+
+```
+/ultrapower:omc-setup
+```
 
-- 已安装 [Claude Code](https://docs.anthropic.com/claude-code)
-- 以下之一：
-  - **Claude Max/Pro 订阅**（推荐个人用户）
-  - **Anthropic API key**（`ANTHROPIC_API_KEY` 环境变量）
+Then try your first execution mode:
+
+```bash
+# Autonomous execution
+autopilot: build a REST API with authentication
+
+# Maximum parallel agents
+ultrawork: implement user authentication with OAuth
+
+# Persistent execution loop
+ralph: refactor the authentication module
+```
 
 ---
 
 ## Configuration
 
-### 项目级配置（推荐）
+### Project-Level Configuration (Recommended)
 
-仅为当前项目配置 omc：
+Configure omc for the current project only:
 
 ```
 /ultrapower:omc-setup
 ```
 
-- 在当前项目中创建 `./.claude/CLAUDE.md`
-- 配置仅对本项目生效
-- 不影响其他项目或全局设置
-- **安全**：保留你的全局 CLAUDE.md
+- Creates `./.claude/CLAUDE.md` in the current project
+- Configuration applies only to this project
+- Does not affect other projects or global settings
+- **Safe**: Preserves your global CLAUDE.md
 
-### 全局配置
+### Global Configuration
 
-为所有 Claude Code 会话配置 omc：
+Configure omc for all Claude Code sessions:
 
 ```
 /ultrapower:omc-setup
 ```
 
-- 在全局创建 `~/.claude/CLAUDE.md`
-- 配置对所有项目生效
-- **警告**：会完全覆盖已有的 `~/.claude/CLAUDE.md`
-
-### 配置启用的功能
+- Creates `~/.claude/CLAUDE.md` globally
+- Configuration applies to all projects
+- **Warning**: Will completely overwrite existing `~/.claude/CLAUDE.md`
 
-| 功能 | 未配置 | 配置 omc 后 |
-|---------|---------|-----------------|
-| Agent delegation | 仅手动 | 根据任务自动委派 |
-| Keyword detection | 禁用 | ultrawork、search、analyze |
-| Todo continuation | 基础 | 强制完成 |
-| Model routing | 默认 | 智能分级选择 |
-| Skill composition | 无 | 自动组合 skills |
+### Configuration Priority
 
-### 配置优先级
-
-若两种配置同时存在，**项目级配置优先于**全局配置：
+When both configurations exist, **project-level overrides** global:
 
 ```
-./.claude/CLAUDE.md  (project)   →  Overrides  →  ~/.claude/CLAUDE.md  (global)
+./.claude/CLAUDE.md  (project)   ->  Overrides  ->  ~/.claude/CLAUDE.md  (global)
 ```
 
-### 何时重新运行 Setup
+### Features Enabled by Configuration
+
+| Feature | Without Config | With omc Config |
+|---------|---------------|-----------------|
+| Agent delegation | Manual only | Auto-delegated by task type |
+| Keyword detection | Disabled | ultrawork, search, analyze |
+| Todo continuation | Basic | Forced completion |
+| Model routing | Default | Smart tiered selection |
+| Skill composition | None | Automatic composition |
 
-- **首次使用**：安装后运行（选择项目级或全局）
-- **更新后**：重新运行以获取最新配置
-- **不同机器**：在每台使用 Claude Code 的机器上运行
-- **新项目**：在每个需要 omc 的项目中运行 `/ultrapower:omc-setup --local`
+### When to Re-run Setup
 
-> **注意**：通过 `npm update`、`git pull` 或 Claude Code 插件更新后，必须重新运行 `/ultrapower:omc-setup` 以应用最新的 CLAUDE.md 变更。
+- **First time**: Run after installation (choose project or global)
+- **After updates**: Re-run to get the latest configuration
+- **Different machines**: Run on each machine using Claude Code
+- **New projects**: Run `/ultrapower:omc-setup --local` in each project that needs omc
 
-### 权限配置（步骤 3.75）
+### Permission Configuration
 
-omc-setup 包含一个权限配置步骤，自动将常用工具权限写入 `~/.claude/settings.json`：
+omc-setup includes a permission step that automatically writes common tool permissions to `~/.claude/settings.json`:
 
 ```json
 {
@@ -124,11 +166,9 @@ omc-setup 包含一个权限配置步骤，自动将常用工具权限写入 `~/
 }
 ```
 
-此步骤避免每次工具调用时弹出权限确认对话框，提升工作流流畅度。如需跳过，在 setup 过程中选择"跳过"即可。
+### Agent Customization
 
-### Agent 自定义
-
-编辑 `~/.claude/agents/` 中的 agent 文件以自定义行为：
+Edit agent files in `~/.claude/agents/` to customize behavior:
 
 ```yaml
 ---
@@ -141,27 +181,23 @@ model: opus  # or sonnet, haiku
 Your custom system prompt here...
 ```
 
-### 项目级配置文件
-
-在项目中创建 `.claude/CLAUDE.md` 以添加项目专属说明：
+### Config File Reference
 
-```markdown
-# Project Context
+`~/.claude/.omc-config.json`:
 
-This is a TypeScript monorepo using:
-- Bun runtime
-- React for frontend
-- PostgreSQL database
-
-## Conventions
-- Use functional components
-- All API routes in /src/api
-- Tests alongside source files
+```json
+{
+  "defaultExecutionMode": "ultrawork",
+  "mcpServers": {
+    "context7": { "enabled": true },
+    "exa": { "enabled": true, "apiKey": "..." }
+  }
+}
 ```
 
-### Stop Callback 通知标签
+### Stop Callback Notification Tags
 
-使用 `omc config-stop-callback` 为 Telegram/Discord stop callbacks 配置标签。
+Use `omc config-stop-callback` to configure tags for Telegram/Discord stop callbacks:
 
 ```bash
 # Set/replace tags
@@ -178,711 +214,828 @@ omc config-stop-callback telegram --show
 omc config-stop-callback discord --show
 ```
 
-标签行为：
-- Telegram：`alice` 会被规范化为 `@alice`
-- Discord：支持 `@here`、`@everyone`、数字用户 ID（`<@id>`）和角色标签（`role:<id>` -> `<@&id>`）
-- `file` 类型的 callbacks 忽略标签选项
+Tag behavior:
+- Telegram: `alice` is normalized to `@alice`
+- Discord: supports `@here`, `@everyone`, numeric user IDs (`<@id>`), and role tags (`role:<id>` -> `<@&id>`)
+- `file` type callbacks ignore tag options
+
+---
+
+## Execution Modes
+
+ultrapower provides 6 execution modes for different workflow needs:
+
+| Mode | Trigger Keywords | Description |
+|------|-----------------|-------------|
+| `autopilot` | "autopilot", "build me", "I want a" | Fully autonomous execution from idea to working code |
+| `ultrawork` | "ulw", "ultrawork" | Maximum parallel agent execution |
+| `ralph` | "ralph", "don't stop", "must complete" | Self-referential loop until verified complete |
+| `ultrapilot` | "ultrapilot", "parallel build" | Parallel autopilot with file ownership (Team compatibility facade) |
+| `swarm` | "swarm" | N coordinated agents using Team pipeline (compatibility facade) |
+| `pipeline` | "pipeline", "chain agents" | Sequential agent chain with data passing |
+
+### Mode Details
+
+**autopilot** — Full autonomous execution. Detects task complexity, routes to appropriate agents, executes, validates with verifier. Can escalate to ralph for persistence or ultraqa for QA loops.
+
+**ultrawork** — Maximum parallelism. Spawns multiple agents simultaneously for independent subtasks. Ideal for large-scale refactors or multi-file implementations.
+
+**ralph** — Persistent execution loop. Runs until the verifier confirms completion. Includes ultrawork. Suitable for complex tasks that require multiple iterations.
+
+**ultrapilot** — Maps to Team's phased runtime. Provides parallel execution with agent ownership tracking. Mutually exclusive with autopilot.
+
+**swarm** — Routes to Team's phased pipeline. Preserves `/swarm` syntax. N coordinated agents with task claiming.
+
+**pipeline** — Sequential agent chain. Each stage's output becomes the next stage's input. Explicit data passing between agents.
+
+### Team Pipeline Phases
+
+The Team pipeline used by swarm/ultrapilot follows:
+
+```
+team-plan -> team-prd -> team-exec -> team-verify -> team-fix (loop)
+```
+
+Phase agent routing:
+- `team-plan`: `explore` (haiku) + `planner` (opus), optional `analyst`/`architect`
+- `team-prd`: `analyst` (opus), optional `product-manager`/`critic`
+- `team-exec`: `executor` (sonnet) + domain specialists as needed
+- `team-verify`: `verifier` (sonnet) + reviewers as needed
+- `team-fix`: `executor`/`build-fixer`/`debugger` based on defect type
+
+Terminal states: `complete`, `failed`, `cancelled`.
+
+---
+
+## Agents (49 total)
+
+All agents are invoked via the `ultrapower:` prefix in Task calls.
+
+### Agent Selection Guide
+
+| Task Type | Best Agent | Model |
+|-----------|-----------|-------|
+| Fast code lookup | `explore` | haiku |
+| Feature implementation | `executor` | sonnet |
+| Complex refactor / autonomous tasks | `deep-executor` | opus |
+| Debug / root cause | `debugger` | sonnet |
+| Completion verification | `verifier` | sonnet |
+| System design / architecture | `architect` | opus |
+| Strategic planning | `planner` | opus |
+| Requirements analysis | `analyst` | opus |
+| Review / critique a plan | `critic` | opus |
+| UI components / design | `designer` | sonnet |
+| Write docs / comments | `writer` | haiku |
+| Research docs / APIs | `document-specialist` | sonnet |
+| Analyze images / diagrams | `vision` | sonnet |
+| Interactive CLI testing | `qa-tester` | sonnet |
+| Security review | `security-reviewer` | sonnet |
+| Fix build errors | `build-fixer` | sonnet |
+| TDD workflow | `test-engineer` | sonnet |
+| Comprehensive code review | `code-reviewer` | opus |
+| Data analysis / statistics | `scientist` | sonnet |
+| External packages / SDKs | `dependency-expert` | sonnet |
+| Git commits / history | `git-master` | sonnet |
+| Product requirements / PRD | `product-manager` | sonnet |
+| Usability / accessibility audit | `ux-researcher` | sonnet |
+| Information architecture | `information-architect` | sonnet |
+| Product metrics / experiments | `product-analyst` | sonnet |
+
+---
+
+### Build/Analysis Lane (8)
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| `explore` | haiku | Codebase discovery, symbol/file mapping |
+| `analyst` | opus | Requirements clarification, acceptance criteria, hidden constraints |
+| `planner` | opus | Task ordering, execution plans, risk flagging |
+| `architect` | opus | System design, boundaries, interfaces, long-term trade-offs |
+| `debugger` | sonnet | Root cause analysis, regression isolation, fault diagnosis |
+| `executor` | sonnet | Code implementation, refactoring, feature development |
+| `deep-executor` | opus | Complex autonomous goal-directed tasks |
+| `verifier` | sonnet | Completion evidence, claim verification, test adequacy |
+
+---
+
+### Review Lane (6)
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| `style-reviewer` | haiku | Formatting, naming, idiomatic style, lint rules |
+| `quality-reviewer` | sonnet | Logic defects, maintainability, anti-patterns |
+| `api-reviewer` | sonnet | API contracts, versioning, backward compatibility |
+| `security-reviewer` | sonnet | Vulnerabilities, trust boundaries, auth/authz |
+| `performance-reviewer` | sonnet | Hotspots, complexity, memory/latency optimization |
+| `code-reviewer` | opus | Cross-concern comprehensive review |
+
+---
+
+### Domain Specialists (16)
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| `dependency-expert` | sonnet | External SDK/API/package evaluation |
+| `test-engineer` | sonnet | Test strategy, coverage, flaky test hardening |
+| `quality-strategist` | sonnet | Quality strategy, release readiness, risk assessment |
+| `build-fixer` | sonnet | Build/toolchain/type error repair |
+| `designer` | sonnet | UX/UI architecture, interaction design |
+| `writer` | haiku | Documentation, migration notes, user guides |
+| `qa-tester` | sonnet | Interactive CLI/service runtime validation |
+| `scientist` | sonnet | Data/statistical analysis |
+| `document-specialist` | sonnet | External documentation and reference lookup |
+| `git-master` | sonnet | Commit strategy, history management |
+| `vision` | sonnet | Image/screenshot/diagram analysis |
+| `database-expert` | sonnet | Database design, query optimization, and migrations |
+| `devops-engineer` | sonnet | CI/CD, containerization, infrastructure-as-code |
+| `i18n-specialist` | sonnet | Internationalization, localization, multilingual support |
+| `accessibility-auditor` | sonnet | Web accessibility review and WCAG compliance |
+| `api-designer` | sonnet | REST/GraphQL API design and contract definition |
+
+Deprecated aliases (backward compatible):
+- `researcher` -> `document-specialist`
+- `tdd-guide` -> `test-engineer`
+
+---
+
+### Product Lane (4)
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| `product-manager` | sonnet | Problem framing, user personas/JTBD, PRD |
+| `ux-researcher` | sonnet | Heuristic audit, usability, accessibility |
+| `information-architect` | sonnet | Taxonomy, navigation, discoverability |
+| `product-analyst` | sonnet | Product metrics, funnel analysis, experiments |
+
+---
+
+### Axiom Lane (14)
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| `axiom-requirement-analyst` | sonnet | Requirements tri-state gate (PASS/CLARIFY/REJECT) |
+| `axiom-product-designer` | sonnet | Draft PRD generation with Mermaid flowcharts |
+| `axiom-review-aggregator` | sonnet | 5-expert parallel review aggregation and conflict arbitration |
+| `axiom-prd-crafter` | sonnet | Engineering-grade PRD with gated validation |
+| `axiom-system-architect` | sonnet | Atomic task DAG and Manifest generation |
+| `axiom-evolution-engine` | sonnet | Knowledge harvesting, pattern detection, workflow optimization |
+| `axiom-context-manager` | sonnet | 7-operation memory system (read/write/state/checkpoint) |
+| `axiom-worker` | sonnet | PM->Worker protocol, tri-state output (QUESTION/COMPLETE/BLOCKED) |
+| `axiom-ux-director` | sonnet | UX/experience expert review, outputs review_ux.md |
+| `axiom-product-director` | sonnet | Product strategy expert review, outputs review_product.md |
+| `axiom-domain-expert` | sonnet | Domain knowledge expert review, outputs review_domain.md |
+| `axiom-tech-lead` | sonnet | Technical feasibility review, outputs review_tech.md |
+| `axiom-critic` | sonnet | Security/quality/logic review, outputs review_critic.md |
+| `axiom-sub-prd-writer` | sonnet | Decompose Manifest tasks into executable Sub-PRDs |
 
 ---
 
-## Agents（49 Total）
-
-通过 Task 工具调用时，始终使用 `ultrapower:` 前缀。
-
-### 按领域和层级分类
-
-| 领域 | Agent | 默认模型 | 说明 |
-|--------|-------|----------|------|
-| **分析/规划** | `explore` | haiku | 代码库发现、符号/文件映射 |
-| **分析/规划** | `analyst` | opus | 需求分析、验收标准 |
-| **分析/规划** | `planner` | opus | 任务排序、执行计划 |
-| **分析/规划** | `architect` | opus | 系统设计、接口、长期权衡 |
-| **执行** | `debugger` | sonnet | 根因分析、回归隔离 |
-| **执行** | `executor` | sonnet | 代码实现、重构、功能开发 |
-| **执行** | `deep-executor` | opus | 复杂自主目标导向任务 |
-| **执行** | `verifier` | sonnet | 完成证据、声明验证 |
-| **代码审查** | `style-reviewer` | haiku | 格式、命名、lint 规范 |
-| **代码审查** | `quality-reviewer` | sonnet | 逻辑缺陷、可维护性 |
-| **代码审查** | `api-reviewer` | sonnet | API 契约、版本兼容性 |
-| **代码审查** | `security-reviewer` | sonnet | 漏洞、信任边界、认证授权 |
-| **代码审查** | `performance-reviewer` | sonnet | 热点、复杂度、内存/延迟 |
-| **代码审查** | `code-reviewer` | opus | 跨关注点综合审查 |
-| **领域专家** | `dependency-expert` | sonnet | 外部 SDK/API/包评估 |
-| **领域专家** | `test-engineer` | sonnet | 测试策略、覆盖率、flaky 测试 |
-| **领域专家** | `quality-strategist` | sonnet | 质量策略、发布就绪、风险评估 |
-| **领域专家** | `build-fixer` | sonnet | 构建/工具链/类型错误修复 |
-| **领域专家** | `designer` | sonnet | UX/UI 架构、交互设计 |
-| **领域专家** | `writer` | haiku | 文档、迁移说明、用户指南 |
-| **领域专家** | `qa-tester` | sonnet | 交互式 CLI/服务运行时验证 |
-| **领域专家** | `scientist` | sonnet | 数据/统计分析 |
-| **领域专家** | `document-specialist` | sonnet | 外部文档与参考查找 |
-| **领域专家** | `git-master` | sonnet | 提交策略、历史管理 |
-| **领域专家** | `vision` | sonnet | 图片/截图/图表分析 |
-| **领域专家** | `database-expert` | sonnet | 数据库设计、查询优化和迁移 |
-| **领域专家** | `devops-engineer` | sonnet | CI/CD、容器化、基础设施即代码 |
-| **领域专家** | `i18n-specialist` | sonnet | 国际化、本地化和多语言支持 |
-| **领域专家** | `accessibility-auditor` | sonnet | Web 无障碍审查和 WCAG 合规 |
-| **领域专家** | `api-designer` | sonnet | REST/GraphQL API 设计和契约定义 |
-| **协调** | `critic` | opus | 计划/设计批判性挑战 |
-| **产品** | `product-manager` | sonnet | 问题框架、PRD |
-| **产品** | `ux-researcher` | sonnet | 启发式审计、可用性、无障碍 |
-| **产品** | `information-architect` | sonnet | 分类、导航、可发现性 |
-| **产品** | `product-analyst` | sonnet | 产品指标、漏斗分析、实验 |
-| **废弃别名** | `researcher` | - | 已废弃，映射到 `document-specialist` |
-| **废弃别名** | `tdd-guide` | - | 已废弃，映射到 `test-engineer` |
-| **Axiom** | `axiom-requirement-analyst` | sonnet | 需求分析三态门（PASS/CLARIFY/REJECT） |
-| **Axiom** | `axiom-product-designer` | sonnet | Draft PRD 生成，含 Mermaid 流程图 |
-| **Axiom** | `axiom-review-aggregator` | sonnet | 5 专家并行审查聚合与冲突仲裁 |
-| **Axiom** | `axiom-prd-crafter` | sonnet | 工程级 PRD，含门控验证 |
-| **Axiom** | `axiom-system-architect` | sonnet | 原子任务 DAG 与 Manifest 生成 |
-| **Axiom** | `axiom-evolution-engine` | sonnet | 知识收割、模式检测、工作流优化 |
-| **Axiom** | `axiom-context-manager` | sonnet | 7 操作记忆系统（读/写/状态/检查点） |
-| **Axiom** | `axiom-worker` | sonnet | PM→Worker 协议，三态输出（QUESTION/COMPLETE/BLOCKED） |
-| **Axiom 专家** | `axiom-ux-director` | sonnet | UX/体验专家评审，输出 review_ux.md |
-| **Axiom 专家** | `axiom-product-director` | sonnet | 产品战略专家评审，输出 review_product.md |
-| **Axiom 专家** | `axiom-domain-expert` | sonnet | 领域知识专家评审，输出 review_domain.md |
-| **Axiom 专家** | `axiom-tech-lead` | sonnet | 技术可行性评审，输出 review_tech.md |
-| **Axiom 专家** | `axiom-critic` | sonnet | 安全/质量/逻辑评审，输出 review_critic.md |
-| **Axiom 专家** | `axiom-sub-prd-writer` | sonnet | 将 Manifest 任务拆解为可执行 Sub-PRD |
-
-### Agent 选择指南
-
-| 任务类型 | 最佳 Agent | 模型 |
-|-----------|------------|-------|
-| 快速代码查找 | `explore` | haiku |
-| 功能实现 | `executor` | sonnet |
-| 复杂重构/自主任务 | `deep-executor` | opus |
-| 调试/根因分析 | `debugger` | sonnet |
-| 完成验证 | `verifier` | sonnet |
-| 系统设计/架构 | `architect` | opus |
-| 战略规划 | `planner` | opus |
-| 需求分析 | `analyst` | opus |
-| 审查/评审计划 | `critic` | opus |
-| UI 组件/设计 | `designer` | sonnet |
-| 编写文档/注释 | `writer` | haiku |
-| 研究文档/API | `document-specialist` | sonnet |
-| 分析图片/图表 | `vision` | sonnet |
-| 交互式测试 CLI | `qa-tester` | sonnet |
-| 安全审查 | `security-reviewer` | sonnet |
-| 修复构建错误 | `build-fixer` | sonnet |
-| TDD 工作流 | `test-engineer` | sonnet |
-| 代码审查 | `code-reviewer` | opus |
-| 数据分析/统计 | `scientist` | sonnet |
-| 外部包/SDK 评估 | `dependency-expert` | sonnet |
-| Git 提交/历史 | `git-master` | sonnet |
-| 产品需求/PRD | `product-manager` | sonnet |
-| 可用性/无障碍审计 | `ux-researcher` | sonnet |
-| 信息架构 | `information-architect` | sonnet |
-| 产品指标/实验 | `product-analyst` | sonnet |
+### Coordination (1)
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| `critic` | opus | Critical challenge of plans and designs |
 
 ---
 
-## Skills（共 71 个）
-
-### 核心 Skills
-
-| Skill | 说明 | 手动命令 |
-|-------|-------------|----------------|
-| `autopilot` | 从想法到可运行代码的全自主执行 | `/ultrapower:autopilot` |
-| `ultrawork` | 并行 agents 最大性能模式 | `/ultrapower:ultrawork` |
-| `ultrapilot` | 并行 autopilot，速度提升 3-5 倍 | `/ultrapower:ultrapilot` |
-| `swarm` | N 个协调 agents 并行认领任务 | `/ultrapower:swarm` |
-| `team` | N 个协调 agents 使用 Claude Code 原生 team | `/ultrapower:team` |
-| `pipeline` | 顺序 agent 链式执行 | `/ultrapower:pipeline` |
-| `ralph` | 自引用开发直至完成 | `/ultrapower:ralph` |
-| `ralph-init` | 初始化 PRD 以进行结构化任务跟踪 | `/ultrapower:ralph-init` |
-| `ultraqa` | 自主 QA 循环工作流 | `/ultrapower:ultraqa` |
-| `plan` | 启动规划会话 | `/ultrapower:plan` |
-| `ralplan` | 迭代规划（Planner+Architect+Critic） | `/ultrapower:ralplan` |
-| `review` | 用 critic 审查工作计划 | `/ultrapower:review` |
-
-### 工作流 Skills
-
-| Skill | 说明 | 手动命令 |
-|-------|-------------|----------------|
-| `brainstorming` | 实现前探索需求和设计方案 | `/ultrapower:brainstorming` |
-| `writing-plans` | 将需求拆解为原子任务计划 | `/ultrapower:writing-plans` |
-| `subagent-driven-development` | 当前 session 中执行独立任务 | `/ultrapower:subagent-driven-development` |
-| `executing-plans` | 在独立 session 中执行计划 | `/ultrapower:executing-plans` |
-| `test-driven-development` | TDD 强制执行：测试优先开发 | `/ultrapower:test-driven-development` |
-| `systematic-debugging` | 系统化调试工作流 | `/ultrapower:systematic-debugging` |
-| `requesting-code-review` | 完成任务后请求代码审查 | `/ultrapower:requesting-code-review` |
-| `receiving-code-review` | 接收并处理代码审查反馈 | `/ultrapower:receiving-code-review` |
-| `finishing-a-development-branch` | 完成开发分支并整合工作 | `/ultrapower:finishing-a-development-branch` |
-| `using-git-worktrees` | 创建隔离 git worktree 工作区 | `/ultrapower:using-git-worktrees` |
-| `verification-before-completion` | 声明完成前运行验证 | `/ultrapower:verification-before-completion` |
-| `using-superpowers` | 建立 skill 使用规则 | `/ultrapower:using-superpowers` |
-| `dispatching-parallel-agents` | 并行分发独立任务给多个 agents | `/ultrapower:dispatching-parallel-agents` |
-
-### 增强 Skills
-
-| Skill | 说明 | 手动命令 |
-|-------|-------------|----------------|
-| `next-step-router` | 关键节点路由，推荐最优下一步 skill/agent | （内部调用） |
-| `deepinit` | 分层 AGENTS.md 代码库文档化 | `/ultrapower:deepinit` |
-| `deepsearch` | 多策略深度代码库搜索 | `/ultrapower:deepsearch` |
-| `analyze` | 深度分析与调查 | `/ultrapower:analyze` |
-| `sciomc` | 并行 scientist 编排 | `/ultrapower:sciomc` |
-| `external-context` | 并行 document-specialist 网络搜索 | `/ultrapower:external-context` |
-| `ccg` | Claude-Codex-Gemini 三模型并行编排 | `/ultrapower:ccg` |
-| `frontend-ui-ux` | 设计师转开发者的 UI/UX 专业能力 | （静默激活） |
-| `git-master` | Git 专家，处理原子提交和历史管理 | （静默激活） |
-| `tdd` | TDD 强制执行（`test-driven-development` 别名） | `/ultrapower:tdd` |
-| `learner` | 从会话中提取可复用 skill | `/ultrapower:learner` |
-| `build-fix` | 修复构建和 TypeScript 错误 | `/ultrapower:build-fix` |
-| `code-review` | 全面代码审查 | `/ultrapower:code-review` |
-| `security-review` | 安全漏洞检测 | `/ultrapower:security-review` |
-| `trace` | 显示 agent 流程追踪时间线 | `/ultrapower:trace` |
-| `learn-about-omc` | 了解 OMC 使用模式并获取建议 | `/ultrapower:learn-about-omc` |
-| `writing-skills` | 创建/编辑/验证 skills | `/ultrapower:writing-skills` |
-
-### 工具 Skills
-
-| Skill | 说明 | 手动命令 |
-|-------|-------------|----------------|
-| `note` | 保存笔记到抗压缩 notepad | `/ultrapower:note` |
-| `cancel` | 统一取消所有模式 | `/ultrapower:cancel` |
-| `omc-setup` | 一次性安装向导 | `/ultrapower:omc-setup` |
-| `omc-doctor` | 诊断并修复安装问题 | `/ultrapower:omc-doctor` |
-| `omc-help` | 显示 OMC 使用指南 | `/ultrapower:omc-help` |
-| `hud` | 配置 HUD 状态栏 | `/ultrapower:hud` |
-| `release` | 自动化发布工作流 | `/ultrapower:release` |
-| `mcp-setup` | 配置 MCP 服务器 | `/ultrapower:mcp-setup` |
-| `writer-memory` | 面向写作者的 agent 记忆系统 | `/ultrapower:writer-memory` |
-| `project-session-manager` | 管理隔离开发环境（git worktrees + tmux） | `/ultrapower:project-session-manager` |
-| `psm` | project-session-manager 别名 | `/ultrapower:psm` |
-| `skill` | 管理本地 skills（列出、添加、删除、搜索、编辑） | `/ultrapower:skill` |
-| `configure-discord` | 配置 Discord webhook/bot 通知 | `/ultrapower:configure-discord` |
-| `configure-telegram` | 配置 Telegram bot 通知 | `/ultrapower:configure-telegram` |
-| `wizard` | 交互式配置向导 | `/ultrapower:wizard` |
-| `nexus` | 主动学习系统管理（Phase 2 自我改进） | `/ultrapower:nexus` |
+## Skills (71 total)
+
+All skills are invocable as slash commands with `/ultrapower:` prefix.
+
+### Workflow Skills
+
+Core orchestration and execution skills:
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `autopilot` | `/ultrapower:autopilot` | Fully autonomous execution from idea to working code |
+| `ultrawork` | `/ultrapower:ultrawork` | Maximum parallel agent execution |
+| `ultrapilot` | `/ultrapower:ultrapilot` | Parallel autopilot, 3-5x speed improvement |
+| `swarm` | `/ultrapower:swarm` | N coordinated agents with Team pipeline |
+| `team` | `/ultrapower:team` | N coordinated agents using Claude Code native team |
+| `pipeline` | `/ultrapower:pipeline` | Sequential agent chain with data passing |
+| `ralph` | `/ultrapower:ralph` | Self-referential development until complete |
+| `ralph-init` | `/ultrapower:ralph-init` | Initialize PRD for structured task tracking |
+| `ultraqa` | `/ultrapower:ultraqa` | Autonomous QA loop workflow |
+| `plan` | `/ultrapower:plan` | Start a planning session |
+| `ralplan` | `/ultrapower:ralplan` | Iterative planning (Planner+Architect+Critic) |
+| `review` | `/ultrapower:review` | Review a work plan with critic |
+| `ccg` | `/ultrapower:ccg` | Claude-Codex-Gemini three-model parallel orchestration |
+
+---
 
 ### Axiom Skills
 
-| Skill | 说明 | 手动命令 |
-|-------|-------------|----------------|
-| `ax-analyze-error` | 分析错误并生成修复方案 | `/ultrapower:ax-analyze-error` |
-| `ax-context` | 加载/保存 Axiom 上下文快照 | `/ultrapower:ax-context` |
-| `ax-decompose` | 将需求分解为原子任务 DAG | `/ultrapower:ax-decompose` |
-| `ax-draft` | 生成 Draft PRD | `/ultrapower:ax-draft` |
-| `ax-evolution` | 查看知识演化历史 | `/ultrapower:ax-evolution` |
-| `ax-evolve` | 触发知识收割与工作流优化 | `/ultrapower:ax-evolve` |
-| `ax-implement` | 执行 Axiom 任务实现 | `/ultrapower:ax-implement` |
-| `ax-reflect` | 任务完成后反思与学习 | `/ultrapower:ax-reflect` |
-| `ax-review` | 5 专家并行审查聚合 | `/ultrapower:ax-review` |
-| `ax-rollback` | 回滚到上一个检查点 | `/ultrapower:ax-rollback` |
-| `ax-status` | 查看 Axiom 工作流状态 | `/ultrapower:ax-status` |
-| `ax-suspend` | 挂起当前工作流并保存状态 | `/ultrapower:ax-suspend` |
-| `ax-knowledge` | 查询 Axiom 知识库 | `/ultrapower:ax-knowledge` |
-| `ax-export` | 导出 Axiom 工作流产物 | `/ultrapower:ax-export` |
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `ax-draft` | `/ultrapower:ax-draft` | Requirements clarification -> Draft PRD -> user confirm |
+| `ax-review` | `/ultrapower:ax-review` | 5-expert parallel review -> aggregation -> Rough PRD |
+| `ax-decompose` | `/ultrapower:ax-decompose` | Rough PRD -> system architecture -> atomic task DAG |
+| `ax-implement` | `/ultrapower:ax-implement` | Execute Axiom tasks with CI gate, auto-repair |
+| `ax-analyze-error` | `/ultrapower:ax-analyze-error` | Root cause diagnosis -> auto-fix -> knowledge queue |
+| `ax-reflect` | `/ultrapower:ax-reflect` | Session reflection -> experience extraction -> action items |
+| `ax-evolve` | `/ultrapower:ax-evolve` | Process learning queue -> update knowledge base -> pattern detection |
+| `ax-status` | `/ultrapower:ax-status` | Full system status dashboard |
+| `ax-rollback` | `/ultrapower:ax-rollback` | Roll back to the last checkpoint (user confirmation required) |
+| `ax-suspend` | `/ultrapower:ax-suspend` | Save session state and safely exit |
+| `ax-context` | `/ultrapower:ax-context` | Directly operate the Axiom memory system |
+| `ax-evolution` | `/ultrapower:ax-evolution` | Evolution engine unified entry (evolve/reflect/knowledge/patterns) |
+| `ax-knowledge` | `/ultrapower:ax-knowledge` | Query the Axiom knowledge base |
+| `ax-export` | `/ultrapower:ax-export` | Export Axiom workflow artifacts as portable zip |
 
 ---
 
-## Slash Commands
-
-所有 skills 均可通过 `/ultrapower:` 前缀作为 slash 命令使用。
-
-| 命令 | 说明 |
-|---------|-------------|
-| `/ultrapower:autopilot <task>` | 全自主执行 |
-| `/ultrapower:ultrawork <task>` | 并行 agents 最大性能模式 |
-| `/ultrapower:ultrapilot <task>` | 并行 autopilot（速度提升 3-5 倍） |
-| `/ultrapower:swarm <N>:<agent> <task>` | 协调 agent 集群 |
-| `/ultrapower:team <task>` | N 个协调 agents（Claude Code 原生 team） |
-| `/ultrapower:pipeline <stages>` | 顺序 agent 链式执行 |
-| `/ultrapower:ralph-init <task>` | 初始化 PRD 以进行结构化任务跟踪 |
-| `/ultrapower:ralph <task>` | 自引用循环直至任务完成 |
-| `/ultrapower:ultraqa <goal>` | 自主 QA 循环工作流 |
-| `/ultrapower:plan <description>` | 启动规划会话 |
-| `/ultrapower:ralplan <description>` | 共识迭代规划 |
-| `/ultrapower:review [plan-path]` | 用 critic 审查计划 |
-| `/ultrapower:brainstorming` | 实现前探索需求和设计方案 |
-| `/ultrapower:writing-plans <task>` | 将需求拆解为原子任务计划 |
-| `/ultrapower:test-driven-development <feature>` | TDD 工作流强制执行 |
-| `/ultrapower:systematic-debugging` | 系统化调试工作流 |
-| `/ultrapower:requesting-code-review` | 请求代码审查 |
-| `/ultrapower:receiving-code-review` | 处理代码审查反馈 |
-| `/ultrapower:finishing-a-development-branch` | 完成开发分支 |
-| `/ultrapower:using-git-worktrees` | 创建隔离 git worktree |
-| `/ultrapower:verification-before-completion` | 声明完成前验证 |
-| `/ultrapower:dispatching-parallel-agents` | 并行分发独立任务 |
-| `/ultrapower:deepsearch <query>` | 多策略深度代码库搜索 |
-| `/ultrapower:deepinit [path]` | 用分层 AGENTS.md 文件索引代码库 |
-| `/ultrapower:analyze <target>` | 深度分析与调查 |
-| `/ultrapower:sciomc <topic>` | 并行研究编排 |
-| `/ultrapower:ccg <task>` | Claude-Codex-Gemini 三模型并行编排 |
-| `/ultrapower:external-context <query>` | 并行网络搜索 |
-| `/ultrapower:tdd <feature>` | TDD 工作流（test-driven-development 别名） |
-| `/ultrapower:learner` | 从会话中提取可复用 skill |
-| `/ultrapower:trace` | 显示 agent 流程追踪时间线 |
-| `/ultrapower:note <content>` | 保存笔记到 notepad.md |
-| `/ultrapower:cancel` | 统一取消 |
-| `/ultrapower:omc-setup` | 一次性安装向导 |
-| `/ultrapower:omc-doctor` | 诊断并修复安装问题 |
-| `/ultrapower:omc-help` | 显示 OMC 使用指南 |
-| `/ultrapower:hud` | 配置 HUD 状态栏 |
-| `/ultrapower:release` | 自动化发布工作流 |
-| `/ultrapower:mcp-setup` | 配置 MCP 服务器 |
-| `/ultrapower:configure-discord` | 配置 Discord 通知 |
-| `/ultrapower:configure-telegram` | 配置 Telegram 通知 |
-| `/ultrapower:project-session-manager` | 管理隔离开发环境 |
-| `/ultrapower:skill` | 管理本地 skills |
-| `/ultrapower:writing-skills` | 创建/编辑/验证 skills |
-| `/ultrapower:learn-about-omc` | 了解 OMC 使用模式 |
+### Superpowers Skills
+
+Structured guidance for advanced workflows:
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `brainstorming` | `/ultrapower:brainstorming` | Structured exploration of requirements and design options |
+| `writing-plans` | `/ultrapower:writing-plans` | Decompose requirements into atomic task plans |
+| `subagent-driven-development` | `/ultrapower:subagent-driven-development` | Execute independent tasks in current session |
+| `executing-plans` | `/ultrapower:executing-plans` | Execute plans in independent sessions |
+| `test-driven-development` | `/ultrapower:test-driven-development` | TDD enforcement: test-first development |
+| `systematic-debugging` | `/ultrapower:systematic-debugging` | Systematic debugging workflow |
+| `requesting-code-review` | `/ultrapower:requesting-code-review` | Request code review after task completion |
+| `receiving-code-review` | `/ultrapower:receiving-code-review` | Receive and process code review feedback |
+| `finishing-a-development-branch` | `/ultrapower:finishing-a-development-branch` | Complete development branch and integrate work |
+| `using-git-worktrees` | `/ultrapower:using-git-worktrees` | Create isolated git worktree workspaces |
+| `verification-before-completion` | `/ultrapower:verification-before-completion` | Run verification before claiming completion |
+| `using-superpowers` | `/ultrapower:using-superpowers` | Establish skill usage rules |
+| `dispatching-parallel-agents` | `/ultrapower:dispatching-parallel-agents` | Dispatch independent tasks to multiple agents in parallel |
+| `next-step-router` | (internal) | Analyze outputs at critical nodes, recommend optimal next step |
+| `writing-skills` | `/ultrapower:writing-skills` | Create/edit/validate skills |
 
 ---
 
-## Hooks System
+### Agent Shortcuts
 
-ultrapower 包含 47 个生命周期 hooks，用于增强 Claude Code 的行为。
+Lightweight wrappers for common agent invocations:
 
-### 执行模式 Hooks
+| Skill | Command | Routes To | Triggers |
+|-------|---------|-----------|---------|
+| `analyze` | `/ultrapower:analyze` | `debugger` | "analyze", "debug", "investigate" |
+| `deepsearch` | `/ultrapower:deepsearch` | `explore` | "search", "find in codebase" |
+| `tdd` | `/ultrapower:tdd` | `test-engineer` | "tdd", "test first", "red green" |
+| `build-fix` | `/ultrapower:build-fix` | `build-fixer` | "fix build", "type errors" |
+| `code-review` | `/ultrapower:code-review` | `code-reviewer` | "review code" |
+| `security-review` | `/ultrapower:security-review` | `security-reviewer` | "security review" |
+| `frontend-ui-ux` | (silent activation) | `designer` | UI/component/styling work |
+| `git-master` | (silent activation) | `git-master` | git/commit work |
+| `sciomc` | `/ultrapower:sciomc` | parallel `scientist` | "sciomc" |
+| `external-context` | `/ultrapower:external-context` | parallel `document-specialist` | web search |
 
-| Hook | 说明 |
-|------|-------------|
-| `autopilot` | 从想法到可运行代码的全自主执行 |
-| `ultrawork` | 最大并行 agent 执行 |
-| `ralph` | 持续执行直至验证完成 |
-| `ultrapilot` | 带文件所有权的并行 autopilot |
-| `ultraqa` | QA 循环直至目标达成 |
-| `mode-registry` | 跟踪当前执行模式（含 ultrawork、ralph、team 等） |
-| `persistent-mode` | 跨会话维护模式状态 |
+---
 
-### 核心 Hooks
+### Utility Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| `note` | `/ultrapower:note` | Save notes to compression-resistant notepad |
+| `cancel` | `/ultrapower:cancel` | Unified cancel of all active modes |
+| `omc-setup` | `/ultrapower:omc-setup` | One-time installation wizard |
+| `omc-doctor` | `/ultrapower:omc-doctor` | Diagnose and repair installation issues |
+| `omc-help` | `/ultrapower:omc-help` | Display OMC usage guide |
+| `hud` | `/ultrapower:hud` | Configure HUD status bar |
+| `release` | `/ultrapower:release` | Automated release workflow |
+| `mcp-setup` | `/ultrapower:mcp-setup` | Configure MCP servers |
+| `writer-memory` | `/ultrapower:writer-memory` | Agent memory system for writers |
+| `project-session-manager` | `/ultrapower:project-session-manager` | Manage isolated dev environments (git worktrees + tmux) |
+| `psm` | `/ultrapower:psm` | Alias for project-session-manager |
+| `skill` | `/ultrapower:skill` | Manage local skills (list, add, delete, search, edit) |
+| `configure-discord` | `/ultrapower:configure-discord` | Configure Discord webhook/bot notifications |
+| `configure-telegram` | `/ultrapower:configure-telegram` | Configure Telegram bot notifications |
+| `wizard` | `/ultrapower:wizard` | Interactive configuration wizard |
+| `nexus` | `/ultrapower:nexus` | Active learning system management (Phase 2 self-improvement) |
+| `deepinit` | `/ultrapower:deepinit` | Deep codebase initialization with layered AGENTS.md |
+| `learner` | `/ultrapower:learner` | Extract reusable skill from session |
+| `trace` | `/ultrapower:trace` | Display agent flow trace timeline |
+| `learn-about-omc` | `/ultrapower:learn-about-omc` | Learn OMC usage patterns and get recommendations |
 
-| Hook | 说明 |
-|------|-------------|
-| `rules-injector` | 动态规则注入，支持 YAML frontmatter 解析 |
-| `omc-orchestrator` | 强制执行编排器行为和委派 |
-| `auto-slash-command` | 自动检测并执行 slash 命令 |
-| `keyword-detector` | Magic keyword 检测（ultrawork、ralph 等） |
-| `todo-continuation` | 确保 todo 列表完成 |
-| `notepad` | 抗压缩记忆系统 |
-| `learner` | 从对话中提取 skill |
+---
 
-### 上下文与恢复 Hooks
+## Custom Tools (35 total)
 
-| Hook | 说明 |
-|------|-------------|
-| `recovery` | 编辑错误、会话和上下文窗口恢复 |
-| `preemptive-compaction` | 监控上下文使用量以防止超限 |
-| `pre-compact` | 压缩前处理 |
-| `subagent-stop` | 子 agent 完成时触发，防止无限循环 |
-| `teammate-idle` | 团队成员空闲时触发，默认允许 |
-| `session-end` | 会话结束时触发，清理临时状态 |
-| `user-prompt-submit` | 用户提交提示词前触发，用于关键词检测 |
-| `permission-request` | 工具权限请求时触发 |
-| `task-completed` | 任务完成时触发 |
-| `config-change` | 配置变更时触发 |
-| `directory-readme-injector` | README 上下文注入 |
-
-### 质量与验证 Hooks
-
-| Hook | 说明 |
-|------|-------------|
-| `comment-checker` | BDD 检测和指令过滤 |
-| `thinking-block-validator` | 扩展思考验证 |
-| `empty-message-sanitizer` | 空消息处理 |
-| `permission-handler` | 权限请求与验证 |
-| `think-mode` | 扩展思考检测 |
+ultrapower exposes **35 custom tools** via the `mcp__plugin_ultrapower_t__` prefix.
 
-### 协调与环境 Hooks
+| Category | Count | Tool Prefix |
+|----------|-------|-------------|
+| LSP (Language Server Protocol) | 12 | `lsp_*` |
+| AST (Structured code search) | 2 | `ast_grep_*` |
+| Python REPL | 1 | `python_repl` |
+| Notepad (Session memory) | 6 | `notepad_*` |
+| State (Execution mode state) | 5 | `state_*` |
+| Project Memory (Project-level memory) | 4 | `project_memory_*` |
+| Trace (Flow tracing) | 2 | `trace_*` |
+| Skills (Skill loading) | 3 | `*_omc_skills*` |
+| **Total** | **35** | |
 
-| Hook | 说明 |
-|------|-------------|
-| `subagent-tracker` | 跟踪已生成的子 agents |
-| `flow-tracer` | Agent 流程追踪记录（hook 触发、keyword 检测、skill 激活、模式变更） |
-| `session-end` | 会话终止处理 |
-| `non-interactive-env` | CI/非交互式环境处理 |
-| `agent-usage-reminder` | 提醒使用专业 agents |
-| `background-notification` | 后台任务完成通知 |
-| `plugin-patterns` | 插件模式检测 |
-| `setup` | 初始安装与配置 |
-| `beads-context` | 上下文珠链管理 |
-| `project-memory` | 项目级记忆管理 |
-
-### Axiom Hooks
-
-| Hook | 说明 |
-|------|-------------|
-| `axiom-boot` | 会话启动时注入 Axiom 记忆上下文 |
-| `axiom-guards` | Axiom 门禁规则执行（Expert/User/CI Gate） |
+> **Disable tool groups**: Set `OMC_DISABLE_TOOLS=lsp,python-repl,project-memory` to disable specific groups at startup. Supported group names: `lsp`, `ast`, `python`/`python-repl`, `trace`, `state`, `notepad`, `memory`/`project-memory`, `skills`.
 
 ---
 
-## Magic Keywords
+### LSP Tools (12)
 
-在提示词中任意位置包含以下关键词即可激活增强模式：
+IDE-grade code intelligence via Language Server Protocol:
 
-| 关键词 | 效果 |
-|---------|--------|
-| `ultrawork`, `ulw` | 激活并行 agent 编排 |
-| `autopilot`, `auto-pilot`, `fullsend`, `full auto` | 全自主执行 |
-| `ultrapilot`, `ultra-pilot`, `parallel build`, `swarm build` | 并行 autopilot（速度提升 3-5 倍） |
-| `ralph` | 持续执行直至验证完成 |
-| `team`, `coordinated team` | Team 模式多 agent 协调 |
-| `swarm N agents`, `coordinated agents`, `team mode` | 协调 agent 集群 |
-| `plan this`, `plan the` | 规划访谈工作流 |
-| `ralplan` | 迭代规划共识 |
-| `tdd`, `test first` | TDD 工作流强制执行 |
-| `ultrathink` | 扩展思考模式 |
-| `deepsearch`, `search the codebase`, `find in codebase` | 深度代码库搜索 |
-| `deep analyze`, `deepanalyze` | 深度分析模式 |
-| `ccg`, `claude-codex-gemini` | Claude-Codex-Gemini 三模型并行编排 |
-| `ask codex`, `use codex`, `delegate to codex` | 委派给 Codex（OpenAI） |
-| `ask gemini`, `use gemini`, `delegate to gemini` | 委派给 Gemini（Google） |
-| `agent pipeline`, `chain agents` | 顺序 agent 链式执行 |
-| `cancelomc`, `stopomc` | 统一取消所有活跃模式 |
-
-### 示例
+```
+mcp__plugin_ultrapower_t__lsp_hover              -- Type info and docs at position
+mcp__plugin_ultrapower_t__lsp_goto_definition    -- Jump to symbol definition
+mcp__plugin_ultrapower_t__lsp_find_references    -- Find all usages
+mcp__plugin_ultrapower_t__lsp_document_symbols   -- File outline (functions, classes)
+mcp__plugin_ultrapower_t__lsp_workspace_symbols  -- Search symbols across workspace
+mcp__plugin_ultrapower_t__lsp_diagnostics        -- Errors, warnings, hints (single file)
+mcp__plugin_ultrapower_t__lsp_diagnostics_directory  -- Project-level type checking
+mcp__plugin_ultrapower_t__lsp_servers            -- List available language servers
+mcp__plugin_ultrapower_t__lsp_prepare_rename     -- Check if rename is valid
+mcp__plugin_ultrapower_t__lsp_rename             -- Preview multi-file rename
+mcp__plugin_ultrapower_t__lsp_code_actions       -- Available refactors/quick fixes
+mcp__plugin_ultrapower_t__lsp_code_action_resolve -- Get action details
+```
 
-```bash
-# 在 Claude Code 中：
+Supported languages: TypeScript, Python, Rust, Go, C/C++, Java, JSON, HTML, CSS, YAML.
 
-# 最大并行度
-ultrawork implement user authentication with OAuth
+> **Note**: LSP tools require language server installation (typescript-language-server, pylsp, rust-analyzer, gopls, etc.). Use `lsp_servers` to check installation status.
 
-# 自主执行
-autopilot: build a todo app with React
+---
 
-# 并行 autopilot
-ultrapilot: build a fullstack todo app
+### AST Tools (2)
 
-# 持续执行模式
-ralph: refactor the authentication module
+Structural code search and transformation via ast-grep:
 
-# 规划会话
-plan this feature
+```
+mcp__plugin_ultrapower_t__ast_grep_search   -- Pattern-based AST matching with meta-variables ($NAME, $$$ARGS)
+mcp__plugin_ultrapower_t__ast_grep_replace  -- AST-aware code transformation (dry-run by default)
+```
 
-# TDD 工作流
-tdd: implement password validation
+Supported languages: JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML.
 
-# 协调集群
-swarm 5 agents: fix all lint errors
+---
 
-# Agent 链式执行
-chain agents: analyze → fix → test this bug
+### Python REPL (1)
 
-# 深度代码库搜索
-deepsearch all files that import the utils module
+```
+mcp__plugin_ultrapower_t__python_repl  -- Persistent Python REPL with pandas/numpy/matplotlib for data analysis
+```
 
-# 深度分析
-deep analyze why the tests are failing
+---
 
-# 三模型并行编排
-ccg: implement the payment module
+### Notepad Tools (6)
+
+Compression-resistant session memory stored at `{worktree}/.omc/notepad.md`:
 
-# 取消活跃模式
-cancelomc
+```
+mcp__plugin_ultrapower_t__notepad_read            -- Read notepad (sections: all/priority/working/manual)
+mcp__plugin_ultrapower_t__notepad_write_priority  -- Write priority context (<=500 chars, auto-loaded at session start)
+mcp__plugin_ultrapower_t__notepad_write_working   -- Write working memory (timestamped, auto-pruned after 7 days)
+mcp__plugin_ultrapower_t__notepad_write_manual    -- Write manual record (permanent, never auto-pruned)
+mcp__plugin_ultrapower_t__notepad_prune           -- Prune working memory entries older than N days
+mcp__plugin_ultrapower_t__notepad_stats           -- Get notepad statistics (size, entry count, oldest entry)
 ```
 
 ---
 
-## MCP Path Boundary Rules
+### State Tools (5)
 
-MCP 工具（`ask_codex`、`ask_gemini`）出于安全考虑强制执行严格的路径边界。`prompt_file` 和 `output_file` 均相对于 `working_directory` 解析。
+Execution mode state management stored at `{worktree}/.omc/state/{mode}-state.json`:
 
-### 默认行为（严格模式）
+```
+mcp__plugin_ultrapower_t__state_read          -- Read state for a mode (autopilot/ralph/ultrawork/team etc.)
+mcp__plugin_ultrapower_t__state_write         -- Write/update mode state (supports active, iteration, phase fields)
+mcp__plugin_ultrapower_t__state_clear         -- Clear state file for a mode
+mcp__plugin_ultrapower_t__state_list_active   -- List all currently active modes
+mcp__plugin_ultrapower_t__state_get_status    -- Get detailed status for a mode or all modes
+```
 
-默认情况下，两个文件都必须位于 `working_directory` 内：
+Supported modes: `autopilot`, `ultrapilot`, `team`, `pipeline`, `ralph`, `ultrawork`, `ultraqa`, `ralplan`.
 
-| 参数 | 要求 |
-|-----------|-------------|
-| `prompt_file` | 必须位于 `working_directory` 内（符号链接解析后） |
-| `output_file` | 必须位于 `working_directory` 内（符号链接解析后） |
-| `working_directory` | 必须位于项目 worktree 内（除非绕过） |
+> **Security**: The `mode` parameter must pass `assertValidMode()` validation before path concatenation to prevent path traversal. See [Security & Safety Rules](#security--safety-rules).
+
+---
 
-### 环境变量覆盖
+### Project Memory Tools (4)
+
+Project-level persistent memory stored at `{worktree}/.omc/project-memory.json`:
 
-| 变量 | 取值 | 说明 |
-|----------|--------|-------------|
-| `OMC_MCP_OUTPUT_PATH_POLICY` | `strict`（默认）、`redirect_output` | 控制输出文件路径强制策略 |
-| `OMC_MCP_OUTPUT_REDIRECT_DIR` | 路径（默认：`.omc/outputs`） | 策略为 `redirect_output` 时的重定向目录 |
-| `OMC_MCP_ALLOW_EXTERNAL_PROMPT` | `0`（默认）、`1` | 允许 prompt 文件位于 working directory 之外 |
-| `OMC_ALLOW_EXTERNAL_WORKDIR` | 未设置（默认）、`1` | 允许 working_directory 位于项目 worktree 之外 |
-| `OMC_DISCORD_WEBHOOK_URL` | URL | Discord webhook URL，用于通知 |
-| `OMC_DISCORD_NOTIFIER_BOT_TOKEN` | Token | Discord bot token，用于 Bot API 通知 |
-| `OMC_DISCORD_NOTIFIER_CHANNEL` | Channel ID | Discord 频道 ID，用于 Bot API 通知 |
-| `OMC_DISCORD_MENTION` | `<@uid>` 或 `<@&role_id>` | 在 Discord 消息前添加的 mention |
-| `OMC_TELEGRAM_BOT_TOKEN` | Token | Telegram bot token，用于通知 |
-| `OMC_TELEGRAM_CHAT_ID` | Chat ID | Telegram chat ID，用于通知 |
-| `OMC_SLACK_WEBHOOK_URL` | URL | Slack incoming webhook URL，用于通知 |
-
-### 策略说明
-
-**`OMC_MCP_OUTPUT_PATH_POLICY=strict`（默认）**
-- 输出文件必须位于 `working_directory` 内
-- 尝试写入边界外的文件将失败，错误码为 `E_PATH_OUTSIDE_WORKDIR_OUTPUT`
-- 最安全的选项——推荐用于生产环境
-
-**`OMC_MCP_OUTPUT_PATH_POLICY=redirect_output`**
-- 输出文件自动重定向到 `OMC_MCP_OUTPUT_REDIRECT_DIR`
-- 仅保留文件名，目录结构被展平
-- 适用于希望将所有输出集中到一个位置的场景
-- 在 `[MCP Config]` 级别记录重定向日志
-
-**`OMC_MCP_ALLOW_EXTERNAL_PROMPT=1`**
-- 允许从 `working_directory` 外部读取 prompt 文件
-- **安全警告**：允许读取文件系统上的任意文件
-- 仅在可信环境中使用
-
-**`OMC_ALLOW_EXTERNAL_WORKDIR=1`**
-- 允许 `working_directory` 位于项目 worktree 之外
-- 绕过 worktree 边界检查
-- 适用于对外部项目运行 MCP 工具的场景
-
-### 错误码
-
-| 错误码 | 含义 |
-|-------|---------|
-| `E_PATH_OUTSIDE_WORKDIR_PROMPT` | prompt_file 位于 working_directory 之外 |
-| `E_PATH_OUTSIDE_WORKDIR_OUTPUT` | output_file 位于 working_directory 之外 |
-| `E_PATH_RESOLUTION_FAILED` | 符号链接或目录解析失败 |
-| `E_WRITE_FAILED` | 输出文件写入失败（I/O 错误） |
-| `E_WORKDIR_INVALID` | working_directory 不存在或无法访问 |
-
-### 有效/无效路径示例
-
-**有效路径（working_directory: `/home/user/project`）**
 ```
-prompt.txt                    -> /home/user/project/prompt.txt
-./prompts/task.md             -> /home/user/project/prompts/task.md
-../project/output.txt         -> /home/user/project/output.txt (resolves inside)
-.omc/outputs/response.md      -> /home/user/project/.omc/outputs/response.md
+mcp__plugin_ultrapower_t__project_memory_read          -- Read project memory (sections: techStack/build/conventions/structure/notes/directives)
+mcp__plugin_ultrapower_t__project_memory_write         -- Write/update project memory (merge mode supported)
+mcp__plugin_ultrapower_t__project_memory_add_note      -- Add categorized note (build/test/deploy/env/architecture etc.)
+mcp__plugin_ultrapower_t__project_memory_add_directive -- Add user directive (cross-session persistent, compression-resistant)
 ```
 
-**无效路径（working_directory: `/home/user/project`）**
+---
+
+### Trace Tools (2)
+
+Agent flow tracing and session analytics:
+
 ```
-/etc/passwd                   -> Outside working directory (absolute)
-../../etc/shadow              -> Outside working directory (traverses too far)
-/tmp/output.txt               -> Outside working directory (different root)
+mcp__plugin_ultrapower_t__trace_timeline  -- Chronological agent flow trace (hooks/skills/agents/keywords/tools/modes)
+mcp__plugin_ultrapower_t__trace_summary   -- Session aggregate stats (hook counts, keyword frequency, skill activations, tool bottlenecks)
 ```
 
-### 故障排查矩阵
+---
 
-| 现象 | 原因 | 解决方法 |
-|---------|-------|-----|
-| `E_PATH_OUTSIDE_WORKDIR_PROMPT` 错误 | prompt_file 位于 working_directory 之外 | 将文件移至 working directory，或将 working_directory 改为公共父目录 |
-| `E_PATH_OUTSIDE_WORKDIR_OUTPUT` 错误 | output_file 位于 working_directory 之外 | 使用 working directory 内的相对路径，或设置 `OMC_MCP_OUTPUT_PATH_POLICY=redirect_output` |
-| `E_PATH_RESOLUTION_FAILED` 错误 | 符号链接解析失败或目录不可访问 | 确保目标目录存在且可访问 |
-| `E_WRITE_FAILED` 错误 | I/O 错误（权限不足、磁盘已满） | 检查文件权限和磁盘空间 |
-| `working_directory is outside the project worktree` | working_directory 不在 git worktree 内 | 设置 `OMC_ALLOW_EXTERNAL_WORKDIR=1`，或使用项目内的 working directory |
-| 输出文件不在预期位置 | `redirect_output` 策略已激活 | 检查 `OMC_MCP_OUTPUT_REDIRECT_DIR`（默认：`.omc/outputs`） |
+### Skills Tools (3)
+
+Skill loading and discovery:
+
+```
+mcp__plugin_ultrapower_t__load_omc_skills_local   -- Load OMC skills from project local
+mcp__plugin_ultrapower_t__load_omc_skills_global  -- Load OMC skills from global installation
+mcp__plugin_ultrapower_t__list_omc_skills         -- List all available skills
+```
 
 ---
 
-## Platform Support
+## Hooks System (35 hooks)
 
-### 操作系统
+ultrapower includes 35 lifecycle hooks that enhance Claude Code behavior.
 
-| 平台 | 安装方式 | Hook 类型 |
-|----------|---------------|-----------|
-| **Windows** | Claude Code Plugin | Node.js (.mjs) |
-| **macOS** | Claude Code Plugin | Node.js (.mjs) |
-| **Linux** | Claude Code Plugin | Node.js (.mjs) |
+### Execution Mode Hooks
 
-> **注意**：Bash hooks 在 macOS 和 Linux 上完全可移植（无 GNU 特定依赖）。
+| Hook | Description |
+|------|-------------|
+| `autopilot` | Fully autonomous execution from idea to working code |
+| `ultrawork` | Maximum parallel agent execution |
+| `ralph` | Persistent execution until verified complete |
+| `ultrapilot` | Parallel autopilot with file ownership |
+| `ultraqa` | QA loop until goal is achieved |
+| `mode-registry` | Tracks current execution mode (ultrawork, ralph, team, etc.) |
+| `persistent-mode` | Maintains mode state across sessions |
 
-> **高级**：设置 `OMC_USE_NODE_HOOKS=1` 可在 macOS/Linux 上使用 Node.js hooks。
+### Core Hooks
 
-### 可用工具
+| Hook | Description |
+|------|-------------|
+| `rules-injector` | Dynamic rule injection with YAML frontmatter parsing |
+| `omc-orchestrator` | Enforces orchestrator behavior and delegation |
+| `auto-slash-command` | Auto-detects and executes slash commands |
+| `keyword-detector` | Magic keyword detection (ultrawork, ralph, etc.) |
+| `todo-continuation` | Ensures todo list completion |
+| `notepad` | Compression-resistant memory system |
+| `learner` | Extracts skills from conversations |
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| **Read** | ✅ 可用 | 读取文件 |
-| **Write** | ✅ 可用 | 创建文件 |
-| **Edit** | ✅ 可用 | 修改文件 |
-| **Bash** | ✅ 可用 | 运行 shell 命令 |
-| **Glob** | ✅ 可用 | 按模式查找文件 |
-| **Grep** | ✅ 可用 | 搜索文件内容 |
-| **WebSearch** | ✅ 可用 | 搜索网络 |
-| **WebFetch** | ✅ 可用 | 获取网页内容 |
-| **Task** | ✅ 可用 | 生成子 agents |
-| **TodoWrite** | ✅ 可用 | 跟踪任务 |
-
-### LSP 工具（真实实现）
-
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `lsp_hover` | ✅ 已实现 | 获取指定位置的类型信息和文档 |
-| `lsp_goto_definition` | ✅ 已实现 | 跳转到符号定义 |
-| `lsp_find_references` | ✅ 已实现 | 查找符号的所有引用 |
-| `lsp_document_symbols` | ✅ 已实现 | 获取文件大纲（函数、类等） |
-| `lsp_workspace_symbols` | ✅ 已实现 | 在工作区内搜索符号 |
-| `lsp_diagnostics` | ✅ 已实现 | 获取错误、警告和提示 |
-| `lsp_prepare_rename` | ✅ 已实现 | 检查重命名是否有效 |
-| `lsp_rename` | ✅ 已实现 | 在整个项目中重命名符号 |
-| `lsp_code_actions` | ✅ 已实现 | 获取可用的重构操作 |
-| `lsp_code_action_resolve` | ✅ 已实现 | 获取代码操作的详细信息 |
-| `lsp_servers` | ✅ 已实现 | 列出可用的语言服务器 |
-| `lsp_diagnostics_directory` | ✅ 已实现 | 项目级类型检查 |
-
-> **注意**：LSP 工具需要安装语言服务器（typescript-language-server、pylsp、rust-analyzer、gopls 等）。使用 `lsp_servers` 检查安装状态。
-
-### AST 工具（ast-grep 集成）
-
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `ast_grep_search` | ✅ 已实现 | 基于 AST 匹配的模式代码搜索 |
-| `ast_grep_replace` | ✅ 已实现 | 基于模式的代码转换 |
+### Context & Recovery Hooks
 
-> **注意**：AST 工具使用 [@ast-grep/napi](https://ast-grep.github.io/) 进行结构化代码匹配。支持元变量，如 `$VAR`（单节点）和 `$$$`（多节点）。
+| Hook | Description |
+|------|-------------|
+| `recovery` | Edit error, session, and context window recovery |
+| `preemptive-compaction` | Monitors context usage to prevent overflow |
+| `pre-compact` | Pre-compaction processing |
+| `subagent-stop` | Triggered when sub-agents complete, prevents infinite loops |
+| `teammate-idle` | Triggered when team members idle, permits by default |
+| `session-end` | Session termination cleanup of temporary state |
+| `user-prompt-submit` | Triggered before user submits prompt, for keyword detection |
+| `permission-request` | Triggered on tool permission requests |
+| `task-completed` | Triggered on task completion |
+| `config-change` | Triggered on configuration changes |
+| `directory-readme-injector` | README context injection |
+
+### Quality & Validation Hooks
+
+| Hook | Description |
+|------|-------------|
+| `comment-checker` | BDD detection and instruction filtering |
+| `thinking-block-validator` | Extended thinking validation |
+| `empty-message-sanitizer` | Empty message handling |
+| `permission-handler` | Permission request and validation |
+| `think-mode` | Extended thinking detection |
 
-### Python REPL 工具
+### Coordination & Environment Hooks
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `python_repl` | ✅ 已实现 | 持久 Python REPL，支持 pandas/numpy/matplotlib 数据分析 |
+| Hook | Description |
+|------|-------------|
+| `subagent-tracker` | Tracks spawned sub-agents |
+| `flow-tracer` | Agent flow trace recording (hook triggers, keyword detection, skill activations, mode changes) |
+| `non-interactive-env` | CI/non-interactive environment handling |
+| `agent-usage-reminder` | Reminds to use specialist agents |
+| `background-notification` | Background task completion notifications |
+| `plugin-patterns` | Plugin pattern detection |
+| `setup` | Initial installation and configuration |
+| `beads-context` | Context bead chain management |
+| `project-memory` | Project-level memory management |
+
+### Axiom Hooks (2)
+
+| Hook | Location | Description |
+|------|----------|-------------|
+| `axiom-boot` | `src/hooks/axiom-boot/` | Inject Axiom memory context at session startup |
+| `axiom-guards` | `src/hooks/axiom-guards/` | Gate rule enforcement (Expert/User/CI Gate) |
+
+### Hook Runtime Guarantees
+
+- Hook inputs use snake_case fields: `tool_name`, `tool_input`, `tool_response`, `session_id`, `cwd`, `hook_event_name`
+- Kill switches: `DISABLE_OMC` (disable all hooks), `OMC_SKIP_HOOKS` (skip specific hooks by comma-separated names)
+- Sensitive hook fields (permission-request, setup, session-end) are filtered through strict whitelist in bridge-normalize; unknown fields are discarded
+- Required key validation per hook event type (e.g., session-end requires `sessionId`, `directory`)
+- `SubagentStop` inference: Never read `input.success` directly; use `input.success !== false`
 
-### Notepad 工具（会话记忆）
+---
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `notepad_read` | ✅ 已实现 | 读取 notepad 内容（章节：all/priority/working/manual） |
-| `notepad_write_priority` | ✅ 已实现 | 写入优先上下文（≤500 字符，会话开始时自动加载） |
-| `notepad_write_working` | ✅ 已实现 | 写入工作记忆（带时间戳，7 天后自动清理） |
-| `notepad_write_manual` | ✅ 已实现 | 写入手动记录（永久保存，永不自动清理） |
-| `notepad_prune` | ✅ 已实现 | 清理 N 天前的工作记忆条目 |
-| `notepad_stats` | ✅ 已实现 | 获取 notepad 统计信息（大小、条目数、最旧条目） |
+## MCP Integration
 
-> **存储位置**：`{worktree}/.omc/notepad.md`
+### MCP Providers
 
-### State 工具（执行模式状态）
+| Provider | Tool | Best For |
+|----------|------|---------|
+| Codex (OpenAI) | `mcp__x__ask_codex` | Architecture review, planning validation, code review, security review |
+| Gemini (Google) | `mcp__g__ask_gemini` | UI/UX design review, docs, large-context tasks (1M tokens) |
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `state_read` | ✅ 已实现 | 读取指定模式的状态（autopilot/ralph/ultrawork/team 等） |
-| `state_write` | ✅ 已实现 | 写入/更新模式状态（支持 active、iteration、phase 等字段） |
-| `state_clear` | ✅ 已实现 | 清除指定模式的状态文件 |
-| `state_list_active` | ✅ 已实现 | 列出所有当前活跃的模式 |
-| `state_get_status` | ✅ 已实现 | 获取指定模式或所有模式的详细状态 |
+Any OMC agent role can be passed as `agent_role` to either provider.
 
-> **支持的模式**：`autopilot`、`ultrapilot`、`team`、`pipeline`、`ralph`、`ultrawork`、`ultraqa`、`ralplan`
+### Tool Discovery
 
-### Project Memory 工具（项目级持久记忆）
+MCP tools are lazy-loaded and not in your tool list at session start. Before first use, call `ToolSearch` to discover:
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `project_memory_read` | ✅ 已实现 | 读取项目记忆（章节：techStack/build/conventions/structure/notes/directives） |
-| `project_memory_write` | ✅ 已实现 | 写入/更新项目记忆（支持合并模式） |
-| `project_memory_add_note` | ✅ 已实现 | 添加分类笔记（build/test/deploy/env/architecture 等） |
-| `project_memory_add_directive` | ✅ 已实现 | 添加用户指令（跨会话持久化，抗压缩） |
+```
+ToolSearch("mcp")       -- discover all MCP tools (recommended, run once early)
+ToolSearch("ask_codex") -- discover Codex specifically
+ToolSearch("ask_gemini") -- discover Gemini specifically
+```
 
-> **存储位置**：`{worktree}/.omc/project-memory.json`
+If ToolSearch returns no results, the MCP server is not configured — fall back to equivalent Claude agents.
 
-### Trace 工具（Agent 流程追踪）
+### Local MCP Tools (via `claude mcp add`)
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `trace_timeline` | ✅ 已实现 | 显示按时间顺序的 agent 流程追踪（hooks/skills/agents/keywords/tools/modes） |
-| `trace_summary` | ✅ 已实现 | 显示会话聚合统计（hook 统计、keyword 频率、skill 激活、工具瓶颈） |
+| Tool | Description |
+|------|-------------|
+| `sequential-thinking` | Structured step-by-step reasoning — breaks complex problems into ordered thought chains |
+| `software-planning-tool` | Task planning and decomposition — structured task analysis, dependency graphs, execution tracking |
 
-### Skills 工具（Skill 加载）
+### Custom Tools via MCP (32 total)
 
-| 工具 | 状态 | 说明 |
-|------|--------|-------------|
-| `load_omc_skills_local` | ✅ 已实现 | 从项目本地加载 OMC skills |
-| `load_omc_skills_global` | ✅ 已实现 | 从全局安装加载 OMC skills |
-| `list_omc_skills` | ✅ 已实现 | 列出所有可用 skills |
+ultrapower exposes 32 custom tools through the MCP server using the `mcp__plugin_ultrapower_t__` prefix.
 
-### 工具汇总
+#### LSP Tools (12)
 
-ultrapower 通过 `mcp__plugin_ultrapower_t__` 前缀暴露 **35 个自定义工具**：
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `lsp_hover` | `mcp__plugin_ultrapower_t__lsp_hover` | Get type information and documentation at cursor position |
+| `lsp_goto_definition` | `mcp__plugin_ultrapower_t__lsp_goto_definition` | Find definition location of a symbol |
+| `lsp_find_references` | `mcp__plugin_ultrapower_t__lsp_find_references` | Find all references to a symbol across codebase |
+| `lsp_document_symbols` | `mcp__plugin_ultrapower_t__lsp_document_symbols` | Get hierarchical outline of symbols in a file |
+| `lsp_workspace_symbols` | `mcp__plugin_ultrapower_t__lsp_workspace_symbols` | Search for symbols by name across workspace |
+| `lsp_diagnostics` | `mcp__plugin_ultrapower_t__lsp_diagnostics` | Get language server diagnostics for a file |
+| `lsp_diagnostics_directory` | `mcp__plugin_ultrapower_t__lsp_diagnostics_directory` | Run project-level diagnostics on a directory |
+| `lsp_servers` | `mcp__plugin_ultrapower_t__lsp_servers` | List all known language servers and installation status |
+| `lsp_prepare_rename` | `mcp__plugin_ultrapower_t__lsp_prepare_rename` | Check if a symbol can be renamed |
+| `lsp_rename` | `mcp__plugin_ultrapower_t__lsp_rename` | Rename a symbol across all files in project |
+| `lsp_code_actions` | `mcp__plugin_ultrapower_t__lsp_code_actions` | Get available code actions (refactorings, quick fixes) |
+| `lsp_code_action_resolve` | `mcp__plugin_ultrapower_t__lsp_code_action_resolve` | Get full edit details for a specific code action |
 
-| 类别 | 数量 | 工具前缀 |
-|------|------|---------|
-| LSP（语言服务器协议） | 12 | `lsp_*` |
-| AST（结构化代码搜索） | 2 | `ast_grep_*` |
-| Python REPL | 1 | `python_repl` |
-| Notepad（会话记忆） | 6 | `notepad_*` |
-| State（执行模式状态） | 5 | `state_*` |
-| Project Memory（项目记忆） | 4 | `project_memory_*` |
-| Trace（流程追踪） | 2 | `trace_*` |
-| Skills（Skill 加载） | 3 | `*_omc_skills*` |
-| **合计** | **35** | |
+#### AST Tools (2)
 
-> **禁用工具组**：通过 `OMC_DISABLE_TOOLS=lsp,python-repl,project-memory` 等环境变量可在启动时禁用指定工具组。
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `ast_grep_search` | `mcp__plugin_ultrapower_t__ast_grep_search` | Search for code patterns using AST matching |
+| `ast_grep_replace` | `mcp__plugin_ultrapower_t__ast_grep_replace` | Replace code patterns using AST matching |
 
----
+#### Python REPL (1)
 
-## Performance Monitoring
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `python_repl` | `mcp__plugin_ultrapower_t__python_repl` | Execute Python code in persistent REPL environment |
 
-ultrapower 包含全面的 agent 性能、token 使用量监控及并行工作流调试功能。
+#### Notepad Tools (6)
 
-完整文档请参阅 **[Performance Monitoring Guide](./PERFORMANCE-MONITORING.md)**。
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `notepad_read` | `mcp__plugin_ultrapower_t__notepad_read` | Read notepad content (all/priority/working/manual sections) |
+| `notepad_write_priority` | `mcp__plugin_ultrapower_t__notepad_write_priority` | Write to Priority Context section (max 500 chars) |
+| `notepad_write_working` | `mcp__plugin_ultrapower_t__notepad_write_working` | Add entry to Working Memory section (auto-pruned after 7 days) |
+| `notepad_write_manual` | `mcp__plugin_ultrapower_t__notepad_write_manual` | Add entry to MANUAL section (never auto-pruned) |
+| `notepad_prune` | `mcp__plugin_ultrapower_t__notepad_prune` | Prune Working Memory entries older than N days |
+| `notepad_stats` | `mcp__plugin_ultrapower_t__notepad_stats` | Get statistics about the notepad |
 
-### 快速概览
+#### State Tools (5)
 
-| 功能 | 说明 | 访问方式 |
-|---------|-------------|--------|
-| **Agent Observatory** | 实时 agent 状态、效率、瓶颈 | HUD / API |
-| **Token Analytics** | 成本跟踪、使用报告、预算警告 | `omc stats`, `omc cost` |
-| **Session Replay** | 会话后分析的事件时间线 | `.omc/state/agent-replay-*.jsonl` |
-| **Intervention System** | 自动检测停滞 agents 和成本超支 | 自动 |
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `state_read` | `mcp__plugin_ultrapower_t__state_read` | Read state for a specific mode |
+| `state_write` | `mcp__plugin_ultrapower_t__state_write` | Write/update state for a specific mode |
+| `state_clear` | `mcp__plugin_ultrapower_t__state_clear` | Clear/delete state for a specific mode |
+| `state_list_active` | `mcp__plugin_ultrapower_t__state_list_active` | List all currently active modes |
+| `state_get_status` | `mcp__plugin_ultrapower_t__state_get_status` | Get detailed status for a specific mode or all modes |
 
-### CLI 命令
+#### Project Memory Tools (4)
 
-CLI 入口：`ultrapower`、`omc`、`omc-cli`（三者等价）。
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `project_memory_read` | `mcp__plugin_ultrapower_t__project_memory_read` | Read project memory (techStack/build/conventions/structure/notes/directives) |
+| `project_memory_write` | `mcp__plugin_ultrapower_t__project_memory_write` | Write/update project memory with merge support |
+| `project_memory_add_note` | `mcp__plugin_ultrapower_t__project_memory_add_note` | Add a custom note to project memory |
+| `project_memory_add_directive` | `mcp__plugin_ultrapower_t__project_memory_add_directive` | Add a user directive to project memory |
 
-```bash
-omc stats          # 当前会话统计
-omc cost daily     # 每日成本报告
-omc cost weekly    # 每周成本报告
-omc sessions       # 列出会话记录
-omc agents         # Agent 明细
-omc export         # 导出数据
-omc cleanup        # 清理旧数据
-omc backfill       # 导入历史记录数据
-omc wait           # 等待后台任务完成
-omc config-stop-callback  # 配置 stop callback 通知标签
-```
+#### Trace Tools (2)
 
-分析工具：`omc-analytics`（独立分析命令）。
+| Tool | MCP Name | Description |
+|------|----------|-------------|
+| `trace_timeline` | `mcp__plugin_ultrapower_t__trace_timeline` | Show chronological agent flow trace timeline |
+| `trace_summary` | `mcp__plugin_ultrapower_t__trace_summary` | Show aggregate statistics for an agent flow trace session |
 
-### HUD Analytics 预设
+### MCP Path Boundary Rules
 
-在状态栏中启用详细成本跟踪：
+MCP tools (`ask_codex`, `ask_gemini`) enforce strict path boundaries. Both `prompt_file` and `output_file` are resolved relative to `working_directory`.
 
-```json
-{
-  "omcHud": {
-    "preset": "analytics"
-  }
-}
+| Parameter | Requirement |
+|-----------|-------------|
+| `prompt_file` | Must be within `working_directory` (after symlink resolution) |
+| `output_file` | Must be within `working_directory` (after symlink resolution) |
+| `working_directory` | Must be within the project worktree (unless bypassed) |
+
+### Environment Variable Overrides
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `OMC_MCP_OUTPUT_PATH_POLICY` | `strict` (default), `redirect_output` | Controls output file path enforcement |
+| `OMC_MCP_OUTPUT_REDIRECT_DIR` | path (default: `.omc/outputs`) | Redirect directory when policy is `redirect_output` |
+| `OMC_MCP_ALLOW_EXTERNAL_PROMPT` | `0` (default), `1` | Allow prompt file outside working directory |
+| `OMC_ALLOW_EXTERNAL_WORKDIR` | unset (default), `1` | Allow working_directory outside project worktree |
+| `OMC_DISCORD_WEBHOOK_URL` | URL | Discord webhook URL for notifications |
+| `OMC_DISCORD_NOTIFIER_BOT_TOKEN` | Token | Discord bot token for Bot API notifications |
+| `OMC_DISCORD_NOTIFIER_CHANNEL` | Channel ID | Discord channel ID for Bot API notifications |
+| `OMC_DISCORD_MENTION` | `<@uid>` or `<@&role_id>` | Mention prepended to Discord messages |
+| `OMC_TELEGRAM_BOT_TOKEN` | Token | Telegram bot token for notifications |
+| `OMC_TELEGRAM_CHAT_ID` | Chat ID | Telegram chat ID for notifications |
+| `OMC_SLACK_WEBHOOK_URL` | URL | Slack incoming webhook URL for notifications |
+
+### MCP Error Codes
+
+| Error Code | Meaning |
+|-----------|---------|
+| `E_PATH_OUTSIDE_WORKDIR_PROMPT` | prompt_file is outside working_directory |
+| `E_PATH_OUTSIDE_WORKDIR_OUTPUT` | output_file is outside working_directory |
+| `E_PATH_RESOLUTION_FAILED` | Symlink or directory resolution failed |
+| `E_WRITE_FAILED` | Output file write failed (I/O error) |
+| `E_WORKDIR_INVALID` | working_directory does not exist or is inaccessible |
+
+---
+
+## Security & Safety Rules
+
+### Non-Negotiable Security Rules
+
+These rules are enforced at the framework level and must not be bypassed:
+
+**1. Path Traversal Prevention**
+
+The `mode` parameter must pass `assertValidMode()` validation before path concatenation:
+
+```typescript
+import { assertValidMode } from './src/lib/validateMode';
+const validMode = assertValidMode(mode);
+const path = `.omc/state/${validMode}-state.json`;
 ```
 
-### 外部资源
+**2. Hook Input Sanitization**
+
+All hook inputs pass through `bridge-normalize.ts` whitelist filtering. Unknown fields are discarded. This prevents injection attacks via malformed hook payloads.
+
+**3. Shell Execution Safety (v5.5.0+)**
+
+Shell commands use `execFileSync` instead of `exec`/`execSync` to prevent shell injection. Arguments are passed as arrays, not interpolated strings.
 
-- **[MarginLab.ai](https://marginlab.ai)** - 带统计显著性检验的 SWE-Bench-Pro 性能跟踪，用于检测 Claude 模型退化
+**4. Sensitive Hook Field Filtering (v5.5.0+)**
+
+The `SENSITIVE_HOOKS` constant in bridge-normalize defines hooks with sensitive fields (permission-request, setup, session-end). These hooks apply strict field whitelisting — only explicitly allowed fields pass through.
+
+**5. SubagentStop Inference Rule**
+
+Never read `input.success` directly. Use `input.success !== false` to allow undefined/missing values to be treated as success. This prevents false-positive blocking of legitimate sub-agent completions.
+
+### Delegation Enforcer (v5.5.2+)
+
+The `delegation-enforcer` feature ensures the orchestrator delegates implementation work rather than executing it directly. When triggered, it routes substantial code changes to the appropriate executor agent and logs the delegation decision.
+
+### Security Review Checklist
+
+When modifying security-sensitive code, verify:
+- [ ] `mode` parameters validated with `assertValidMode()` before path use
+- [ ] Hook field access uses whitelist pattern from bridge-normalize
+- [ ] Shell commands use `execFileSync` with argument arrays
+- [ ] No `eval()` or dynamic `require()` with untrusted input
+- [ ] State file paths constrained to `.omc/state/` directory
 
 ---
 
-## Troubleshooting
+## Magic Keywords
+
+Include any of the following keywords anywhere in your prompt to activate enhanced modes:
 
-### 诊断安装问题
+| Keyword | Effect |
+|---------|--------|
+| `ultrawork`, `ulw` | Activate parallel agent orchestration |
+| `autopilot`, `auto-pilot`, `fullsend`, `full auto` | Fully autonomous execution |
+| `ultrapilot`, `ultra-pilot`, `parallel build`, `swarm build` | Parallel autopilot (3-5x speed) |
+| `ralph` | Persistent execution until verified complete |
+| `team`, `coordinated team` | Team mode multi-agent coordination |
+| `swarm N agents`, `coordinated agents`, `team mode` | Coordinated agent cluster |
+| `plan this`, `plan the` | Planning interview workflow |
+| `ralplan` | Iterative planning consensus |
+| `tdd`, `test first` | TDD workflow enforcement |
+| `ultrathink` | Extended thinking mode |
+| `deepsearch`, `search the codebase`, `find in codebase` | Deep codebase search |
+| `deep analyze`, `deepanalyze` | Deep analysis mode |
+| `ccg`, `claude-codex-gemini` | Three-model parallel orchestration |
+| `ask codex`, `use codex`, `delegate to codex` | Delegate to Codex (OpenAI) |
+| `ask gemini`, `use gemini`, `delegate to gemini` | Delegate to Gemini (Google) |
+| `agent pipeline`, `chain agents` | Sequential agent chain |
+| `cancelomc`, `stopomc` | Unified cancel of all active modes |
+
+### Examples
 
 ```bash
-/ultrapower:omc-doctor
+# Maximum parallelism
+ultrawork implement user authentication with OAuth
+
+# Autonomous execution
+autopilot: build a todo app with React
+
+# Persistent execution
+ralph: refactor the authentication module
+
+# Planning session
+plan this feature
+
+# TDD workflow
+tdd: implement password validation
+
+# Three-model orchestration
+ccg: implement the payment module
+
+# Cancel active modes
+cancelomc
 ```
 
-检查项目：
-- 缺失的依赖
-- 配置错误
-- Hook 安装状态
-- Agent 可用性
-- Skill 注册情况
+---
+
+## Platform Support
+
+### Operating Systems
+
+| Platform | Installation | Hook Type |
+|----------|-------------|-----------|
+| **Windows** | Claude Code Plugin | Node.js (.mjs) |
+| **macOS** | Claude Code Plugin | Node.js (.mjs) |
+| **Linux** | Claude Code Plugin | Node.js (.mjs) |
+
+> **Note**: Set `OMC_USE_NODE_HOOKS=1` to use Node.js hooks on macOS/Linux.
+
+### Available Tools
+
+| Tool | Status | Description |
+|------|--------|-------------|
+| **Read** | Available | Read files |
+| **Write** | Available | Create files |
+| **Edit** | Available | Modify files |
+| **Bash** | Available | Run shell commands |
+| **Glob** | Available | Find files by pattern |
+| **Grep** | Available | Search file contents |
+| **WebSearch** | Available | Search the web |
+| **WebFetch** | Available | Fetch web pages |
+| **Task** | Available | Spawn sub-agents |
+| **TodoWrite** | Available | Track tasks |
+
+---
+
+## Performance Monitoring
+
+ultrapower includes comprehensive agent performance, token usage, and parallel workflow debugging.
+
+Full documentation: **[Performance Monitoring Guide](./PERFORMANCE-MONITORING.md)**
+
+### Quick Overview
+
+| Feature | Description | Access |
+|---------|-------------|--------|
+| **Agent Observatory** | Real-time agent status, efficiency, bottlenecks | HUD / API |
+| **Token Analytics** | Cost tracking, usage reports, budget warnings | `omc stats`, `omc cost` |
+| **Session Replay** | Post-session event timeline analysis | `.omc/state/agent-replay-*.jsonl` |
+| **Intervention System** | Auto-detects stalled agents and cost overruns | Automatic |
+
+### CLI Commands
 
-### 配置 HUD 状态栏
+CLI entry points: `ultrapower`, `omc`, `omc-cli` (all equivalent).
 
 ```bash
-/ultrapower:hud setup
+omc stats          # Current session statistics
+omc cost daily     # Daily cost report
+omc cost weekly    # Weekly cost report
+omc sessions       # List session records
+omc agents         # Agent breakdown
+omc export         # Export data
+omc cleanup        # Clean up old data
+omc backfill       # Import historical data
+omc wait           # Wait for background task completion
+omc config-stop-callback  # Configure stop callback notification tags
 ```
 
-安装或修复 HUD 状态栏以获取实时状态更新。
+### HUD Configuration
 
-### HUD 配置（settings.json）
-
-在 `~/.claude/settings.json` 中配置 HUD 元素：
+Configure HUD elements in `~/.claude/settings.json`:
 
 ```json
 {
@@ -897,44 +1050,51 @@ omc config-stop-callback  # 配置 stop callback 通知标签
 }
 ```
 
-| 元素 | 说明 | 默认值 |
+| Element | Description | Default |
 |---------|-------------|---------|
-| `cwd` | 显示当前工作目录 | `false` |
-| `gitRepo` | 显示 git 仓库名称 | `false` |
-| `gitBranch` | 显示当前 git 分支 | `false` |
-| `omcLabel` | 显示 [OMC] 标签 | `true` |
-| `contextBar` | 显示上下文窗口使用量 | `true` |
-| `agents` | 显示活跃 agents 数量 | `true` |
-| `todos` | 显示 todo 进度 | `true` |
-| `ralph` | 显示 ralph 循环状态 | `true` |
-| `autopilot` | 显示 autopilot 状态 | `true` |
-| `axiom` | 显示 Axiom 系统状态（状态/目标/任务/学习队列/知识库/成功率） | `false` |
-| `suggestions` | 显示智能下一步建议（基于上下文/Axiom 状态/会话健康） | `false` |
+| `cwd` | Display current working directory | `false` |
+| `gitRepo` | Display git repository name | `false` |
+| `gitBranch` | Display current git branch | `false` |
+| `omcLabel` | Display [OMC] label | `true` |
+| `contextBar` | Display context window usage | `true` |
+| `agents` | Display active agent count | `true` |
+| `todos` | Display todo progress | `true` |
+| `ralph` | Display ralph loop status | `true` |
+| `autopilot` | Display autopilot status | `true` |
+| `axiom` | Display Axiom system status | `false` |
+| `suggestions` | Display smart next-step suggestions | `false` |
+
+Available presets: `minimal`, `focused`, `full`, `dense`, `analytics`, `opencode`
 
-可用预设：`minimal`、`focused`、`full`、`dense`、`analytics`、`opencode`
+---
 
-### 常见问题
+## Troubleshooting
 
-| 问题 | 解决方法 |
-|-------|----------|
-| 命令未找到 | 重新运行 `/ultrapower:omc-setup` |
-| Hooks 未执行 | 检查 hook 权限：`chmod +x ~/.claude/hooks/**/*.sh` |
-| Agents 未委派 | 验证 CLAUDE.md 已加载：检查 `./.claude/CLAUDE.md` 或 `~/.claude/CLAUDE.md` |
-| LSP 工具不工作 | 安装语言服务器：`npm install -g typescript-language-server` |
-| Token 限制错误 | 使用 `/ultrapower:` 进行 token 高效执行 |
+### Diagnose Installation Issues
 
-### 自动更新
+```bash
+/ultrapower:omc-doctor
+```
 
-ultrapower 包含一个静默自动更新系统，在后台检查更新。
+Checks:
+- Missing dependencies
+- Configuration errors
+- Hook installation status
+- Agent availability
+- Skill registration
 
-特性：
-- **频率限制**：最多每 24 小时检查一次
-- **并发安全**：锁文件防止同时更新
-- **跨平台**：在 macOS 和 Linux 上均可工作
+### Common Issues
 
-如需手动更新，重新运行插件安装命令或使用 Claude Code 内置的更新机制。
+| Issue | Resolution |
+|-------|-----------|
+| Command not found | Re-run `/ultrapower:omc-setup` |
+| Hooks not executing | Check hook permissions: `chmod +x ~/.claude/hooks/**/*.sh` |
+| Agents not delegating | Verify CLAUDE.md is loaded: check `./.claude/CLAUDE.md` or `~/.claude/CLAUDE.md` |
+| LSP tools not working | Install language server: `npm install -g typescript-language-server` |
+| Token limit errors | Use `/ultrapower:` for token-efficient execution |
+| Path traversal error | Ensure mode parameter passes `assertValidMode()` validation |
 
-### 卸载
+### Uninstall
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/liangjie559567/ultrapower/main/scripts/uninstall.sh | bash
@@ -949,79 +1109,81 @@ rm ~/.claude/commands/{analyze,autopilot,deepsearch,plan,review,ultrawork}.md
 
 ---
 
-## Axiom 系统（深度融合）
-
-ultrapower 深度融合了 Axiom 智能体编排框架，提供完整的需求→开发→进化工作流。
-
-### Axiom Agents（14 个）
-
-| 智能体 | 模型 | 用途 |
-|-------|-------|------|
-| axiom-requirement-analyst | sonnet | 需求三态门（PASS/CLARIFY/REJECT） |
-| axiom-product-designer | sonnet | Draft PRD + Mermaid 流程图生成 |
-| axiom-review-aggregator | sonnet | 5 专家并行评审 + 冲突仲裁 |
-| axiom-prd-crafter | sonnet | 工程级 PRD + 门禁验证 |
-| axiom-system-architect | sonnet | 原子任务 DAG + Manifest 生成 |
-| axiom-evolution-engine | sonnet | 知识收割 + 模式检测 + 工作流优化 |
-| axiom-context-manager | sonnet | 7 种记忆操作（读/写/状态/检查点） |
-| axiom-worker | sonnet | PM→Worker 协议，三态输出（QUESTION/COMPLETE/BLOCKED） |
-| axiom-ux-director | sonnet | UX/体验专家评审，输出 review_ux.md |
-| axiom-product-director | sonnet | 产品战略专家评审，输出 review_product.md |
-| axiom-domain-expert | sonnet | 领域知识专家评审，输出 review_domain.md |
-| axiom-tech-lead | sonnet | 技术可行性评审，输出 review_tech.md |
-| axiom-critic | sonnet | 安全/质量/逻辑评审，输出 review_critic.md |
-| axiom-sub-prd-writer | sonnet | 将 Manifest 任务拆解为可执行 Sub-PRD |
-
-### Axiom Skills（14 个）
-
-| Skill | 指令 | 用途 |
-|-------|------|------|
-| ax-draft | `/ax-draft` | 需求澄清 → Draft PRD → 用户确认 |
-| ax-review | `/ax-review` | 5 专家并行评审 → 聚合 → Rough PRD |
-| ax-decompose | `/ax-decompose` | Rough PRD → 系统架构 → 原子任务 DAG |
-| ax-implement | `/ax-implement` | 按 Manifest 执行任务，CI 门禁，自动修复 |
-| ax-analyze-error | `/ax-analyze-error` | 根因诊断 → 自动修复 → 知识队列 |
-| ax-reflect | `/ax-reflect` | 会话反思 → 经验提取 → Action Items |
-| ax-evolve | `/ax-evolve` | 处理学习队列 → 更新知识库 → 模式检测 |
-| ax-status | `/ax-status` | 完整系统状态仪表盘 |
-| ax-rollback | `/ax-rollback` | 回滚到最近检查点（需用户确认） |
-| ax-suspend | `/ax-suspend` | 保存会话状态，安全退出 |
-| ax-context | `/ax-context` | 直接操作 Axiom 记忆系统 |
-| ax-evolution | `/ax-evolution` | 进化引擎统一入口（evolve/reflect/knowledge/patterns） |
-| ax-knowledge | `/ax-knowledge` | 查询 Axiom 知识库和模式库 |
-| ax-export | `/ax-export` | 导出 Axiom 工作流产物为可移植 zip |
-
-### Axiom Hooks（2 个）
-
-| Hook | 位置 | 用途 |
-|------|------|------|
-| axiom-boot | `src/hooks/axiom-boot/` | 会话启动时注入记忆上下文 |
-| axiom-guards | `src/hooks/axiom-guards/` | 门禁规则执行（Expert/User/CI Gate） |
-
-### Axiom 记忆系统
+## Axiom System
+
+ultrapower deeply integrates the Axiom agent orchestration framework, providing a complete requirements -> development -> evolution workflow.
+
+### Axiom State Machine
+
+```
+IDLE -> PLANNING -> CONFIRMING -> EXECUTING -> AUTO_FIX -> BLOCKED -> ARCHIVING -> IDLE
+```
+
+### Axiom Gate System
+
+| Gate | Trigger | Action |
+|------|---------|--------|
+| Expert Gate | All new feature requirements | Must pass `/ax-draft` -> `/ax-review` flow |
+| User Gate | PRD draft finalization | Must display "PRD generated, confirm execution? (Yes/No)" |
+| CI Gate | Code modification completion | Must run `tsc --noEmit && npm run build && npm test` |
+| Scope Gate | File modification | Check if within `manifest.md` Impact Scope; out-of-scope triggers warning |
+
+### Axiom Memory System
 
 ```
 .omc/axiom/
-├── active_context.md       # 当前任务状态（短期记忆）
-├── project_decisions.md    # 架构决策记录（长期记忆）
-├── user_preferences.md     # 用户偏好
-├── state_machine.md        # 状态机定义
-├── reflection_log.md       # 反思日志
+├── active_context.md       # Current task state (short-term memory)
+├── project_decisions.md    # Architecture decision records (long-term memory)
+├── user_preferences.md     # User preferences
+├── state_machine.md        # State machine definition
+├── reflection_log.md       # Reflection log
 └── evolution/
-    ├── knowledge_base.md   # 知识图谱（置信度系统）
-    ├── pattern_library.md  # 代码模式库（出现次数 >= 3 提升）
-    ├── learning_queue.md   # 待处理学习素材（P0-P3 优先级）
-    └── workflow_metrics.md # 工作流执行指标
+    ├── knowledge_base.md   # Knowledge graph (confidence system)
+    ├── pattern_library.md  # Code pattern library (promoted at >= 3 occurrences)
+    ├── learning_queue.md   # Pending learning materials (P0-P3 priority)
+    └── workflow_metrics.md # Workflow execution metrics
 ```
 
-### Axiom 状态机
+### Axiom Worker Protocol
+
+Worker agents receive atomic tasks from PM, and output one of three formats:
 
-`IDLE → PLANNING → CONFIRMING → EXECUTING → AUTO_FIX → BLOCKED → ARCHIVING → IDLE`
+```
+## QUESTION
+Question: [specific question]
+Reason: [why clarification is needed]
+```
 
-### 适配器文件
+```
+## COMPLETE
+Completed: [task description]
+Changes: [list of modified files]
+Verification: [CI command output]
+```
 
-| 文件 | 目标工具 |
-|------|---------|
+```
+## BLOCKED
+Reason: [blocking cause]
+Attempted: [methods tried]
+Needs: [what help is needed]
+```
+
+**Self-repair strategy**: Up to 3 attempts. After each failure, runs `tsc --noEmit && npm run build && npm test`. After 3 failures, outputs BLOCKED.
+
+### Axiom Evolution Engine (Auto-Behavior)
+
+| Trigger Event | Auto-Action |
+|--------------|------------|
+| Task completed | Add code changes to `learning_queue.md` |
+| Error fix successful | Add fix pattern to learning queue (P1) |
+| Workflow completed | Update `workflow_metrics.md` |
+| State -> ARCHIVING | Auto-trigger `/ax-reflect` |
+| State -> IDLE | Process learning queue (P0/P1) |
+
+### Tool Adapter Files
+
+| File | Target Tool |
+|------|------------|
 | `.kiro/steering/axiom.md` | Kiro |
 | `.cursorrules` | Cursor |
 | `.gemini/GEMINI.md` | Gemini |
@@ -1030,49 +1192,31 @@ ultrapower 深度融合了 Axiom 智能体编排框架，提供完整的需求
 | `.github/copilot-instructions.md` | GitHub Copilot |
 | `.codex/CODEX.md` | Codex CLI |
 
-### 自我进化系统详细文档
-
-Axiom 自我进化系统的完整使用指南、安装说明和故障排除请参阅：
-
-**[docs/EVOLUTION.md](./EVOLUTION.md)** — Axiom 自我进化系统完整文档
-
-包含内容：
-- 系统概述与架构
-- 安装与初始化步骤
-- 核心组件说明（进化引擎、上下文管理器、Boot Hook、Guards Hook）
-- 记忆系统详解（知识库、模式库、学习队列）
-- 进化工作流（ax-reflect + ax-evolve 完整流程）
-- 所有 ax-* Skills 使用指南
-- 自动触发机制
-- 知识库管理与置信度系统
-- 状态机与门禁系统
-- HUD 集成
-- 故障排除
-
-**[docs/NEXUS.md](./NEXUS.md)** — Nexus 主动进化系统完整文档
-
-包含内容：
-- Phase 1 被动学习（已完成）与 Phase 2 主动学习架构
-- Nexus 双层架构（插件层 + VPS 云端层）
-- 反馈系统、效果追踪、主动推荐、质量迭代模块详解
-- Consciousness Loop、Self-Modifier、Self-Evaluator 模块
-- Git 同步通信机制与数据存储结构
-- Phase 2 与 Nexus 配置参考
-- VPS 部署指南（nexus-daemon）
-- 实现路线图（P0/P1/P2 优先级）
+For detailed Axiom documentation see:
+- **[docs/EVOLUTION.md](./EVOLUTION.md)** — Axiom self-evolution system complete documentation
+- **[docs/NEXUS.md](./NEXUS.md)** — Nexus active evolution system complete documentation
 
 ---
 
 ## Changelog
 
-版本历史和发布说明请参阅 [CHANGELOG.md](../CHANGELOG.md)。
+For version history and release notes see [CHANGELOG.md](../CHANGELOG.md).
+
+### Key Version Milestones
+
+- **v5.5.5** — This release: comprehensive reference documentation rewrite
+- **v5.5.2** — delegation-enforcer: ensures orchestrator delegates implementation work
+- **v5.5.0** — Security hardening: `assertValidMode()`, `execFileSync`, `SENSITIVE_HOOKS`, bridge-normalize strict whitelist
+- **v5.4.x** — Axiom deep integration: 14 agents, 14 skills, 2 hooks
+- **v5.2.x** — Team pipeline with phased routing; ultrapilot/swarm as Team facades
+- **v5.0.x** — 35 custom tools via `mcp__plugin_ultrapower_t__` prefix
 
 ---
 
 ## License
 
-MIT - 参见 [LICENSE](../LICENSE)
+MIT — see [LICENSE](../LICENSE)
 
 ## Credits
 
-灵感来源于 code-yeongyu 的 [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)。
+Inspired by code-yeongyu's [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode).