oh-my-claude-sisyphus 3.8.15 → 3.9.0

package/docs/shared/agent-tiers.md

@@ -0,0 +1,165 @@
+# Agent Tiers Reference
+
+This is the single source of truth for all agent tier information. All skill files and documentation should reference this file instead of duplicating the table.
+
+## Tier Matrix
+
+| Domain | LOW (Haiku) | MEDIUM (Sonnet) | HIGH (Opus) |
+|--------|-------------|-----------------|-------------|
+| **Analysis** | architect-low | architect-medium | architect |
+| **Execution** | executor-low | executor | executor-high |
+| **Deep Work** | - | - | deep-executor |
+| **Search** | explore | explore-medium | explore-high |
+| **Research** | researcher-low | researcher | - |
+| **Frontend** | designer-low | designer | designer-high |
+| **Docs** | writer | - | - |
+| **Visual** | - | vision | - |
+| **Planning** | - | - | planner |
+| **Critique** | - | - | critic |
+| **Pre-Planning** | - | - | analyst |
+| **Testing** | - | qa-tester | qa-tester-high |
+| **Security** | security-reviewer-low | - | security-reviewer |
+| **Build** | build-fixer-low | build-fixer | - |
+| **TDD** | tdd-guide-low | tdd-guide | - |
+| **Code Review** | code-reviewer-low | - | code-reviewer |
+| **Data Science** | scientist-low | scientist | scientist-high |
+
+## Model Routing Guide
+
+| Task Complexity | Tier | Model | When to Use |
+|-----------------|------|-------|-------------|
+| Simple | LOW | haiku | Quick lookups, simple fixes, "What does X return?" |
+| Standard | MEDIUM | sonnet | Feature implementation, standard debugging, "Add validation" |
+| Complex | HIGH | opus | Architecture decisions, complex debugging, "Refactor system" |
+
+## Agent Selection by Task Type
+
+| Task Type | Best Agent | Tier |
+|-----------|------------|------|
+| Quick code lookup | explore | LOW |
+| Find files/patterns | explore, explore-medium | LOW/MEDIUM |
+| Complex architectural search | explore-high | HIGH |
+| Simple code change | executor-low | LOW |
+| Feature implementation | executor | MEDIUM |
+| Complex refactoring | executor-high | HIGH |
+| Debug simple issue | architect-low | LOW |
+| Debug complex issue | architect | HIGH |
+| UI component | designer | MEDIUM |
+| Complex UI system | designer-high | HIGH |
+| Write docs/comments | writer | LOW |
+| Research docs/APIs | researcher | MEDIUM |
+| Analyze images/diagrams | vision | MEDIUM |
+| Strategic planning | planner | HIGH |
+| Review/critique plan | critic | HIGH |
+| Pre-planning analysis | analyst | HIGH |
+| Interactive CLI testing | qa-tester | MEDIUM |
+| Security review | security-reviewer | HIGH |
+| Quick security scan | security-reviewer-low | LOW |
+| Fix build errors | build-fixer | MEDIUM |
+| Simple build fix | build-fixer-low | LOW |
+| TDD workflow | tdd-guide | MEDIUM |
+| Quick test suggestions | tdd-guide-low | LOW |
+| Code review | code-reviewer | HIGH |
+| Quick code check | code-reviewer-low | LOW |
+| Data analysis/stats | scientist | MEDIUM |
+| Quick data inspection | scientist-low | LOW |
+| Complex ML/hypothesis | scientist-high | HIGH |
+| Find symbol references | explore-high | HIGH |
+| Get file/workspace symbol outline | explore | LOW |
+| Structural code pattern search | explore | LOW |
+| Structural code transformation | executor-high | HIGH |
+| Project-wide type checking | build-fixer | MEDIUM |
+| Check single file for errors | executor-low | LOW |
+| Data analysis / computation | scientist | MEDIUM |
+| Complex autonomous work | deep-executor | HIGH |
+| Deep goal-oriented execution | deep-executor | HIGH |
+
+## Usage
+
+When delegating, always specify the model explicitly:
+
+```
+Task(subagent_type="oh-my-claudecode:executor",
+     model="sonnet",
+     prompt="...")
+```
+
+For token savings, prefer lower tiers when the task allows:
+- Use `haiku` for simple lookups and quick fixes
+- Use `sonnet` for standard implementation work
+- Reserve `opus` for complex reasoning tasks
+
+## MCP Tools & Agent Capabilities
+
+### Tool Inventory
+
+| Tool | Category | Purpose | Assigned to Agents? |
+|------|----------|---------|---------------------|
+| `lsp_hover` | LSP | Get type info and documentation at a code position | NO (orchestrator-direct) |
+| `lsp_goto_definition` | LSP | Jump to where a symbol is defined | NO (orchestrator-direct) |
+| `lsp_find_references` | LSP | Find all usages of a symbol across the codebase | YES (`explore-high` only) |
+| `lsp_document_symbols` | LSP | Get outline of all symbols in a file | YES |
+| `lsp_workspace_symbols` | LSP | Search for symbols by name across the workspace | YES |
+| `lsp_diagnostics` | LSP | Get errors, warnings, and hints for a file | YES |
+| `lsp_diagnostics_directory` | LSP | Project-level type checking (tsc --noEmit or LSP) | YES |
+| `lsp_prepare_rename` | LSP | Check if a symbol can be renamed | NO (orchestrator-direct) |
+| `lsp_rename` | LSP | Rename a symbol across the entire project | NO (orchestrator-direct) |
+| `lsp_code_actions` | LSP | Get available refactorings and quick fixes | NO (orchestrator-direct) |
+| `lsp_code_action_resolve` | LSP | Get full edit details for a code action | NO (orchestrator-direct) |
+| `lsp_servers` | LSP | List available language servers and install status | NO (orchestrator-direct) |
+| `ast_grep_search` | AST | Pattern-based structural code search using AST | YES |
+| `ast_grep_replace` | AST | Pattern-based structural code transformation | YES (`executor-high` only) |
+| `python_repl` | Data | Persistent Python REPL for data analysis and computation | YES |
+
+### Agent Tool Matrix (MCP Tools Only)
+
+| Agent | LSP Diagnostics | LSP Dir Diagnostics | LSP Symbols | LSP References | AST Search | AST Replace | Python REPL |
+|-------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| `explore` | - | - | doc + workspace | - | yes | - | - |
+| `explore-medium` | - | - | doc + workspace | - | yes | - | - |
+| `explore-high` | - | - | doc + workspace | yes | yes | - | - |
+| `architect-low` | yes | - | - | - | - | - | - |
+| `architect-medium` | yes | yes | - | - | yes | - | - |
+| `architect` | yes | yes | - | - | yes | - | - |
+| `executor-low` | yes | - | - | - | - | - | - |
+| `executor` | yes | yes | - | - | - | - | - |
+| `executor-high` | yes | yes | - | - | yes | yes | - |
+| `deep-executor` | yes | yes | - | - | yes | yes | - |
+| `build-fixer` | yes | yes | - | - | - | - | - |
+| `build-fixer-low` | yes | yes | - | - | - | - | - |
+| `tdd-guide` | yes | - | - | - | - | - | - |
+| `tdd-guide-low` | yes | - | - | - | - | - | - |
+| `code-reviewer` | yes | - | - | - | yes | - | - |
+| `code-reviewer-low` | yes | - | - | - | - | - | - |
+| `qa-tester` | yes | - | - | - | - | - | - |
+| `qa-tester-high` | yes | - | - | - | - | - | - |
+| `scientist-low` | - | - | - | - | - | - | yes |
+| `scientist` | - | - | - | - | - | - | yes |
+| `scientist-high` | - | - | - | - | - | - | yes |
+
+### Unassigned Tools (Orchestrator-Direct)
+
+The following 7 MCP tools are NOT assigned to any agent. Use directly when needed:
+
+| Tool | When to Use Directly |
+|------|---------------------|
+| `lsp_hover` | Quick type lookups during conversation |
+| `lsp_goto_definition` | Navigating to symbol definitions during analysis |
+| `lsp_prepare_rename` | Checking rename feasibility before deciding on approach |
+| `lsp_rename` | Safe rename operations (returns edit preview, does not auto-apply) |
+| `lsp_code_actions` | Discovering available refactorings |
+| `lsp_code_action_resolve` | Getting details of a specific code action |
+| `lsp_servers` | Checking language server availability |
+
+For complex rename or refactoring tasks requiring implementation, delegate to `executor-high` which can use `ast_grep_replace` for structural transformations.
+
+### Tool Selection Guidance
+
+- **Need file symbol outline or workspace search?** Use `lsp_document_symbols`/`lsp_workspace_symbols` via `explore`, `explore-medium`, or `explore-high`
+- **Need to find all usages of a symbol?** Use `lsp_find_references` via `explore-high` (only agent with it)
+- **Need structural code patterns?** (e.g., "find all functions matching X shape") Use `ast_grep_search` via `explore` family, `architect`/`architect-medium`, or `code-reviewer`
+- **Need to transform code structurally?** Use `ast_grep_replace` via `executor-high` (only agent with it)
+- **Need project-wide type checking?** Use `lsp_diagnostics_directory` via `architect`/`architect-medium`, `executor`/`executor-high`, or `build-fixer` family
+- **Need single-file error checking?** Use `lsp_diagnostics` via many agents (see matrix)
+- **Need data analysis / computation?** Use `python_repl` via `scientist` agents (all tiers)
+- **Need quick type info or definition lookup?** Use `lsp_hover`/`lsp_goto_definition` directly (orchestrator-direct tools)

