@stanco323/oh-my-claude-code 4.10.3

package/docs/ARCHITECTURE.md

@@ -0,0 +1,583 @@
+# Architecture
+
+> How oh-my-claudecode orchestrates multi-agent workflows.
+
+## Overview
+
+oh-my-claudecode enables Claude Code to orchestrate specialized agents through a skill-based routing system. It is built on four interlocking systems: **Hooks** detect lifecycle events, **Skills** inject behaviors, **Agents** execute specialized work, and **State** tracks progress across context resets.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         OH-MY-CLAUDECODE                                 │
+│                     Intelligent Skill Activation                         │
+└─────────────────────────────────────────────────────────────────────────┘
+
+  User Input                      Skill Detection                 Execution
+  ──────────                      ───────────────                 ─────────
+       │                                │                              │
+       ▼                                ▼                              ▼
+┌─────────────┐              ┌──────────────────┐           ┌─────────────────┐
+│  "ultrawork │              │   CLAUDE.md      │           │ SKILL ACTIVATED │
+│   refactor  │─────────────▶│   Auto-Routing   │──────────▶│                 │
+│   the API"  │              │                  │           │ ultrawork +     │
+└─────────────┘              │ Task Type:       │           │ default +       │
+                             │  - Implementation│           │ git-master      │
+                             │  - Multi-file    │           │                 │
+                             │  - Parallel OK   │           │ ┌─────────────┐ │
+                             │                  │           │ │ Parallel    │ │
+                             │ Skills:          │           │ │ agents      │ │
+                             │  - ultrawork ✓   │           │ │ launched    │ │
+                             │  - default ✓     │           │ └─────────────┘ │
+                             │  - git-master ✓  │           │                 │
+                             └──────────────────┘           │ ┌─────────────┐ │
+                                                            │ │ Atomic      │ │
+                                                            │ │ commits     │ │
+                                                            │ └─────────────┘ │
+                                                            └─────────────────┘
+```
+
+The four systems flow in sequence:
+
+```
+User Input --> Hooks (event detection) --> Skills (behavior injection)
+           --> Agents (task execution) --> State (progress tracking)
+```
+
+---
+
+## Agent System
+
+### Overview
+
+OMC provides 19 specialized agents organized into 4 lanes. Each agent is invoked as `oh-my-claudecode:<agent-name>` and runs on the appropriate model tier.
+
+### Build/Analysis Lane
+
+Covers the full development lifecycle from exploration to verification.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `explore` | haiku | Codebase discovery, file/symbol mapping |
+| `analyst` | opus | Requirements analysis, hidden constraint discovery |
+| `planner` | opus | Task sequencing, execution plan creation |
+| `architect` | opus | System design, interface definition, trade-off analysis |
+| `debugger` | sonnet | Root-cause analysis, build error resolution |
+| `executor` | sonnet | Code implementation, refactoring |
+| `verifier` | sonnet | Completion verification, test adequacy confirmation |
+| `tracer` | sonnet | Evidence-driven causal tracing, competing hypothesis analysis |
+
+### Review Lane
+
+Quality gates before handoff. Catches correctness and security issues.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `security-reviewer` | sonnet | Security vulnerabilities, trust boundaries, authn/authz review |
+| `code-reviewer` | opus | Comprehensive code review, API contracts, backward compatibility |
+
+### Domain Lane
+
+Domain experts called in when needed.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `test-engineer` | sonnet | Test strategy, coverage, flaky-test hardening |
+| `designer` | sonnet | UI/UX architecture, interaction design |
+| `writer` | haiku | Documentation, migration notes |
+| `qa-tester` | sonnet | Interactive CLI/service runtime validation via tmux |
+| `scientist` | sonnet | Data analysis, statistical research |
+| `git-master` | sonnet | Git operations, commits, rebase, history management |
+| `document-specialist` | sonnet | External documentation, API/SDK reference lookup |
+| `code-simplifier` | opus | Code clarity, simplification, maintainability improvement |
+
+### Coordination Lane
+
+Challenges plans and designs made by other agents. A plan passes only when no gaps can be found.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `critic` | opus | Gap analysis of plans and designs, multi-angle review |
+
+### Model Routing
+
+OMC uses three model tiers:
+
+| Tier | Model | Characteristics | Cost |
+|------|-------|-----------------|------|
+| LOW | haiku | Fast and inexpensive | Low |
+| MEDIUM | sonnet | Balanced performance and cost | Medium |
+| HIGH | opus | Highest-quality reasoning | High |
+
+Default assignments by role:
+- **haiku**: Fast lookups and simple tasks (`explore`, `writer`)
+- **sonnet**: Code implementation, debugging, testing (`executor`, `debugger`, `test-engineer`)
+- **opus**: Architecture, strategic analysis, review (`architect`, `planner`, `critic`, `code-reviewer`)
+
+### Delegation
+
+Work is delegated through the Task tool with intelligent model routing:
+
+```typescript
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  model="sonnet",
+  prompt="Implement feature..."
+)
+```
+
+**Delegate to agents when:**
+- Multiple files need to change
+- Refactoring is required
+- Debugging or root-cause analysis is needed
+- Code review or security review is needed
+- Planning or research is required
+
+**Handle directly when:**
+- Simple file lookups
+- Straightforward question answering
+- Single-command operations
+
+### Agent Selection Guide
+
+| Task Type | Recommended Agent | Model |
+|-----------|-------------------|-------|
+| Quick code lookup | `explore` | haiku |
+| Feature implementation | `executor` | sonnet |
+| Complex refactoring | `executor` (model=opus) | opus |
+| Simple bug fix | `debugger` | sonnet |
+| Complex debugging | `architect` | opus |
+| UI component | `designer` | sonnet |
+| Documentation | `writer` | haiku |
+| Test strategy | `test-engineer` | sonnet |
+| Security review | `security-reviewer` | sonnet |
+| Code review | `code-reviewer` | opus |
+| Data analysis | `scientist` | sonnet |
+
+### Typical Agent Workflow
+
+```
+explore --> analyst --> planner --> critic --> executor --> verifier
+(discover)  (analyze)   (sequence)  (review)   (implement)  (confirm)
+```
+
+### Agent Role Boundaries
+
+| Agent | Does | Does Not |
+|-------|------|----------|
+| `architect` | Code analysis, debugging, verification | Requirements gathering, planning |
+| `analyst` | Find requirements gaps | Code analysis, planning |
+| `planner` | Create task plans | Requirements analysis, plan review |
+| `critic` | Review plan quality | Requirements analysis, code analysis |
+
+---
+
+## Skills System
+
+### Overview
+
+Skills are **behavior injections** that modify how the orchestrator operates. Instead of swapping agents, skills add capabilities on top of existing agents. OMC provides 31 skills total (28 user-invocable + 3 internal/pipeline).
+
+### Skill Layers
+
+Skills compose in three layers:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  GUARANTEE LAYER (optional)                                  │
+│  ralph: "Cannot stop until verified done"                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  ENHANCEMENT LAYER (0-N skills)                              │
+│  ultrawork (parallel) | git-master (commits) | frontend-ui-ux│
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  EXECUTION LAYER (primary skill)                             │
+│  default (build) | orchestrate (coordinate) | planner (plan) │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Formula:** `[Execution Skill] + [0-N Enhancements] + [Optional Guarantee]`
+
+Example:
+```
+Task: "ultrawork: refactor API with proper commits"
+Active skills: ultrawork + default + git-master
+```
+
+### How to Invoke Skills
+
+**Slash commands:**
+```bash
+/oh-my-claudecode:autopilot build me a todo app
+/oh-my-claudecode:ralph refactor the auth module
+/oh-my-claudecode:team 3:executor "implement fullstack app"
+```
+
+**Magic keywords** — include a keyword in natural language and the skill activates automatically:
+```bash
+autopilot build me a todo app      # activates autopilot
+ralph: refactor the auth module    # activates ralph
+ultrawork implement OAuth          # activates ultrawork
+```
+
+### Core Workflow Skills
+
+#### autopilot
+Full autonomous 5-stage pipeline from idea to working code.
+- Trigger: `autopilot`, `build me`, `I want a`
+```bash
+autopilot build me a REST API with authentication
+```
+
+#### ralph
+Repeating loop that does not stop until work is verified complete. The `verifier` agent confirms completion before the loop exits.
+- Trigger: `ralph`, `don't stop`, `must complete`
+```bash
+ralph: refactor the authentication module
+```
+
+#### ultrawork
+Maximum parallelism — launches multiple agents simultaneously.
+- Trigger: `ultrawork`, `ulw`
+```bash
+ultrawork implement user authentication with OAuth
+```
+
+#### team
+Coordinates N Claude agents with a 5-stage pipeline: `plan → prd → exec → verify → fix`
+```bash
+/oh-my-claudecode:team 3:executor "implement fullstack todo app"
+```
+
+#### ccg (Claude-Codex-Gemini)
+Fans out to Codex and Gemini simultaneously; Claude synthesizes the results.
+- Trigger: `ccg`, `claude-codex-gemini`
+```bash
+ccg: review this authentication implementation
+```
+
+#### ralplan
+Iterative planning: Planner, Architect, and Critic loop until they reach consensus.
+- Trigger: `ralplan`
+```bash
+ralplan this feature
+```
+
+### Utility Skills
+
+| Skill | Description | Command |
+|-------|-------------|---------|
+| `cancel` | Cancel active execution mode | `/oh-my-claudecode:cancel` |
+| `hud` | Status bar configuration | `/oh-my-claudecode:hud` |
+| `omc-setup` | Initial setup wizard | `/oh-my-claudecode:omc-setup` |
+| `omc-doctor` | Diagnose installation | `/oh-my-claudecode:omc-doctor` |
+| `learner` | Extract reusable skills from session | `/oh-my-claudecode:learner` |
+| `skill` | Manage local skills (list/add/remove) | `/oh-my-claudecode:skill` |
+| `trace` | Evidence-driven causal tracing | `/oh-my-claudecode:trace` |
+| `release` | Automated release workflow | `/oh-my-claudecode:release` |
+| `deepinit` | Generate hierarchical AGENTS.md | `/oh-my-claudecode:deepinit` |
+| `deep-interview` | Socratic deep interview | `/oh-my-claudecode:deep-interview` |
+| `sciomc` | Parallel scientist agent orchestration | `/oh-my-claudecode:sciomc` |
+| `external-context` | Parallel document-specialist research | `/oh-my-claudecode:external-context` |
+| `ai-slop-cleaner` | Clean AI expression patterns | `/oh-my-claudecode:ai-slop-cleaner` |
+| `writer-memory` | Memory system for writing projects | `/oh-my-claudecode:writer-memory` |
+
+### Magic Keyword Reference
+
+| Keyword | Effect |
+|---------|--------|
+| `ultrawork`, `ulw`, `uw` | Parallel agent orchestration |
+| `autopilot`, `build me`, `I want a`, `handle it all`, `end to end`, `e2e this` | Autonomous execution pipeline |
+| `ralph`, `don't stop`, `must complete`, `until done` | Loop until verified complete |
+| `ccg`, `claude-codex-gemini` | 3-model orchestration |
+| `ralplan` | Consensus-based planning |
+| `deep interview`, `ouroboros` | Socratic deep interview |
+| `code review`, `review code` | Comprehensive code review mode |
+| `security review`, `review security` | Security-focused review mode |
+| `deepsearch`, `search the codebase`, `find in codebase` | Codebase search mode |
+| `deepanalyze`, `deep-analyze` | Deep analysis mode |
+| `ultrathink`, `think hard`, `think deeply` | Deep reasoning mode |
+| `tdd`, `test first`, `red green` | TDD workflow |
+| `deslop`, `anti-slop` | AI expression cleanup |
+| `cancelomc`, `stopomc` | Cancel active execution mode |
+
+### Keyword Detection Sources
+
+Keywords are processed in two places:
+
+| Source | Role | Customizable |
+|--------|------|--------------|
+| `config.jsonc` `magicKeywords` | 4 categories (ultrawork, search, analyze, ultrathink) | Yes |
+| `keyword-detector` hook | 11+ triggers (autopilot, ralph, ccg, etc.) | No |
+
+The `autopilot`, `ralph`, and `ccg` triggers are hardcoded in the hook and cannot be changed through config.
+
+---
+
+## Hooks
+
+### Overview
+
+Hooks are code that reacts to Claude Code lifecycle events. They run automatically when a user submits a prompt, uses a tool, or starts/ends a session. OMC implements agent delegation, keyword detection, and state persistence through this hook system.
+
+### Lifecycle Events
+
+Claude Code provides 11 lifecycle events. OMC registers hooks on these events:
+
+| Event | When It Fires | OMC Usage |
+|-------|---------------|-----------|
+| `UserPromptSubmit` | User submits a prompt | Magic keyword detection, skill injection |
+| `SessionStart` | Session begins | Initial setup, project memory load |
+| `PreToolUse` | Before a tool is used | Permission validation, parallel execution hints |
+| `PermissionRequest` | Permission requested | Bash command permission handling |
+| `PostToolUse` | After a tool is used | Result validation, project memory update |
+| `PostToolUseFailure` | After a tool fails | Error recovery handling |
+| `SubagentStart` | Subagent starts | Agent tracking |
+| `SubagentStop` | Subagent stops | Agent tracking, output verification |
+| `PreCompact` | Before context compaction | Preserve critical information, save project memory |
+| `Stop` | Claude is about to stop | Persistent mode enforcement, code simplification |
+| `SessionEnd` | Session ends | Session data cleanup |
+
+### system-reminder Injection
+
+Hooks inject additional context to Claude via `<system-reminder>` tags:
+
+```xml
+<system-reminder>
+hook success: Success
+</system-reminder>
+```
+
+Injected pattern meanings:
+
+| Pattern | Meaning |
+|---------|---------|
+| `hook success: Success` | Hook ran normally, continue as planned |
+| `hook additional context: ...` | Additional context information, take note |
+| `[MAGIC KEYWORD: ...]` | Magic keyword detected, execute indicated skill |
+| `The boulder never stops` | ralph/ultrawork mode is active |
+
+### Key Hooks
+
+**keyword-detector** — fires on `UserPromptSubmit`. Detects magic keywords in user input and activates the corresponding skill.
+
+**persistent-mode** — fires on `Stop`. When a persistent mode (ralph, ultrawork) is active, prevents Claude from stopping until work is verified complete.
+
+**pre-compact** — fires on `PreCompact`. Saves critical information to the notepad before the context window is compressed.
+
+**subagent-tracker** — fires on `SubagentStart` and `SubagentStop`. Tracks currently running agents; validates output on stop.
+
+**context-guard-stop** — fires on `Stop`. Monitors context usage and warns when approaching the limit.
+
+**code-simplifier** — fires on `Stop`. Disabled by default. When enabled, automatically simplifies modified files when Claude stops.
+
+Enable via config:
+```json
+{
+  "codeSimplifier": {
+    "enabled": true,
+    "extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
+    "maxFiles": 10
+  }
+}
+```
+
+### Hook Registration Structure
+
+OMC hooks are declared in `hooks.json`. Each hook is a Node.js script with a timeout:
+
+```json
+{
+  "UserPromptSubmit": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node scripts/keyword-detector.mjs",
+          "timeout": 5
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `matcher`: Pattern the hook responds to (`*` matches all input)
+- `timeout`: Timeout in seconds
+- `type`: Always `"command"` (runs an external command)
+
+### Disabling Hooks
+
+Disable all hooks:
+```bash
+export DISABLE_OMC=1
+```
+
+Skip specific hooks (comma-separated):
+```bash
+export OMC_SKIP_HOOKS="keyword-detector,persistent-mode"
+```
+
+---
+
+## State Management
+
+### Overview
+
+OMC stores task progress and project knowledge in the `.omc/` directory. The state system preserves critical information even when context compaction resets the context window.
+
+### Directory Structure
+
+```
+.omc/
+├── state/                    # Per-mode state files
+│   ├── autopilot-state.json  # autopilot progress
+│   ├── ralph-state.json      # ralph loop state
+│   ├── team/                 # team task state
+│   └── sessions/             # per-session state
+│       └── {sessionId}/
+├── notepad.md                # Compaction-resistant memo pad
+├── project-memory.json       # Project knowledge store
+├── plans/                    # Execution plans
+├── notepads/                 # Per-plan knowledge capture
+│   └── {plan-name}/
+│       ├── learnings.md
+│       ├── decisions.md
+│       ├── issues.md
+│       └── problems.md
+├── autopilot/                # autopilot artifacts
+│   └── spec.md
+├── research/                 # Research results
+└── logs/                     # Execution logs
+```
+
+**Global State:**
+- `~/.omc/state/{name}.json` — user preferences and global config
+
+Legacy locations are auto-migrated on read.
+
+### Notepad
+
+**File:** `.omc/notepad.md`
+
+The notepad survives context compaction. Content written to it persists even after the context window is reset.
+
+Notes can be saved using the `notepad_write_manual` MCP tool or the `notepad_write_priority` tool for persistent notes.
+
+**MCP Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `notepad_read` | Read notepad contents |
+| `notepad_write_priority` | Write high-priority memo (permanent retention) |
+| `notepad_write_working` | Write working memo |
+| `notepad_write_manual` | Write manual memo |
+| `notepad_prune` | Clean up old memos |
+| `notepad_stats` | View notepad statistics |
+
+**How it works:**
+1. On `PreCompact` event, important information is saved to the notepad
+2. After compaction, notepad contents are re-injected into context
+3. Agents use the notepad to recover previous context
+
+### Project Memory
+
+**File:** `.omc/project-memory.json`
+
+Project memory is a persistent store for project-level knowledge. It survives across sessions.
+
+**MCP Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `project_memory_read` | Read project memory |
+| `project_memory_write` | Overwrite entire project memory |
+| `project_memory_add_note` | Add a note |
+| `project_memory_add_directive` | Add a directive |
+
+**Lifecycle integration:**
+- `SessionStart`: Load project memory and inject into context
+- `PostToolUse`: Extract project knowledge from tool results and save
+- `PreCompact`: Save project memory before context compaction
+
+### Session Scope
+
+**Path:** `.omc/state/sessions/{sessionId}/`
+
+Stores state isolated per session. Multiple sessions on the same project run simultaneously without state conflicts.
+
+### Plan Notepad (Per-Plan Knowledge Capture)
+
+**Path:** `.omc/notepads/{plan-name}/`
+
+Stores learnings from each execution plan separately.
+
+| File | Contents |
+|------|----------|
+| `learnings.md` | Discovered patterns, successful approaches |
+| `decisions.md` | Architecture decisions and rationale |
+| `issues.md` | Problems and blockers |
+| `problems.md` | Technical debt and cautions |
+
+All entries are timestamped automatically.
+
+### Centralized State (Optional)
+
+By default, state is stored in the project's `.omc/` directory and is deleted when the worktree is removed.
+
+To preserve state across worktree deletions, set the `OMC_STATE_DIR` environment variable:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export OMC_STATE_DIR="$HOME/.claude/omc"
+```
+
+State is then stored at `~/.claude/omc/{project-identifier}/`. The project identifier is a hash of the Git remote URL, so the same repository shares state across different worktrees.
+
+### Persistent Memory Tags
+
+For critical information, use `<remember>` tags:
+
+```xml
+<!-- Retained for 7 days -->
+<remember>API endpoint changed to /v2</remember>
+
+<!-- Retained permanently -->
+<remember priority>Never access production DB directly</remember>
+```
+
+| Tag | Retention |
+|-----|-----------|
+| `<remember>` | 7 days |
+| `<remember priority>` | Permanent |
+
+---
+
+## Verification Protocol
+
+The verification module ensures work completion with evidence:
+
+**Standard Checks:**
+- BUILD: Compilation passes
+- TEST: All tests pass
+- LINT: No linting errors
+- FUNCTIONALITY: Feature works as expected
+- ARCHITECT: Opus-tier review approval
+- TODO: All tasks completed
+- ERROR_FREE: No unresolved errors
+
+Evidence must be fresh (within 5 minutes) and include actual command output.
+
+---
+
+## For More Details
+
+- **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