oh-my-codex 0.1.1

package/skills/pipeline/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: pipeline
+description: Chain agents together in sequential or branching workflows with data passing
+---
+
+# Pipeline Skill
+
+## Overview
+
+The pipeline skill enables chaining multiple agents together in defined workflows where the output of one agent becomes the input to the next. This creates powerful agent pipelines similar to Unix pipes but designed for AI agent orchestration.
+
+## Core Concepts
+
+### 1. Sequential Pipelines
+
+The simplest form: Agent A's output flows to Agent B, which flows to Agent C.
+
+```
+explore -> architect -> executor
+```
+
+**Flow:**
+1. Explore agent searches codebase and produces findings
+2. Architect receives findings and produces analysis/recommendations
+3. Executor receives recommendations and implements changes
+
+### 2. Branching Pipelines
+
+Route to different agents based on output conditions.
+
+```
+explore -> {
+  if "complex refactoring" -> architect -> executor-high
+  if "simple change" -> executor-low
+  if "UI work" -> designer -> executor
+}
+```
+
+### 3. Parallel-Then-Merge Pipelines
+
+Run multiple agents in parallel, merge their outputs.
+
+```
+parallel(explore, researcher) -> architect -> executor
+```
+
+## Built-in Pipeline Presets
+
+### Review Pipeline
+**Purpose:** Comprehensive code review and implementation
+
+```
+/pipeline review <task>
+```
+
+**Stages:**
+1. `explore` - Find relevant code and patterns
+2. `architect` - Analyze architecture and design implications
+3. `critic` - Review and critique the analysis
+4. `executor` - Implement with full context
+
+**Use for:** Major features, refactorings, complex changes
+
+---
+
+### Implement Pipeline
+**Purpose:** Planned implementation with testing
+
+```
+/pipeline implement <task>
+```
+
+**Stages:**
+1. `planner` - Create detailed implementation plan
+2. `executor` - Implement the plan
+3. `tdd-guide` - Add/verify tests
+
+**Use for:** New features with clear requirements
+
+---
+
+### Debug Pipeline
+**Purpose:** Systematic debugging workflow
+
+```
+/pipeline debug <issue>
+```
+
+**Stages:**
+1. `explore` - Locate error locations and related code
+2. `architect` - Analyze root cause
+3. `build-fixer` - Apply fixes and verify
+
+**Use for:** Bugs, build errors, test failures
+
+---
+
+### Research Pipeline
+**Purpose:** External research + internal analysis
+
+```
+/pipeline research <topic>
+```
+
+**Stages:**
+1. `parallel(researcher, explore)` - External docs + internal code
+2. `architect` - Synthesize findings
+3. `writer` - Document recommendations
+
+**Use for:** Technology decisions, API integrations
+
+---
+
+### Refactor Pipeline
+**Purpose:** Safe, verified refactoring
+
+```
+/pipeline refactor <target>
+```
+
+**Stages:**
+1. `explore` - Find all usages and dependencies
+2. `architect-medium` - Design refactoring strategy
+3. `executor-high` - Execute refactoring
+4. `qa-tester` - Verify no regressions
+
+**Use for:** Architectural changes, API redesigns
+
+---
+
+### Security Pipeline
+**Purpose:** Security audit and fixes
+
+```
+/pipeline security <scope>
+```
+
+**Stages:**
+1. `explore` - Find potential vulnerabilities
+2. `security-reviewer` - Audit and identify issues
+3. `executor` - Implement fixes
+4. `security-reviewer-low` - Re-verify
+
+**Use for:** Security reviews, vulnerability fixes
+
+---
+
+## Custom Pipeline Syntax
+
+### Basic Sequential
+
+```
+/pipeline agent1 -> agent2 -> agent3 "task description"
+```
+
+**Example:**
+```
+/pipeline explore -> architect -> executor "add authentication"
+```
+
+### With Model Specification
+
+```
+/pipeline explore:haiku -> architect:opus -> executor:sonnet "optimize performance"
+```
+
+### With Branching
+
+```
+/pipeline explore -> (
+  complexity:high -> architect:opus -> executor-high:opus
+  complexity:medium -> executor:sonnet
+  complexity:low -> executor-low:haiku
+) "fix reported issues"
+```
+
+### With Parallel Stages
+
+```
+/pipeline [explore, researcher] -> architect -> executor "implement OAuth"
+```
+
+## Data Passing Protocol
+
+Each agent in the pipeline receives structured context from the previous stage:
+
+```json
+{
+  "pipeline_context": {
+    "original_task": "user's original request",
+    "previous_stages": [
+      {
+        "agent": "explore",
+        "model": "haiku",
+        "findings": "...",
+        "files_identified": ["src/auth.ts", "src/user.ts"]
+      }
+    ],
+    "current_stage": "architect",
+    "next_stage": "executor"
+  },
+  "task": "specific task for this agent"
+}
+```
+
+## Error Handling
+
+### Retry Logic
+
+When an agent fails, the pipeline can:
+
+1. **Retry** - Re-run the same agent (up to 3 times)
+2. **Skip** - Continue to next stage with partial output
+3. **Abort** - Stop entire pipeline
+4. **Fallback** - Route to alternative agent
+
+**Configuration:**
+
+```
+/pipeline explore -> architect -> executor --retry=3 --on-error=abort
+```
+
+### Error Recovery Patterns
+
+**Pattern 1: Fallback to Higher Tier**
+```
+executor-low -> on-error -> executor:sonnet
+```
+
+**Pattern 2: Consult Architect**
+```
+executor -> on-error -> architect -> executor
+```
+
+**Pattern 3: Human-in-the-Loop**
+```
+any-stage -> on-error -> pause-for-user-input
+```
+
+## Pipeline State Management
+
+Use `omx_state` MCP tools for pipeline lifecycle state.
+
+- **On start**:
+  `state_write({mode: "pipeline", active: true, current_phase: "plan", started_at: "<now>"})`
+- **On phase transitions**:
+  `state_write({mode: "pipeline", current_phase: "execute"})`
+  `state_write({mode: "pipeline", current_phase: "verify"})`
+  `state_write({mode: "pipeline", current_phase: "fix"})`
+- **On completion**:
+  `state_write({mode: "pipeline", active: false, current_phase: "complete", completed_at: "<now>"})`
+- **For resume detection**:
+  `state_read({mode: "pipeline"})`
+
+## Verification Rules
+
+Before pipeline completion, verify:
+
+- [ ] All stages completed successfully
+- [ ] Output from final stage addresses original task
+- [ ] No unhandled errors in any stage
+- [ ] All files modified pass lsp_diagnostics
+- [ ] Tests pass (if applicable)
+
+## Advanced Features
+
+### Conditional Branching
+
+Based on agent output, route to different paths:
+
+```
+explore -> {
+  if files_found > 5 -> architect:opus -> executor-high:opus
+  if files_found <= 5 -> executor:sonnet
+}
+```
+
+### Loop Constructs
+
+Repeat stages until condition met:
+
+```
+repeat_until(tests_pass) {
+  executor -> qa-tester
+}
+```
+
+### Merge Strategies
+
+When parallel agents complete:
+
+- **concat**: Concatenate all outputs
+- **summarize**: Use architect to summarize findings
+- **vote**: Use critic to choose best output
+
+## Usage Examples
+
+### Example 1: Feature Implementation
+```
+/pipeline review "add rate limiting to API"
+```
+→ Triggers: explore → architect → critic → executor
+
+### Example 2: Bug Fix
+```
+/pipeline debug "login fails with OAuth"
+```
+→ Triggers: explore → architect → build-fixer
+
+### Example 3: Custom Chain
+```
+/pipeline explore:haiku -> architect:opus -> executor:sonnet -> tdd-guide:sonnet "refactor auth module"
+```
+
+### Example 4: Research-Driven Implementation
+```
+/pipeline research "implement GraphQL subscriptions"
+```
+→ Triggers: parallel(researcher, explore) → architect → writer
+
+## Cancellation
+
+Stop active pipeline:
+
+```
+/pipeline cancel
+```
+
+Or use the general cancel command which detects active pipeline.
+
+## Integration with Other Skills
+
+Pipelines can be used within other skills:
+
+- **Ralph**: Loop pipelines until verified complete
+- **Ultrawork**: Run multiple pipelines in parallel
+- **Autopilot**: Use pipelines as building blocks
+
+## Best Practices
+
+1. **Start with presets** - Use built-in pipelines before creating custom ones
+2. **Match model to complexity** - Don't waste opus on simple tasks
+3. **Keep stages focused** - Each agent should have one clear responsibility
+4. **Use parallel stages** - Run independent work simultaneously
+5. **Verify at checkpoints** - Use architect or critic to verify progress
+6. **Document custom pipelines** - Save successful patterns for reuse
+
+## Troubleshooting
+
+### Pipeline Hangs
+
+**Check:** `state_read({mode: "pipeline"})` for current stage
+**Fix:** Resume with `/pipeline resume` or cancel and restart
+
+### Agent Fails Repeatedly
+
+**Check:** Retry count and error messages
+**Fix:** Route to higher-tier agent or add architect consultation
+
+### Output Not Flowing
+
+**Check:** Data passing structure in agent prompts
+**Fix:** Ensure each agent is prompted with `pipeline_context`
+
+## Technical Implementation
+
+The pipeline orchestrator:
+
+1. **Parses pipeline definition** - Validates syntax and agent names
+2. **Initializes state** - Calls `state_write({mode: "pipeline", active: true, ...})`
+3. **Executes stages sequentially** - Spawns agents with sub-agent spawning
+4. **Passes context between stages** - Structures output for next agent
+5. **Handles branching logic** - Evaluates conditions and routes
+6. **Manages parallel execution** - Spawns concurrent agents and merges
+7. **Persists state** - Calls `state_write` after each stage
+8. **Enforces verification** - Runs checks before completion
+
+## STATE CLEANUP ON COMPLETION
+
+**IMPORTANT: Use OMX MCP cleanup on completion**
+
+When pipeline completes (all stages done or cancelled):
+
+```text
+state_clear({mode: "pipeline"})
+```
+
+This ensures clean state for future sessions without direct file deletion.
+
+## Skill Invocation
+
+This skill activates when:
+
+- User types `/pipeline` command
+- User mentions "agent chain", "workflow", "pipe agents"
+- Pattern detected: "X then Y then Z" with agent names
+
+**Explicit invocation:**
+```
+/pipeline review "task"
+```
+
+**Auto-detection:**
+```
+"First explore the codebase, then architect should analyze it, then executor implements"
+```
+→ Automatically creates pipeline: explore → architect → executor