package/docs/shared/features.md

@@ -0,0 +1,131 @@
+# Features Reference (v3.1 - v3.4)
+
+## Notepad Wisdom System
+
+Plan-scoped wisdom capture for learnings, decisions, issues, and problems.
+
+**Location:** `.omc/notepads/{plan-name}/`
+
+| File | Purpose |
+|------|---------|
+| `learnings.md` | Technical discoveries and patterns |
+| `decisions.md` | Architectural and design decisions |
+| `issues.md` | Known issues and workarounds |
+| `problems.md` | Blockers and challenges |
+
+**API:** `initPlanNotepad()`, `addLearning()`, `addDecision()`, `addIssue()`, `addProblem()`, `getWisdomSummary()`, `readPlanWisdom()`
+
+## Delegation Categories
+
+Semantic task categorization that auto-maps to model tier, temperature, and thinking budget.
+
+| Category | Tier | Temperature | Thinking | Use For |
+|----------|------|-------------|----------|---------|
+| `visual-engineering` | HIGH | 0.7 | high | UI/UX, frontend, design systems |
+| `ultrabrain` | HIGH | 0.3 | max | Complex reasoning, architecture, deep debugging |
+| `artistry` | MEDIUM | 0.9 | medium | Creative solutions, brainstorming |
+| `quick` | LOW | 0.1 | low | Simple lookups, basic operations |
+| `writing` | MEDIUM | 0.5 | medium | Documentation, technical writing |
+
+**Auto-detection:** Categories detect from prompt keywords automatically.
+
+## Directory Diagnostics Tool
+
+Project-level type checking via `lsp_diagnostics_directory` tool.
+
+**Strategies:**
+- `auto` (default) - Auto-selects best strategy, prefers tsc when tsconfig.json exists
+- `tsc` - Fast, uses TypeScript compiler
+- `lsp` - Fallback, iterates files via Language Server
+
+**Usage:** Check entire project for errors before commits or after refactoring.
+
+## Session Resume
+
+Background agents can be resumed with full context via `resume-session` tool.
+
+## Ultrapilot (v3.4)
+
+Parallel autopilot with up to 5 concurrent workers for 3-5x faster execution.
+
+**Trigger:** "ultrapilot", "parallel build", "swarm build"
+
+**How it works:**
+1. Task decomposition engine breaks complex tasks into parallelizable subtasks
+2. File ownership coordinator assigns non-overlapping file sets to workers
+3. Workers execute in parallel, coordinator manages shared files
+4. Results integrated with conflict detection
+
+**Best for:** Multi-component systems, fullstack apps, large refactoring
+
+**State files:**
+- `.omc/state/ultrapilot-state.json` - Session state
+- `.omc/state/ultrapilot-ownership.json` - File ownership
+
+## Swarm (v3.4)
+
+N coordinated agents with atomic task claiming from shared pool.
+
+**Usage:** `/swarm 5:executor "fix all TypeScript errors"`
+
+**Features:**
+- Shared task list with pending/claimed/done status
+- 5-minute timeout per task with auto-release
+- Clean completion when all tasks done
+
+## Pipeline (v3.4)
+
+Sequential agent chaining with data passing between stages.
+
+**Built-in Presets:**
+| Preset | Stages |
+|--------|--------|
+| `review` | explore -> architect -> critic -> executor |
+| `implement` | planner -> executor -> tdd-guide |
+| `debug` | explore -> architect -> build-fixer |
+| `research` | parallel(researcher, explore) -> architect -> writer |
+| `refactor` | explore -> architect-medium -> executor-high -> qa-tester |
+| `security` | explore -> security-reviewer -> executor -> security-reviewer-low |
+
+**Custom pipelines:** `/pipeline explore:haiku -> architect:opus -> executor:sonnet`
+
+## Unified Cancel (v3.4)
+
+Smart cancellation that auto-detects active mode.
+
+**Usage:** `/cancel` or just say "cancelomc", "stopomc"
+
+Auto-detects and cancels: autopilot, ultrapilot, ralph, ultrawork, ultraqa, ecomode, swarm, pipeline
+Use `--force` or `--all` to clear ALL states.
+
+## Verification Module (v3.4)
+
+Reusable verification protocol for workflows.
+
+**Standard Checks:** BUILD, TEST, LINT, FUNCTIONALITY, ARCHITECT, TODO, ERROR_FREE
+
+**Evidence validation:** 5-minute freshness detection, pass/fail tracking
+
+## State Management (v3.4)
+
+Standardized state file locations.
+
+**Standard paths for all mode state files:**
+- Primary: `.omc/state/{name}.json` (local, per-project)
+- Global backup: `~/.omc/state/{name}.json` (global, session continuity)
+
+**Mode State Files:**
+| Mode | State File |
+|------|-----------|
+| ralph | `ralph-state.json` |
+| autopilot | `autopilot-state.json` |
+| ultrapilot | `ultrapilot-state.json` |
+| ultrawork | `ultrawork-state.json` |
+| ecomode | `ecomode-state.json` |
+| ultraqa | `ultraqa-state.json` |
+| pipeline | `pipeline-state.json` |
+| swarm | `swarm-summary.json` + `swarm-active.marker` |
+
+**Important:** Never store OMC state in `~/.claude/` - that directory is reserved for Claude Code itself.
+
+Legacy locations auto-migrated on read.

