oh-my-claude-sisyphus 3.2.3 → 3.3.0

package/dist/tools/python-repl/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Bridge metadata stored in bridge_meta.json
+ */
+export interface BridgeMeta {
+    pid: number;
+    socketPath: string;
+    startedAt: string;
+    sessionId: string;
+    pythonEnv: PythonEnvInfo;
+    processStartTime?: number;
+}
+export interface PythonEnvInfo {
+    pythonPath: string;
+    type: 'venv';
+}
+export interface LockInfo {
+    lockId: string;
+    pid: number;
+    processStartTime?: number;
+    hostname: string;
+    acquiredAt: string;
+}
+export interface ExecuteResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    markers: MarkerInfo[];
+    artifacts: unknown[];
+    timing: {
+        started_at: string;
+        duration_ms: number;
+    };
+    memory: {
+        rss_mb: number;
+        vms_mb: number;
+    };
+    error?: {
+        type: string;
+        message: string;
+        traceback: string;
+    };
+}
+export interface MarkerInfo {
+    type: string;
+    subtype: string | null;
+    content: string;
+    line_number: number;
+    category: string;
+}
+export interface StateResult {
+    memory: {
+        rss_mb: number;
+        vms_mb: number;
+    };
+    variables: string[];
+    variable_count: number;
+}
+export interface ResetResult {
+    status: string;
+    memory: {
+        rss_mb: number;
+        vms_mb: number;
+    };
+}
+export interface InterruptResult {
+    status: string;
+    terminatedBy?: 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'graceful';
+    terminationTimeMs?: number;
+}
+export interface PythonReplInput {
+    action: 'execute' | 'interrupt' | 'reset' | 'get_state';
+    researchSessionID: string;
+    code?: string;
+    executionLabel?: string;
+    executionTimeout?: number;
+    queueTimeout?: number;
+    projectDir?: string;
+}
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/python-repl/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/python-repl/types.ts"],"names":[],"mappings":"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"}

package/dist/tools/python-repl/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/python-repl/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tools/python-repl/types.ts"],"names":[],"mappings":""}

package/docs/CLAUDE.md

@@ -64,6 +64,37 @@ When you detect these patterns, you MUST invoke the corresponding skill:
 | Standard work | `sonnet` | "Add error handling", "Implement feature" |
 | Complex reasoning | `opus` | "Debug race condition", "Refactor architecture" |
 
+### Path-Based Write Rules
+
+Direct file writes are enforced via path patterns:
+
+**Allowed Paths (Direct Write OK):**
+| Path | Allowed For |
+|------|-------------|
+| `~/.claude/**` | System configuration |
+| `.omc/**` | OMC state and config |
+| `.claude/**` | Local Claude config |
+| `CLAUDE.md` | User instructions |
+| `AGENTS.md` | AI documentation |
+
+**Warned Paths (Should Delegate):**
+| Extension | Type |
+|-----------|------|
+| `.ts`, `.tsx`, `.js`, `.jsx` | JavaScript/TypeScript |
+| `.py` | Python |
+| `.go`, `.rs`, `.java` | Compiled languages |
+| `.c`, `.cpp`, `.h` | C/C++ |
+| `.svelte`, `.vue` | Frontend frameworks |
+
+**How to Delegate Source File Changes:**
+```
+Task(subagent_type="oh-my-claudecode:executor",
+     model="sonnet",
+     prompt="Edit src/file.ts to add validation...")
+```
+
+This is **soft enforcement** (warnings only). Audit log at `.omc/logs/delegation-audit.jsonl`.
+
 ---
 
 ## PART 2: USER EXPERIENCE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-claude-sisyphus",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "description": "Multi-agent orchestration system for Claude Code - Inspired by oh-my-opencode",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "agents",
+    "bridge",
     "commands",
     "hooks",
     "scripts",

package/skills/deepinit/SKILL.md