package/skills/plan/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: plan
+description: Strategic planning with optional interview workflow
+---
+
+<Purpose>
+Plan creates comprehensive, actionable work plans through intelligent interaction. It auto-detects whether to interview the user (broad requests) or plan directly (detailed requests), and supports consensus mode (iterative Planner/Architect/Critic loop) and review mode (Critic evaluation of existing plans).
+</Purpose>
+
+<Use_When>
+- User wants to plan before implementing -- "plan this", "plan the", "let's plan"
+- User wants structured requirements gathering for a vague idea
+- User wants an existing plan reviewed -- "review this plan", `--review`
+- User wants multi-perspective consensus on a plan -- `--consensus`, "ralplan"
+- Task is broad or vague and needs scoping before any code is written
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants autonomous end-to-end execution -- use `autopilot` instead
+- User wants to start coding immediately with a clear task -- use `ralph` or delegate to executor
+- User asks a simple question that can be answered directly -- just answer it
+- Task is a single focused fix with obvious scope -- skip planning, just do it
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Jumping into code without understanding requirements leads to rework, scope creep, and missed edge cases. Plan provides structured requirements gathering, expert analysis, and quality-gated plans so that execution starts from a solid foundation. The consensus mode adds multi-perspective validation for high-stakes projects.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Auto-detect interview vs direct mode based on request specificity
+- Ask one question at a time during interviews -- never batch multiple questions
+- Gather codebase facts via `explore` agent before asking the user about them
+- Plans must meet quality standards: 80%+ claims cite file/line, 90%+ criteria are testable
+- Consensus mode requires explicit user approval before proceeding to implementation
+</Execution_Policy>
+
+<Steps>
+
+### Mode Selection
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Interview | Default for broad requests | Interactive requirements gathering |
+| Direct | `--direct`, or detailed request | Skip interview, generate plan directly |
+| Consensus | `--consensus`, "ralplan" | Planner -> Architect -> Critic loop until agreement |
+| Review | `--review`, "review this plan" | Critic evaluation of existing plan |
+
+### Interview Mode (broad/vague requests)
+
+1. **Classify the request**: Broad (vague verbs, no specific files, touches 3+ areas) triggers interview mode
+2. **Ask one focused question** using `AskUserQuestion` for preferences, scope, and constraints
+3. **Gather codebase facts first**: Before asking "what patterns does your code use?", spawn an `explore` agent to find out, then ask informed follow-up questions
+4. **Build on answers**: Each question builds on the previous answer
+5. **Consult Analyst** (Opus) for hidden requirements, edge cases, and risks
+6. **Create plan** when the user signals readiness: "create the plan", "I'm ready", "make it a work plan"
+
+### Direct Mode (detailed requests)
+
+1. **Quick Analysis**: Optional brief Analyst consultation
+2. **Create plan**: Generate comprehensive work plan immediately
+3. **Review** (optional): Critic review if requested
+
+### Consensus Mode (`--consensus` / "ralplan")
+
+1. **Planner** creates initial plan
+2. **User feedback**: **MUST** use `AskUserQuestion` to present the draft plan with these options:
+   - **Proceed to review** — send to Architect and Critic for evaluation
+   - **Request changes** — return to step 1 with user feedback incorporated
+   - **Skip review** — go directly to final approval (step 6)
+3. **Architect** reviews for architectural soundness (prefer `ask_codex` with `architect` role)
+4. **Critic** evaluates against quality criteria (prefer `ask_codex` with `critic` role)
+5. If Critic rejects: iterate with feedback (max 5 iterations)
+6. On Critic approval: **MUST** use `AskUserQuestion` to present the plan with these options:
+   - **Approve and execute** — proceed to implementation via ralph+ultrawork
+   - **Request changes** — return to step 1 with user feedback
+   - **Reject** — discard the plan entirely
+7. User chooses via the structured `AskUserQuestion` UI (never ask for approval in plain text)
+8. On user approval: **MUST** invoke `/ralph` with the approved plan path from `.omx/plans/` as context. Do NOT implement directly. Do NOT edit source code files in the planning agent. The ralph skill handles execution via ultrawork parallel agents.
+
+### Review Mode (`--review`)
+
+1. Read plan file from `.omx/plans/`
+2. Evaluate via Critic (prefer `ask_codex` with `critic` role)
+3. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
+
+### Plan Output Format
+
+Every plan includes:
+- Requirements Summary
+- Acceptance Criteria (testable)
+- Implementation Steps (with file references)
+- Risks and Mitigations
+- Verification Steps
+
+Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
+</Steps>
+
+<Tool_Usage>
+- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
+- Use `AskUserQuestion` for preference questions (scope, priority, timeline, risk tolerance) -- provides clickable UI
+- Use plain text for questions needing specific values (port numbers, names, follow-up clarifications)
+- Use `explore` agent (Haiku, 30s timeout) to gather codebase facts before asking the user
+- Use `ask_codex` with `agent_role: "planner"` for planning validation on large-scope plans
+- Use `ask_codex` with `agent_role: "analyst"` for requirements analysis
+- Use `ask_codex` with `agent_role: "critic"` for plan review in consensus and review modes
+- If ToolSearch finds no MCP tools or Codex is unavailable, fall back to equivalent Claude agents -- never block on external tools
+- In consensus mode, **MUST** use `AskUserQuestion` for the user feedback step (step 2) and the final approval step (step 6) -- never ask for approval in plain text
+- In consensus mode, on user approval **MUST** invoke `/ralph` for execution (step 8) -- never implement directly in the planning agent
+</Tool_Usage>
+
+<Examples>
+<Good>
+Adaptive interview (gathering facts before asking):
+```
+Planner: [spawns explore agent: "find authentication implementation"]
+Planner: [receives: "Auth is in src/auth/ using JWT with passport.js"]
+Planner: "I see you're using JWT authentication with passport.js in src/auth/.
+         For this new feature, should we extend the existing auth or add a separate auth flow?"
+```
+Why good: Answers its own codebase question first, then asks an informed preference question.
+</Good>
+
+<Good>
+Single question at a time:
+```
+Q1: "What's the main goal?"
+A1: "Improve performance"
+Q2: "For performance, what matters more -- latency or throughput?"
+A2: "Latency"
+Q3: "For latency, are we optimizing for p50 or p99?"
+```
+Why good: Each question builds on the previous answer. Focused and progressive.
+</Good>
+
+<Bad>
+Asking about things you could look up:
+```
+Planner: "Where is authentication implemented in your codebase?"
+User: "Uh, somewhere in src/auth I think?"
+```
+Why bad: The planner should spawn an explore agent to find this, not ask the user.
+</Bad>
+
+<Bad>
+Batching multiple questions:
+```
+"What's the scope? And the timeline? And who's the audience?"
+```
+Why bad: Three questions at once causes shallow answers. Ask one at a time.
+</Bad>
+
+<Bad>
+Presenting all design options at once:
+```
+"Here are 4 approaches: Option A... Option B... Option C... Option D... Which do you prefer?"
+```
+Why bad: Decision fatigue. Present one option with trade-offs, get reaction, then present the next.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- Stop interviewing when requirements are clear enough to plan -- do not over-interview
+- In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version
+- Consensus mode requires explicit user approval before any implementation begins
+- If the user says "just do it" or "skip planning", **MUST** invoke `/ralph` to transition to execution mode. Do NOT implement directly in the planning agent.
+- Escalate to the user when there are irreconcilable trade-offs that require a business decision
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Plan has testable acceptance criteria (90%+ concrete)
+- [ ] Plan references specific files/lines where applicable (80%+ claims)
+- [ ] All risks have mitigations identified
+- [ ] No vague terms without metrics ("fast" -> "p99 < 200ms")
+- [ ] Plan saved to `.omx/plans/`
+- [ ] In consensus mode: user explicitly approved before any execution
+</Final_Checklist>
+
+<Advanced>
+## Design Option Presentation
+
+When presenting design choices during interviews, chunk them:
+
+1. **Overview** (2-3 sentences)
+2. **Option A** with trade-offs
+3. [Wait for user reaction]
+4. **Option B** with trade-offs
+5. [Wait for user reaction]
+6. **Recommendation** (only after options discussed)
+
+Format for each option:
+```
+### Option A: [Name]
+**Approach:** [1 sentence]
+**Pros:** [bullets]
+**Cons:** [bullets]
+
+What's your reaction to this approach?
+```
+
+## Question Classification
+
+Before asking any interview question, classify it:
+
+| Type | Examples | Action |
+|------|----------|--------|
+| Codebase Fact | "What patterns exist?", "Where is X?" | Explore first, do not ask user |
+| User Preference | "Priority?", "Timeline?" | Ask user via AskUserQuestion |
+| Scope Decision | "Include feature Y?" | Ask user |
+| Requirement | "Performance constraints?" | Ask user |
+
+## Review Quality Criteria
+
+| Criterion | Standard |
+|-----------|----------|
+| Clarity | 80%+ claims cite file/line |
+| Testability | 90%+ criteria are concrete |
+| Verification | All file refs exist |
+| Specificity | No vague terms |
+
+## Deprecation Notice
+
+The separate `/planner`, `/ralplan`, and `/review` skills have been merged into `/plan`. All workflows (interview, direct, consensus, review) are available through `/plan`.
+</Advanced>