@stanco323/oh-my-claude-code 4.10.3

package/skills/trace/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: trace
+description: Evidence-driven tracing lane that orchestrates competing tracer hypotheses in Claude built-in team mode
+argument-hint: "<observation to trace>"
+agent: tracer
+level: 2
+---
+
+# Trace Skill
+
+Use this skill for ambiguous, causal, evidence-heavy questions where the goal is to explain **why** an observed result happened, not to jump directly into fixing or rewriting code.
+
+This is the orchestration layer on top of the built-in `tracer` agent. The goal is to make tracing feel like a reusable OMC operating lane: restate the observation, generate competing explanations, gather evidence in parallel, rank the explanations, and propose the next probe that would collapse uncertainty fastest.
+
+## Good entry cases
+
+Use `/oh-my-claudecode:trace` when the problem is:
+
+- ambiguous
+- causal
+- evidence-heavy
+- best answered by exploring competing explanations in parallel
+
+Examples:
+- runtime bugs and regressions
+- performance / latency / resource behavior
+- architecture / premortem / postmortem analysis
+- scientific or experimental result tracing
+- config / routing / orchestration behavior explanation
+- “given this output, trace back the likely causes”
+
+## Core tracing contract
+
+Always preserve these distinctions:
+
+1. **Observation** -- what was actually observed
+2. **Hypotheses** -- competing explanations
+3. **Evidence For** -- what supports each explanation
+4. **Evidence Against / Gaps** -- what contradicts it or is still missing
+5. **Current Best Explanation** -- the leading explanation right now
+6. **Critical Unknown** -- the missing fact keeping the top explanations apart
+7. **Discriminating Probe** -- the highest-value next step to collapse uncertainty
+
+Do **not** collapse into:
+- a generic fix-it coding loop
+- a generic debugger summary
+- a raw dump of worker output
+- fake certainty when evidence is incomplete
+
+## Evidence strength hierarchy
+
+Treat evidence as ranked, not flat.
+
+From strongest to weakest:
+
+1. **Controlled reproductions / direct experiments / uniquely discriminating artifacts**
+2. **Primary source artifacts with tight provenance** (trace events, logs, metrics, benchmark outputs, configs, git history, file:line behavior)
+3. **Multiple independent sources converging on the same explanation**
+4. **Single-source code-path or behavioral inference**
+5. **Weak circumstantial clues** (timing, naming, stack order, resemblance to prior bugs)
+6. **Intuition / analogy / speculation**
+
+Explicitly down-rank hypotheses that depend mostly on lower tiers when stronger contradictory evidence exists.
+
+## Strong falsification / disconfirmation rules
+
+Every serious `/trace` run must try to falsify its own favorite explanation.
+
+For each top hypothesis:
+
+- collect evidence **for** it
+- collect evidence **against** it
+- state what distinctive prediction it makes
+- state what observation would be hard to reconcile with it
+- identify the cheapest probe that would discriminate it from the next-best alternative
+
+Down-rank a hypothesis when:
+
+- direct evidence contradicts it
+- it survives only by adding new unverified assumptions
+- it makes no distinctive prediction compared with rivals
+- a stronger alternative explains the same facts with fewer assumptions
+- its support is mostly circumstantial while the rival has stronger evidence tiers
+
+## Team-mode orchestration shape
+
+Use **Claude built-in team mode** for `/trace`.
+
+The lead should:
+
+1. Restate the observed result or “why” question precisely
+2. Extract the tracing target
+3. Generate multiple deliberately different candidate hypotheses
+4. Spawn **3 tracer lanes by default** in team mode
+5. Assign one tracer worker per lane
+6. Instruct each tracer worker to gather evidence **for** and **against** its lane
+7. Run a **rebuttal round** between the leading hypothesis and the strongest remaining alternative
+8. Detect whether the top lanes genuinely differ or actually converge on the same root cause
+9. Merge findings into a ranked synthesis with an explicit critical unknown and discriminating probe
+
+Important: workers should pursue deliberately different explanations, not the same explanation in parallel.
+
+## Default hypothesis lanes for v1
+
+Unless the prompt strongly suggests a better partition, use these 3 default lanes:
+
+1. **Code-path / implementation cause**
+2. **Config / environment / orchestration cause**
+3. **Measurement / artifact / assumption mismatch cause**
+
+These defaults are intentionally broad so the first slice works across bug, performance, architecture, and experiment tracing.
+
+## Mandatory cross-check lenses
+
+After the initial evidence pass, pressure-test the leaders with these lenses when relevant:
+
+- **Systems lens** -- queues, retries, backpressure, feedback loops, upstream/downstream dependencies, boundary failures, coordination effects
+- **Premortem lens** -- assume the current best explanation is incomplete or wrong; what failure mode would embarrass the trace later?
+- **Science lens** -- controls, confounders, measurement bias, alternative variables, falsifiable predictions
+
+These lenses are not filler. Use them when they can surface a missed explanation, hidden dependency, or weak inference.
+
+## Worker contract
+
+Each worker should be a **`tracer`** lane owner, not a generic executor.
+
+Each worker must:
+
+- own exactly one hypothesis lane
+- restate its lane hypothesis explicitly
+- gather evidence **for** the lane
+- gather evidence **against** the lane
+- rank the evidence strength behind its case
+- call out missing evidence, failed predictions, and remaining uncertainty
+- name the **critical unknown** for the lane
+- recommend the best lane-specific **discriminating probe**
+- avoid collapsing into implementation unless explicitly told to do so
+
+Useful evidence sources include:
+
+- relevant code, tests, configs, docs, logs, outputs, and benchmark artifacts
+- existing trace artifacts via `trace_timeline`
+- existing aggregate trace evidence via `trace_summary`
+
+Recommended worker return structure:
+
+1. **Lane**
+2. **Hypothesis**
+3. **Evidence For**
+4. **Evidence Against / Gaps**
+5. **Evidence Strength**
+6. **Critical Unknown**
+7. **Best Discriminating Probe**
+8. **Confidence**
+
+## Leader synthesis contract
+
+The final `/trace` answer should synthesize, not just concatenate.
+
+Return:
+
+1. **Observed Result**
+2. **Ranked Hypotheses**
+3. **Evidence Summary by Hypothesis**
+4. **Evidence Against / Missing Evidence**
+5. **Rebuttal Round**
+6. **Convergence / Separation Notes**
+7. **Most Likely Explanation**
+8. **Critical Unknown**
+9. **Recommended Discriminating Probe**
+10. **Additional Trace Lanes** (optional, only if uncertainty remains high)
+
+Preserve a ranked shortlist even if one explanation is currently dominant.
+
+## Rebuttal round and convergence detection
+
+Before closing the trace:
+
+- let the strongest non-leading lane present its best rebuttal to the current leader
+- force the leader to answer the rebuttal with evidence, not assertion
+- if the rebuttal materially weakens the leader, re-rank the table
+- if two “different” hypotheses reduce to the same underlying mechanism, merge them and say so explicitly
+- if two hypotheses still imply different next probes, keep them separate even if they sound similar
+
+Do not claim convergence just because multiple workers use similar language. Convergence requires either:
+
+- the same root causal mechanism, or
+- independent evidence streams pointing to the same explanation
+
+## Explicit down-ranking guidance
+
+The lead should explicitly say why a hypothesis moved down:
+
+- contradicted by stronger evidence
+- lacks the observation it predicted
+- requires extra ad hoc assumptions
+- explains fewer facts than the leader
+- lost the rebuttal round
+- converged into a stronger parent explanation
+
+This is important because `/trace` should teach the reader **why** one explanation outranks another, not just present a final table.
+
+## Suggested lead prompt skeleton
+
+Use a team-oriented orchestration prompt along these lines:
+
+1. “Restate the observation exactly.”
+2. “Generate 3 deliberately different hypotheses.”
+3. “Create one tracer lane per hypothesis using Claude built-in team mode.”
+4. “For each lane, gather evidence for and against, rank evidence strength, and name the critical unknown plus best discriminating probe.”
+5. “Apply systems, premortem, and science lenses to the leaders if useful.”
+6. “Run a rebuttal round between the top two explanations.”
+7. “Return a ranked explanation table, convergence notes, the critical unknown, and the single best discriminating probe.”
+
+## Output quality bar
+
+Good `/trace` output is:
+
+- evidence-backed
+- concise but rigorous
+- skeptical of premature certainty
+- explicit about missing evidence
+- practical about the next action
+- explicit about why weaker explanations were down-ranked
+
+## Example final synthesis shape
+
+### Observed Result
+[What happened]
+
+### Ranked Hypotheses
+| Rank | Hypothesis | Confidence | Evidence Strength | Why it leads |
+|------|------------|------------|-------------------|--------------|
+| 1 | ... | High / Medium / Low | Strong / Moderate / Weak | ... |
+
+### Evidence Summary by Hypothesis
+- Hypothesis 1: ...
+- Hypothesis 2: ...
+- Hypothesis 3: ...
+
+### Evidence Against / Missing Evidence
+- Hypothesis 1: ...
+- Hypothesis 2: ...
+- Hypothesis 3: ...
+
+### Rebuttal Round
+- Best rebuttal to leader: ...
+- Why leader held / failed: ...
+
+### Convergence / Separation Notes
+- ...
+
+### Most Likely Explanation
+[Current best explanation]
+
+### Critical Unknown
+[Single missing fact keeping uncertainty open]
+
+### Recommended Discriminating Probe
+[Single next probe]
+
+### Additional Trace Lanes
+[Only if uncertainty remains high]

