oh-my-claude-sisyphus 3.5.6 → 3.5.8

package/docs/ARCHITECTURE.md

@@ -1,261 +1,10 @@
-# Agent Architecture: OpenCode vs Claude Code
+# Architecture
 
-This document explains the architectural differences between OpenCode's swappable master agent system and Claude Code's skill-based routing, and how oh-my-claudecode bridges this gap elegantly.
-
----
+> How oh-my-claudecode orchestrates multi-agent workflows.
 
 ## Overview
 
-| Aspect | OpenCode | Claude Code |
-|--------|----------|-------------|
-| Master Agent | **Swappable** | **Fixed** |
-| Sub Agents | Via Task tool | Via Task tool |
-| Routing | Agent switching | Skill activation |
-| Flexibility | High (any agent as master) | High (via skill composition) |
-
----
-
-## OpenCode: Swappable Master Agent
-
-### How It Works
-
-In OpenCode (oh-my-opencode), the master agent can be dynamically swapped based on task requirements:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    OPENCODE RUNTIME                          │
-└─────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              │               │               │
-              ▼               ▼               ▼
-       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-       │   DEFAULT   │ │  ARCHITECT  │ │   PLANNER   │
-       │  (Default)  │ │  (Debug)    │ │  (Planning) │
-       │             │ │             │ │             │
-       │ Can become  │ │ Can become  │ │ Can become  │
-       │   MASTER    │ │   MASTER    │ │   MASTER    │
-       └─────────────┘ └─────────────┘ └─────────────┘
-              │               │               │
-              └───────────────┼───────────────┘
-                              │
-                              ▼
-                    ┌─────────────────┐
-                    │   SUB-AGENTS    │
-                    │  (Delegated)    │
-                    └─────────────────┘
-```
-
-### Agent Switching Flow
-
-```typescript
-// OpenCode pseudo-code
-class AgentOrchestrator {
-  private masterAgent: Agent;
-
-  // Can swap master at runtime
-  switchMaster(agentType: 'default' | 'architect' | 'planner') {
-    this.masterAgent = AgentFactory.create(agentType);
-  }
-
-  // Master delegates to sub-agents
-  async execute(task: string) {
-    return this.masterAgent.run(task, {
-      subAgents: this.availableSubAgents
-    });
-  }
-}
-
-// Usage
-orchestrator.switchMaster('planner');  // Planning mode
-await orchestrator.execute('Design auth system');
-
-orchestrator.switchMaster('default');    // Implementation mode
-await orchestrator.execute('Implement the plan');
-```
-
-### Pros
-- Direct control over which agent leads
-- Clean separation between master behaviors
-- Easy to add new master agent types
-
-### Cons
-- Requires runtime agent management
-- Context can be lost during switches
-- More complex state management
-
----
-
-## Claude Code: Fixed Master with Skills
-
-### The Constraint
-
-Claude Code has a **fixed master agent** - you cannot swap which agent is the "main" one. The conversation always runs through the same Claude instance.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    CLAUDE CODE RUNTIME                       │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-                    ┌─────────────────┐
-                    │  CLAUDE MASTER  │  ← FIXED, cannot swap
-                    │   (Always On)   │
-                    └────────┬────────┘
-                             │
-              ┌──────────────┼──────────────┐
-              │              │              │
-              ▼              ▼              ▼
-       ┌───────────┐  ┌───────────┐  ┌───────────┐
-       │ architect │  │ researcher│  │  explore  │
-       │ (Opus)    │  │ (Sonnet)  │  │ (Haiku)   │
-       └───────────┘  └───────────┘  └───────────┘
-              ↑              ↑              ↑
-              └──────────────┼──────────────┘
-                             │
-                    Only as SUB-agents
-                    (via Task tool)
-```
-
-### The Solution: Skill-Based Routing
-
-Instead of swapping the master agent, we **inject behaviors** into the fixed master through Skills:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    CLAUDE CODE + SKILLS                      │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-                    ┌─────────────────┐
-                    │  CLAUDE MASTER  │
-                    │                 │
-                    │  ┌───────────┐  │
-                    │  │  SKILL    │  │  ← Injected behavior
-                    │  │  LAYER    │  │
-                    │  └───────────┘  │
-                    └────────┬────────┘
-                             │
-              ┌──────────────┼──────────────┐
-              ▼              ▼              ▼
-         Sub-agents    Sub-agents    Sub-agents
-```
-
-### How Skills Work
-
-Skills are **behavior injections** that modify how the master agent operates:
-
-```markdown
-# When user says "plan the auth system"
-
-1. CLAUDE.md contains routing rules
-2. Claude detects "plan" → planning task
-3. Claude invokes Skill(skill: "planner")
-4. Planner skill template is injected
-5. Claude now BEHAVES like Planner
-6. But it's still the same master agent
-```
-
----
-
-## The Elegant Solution: Intelligent Skill Activation
-
-### Skill Layers
-
-We solved the "can't swap master" limitation by creating **composable skill layers**:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    SKILL COMPOSITION                         │
-└─────────────────────────────────────────────────────────────┘
-
-  ┌─────────────────────────────────────────────────────────┐
-  │  GUARANTEE LAYER (optional)                              │
-  │  ┌─────────────┐                                        │
-  │  │ ralph  │  "Cannot stop until verified done"     │
-  │  └─────────────┘                                        │
-  └─────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-  ┌─────────────────────────────────────────────────────────┐
-  │  ENHANCEMENT LAYER (0-N skills)                          │
-  │  ┌───────────┐ ┌───────────┐ ┌─────────────────┐        │
-  │  │ ultrawork │ │git-master │ │ frontend-ui-ux  │        │
-  │  │ (parallel)│ │ (commits) │ │   (design)      │        │
-  │  └───────────┘ └───────────┘ └─────────────────┘        │
-  └─────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-  ┌─────────────────────────────────────────────────────────┐
-  │  EXECUTION LAYER (pick one primary)                      │
-  │  ┌───────────┐ ┌─────────────┐ ┌────────────┐           │
-  │  │  default  │ │ orchestrator│ │  planner   │           │
-  │  │ (build)   │ │ (coordinate)│ │  (plan)    │           │
-  │  └───────────┘ └─────────────┘ └────────────┘           │
-  └─────────────────────────────────────────────────────────┘
-```
-
-### Composition Formula
-
-```
-[Execution Skill] + [0-N Enhancement Skills] + [Optional Guarantee]
-```
-
-### Examples
-
-```
-Task: "Add dark mode with proper commits"
-Skills: default + frontend-ui-ux + git-master
-
-Task: "ultrawork: refactor entire API"
-Skills: ultrawork + default + git-master
-
-Task: "Plan auth, then implement completely"
-Skills: planner → default + ralph (transition)
-
-Task: "Fix bug, don't stop until done"
-Skills: default + ralph
-```
-
----
-
-## Comparison: Agent Swap vs Skill Activation
-
-### Scenario: Complex Project with Planning → Implementation
-
-**OpenCode Approach (Agent Swap):**
-```
-1. User: "Plan the authentication system"
-2. System: Switch master to Planner
-3. Planner: Creates comprehensive plan
-4. User: "Now implement it"
-5. System: Switch master to Default  ← Context may be lost
-6. Default: Implements (needs to re-read plan)
-```
-
-**Claude Code Approach (Skill Activation):**
-```
-1. User: "Plan the authentication system"
-2. Claude: Activates planner skill
-3. Claude (as Planner): Creates comprehensive plan
-4. User: "Now implement it"
-5. Claude: Transitions to default skill  ← Same context!
-6. Claude (as Default): Implements (already has plan in context)
-```
-
-### Why Skills Are More Elegant
-
-| Aspect | Agent Swap | Skill Activation |
-|--------|------------|------------------|
-| Context | Lost on swap | Preserved |
-| Transitions | Explicit, disruptive | Seamless, fluid |
-| Composition | One master at a time | Multiple skills stack |
-| State | Needs external tracking | In-conversation |
-| User Experience | "Switch to X mode" | Natural language |
-
----
-
-## Architecture Diagram
+oh-my-claudecode enables Claude Code to orchestrate specialized agents through a skill-based routing system.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
@@ -287,179 +36,113 @@ Skills: default + ralph
                                                             └─────────────────┘
 ```
 
----
+## Core Concepts
 
-## Implementation Details
+### Skills
 
-### CLAUDE.md Auto-Routing Section
+Skills are **behavior injections** that modify how the orchestrator operates. Instead of swapping agents, we inject capabilities through composable skills:
 
-```markdown
-## INTELLIGENT SKILL ACTIVATION
+- **Execution Skills**: Primary task handlers (`default`, `planner`, `orchestrate`)
+- **Enhancement Skills**: Additional capabilities (`ultrawork`, `git-master`, `frontend-ui-ux`)
+- **Guarantee Skills**: Completion enforcement (`ralph`)
 