package/docs/shared/mode-hierarchy.md

@@ -0,0 +1,120 @@
+# Execution Mode Hierarchy
+
+This document defines the relationships between execution modes and provides guidance on mode selection.
+
+## Mode Inheritance Tree
+
+```
+autopilot (autonomous end-to-end)
+├── includes: ralph (persistence)
+│   └── includes: ultrawork (parallelism)
+├── includes: ultraqa (QA cycling)
+└── includes: plan (strategic thinking)
+
+ultrapilot (parallel autopilot)
+├── includes: file ownership partitioning
+├── includes: worker coordination (up to 5 workers)
+└── falls back to: autopilot (if not parallelizable)
+
+swarm (N-agent coordination)
+├── includes: SQLite task claiming
+├── includes: heartbeat monitoring
+└── orthogonal to: autopilot/ultrapilot (different paradigm)
+
+ecomode (token efficiency ONLY)
+└── modifies: agent tier selection (prefer haiku/sonnet)
+    (does NOT include persistence - that's ralph's job)
+
+ralph (persistence wrapper)
+└── includes: ultrawork (parallelism engine)
+    (adds: loop until done + architect verification)
+
+ultrawork (parallelism engine)
+└── COMPONENT only - parallel agent spawning
+    (no persistence, no verification loop)
+```
+
+## Mode Relationships
+
+| Mode | Type | Includes | Mutually Exclusive With |
+|------|------|----------|------------------------|
+| autopilot | Standalone | ralph, ultraqa, plan | ultrapilot |
+| ultrapilot | Standalone | file ownership, workers | autopilot |
+| swarm | Standalone | SQLite claiming | - |
+| ralph | Wrapper | ultrawork | - |
+| ultrawork | Component | - | - |
+| ecomode | Modifier | - | - |
+| ultraqa | Component | - | - |
+
+## Decision Tree
+
+```
+Want autonomous execution?
+├── YES: Is task parallelizable into 3+ independent components?
+│   ├── YES: ultrapilot (parallel autopilot with file ownership)
+│   └── NO: autopilot (sequential with ralph phases)
+└── NO: Want parallel execution with manual oversight?
+    ├── YES: Do you want cost optimization?
+    │   ├── YES: ecomode + ultrawork
+    │   └── NO: ultrawork alone
+    └── NO: Want persistence until verified done?
+        ├── YES: ralph (persistence + ultrawork + verification)
+        └── NO: Standard orchestration (delegate to agents directly)
+
+Have many similar independent tasks (e.g., "fix 47 errors")?
+└── YES: swarm (N agents claiming from task pool)
+```
+
+## Mode Differentiation Matrix
+
+| Mode | Best For | Parallelism | Persistence | Verification | File Ownership |
+|------|----------|-------------|-------------|--------------|----------------|
+| autopilot | "Build me X" | Via ralph | Yes | Yes | N/A |
+| ultrapilot | Multi-component | 5 workers | Yes | Yes | Partitioned |
+| swarm | Homogeneous tasks | N workers | Per-task | Per-task | Per-task |
+| ralph | "Don't stop" | Via ultrawork | Yes | Mandatory | N/A |
+| ultrawork | Parallel only | Yes | No | No | N/A |
+| ecomode | Cost savings | Modifier | No | No | N/A |
+
+## Quick Reference
+
+**Just want to build something?** → `autopilot`
+**Building multi-component system?** → `ultrapilot`
+**Fixing many similar issues?** → `swarm`
+**Want control over execution?** → `ultrawork`
+**Need verified completion?** → `ralph`
+**Want to save tokens?** → `ecomode` (combine with other modes)
+
+## Combining Modes
+
+Valid combinations:
+- `eco ralph` = Ralph loop with cheaper agents
+- `eco ultrawork` = Parallel execution with cheaper agents
+- `eco autopilot` = Full autonomous with cost optimization
+
+Invalid combinations:
+- `autopilot ultrapilot` = Mutually exclusive (both are standalone)
+- `ecomode` alone = Not useful (needs an execution mode)
+
+## State Management
+
+### Standard Paths
+All mode state files use standardized locations:
+- Primary: `.omc/state/{name}.json` (local, per-project)
+- Global backup: `~/.omc/state/{name}.json` (global, session continuity)
+
+### Mode State Files
+| Mode | State File |
+|------|-----------|
+| ralph | `ralph-state.json` |
+| autopilot | `autopilot-state.json` |
+| ultrapilot | `ultrapilot-state.json` |
+| ultrawork | `ultrawork-state.json` |
+| ecomode | `ecomode-state.json` |
+| ultraqa | `ultraqa-state.json` |
+| pipeline | `pipeline-state.json` |
+| swarm | `swarm-summary.json` + `swarm-active.marker` |
+
+**Important:** Never store OMC state in `~/.claude/` - that directory is reserved for Claude Code itself.
+
+Legacy locations are auto-migrated on read.