@@ -154,7 +154,7 @@ grep -r "<!-- Parent:" --include="AGENTS.md" .
 | Directory mapping | `explore` |
 | File analysis | `architect-low` |
 | Content generation | `writer` |
-| Multi-file writes | `executor` |
+| AGENTS.md writes | `writer` |
 
 ## Empty Directory Handling
 

package/skills/hud/SKILL.md

@@ -2,6 +2,8 @@
 name: hud
 description: Configure HUD display options (layout, presets, display elements)
 user-invocable: true
+role: config-writer  # DOCUMENTATION ONLY - This skill writes to ~/.claude/ paths
+scope: ~/.claude/**  # DOCUMENTATION ONLY - Allowed write scope
 ---
 
 # HUD Skill

package/skills/research/SKILL.md

@@ -0,0 +1,511 @@
+---
+name: research
+description: Orchestrate parallel scientist agents for comprehensive research with AUTO mode
+user-invocable: true
+argument-hint: <research goal>
+---
+
+# Research Skill
+
+Orchestrate parallel scientist agents for comprehensive research workflows with optional AUTO mode for fully autonomous execution.
+
+## Overview
+
+Research is a multi-stage workflow that decomposes complex research goals into parallel investigations:
+
+1. **Decomposition** - Break research goal into independent stages/hypotheses
+2. **Execution** - Run parallel scientist agents on each stage
+3. **Verification** - Cross-validate findings, check consistency
+4. **Synthesis** - Aggregate results into comprehensive report
+
+## Usage Examples
+
+```
+/research <goal>                    # Standard research with user checkpoints
+/research AUTO: <goal>              # Fully autonomous until complete
+/research status                    # Check current research session status
+/research resume                    # Resume interrupted research session
+/research list                      # List all research sessions
+/research report <session-id>       # Generate report for session
+```
+
+### Quick Examples
+
+```
+/research What are the performance characteristics of different sorting algorithms?
+/research AUTO: Analyze authentication patterns in this codebase
+/research How does the error handling work across the API layer?
+```
+
+## Research Protocol
+
+### Stage Decomposition Pattern
+
+When given a research goal, decompose into 3-7 independent stages:
+
+```markdown
+## Research Decomposition
+
+**Goal:** <original research goal>
+
+### Stage 1: <stage-name>
+- **Focus:** What this stage investigates
+- **Hypothesis:** Expected finding (if applicable)
+- **Scope:** Files/areas to examine
+- **Tier:** LOW | MEDIUM | HIGH
+
+### Stage 2: <stage-name>
+...
+```
+
+### Parallel Scientist Invocation
+
+Fire independent stages in parallel via Task tool:
+
+```
+// Stage 1 - Simple data gathering
+Task(subagent_type="oh-my-claudecode:scientist-low", model="haiku", prompt="[RESEARCH_STAGE:1] Investigate...")
+
+// Stage 2 - Standard analysis
+Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[RESEARCH_STAGE:2] Analyze...")
+
+// Stage 3 - Complex reasoning
+Task(subagent_type="oh-my-claudecode:scientist-high", model="opus", prompt="[RESEARCH_STAGE:3] Deep analysis of...")
+```
+
+### Smart Model Routing
+
+**CRITICAL: Always pass `model` parameter explicitly!**
+
+| Task Complexity | Agent | Model | Use For |
+|-----------------|-------|-------|---------|
+| Data gathering | `scientist-low` | haiku | File enumeration, pattern counting, simple lookups |
+| Standard analysis | `scientist` | sonnet | Code analysis, pattern detection, documentation review |
+| Complex reasoning | `scientist-high` | opus | Architecture analysis, cross-cutting concerns, hypothesis validation |
+
+### Routing Decision Guide
+
+| Research Task | Tier | Example Prompt |
+|---------------|------|----------------|
+| "Count occurrences of X" | LOW | "Count all usages of useState hook" |
+| "Find all files matching Y" | LOW | "List all test files in the project" |
+| "Analyze pattern Z" | MEDIUM | "Analyze error handling patterns in API routes" |
+| "Document how W works" | MEDIUM | "Document the authentication flow" |
+| "Explain why X happens" | HIGH | "Explain why race conditions occur in the cache layer" |
+| "Compare approaches A vs B" | HIGH | "Compare Redux vs Context for state management here" |
+
+### Verification Loop
+
+After parallel execution completes, verify findings:
+
+```
+// Cross-validation stage
+Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="
+[RESEARCH_VERIFICATION]
+Cross-validate these findings for consistency:
+
+Stage 1 findings: <summary>
+Stage 2 findings: <summary>
+Stage 3 findings: <summary>
+
+Check for:
+1. Contradictions between stages
+2. Missing connections
+3. Gaps in coverage
+4. Evidence quality
+
+Output: [VERIFIED] or [CONFLICTS:<list>]
+")
+```
+
+## AUTO Mode
+
+AUTO mode runs the complete research workflow autonomously with loop control.
+
+### Loop Control Protocol
+
+```
+[RESEARCH + AUTO - ITERATION {{ITERATION}}/{{MAX}}]
+
+Your previous attempt did not output the completion promise. Continue working.
+
+Current state: {{STATE}}
+Completed stages: {{COMPLETED_STAGES}}
+Pending stages: {{PENDING_STAGES}}
+```
+
+### Promise Tags
+
+| Tag | Meaning | When to Use |
+|-----|---------|-------------|
+| `[PROMISE:RESEARCH_COMPLETE]` | Research finished successfully | All stages done, verified, report generated |
+| `[PROMISE:RESEARCH_BLOCKED]` | Cannot proceed | Missing data, access issues, circular dependency |
+
+### AUTO Mode Rules
+
+1. **Max Iterations:** 10 (configurable)
+2. **Continue until:** Promise tag emitted OR max iterations
+3. **State tracking:** Persist after each stage completion
+4. **Cancellation:** `/cancel-research` or "stop", "cancel"
+
+### AUTO Mode Example
+
+```
+/research AUTO: Comprehensive security analysis of the authentication system
+
+[Decomposition]
+- Stage 1 (LOW): Enumerate auth-related files
+- Stage 2 (MEDIUM): Analyze token handling
+- Stage 3 (MEDIUM): Review session management
+- Stage 4 (HIGH): Identify vulnerability patterns
+- Stage 5 (MEDIUM): Document security controls
+
+[Execution - Parallel]
+Firing stages 1-3 in parallel...
+Firing stages 4-5 after dependencies complete...
+
+[Verification]
+Cross-validating findings...
+
+[Synthesis]
+Generating report...
+
+[PROMISE:RESEARCH_COMPLETE]
+```
+
+## Parallel Execution Patterns
+
+### Independent Dataset Analysis (Parallel)
+
+When stages analyze different data sources:
+
+```
+// All fire simultaneously
+Task(subagent_type="oh-my-claudecode:scientist-low", model="haiku", prompt="[STAGE:1] Analyze src/api/...")
+Task(subagent_type="oh-my-claudecode:scientist-low", model="haiku", prompt="[STAGE:2] Analyze src/utils/...")
+Task(subagent_type="oh-my-claudecode:scientist-low", model="haiku", prompt="[STAGE:3] Analyze src/components/...")
+```
+
+### Hypothesis Battery (Parallel)
+
+When testing multiple hypotheses:
+
+```
+// Test hypotheses simultaneously
+Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[HYPOTHESIS:A] Test if caching improves...")
+Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[HYPOTHESIS:B] Test if batching reduces...")
+Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[HYPOTHESIS:C] Test if lazy loading helps...")
+```
+
+### Cross-Validation (Sequential)
+
+When verification depends on all findings:
+
+```
+// Wait for all parallel stages
+[stages complete]
+
+// Then sequential verification
+Task(subagent_type="oh-my-claudecode:scientist-high", model="opus", prompt="
+[CROSS_VALIDATION]
+Validate consistency across all findings:
+- Finding 1: ...
+- Finding 2: ...
+- Finding 3: ...
+")
+```
+
+### Concurrency Limit
+
+**Maximum 5 concurrent scientist agents** to prevent resource exhaustion.
+
+If more than 5 stages, batch them:
+```
+Batch 1: Stages 1-5 (parallel)
+[wait for completion]
+Batch 2: Stages 6-7 (parallel)
+```
+
+## Session Management
+
+### Directory Structure
+
+```
+.omc/research/{session-id}/
+  state.json              # Session state and progress
+  stages/
+    stage-1.md            # Stage 1 findings
+    stage-2.md            # Stage 2 findings
+    ...
+  findings/
+    raw/                  # Raw findings from scientists
+    verified/             # Post-verification findings
+  figures/
+    figure-1.png          # Generated visualizations
+    ...
+  report.md               # Final synthesized report
+```
+
+### State File Format
+
+```json
+{
+  "id": "research-20240115-abc123",
+  "goal": "Original research goal",
+  "status": "in_progress | complete | blocked | cancelled",
+  "mode": "standard | auto",
+  "iteration": 3,
+  "maxIterations": 10,
+  "stages": [
+    {
+      "id": 1,
+      "name": "Stage name",
+      "tier": "LOW | MEDIUM | HIGH",
+      "status": "pending | running | complete | failed",
+      "startedAt": "ISO timestamp",
+      "completedAt": "ISO timestamp",
+      "findingsFile": "stages/stage-1.md"
+    }
+  ],
+  "verification": {
+    "status": "pending | passed | failed",
+    "conflicts": [],
+    "completedAt": "ISO timestamp"
+  },
+  "createdAt": "ISO timestamp",
+  "updatedAt": "ISO timestamp"
+}
+```
+
+### Session Commands
+
+| Command | Action |
+|---------|--------|
+| `/research status` | Show current session progress |
+| `/research resume` | Resume most recent interrupted session |
+| `/research resume <session-id>` | Resume specific session |
+| `/research list` | List all sessions with status |
+| `/research report <session-id>` | Generate/regenerate report |
+| `/research cancel` | Cancel current session (preserves state) |
+
+## Tag Extraction
+
+Scientists use structured tags for findings. Extract them with these patterns:
+
+### Finding Tags
+
+```
+[FINDING:<id>] <title>
+<evidence and analysis>
+[/FINDING]
+
+[EVIDENCE:<finding-id>]
+- File: <path>
+- Lines: <range>
+- Content: <relevant code/text>
+[/EVIDENCE]
+
+[CONFIDENCE:<level>] # HIGH | MEDIUM | LOW
+<reasoning for confidence level>
+```
+
+### Extraction Regex Patterns
+
+```javascript
+// Finding extraction
+const findingPattern = /\[FINDING:(\w+)\]\s*(.*?)\n([\s\S]*?)\[\/FINDING\]/g;
+
+// Evidence extraction
+const evidencePattern = /\[EVIDENCE:(\w+)\]([\s\S]*?)\[\/EVIDENCE\]/g;
+
+// Confidence extraction
+const confidencePattern = /\[CONFIDENCE:(HIGH|MEDIUM|LOW)\]\s*(.*)/g;
+
+// Stage completion
+const stageCompletePattern = /\[STAGE_COMPLETE:(\d+)\]/;
+
+// Verification result
+const verificationPattern = /\[(VERIFIED|CONFLICTS):?(.*?)\]/;
+```
+
+### Evidence Window
+
+When extracting evidence, include context window:
+
+```
+[EVIDENCE:F1]
+- File: /src/auth/login.ts
+- Lines: 45-52 (context: 40-57)
+- Content:
+  ```typescript
+  // Lines 45-52 with 5 lines context above/below
+  ```
+[/EVIDENCE]
+```
+
+### Quality Validation
+
+Findings must meet quality threshold:
+
+| Quality Check | Requirement |
+|---------------|-------------|
+| Evidence present | At least 1 [EVIDENCE] per [FINDING] |
+| Confidence stated | Each finding has [CONFIDENCE] |
+| Source cited | File paths are absolute and valid |
+| Reproducible | Another agent could verify |
+
+## Report Generation
+
+### Report Template
+
+```markdown
+# Research Report: {{GOAL}}
+
+**Session ID:** {{SESSION_ID}}
+**Date:** {{DATE}}
+**Status:** {{STATUS}}
+
+## Executive Summary
+
+{{2-3 paragraph summary of key findings}}
+
+## Methodology
+
+### Research Stages
+
+| Stage | Focus | Tier | Status |
+|-------|-------|------|--------|
+{{STAGES_TABLE}}
+
+### Approach
+
+{{Description of decomposition rationale and execution strategy}}
+
+## Key Findings
+
+### Finding 1: {{TITLE}}
+
+**Confidence:** {{HIGH|MEDIUM|LOW}}
+
+{{Detailed finding with evidence}}
+
+#### Evidence
+
+{{Embedded evidence blocks}}
+
+### Finding 2: {{TITLE}}
+...
+
+## Visualizations
+
+{{FIGURES}}
+
+## Cross-Validation Results
+
+{{Verification summary, any conflicts resolved}}
+
+## Limitations
+
+- {{Limitation 1}}
+- {{Limitation 2}}
+- {{Areas not covered and why}}
+
+## Recommendations
+
+1. {{Actionable recommendation}}
+2. {{Actionable recommendation}}
+
+## Appendix
+
+### Raw Data
+
+{{Links to raw findings files}}
+
+### Session State
+
+{{Link to state.json}}
+```
+
+### Figure Embedding Protocol
+
+Scientists generate visualizations using this marker:
+
+```
+[FIGURE:path/to/figure.png]
+Caption: Description of what the figure shows
+Alt: Accessibility description
+[/FIGURE]
+```
+
+Report generator embeds figures:
+
+```markdown
+## Visualizations
+
+![Figure 1: Description](figures/figure-1.png)
+*Caption: Description of what the figure shows*
+
+![Figure 2: Description](figures/figure-2.png)
+*Caption: Description of what the figure shows*
+```
+
+### Figure Types
+
+| Type | Use For | Generated By |
+|------|---------|--------------|
+| Architecture diagram | System structure | scientist-high |
+| Flow chart | Process flows | scientist |
+| Dependency graph | Module relationships | scientist |
+| Timeline | Sequence of events | scientist |
+| Comparison table | A vs B analysis | scientist |
+
+## Configuration
+
+Optional settings in `.claude/settings.json`:
+
+```json
+{
+  "omc": {
+    "research": {
+      "maxIterations": 10,
+      "maxConcurrentScientists": 5,
+      "defaultTier": "MEDIUM",
+      "autoVerify": true,
+      "generateFigures": true,
+      "evidenceContextLines": 5
+    }
+  }
+}
+```
+
+## Cancellation
+
+```
+/cancel-research
+```
+
+Or say: "stop research", "cancel research", "abort"
+
+Progress is preserved in `.omc/research/{session-id}/` for resume.
+
+## Troubleshooting
+
+**Stuck in verification loop?**
+- Check for conflicting findings between stages
+- Review state.json for specific conflicts
+- May need to re-run specific stages with different approach
+
+**Scientists returning low-quality findings?**
+- Check tier assignment - complex analysis needs HIGH tier
+- Ensure prompts include clear scope and expected output format
+- Review if research goal is too broad
+
+**AUTO mode exhausted iterations?**
+- Review state to see where it's stuck
+- Check if goal is achievable with available data
+- Consider breaking into smaller research sessions
+
+**Missing figures in report?**
+- Verify figures/ directory exists
+- Check [FIGURE:] tags in findings
+- Ensure paths are relative to session directory