-Skills ENHANCE your capabilities. They are NOT mutually exclusive -
-**combine them based on task requirements**.
+Skills can stack and compose:
+```
+Task: "ultrawork: refactor API with proper commits"
+Skills: ultrawork + default + git-master
+```
 
-### Task Type → Skill Selection
+### Agents
 
-Use your judgment to detect task type and activate appropriate skills:
+32 specialized agents organized by complexity tier:
 
-| Task Type | Skill Combination | When |
-|-----------|-------------------|------|
-| Multi-step implementation | `default` | Building features |
-| + parallel subtasks | `+ ultrawork` | 3+ independent tasks |
-| + multi-file changes | `+ git-master` | 3+ files |
-| UI/frontend work | `+ frontend-ui-ux` | Components, styling |
-| Strategic planning | `planner` | Need plan first |
-| Must complete | `+ ralph` | Completion critical |
+| Tier | Model | Use For |
+|------|-------|---------|
+| LOW | Haiku | Quick lookups, simple operations |
+| MEDIUM | Sonnet | Standard implementations |
+| HIGH | Opus | Complex reasoning, architecture |
 
-### Activation Guidance
+See [FEATURES.md](./FEATURES.md) for the complete agent roster.
 
-- **DO NOT** wait for explicit skill invocation
-- **DO** use your judgment
-- **DO** combine skills when multiple apply
-- **EXPLICIT** slash commands always take precedence
-```
+### Delegation
 
-### Skill Invocation Flow
+Work is delegated through the Task tool with intelligent model routing:
 
 ```typescript