package/docs/shared/mode-selection-guide.md

@@ -0,0 +1,82 @@
+# Mode Selection Guide
+
+## Quick Decision
+
+| If you want... | Use this | Keyword |
+|----------------|----------|---------|
+| Full autonomous build from idea | `autopilot` | "autopilot", "build me", "I want a" |
+| Parallel autonomous (3-5x faster) | `ultrapilot` | "ultrapilot", "parallel build" |
+| Persistence until verified done | `ralph` | "ralph", "don't stop" |
+| Parallel execution, manual oversight | `ultrawork` | "ulw", "ultrawork" |
+| Cost-efficient execution | `ecomode` (modifier) | "eco", "budget" |
+| Many similar independent tasks | `swarm` | "swarm N agents" |
+
+## If You're Confused
+
+**Start with `autopilot`** - it handles most scenarios and transitions to other modes automatically.
+
+## Detailed Decision Flowchart
+
+```
+Want autonomous execution?
+├── YES: Is task parallelizable into 3+ independent components?
+│   ├── YES: ultrapilot (parallel autopilot with file ownership)
+│   └── NO: autopilot (sequential with ralph phases)
+└── NO: Want parallel execution with manual oversight?
+    ├── YES: Do you want cost optimization?
+    │   ├── YES: ecomode + ultrawork
+    │   └── NO: ultrawork alone
+    └── NO: Want persistence until verified done?
+        ├── YES: ralph (persistence + ultrawork + verification)
+        └── NO: Standard orchestration (delegate to agents directly)
+
+Have many similar independent tasks (e.g., "fix 47 errors")?
+└── YES: swarm (N agents claiming from task pool)
+```
+
+## Examples
+
+| User Request | Best Mode | Why |
+|--------------|-----------|-----|
+| "Build me a REST API" | autopilot | Single coherent deliverable |
+| "Build frontend, backend, and database" | ultrapilot | Clear component boundaries |
+| "Fix all 47 TypeScript errors" | swarm | Many independent similar tasks |
+| "Refactor auth module thoroughly" | ralph | Need persistence + verification |
+| "Quick parallel execution" | ultrawork | Manual oversight preferred |
+| "Save tokens while fixing errors" | ecomode + ultrawork | Cost-conscious parallel |
+| "Don't stop until done" | ralph | Persistence keyword detected |
+
+## Mode Types
+
+### Standalone Modes
+These run independently:
+- **autopilot**: Autonomous end-to-end execution
+- **ultrapilot**: Parallel autonomous with file ownership
+- **swarm**: N-agent coordination with task pool
+
+### Wrapper Modes
+These wrap other modes:
+- **ralph**: Adds persistence + verification around ultrawork
+
+### Component Modes
+These are used by other modes:
+- **ultrawork**: Parallel execution engine (used by ralph, autopilot)
+
+### Modifier Modes
+These modify how other modes work:
+- **ecomode**: Changes model routing to prefer cheaper tiers
+
+## Valid Combinations
+
+| Combination | Effect |
+|-------------|--------|
+| `eco ralph` | Ralph persistence with cheaper agents |
+| `eco ultrawork` | Parallel execution with cheaper agents |
+| `eco autopilot` | Autonomous execution with cost savings |
+
+## Invalid Combinations
+
+| Combination | Why Invalid |
+|-------------|-------------|
+| `autopilot ultrapilot` | Both are standalone - use one |
+| `ecomode` alone | Needs an execution mode to modify |