package/skills/ultraqa/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: ultraqa
+description: QA cycling workflow - test, verify, fix, repeat until goal met
+argument-hint: "[--tests|--build|--lint|--typecheck|--custom <pattern>] [--interactive]"
+level: 3
+---
+
+# UltraQA Skill
+
+[ULTRAQA ACTIVATED - AUTONOMOUS QA CYCLING]
+
+## Overview
+
+You are now in **ULTRAQA** mode - an autonomous QA cycling workflow that runs until your quality goal is met.
+
+**Cycle**: qa-tester → architect verification → fix → repeat
+
+## Goal Parsing
+
+Parse the goal from arguments. Supported formats:
+
+| Invocation | Goal Type | What to Check |
+|------------|-----------|---------------|
+| `/oh-my-claudecode:ultraqa --tests` | tests | All test suites pass |
+| `/oh-my-claudecode:ultraqa --build` | build | Build succeeds with exit 0 |
+| `/oh-my-claudecode:ultraqa --lint` | lint | No lint errors |
+| `/oh-my-claudecode:ultraqa --typecheck` | typecheck | No TypeScript errors |
+| `/oh-my-claudecode:ultraqa --custom "pattern"` | custom | Custom success pattern in output |
+
+If no structured goal provided, interpret the argument as a custom goal.
+
+## Cycle Workflow
+
+### Cycle N (Max 5)
+
+1. **RUN QA**: Execute verification based on goal type
+   - `--tests`: Run the project's test command
+   - `--build`: Run the project's build command
+   - `--lint`: Run the project's lint command
+   - `--typecheck`: Run the project's type check command
+   - `--custom`: Run appropriate command and check for pattern
+   - `--interactive`: Use qa-tester for interactive CLI/service testing:
+     ```
+     Task(subagent_type="oh-my-claudecode:qa-tester", model="sonnet", prompt="TEST:
+     Goal: [describe what to verify]
+     Service: [how to start]
+     Test cases: [specific scenarios to verify]")
+     ```
+
+2. **CHECK RESULT**: Did the goal pass?
+   - **YES** → Exit with success message
+   - **NO** → Continue to step 3
+
+3. **ARCHITECT DIAGNOSIS**: Spawn architect to analyze failure
+   ```
+   Task(subagent_type="oh-my-claudecode:architect", model="opus", prompt="DIAGNOSE FAILURE:
+   Goal: [goal type]
+   Output: [test/build output]
+   Provide root cause and specific fix recommendations.")
+   ```
+
+4. **FIX ISSUES**: Apply architect's recommendations
+   ```
+   Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="FIX:
+   Issue: [architect diagnosis]
+   Files: [affected files]
+   Apply the fix precisely as recommended.")
+   ```
+
+5. **REPEAT**: Go back to step 1
+
+## Exit Conditions
+
+| Condition | Action |
+|-----------|--------|
+| **Goal Met** | Exit with success: "ULTRAQA COMPLETE: Goal met after N cycles" |
+| **Cycle 5 Reached** | Exit with diagnosis: "ULTRAQA STOPPED: Max cycles. Diagnosis: ..." |
+| **Same Failure 3x** | Exit early: "ULTRAQA STOPPED: Same failure detected 3 times. Root cause: ..." |
+| **Environment Error** | Exit: "ULTRAQA ERROR: [tmux/port/dependency issue]" |
+
+## Observability
+
+Output progress each cycle:
+```
+[ULTRAQA Cycle 1/5] Running tests...
+[ULTRAQA Cycle 1/5] FAILED - 3 tests failing
+[ULTRAQA Cycle 1/5] Architect diagnosing...
+[ULTRAQA Cycle 1/5] Fixing: auth.test.ts - missing mock
+[ULTRAQA Cycle 2/5] Running tests...
+[ULTRAQA Cycle 2/5] PASSED - All 47 tests pass
+[ULTRAQA COMPLETE] Goal met after 2 cycles
+```
+
+## State Tracking
+
+Track state in `.omc/ultraqa-state.json`:
+```json
+{
+  "active": true,
+  "goal_type": "tests",
+  "goal_pattern": null,
+  "cycle": 1,
+  "max_cycles": 5,
+  "failures": ["3 tests failing: auth.test.ts"],
+  "started_at": "2024-01-18T12:00:00Z",
+  "session_id": "uuid"
+}
+```
+
+## Cancellation
+
+User can cancel with `/oh-my-claudecode:cancel` which clears the state file.
+
+## Important Rules
+
+1. **PARALLEL when possible** - Run diagnosis while preparing potential fixes
+2. **TRACK failures** - Record each failure to detect patterns
+3. **EARLY EXIT on pattern** - 3x same failure = stop and surface
+4. **CLEAR OUTPUT** - User should always know current cycle and status
+5. **CLEAN UP** - Clear state file on completion or cancellation
+
+## STATE CLEANUP ON COMPLETION
+
+**IMPORTANT: Delete state files on completion - do NOT just set `active: false`**
+
+When goal is met OR max cycles reached OR exiting early:
+
+```bash
+# Delete ultraqa state file
+rm -f .omc/state/ultraqa-state.json
+```
+
+This ensures clean state for future sessions. Stale state files with `active: false` should not be left behind.
+
+---
+
+Begin ULTRAQA cycling now. Parse the goal and start cycle 1.