-// Conceptual flow (happens in Claude's reasoning)
-
-function handleUserRequest(request: string) {
-  // 1. Detect task type
-  const taskType = analyzeTaskType(request);
-
-  // 2. Select skill combination
-  const skills = selectSkills(taskType);
-  // e.g., ['default', 'ultrawork', 'git-master']
-
-  // 3. Invoke skills (stacked)
-  for (const skill of skills) {
-    invoke(Skill, { skill });  // Skill tool
-  }
-
-  // 4. Execute with combined behaviors
-  executeTask(request);
-}
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  model="sonnet",
+  prompt="Implement feature..."
+)
 ```
 
----
+Categories like `visual-engineering` and `ultrabrain` auto-select model tier, temperature, and thinking budget.
 
-## Migration from OpenCode
+## Skill Composition
 
-If you're coming from oh-my-opencode with agent switching:
+Skills compose in layers:
 
-| OpenCode Pattern | Claude Code Equivalent |
-|------------------|------------------------|
-| `switchMaster('planner')` | Invoke `planner` skill |
-| `switchMaster('default')` | Invoke `default` skill |
-| `switchMaster('architect')` | Use `architect` sub-agent via Task |
-| Multiple masters | Skill composition |
-| Master + sub-agents | Execution skill + sub-agents |
-
-### Key Differences
-
-1. **No explicit "switch"** - Skills activate based on task type
-2. **Context preserved** - Same conversation, different behaviors
-3. **Composition** - Multiple skills can be active simultaneously
-4. **Fluid transitions** - `planner` → `default` happens naturally
+```
+┌─────────────────────────────────────────────────────────────┐
+│  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]`
 
-## Conclusion
+## State Management
 
-While Claude Code's fixed master agent might seem like a limitation compared to OpenCode's swappable masters, the **skill-based routing system is actually more elegant**:
+State files follow standardized locations:
 
-1. **Preserves context** across mode changes
-2. **Enables composition** (ultrawork + git-master + sisyphus)
-3. **Natural language** activation (no explicit mode switching)
-4. **Judgment-based** routing (Claude decides based on task)
+**Local Project State:**
+- `.omc/state/{name}.json` - Session state (ultrapilot, swarm, pipeline)
+- `.omc/notepads/{plan-name}/` - Plan-scoped wisdom capture
 
-The skill layer architecture transforms a constraint into a feature, providing a more fluid and powerful orchestration experience.
+**Global State:**
+- `~/.omc/state/{name}.json` - User preferences and global config
 
----
+Legacy locations are auto-migrated on read.
 
-## References
+## Hooks
 
-- [Oh-My-OpenCode](https://github.com/code-yeongyu/oh-my-opencode) - Original multi-agent system
-- [Claude Code Skills](https://docs.anthropic.com/claude-code/skills) - Skill documentation
-- [Intelligent Skill Activation](../README.md#intelligent-skill-activation-beta) - Beta feature docs
+oh-my-claudecode uses Claude Code's hooks system for lifecycle events:
 
----
+- **conversationStart**: Initialize OMC, check for active modes
+- **beforeRequest**: Task delegation, skill routing
+- **afterResponse**: State updates, verification checks
 
-## v3.1 Feature Architecture
+Hooks are defined in `.claude/hooks/` and managed through the plugin system.
 
-### Delegation Categories Flow
+## Verification Protocol
 
-```
-Task Prompt                Category Detection           Model Selection
-───────────                ──────────────────           ───────────────
-     │                           │                            │
-     ▼                           ▼                            ▼
-┌─────────────┐           ┌──────────────────┐          ┌─────────────────┐
-│ "Design a   │           │ detectCategory   │          │ ComplexityTier  │
-│  beautiful  │──────────▶│ FromPrompt()     │─────────▶│                 │
-│  dashboard" │           │                  │          │ HIGH → opus     │
-└─────────────┘           │ Keywords:        │          │ MEDIUM → sonnet │
-                          │ - design ✓       │          │ LOW → haiku     │
-                          │ - dashboard ✓    │          └─────────────────┘
-                          │                  │                  │
-                          │ Category:        │                  ▼
-                          │ visual-engineering│          ┌─────────────────┐
-                          └──────────────────┘          │ Config Applied  │
-                                                        │ tier: HIGH      │
-                                                        │ temp: 0.7       │
-                                                        │ thinking: high  │
-                                                        └─────────────────┘
-```
+The verification module ensures work completion with evidence:
 
-### Notepad Wisdom Storage Structure
+**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
 
-```
-.omc/
-└── notepads/
-    └── {plan-name}/
-        ├── learnings.md    # Technical discoveries
-        ├── decisions.md    # Architectural choices
-        ├── issues.md       # Known issues + workarounds
-        └── problems.md     # Blockers requiring resolution
-
-Entry Format:
-┌─────────────────────────────────────────┐
-│ ## 2024-01-15 14:30:00                  │
-│                                         │
-│ Content of the wisdom entry...          │
-└─────────────────────────────────────────┘
-```
+Evidence must be fresh (within 5 minutes) and include actual command output.
 
-### Directory Diagnostics Strategy Selection
+## For More Details
 
-```
-                    ┌──────────────────┐
-                    │ runDirectory     │
-                    │ Diagnostics()    │
-                    └────────┬─────────┘
-                             │
-              ┌──────────────┴──────────────┐
-              │       strategy = ?          │
-              └──────────────┬──────────────┘
-                             │
-         ┌───────────────────┼───────────────────┐
-         │                   │                   │
-    strategy='tsc'      strategy='auto'    strategy='lsp'
-         │                   │                   │
-         ▼                   ▼                   ▼
-   ┌───────────┐      ┌───────────┐       ┌───────────┐
-   │ tsc       │      │ tsconfig  │       │ LSP       │
-   │ --noEmit  │      │ exists?   │       │ Iteration │
-   │ (fast)    │      │           │       │ (fallback)│
-   └───────────┘      └─────┬─────┘       └───────────┘
-                            │
-                    ┌───────┴───────┐
-                    │ YES       NO  │
-                    └───────┬───────┘
-                            │
-                  ┌─────────┴─────────┐
-                  ▼                   ▼
-            Use tsc              Use LSP
-```
+- **API Reference**: See [FEATURES.md](./FEATURES.md)
+- **User Guide**: See [README.md](../README.md)
+- **Skills Reference**: See CLAUDE.md in your project