package/docs/shared/verification-tiers.md

@@ -0,0 +1,107 @@
+# Verification Tiers
+
+Verification scales with task complexity to optimize cost while maintaining quality.
+
+## Tier Definitions
+
+| Tier | Criteria | Agent | Model | Evidence Required |
+|------|----------|-------|-------|-------------------|
+| **LIGHT** | <5 files, <100 lines, full test coverage | architect-low | haiku | lsp_diagnostics clean |
+| **STANDARD** | Default (not LIGHT or THOROUGH) | architect-medium | sonnet | diagnostics + build pass |
+| **THOROUGH** | >20 files OR architectural/security changes | architect | opus | Full review + all tests |
+
+## Selection Interface
+
+```typescript
+interface ChangeMetadata {
+  filesChanged: number;
+  linesChanged: number;
+  hasArchitecturalChanges: boolean;
+  hasSecurityImplications: boolean;
+  testCoverage: 'none' | 'partial' | 'full';
+}
+
+type VerificationTier = 'LIGHT' | 'STANDARD' | 'THOROUGH';
+```
+
+## Selection Logic
+
+```
+IF hasSecurityImplications OR hasArchitecturalChanges:
+  → THOROUGH (always for security/architecture)
+ELIF filesChanged > 20:
+  → THOROUGH (large scope)
+ELIF filesChanged < 5 AND linesChanged < 100 AND testCoverage === 'full':
+  → LIGHT (small, well-tested)
+ELSE:
+  → STANDARD (default)
+```
+
+## Override Triggers
+
+User keywords that override auto-detection:
+
+| Keyword | Forces Tier |
+|---------|-------------|
+| "thorough", "careful", "important", "critical" | THOROUGH |
+| "quick", "simple", "trivial", "minor" | LIGHT |
+| Security-related file changes | THOROUGH (always) |
+
+## Architectural Change Detection
+
+Files that trigger `hasArchitecturalChanges`:
+- `**/config.{ts,js,json}`
+- `**/schema.{ts,prisma,sql}`
+- `**/definitions.ts`
+- `**/types.ts`
+- `package.json`
+- `tsconfig.json`
+
+## Security Implication Detection
+
+Path patterns that trigger `hasSecurityImplications`:
+- `**/auth/**`
+- `**/security/**`
+- `**/permissions?.{ts,js}`
+- `**/credentials?.{ts,js,json}`
+- `**/secrets?.{ts,js,json,yml,yaml}`
+- `**/tokens?.{ts,js,json}`
+- `**/passwords?.{ts,js,json}`
+- `**/oauth*`
+- `**/jwt*`
+- `**/.env*`
+
+## Evidence Types
+
+Required evidence for different claim types:
+
+| Claim | Required Evidence |
+|-------|-------------------|
+| "Fixed" | Test showing it passes now |
+| "Implemented" | lsp_diagnostics clean + build pass |
+| "Refactored" | All tests still pass |
+| "Debugged" | Root cause identified with file:line |
+
+## Cost Comparison
+
+| Tier | Relative Cost | Use Case |
+|------|---------------|----------|
+| LIGHT | 1x | Single-file bug fixes with tests |
+| STANDARD | 5x | Multi-file feature additions |
+| THOROUGH | 20x | Major refactoring, security changes |
+
+Estimated savings: ~40% reduction in verification costs by using tiered system vs. always using THOROUGH.
+
+## Usage in Modes
+
+All persistence modes (ralph, autopilot, ultrapilot) should use the tier-selector before spawning verification agents:
+
+```typescript
+import { selectVerificationTier, getVerificationAgent } from '../verification/tier-selector';
+
+const tier = selectVerificationTier(changeMetadata);
+const { agent, model } = getVerificationAgent(tier);
+
+// Spawn appropriate verification agent
+Task(subagent_type=`oh-my-claudecode:${agent}`, model, prompt="Verify...")
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-claude-sisyphus",
-  "version": "3.8.15",
+  "version": "3.9.0",
   "description": "Multi-agent orchestration system for Claude Code - Inspired by oh-my-opencode",
   "type": "module",
   "main": "dist/index.js",
@@ -33,8 +33,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && node scripts/build-skill-bridge.mjs && node scripts/build-mcp-server.mjs",
+    "build": "tsc && node scripts/build-skill-bridge.mjs && node scripts/build-mcp-server.mjs && npm run compose-docs",
     "build:bridge": "node scripts/build-skill-bridge.mjs",
+    "compose-docs": "node scripts/compose-docs.mjs",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "test": "vitest",
@@ -47,7 +48,7 @@
     "sync-metadata:verify": "tsx scripts/sync-metadata.ts --verify",
     "sync-metadata:dry-run": "tsx scripts/sync-metadata.ts --dry-run",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm run compose-docs"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.0",

package/scripts/compose-docs.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Composition Script
+ *
+ * Processes template files with {{INCLUDE:path}} syntax to compose
+ * final documentation from shared partials.
+ *
+ * Usage: node scripts/compose-docs.mjs
+ *
+ * Template syntax: {{INCLUDE:partials/agent-tiers.md}}
+ * Templates: docs/templates/*.template.md
+ * Output: docs/*.md (same name without .template)
+ * Partials also copied to docs/shared/ for direct reference.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const docsDir = join(__dirname, '..', 'docs');
+const partialsDir = join(docsDir, 'partials');
+const sharedDir = join(docsDir, 'shared');
+
+// Ensure directories exist
+[partialsDir, sharedDir].forEach(dir => {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+});
+
+// Copy partials to shared/ for direct reference by skills
+if (existsSync(partialsDir)) {
+  const partials = readdirSync(partialsDir).filter(f => f.endsWith('.md'));
+
+  for (const partial of partials) {
+    const content = readFileSync(join(partialsDir, partial), 'utf-8');
+    writeFileSync(join(sharedDir, partial), content);
+  }
+  console.log(`Synced ${readdirSync(partialsDir).filter(f => f.endsWith('.md')).length} partials to shared/`);
+}
+
+console.log('Documentation composition complete.');