package/skills/ultrawork/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ultrawork
+description: Parallel execution engine for high-throughput task completion
+argument-hint: "<task description with parallel work items>"
+level: 4
+---
+
+<Purpose>
+Ultrawork is a parallel execution engine that runs multiple agents simultaneously for independent tasks. It is a component, not a standalone persistence mode -- it provides parallelism and smart model routing but not persistence, verification loops, or state management.
+</Purpose>
+
+<Use_When>
+- Multiple independent tasks can run simultaneously
+- User says "ulw", "ultrawork", or wants parallel execution
+- You need to delegate work to multiple agents at once
+- Task benefits from concurrent execution but the user will manage completion themselves
+</Use_When>
+
+<Do_Not_Use_When>
+- Task requires guaranteed completion with verification -- use `ralph` instead (ralph includes ultrawork)
+- Task requires a full autonomous pipeline -- use `autopilot` instead (autopilot includes ralph which includes ultrawork)
+- There is only one sequential task with no parallelism opportunity -- delegate directly to an executor agent
+- User needs session persistence for resume -- use `ralph` which adds persistence on top of ultrawork
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Sequential task execution wastes time when tasks are independent. Ultrawork enables firing multiple agents simultaneously and routing each to the right model tier, reducing total execution time while controlling token costs. It is designed as a composable component that ralph and autopilot layer on top of.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Fire all independent agent calls simultaneously -- never serialize independent work
+- Always pass the `model` parameter explicitly when delegating
+- Read `docs/shared/agent-tiers.md` before first delegation for agent selection guidance
+- Use `run_in_background: true` for operations over ~30 seconds (installs, builds, tests)
+- Run quick commands (git status, file reads, simple checks) in the foreground
+</Execution_Policy>
+
+<Steps>
+1. **Read agent reference**: Load `docs/shared/agent-tiers.md` for tier selection
+2. **Classify tasks by independence**: Identify which tasks can run in parallel vs which have dependencies
+3. **Route to correct tiers**:
+   - Simple lookups/definitions: LOW tier (Haiku)
+   - Standard implementation: MEDIUM tier (Sonnet)
+   - Complex analysis/refactoring: HIGH tier (Opus)
+4. **Fire independent tasks simultaneously**: Launch all parallel-safe tasks at once
+5. **Run dependent tasks sequentially**: Wait for prerequisites before launching dependent work
+6. **Background long operations**: Builds, installs, and test suites use `run_in_background: true`
+7. **Verify when all tasks complete** (lightweight):
+   - Build/typecheck passes
+   - Affected tests pass
+   - No new errors introduced
+</Steps>
+
+<Tool_Usage>
+- Use `Task(subagent_type="oh-my-claudecode:executor", model="haiku", ...)` for simple changes
+- Use `Task(subagent_type="oh-my-claudecode:executor", model="sonnet", ...)` for standard work
+- Use `Task(subagent_type="oh-my-claudecode:executor", model="opus", ...)` for complex work
+- Use `run_in_background: true` for package installs, builds, and test suites
+- Use foreground execution for quick status checks and file operations
+</Tool_Usage>
+
+<Examples>
+<Good>
+Three independent tasks fired simultaneously:
+```
+Task(subagent_type="oh-my-claudecode:executor", model="haiku", prompt="Add missing type export for Config interface")
+Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="Implement the /api/users endpoint with validation")
+Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="Add integration tests for the auth middleware")
+```
+Why good: Independent tasks at appropriate tiers, all fired at once.
+</Good>
+
+<Good>
+Correct use of background execution:
+```
+Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="npm install && npm run build", run_in_background=true)
+Task(subagent_type="oh-my-claudecode:executor", model="haiku", prompt="Update the README with new API endpoints")
+```
+Why good: Long build runs in background while short task runs in foreground.
+</Good>
+
+<Bad>
+Sequential execution of independent work:
+```
+result1 = Task(executor, "Add type export")  # wait...
+result2 = Task(executor, "Implement endpoint")     # wait...
+result3 = Task(executor, "Add tests")              # wait...
+```
+Why bad: These tasks are independent. Running them sequentially wastes time.
+</Bad>
+
+<Bad>
+Wrong tier selection:
+```
+Task(subagent_type="oh-my-claudecode:executor", model="opus", prompt="Add a missing semicolon")
+```
+Why bad: Opus is expensive overkill for a trivial fix. Use executor with Haiku instead.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- When ultrawork is invoked directly (not via ralph), apply lightweight verification only -- build passes, tests pass, no new errors
+- For full persistence and comprehensive architect verification, recommend switching to `ralph` mode
+- If a task fails repeatedly across retries, report the issue rather than retrying indefinitely
+- Escalate to the user when tasks have unclear dependencies or conflicting requirements
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] All parallel tasks completed
+- [ ] Build/typecheck passes
+- [ ] Affected tests pass
+- [ ] No new errors introduced
+</Final_Checklist>
+
+<Advanced>
+## Relationship to Other Modes
+
+```
+ralph (persistence wrapper)
+ \-- includes: ultrawork (this skill)
+     \-- provides: parallel execution only
+
+autopilot (autonomous execution)
+ \-- includes: ralph
+     \-- includes: ultrawork (this skill)
+```
+
+Ultrawork is the parallelism layer. Ralph adds persistence and verification. Autopilot adds the full lifecycle pipeline.
+</Advanced>

package/skills/verify/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: verify
+description: Verify that a change really works before you claim completion
+---
+
+# Verify
+
+Use this skill when the user wants confidence that a feature, fix, or refactor actually works.
+
+## Goal
+Turn vague “it should work” claims into concrete evidence.
+
+## Workflow
+1. Identify the exact behavior that must be proven.
+2. Prefer existing tests first.
+3. If coverage is missing, run the narrowest direct verification commands available.
+4. If direct automation is not enough, describe the manual validation steps and gather concrete observable evidence.
+5. Report only what was actually verified.
+
+## Verification order
+1. Existing tests
+2. Typecheck / build
+3. Narrow direct command checks
+4. Manual or interactive validation
+
+## Rules
+- Do not say a change is complete without evidence.
+- If a check fails, include the failure clearly.
+- If no realistic verification path exists, say that explicitly instead of bluffing.
+- Prefer concise evidence summaries over noisy logs.
+
+## Output
+- What was verified
+- Which commands/tests were run
+- What passed
+- What failed or remains unverified
+

package/skills/visual-verdict/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: visual-verdict
+description: Structured visual QA verdict for screenshot-to-reference comparisons
+level: 2
+---
+
+<Purpose>
+Use this skill to compare generated UI screenshots against one or more reference images and return a strict JSON verdict that can drive the next edit iteration.
+</Purpose>
+
+<Use_When>
+- The task includes visual fidelity requirements (layout, spacing, typography, component styling)
+- You have a generated screenshot and at least one reference image
+- You need deterministic pass/fail guidance before continuing edits
+</Use_When>
+
+<Inputs>
+- `reference_images[]` (one or more image paths)
+- `generated_screenshot` (current output image)
+- Optional: `category_hint` (e.g., `hackernews`, `sns-feed`, `dashboard`)
+</Inputs>
+
+<Output_Contract>
+Return **JSON only** with this exact shape:
+
+```json
+{
+  "score": 0,
+  "verdict": "revise",
+  "category_match": false,
+  "differences": ["..."],
+  "suggestions": ["..."],
+  "reasoning": "short explanation"
+}
+```
+
+Rules:
+- `score`: integer 0-100
+- `verdict`: short status (`pass`, `revise`, or `fail`)
+- `category_match`: `true` when the generated screenshot matches the intended UI category/style
+- `differences[]`: concrete visual mismatches (layout, spacing, typography, colors, hierarchy)
+- `suggestions[]`: actionable next edits tied to the differences
+- `reasoning`: 1-2 sentence summary
+
+<Threshold_And_Loop>
+- Target pass threshold is **90+**.
+- If `score < 90`, continue editing and rerun `/oh-my-claudecode:visual-verdict` before any further visual review pass.
+- Do **not** treat the visual task as complete until the next screenshot clears the threshold.
+</Threshold_And_Loop>
+
+<Debug_Visualization>
+When mismatch diagnosis is hard:
+1. Keep `$visual-verdict` as the authoritative decision.
+2. Use pixel-level diff tooling (pixel diff / pixelmatch overlay) as a **secondary debug aid** to localize hotspots.
+3. Convert pixel diff hotspots into concrete `differences[]` and `suggestions[]` updates.
+</Debug_Visualization>
+
+<Example>
+```json
+{
+  "score": 87,
+  "verdict": "revise",
+  "category_match": true,
+  "differences": [
+    "Top nav spacing is tighter than reference",
+    "Primary button uses smaller font weight"
+  ],
+  "suggestions": [
+    "Increase nav item horizontal padding by 4px",
+    "Set primary button font-weight to 600"
+  ],
+  "reasoning": "Core layout matches, but style details still diverge."
+}
+```
+</Example>
+
+Task: {{ARGUMENTS}}