# OUR_NOTES.md — oh-my-claudecode

Our annotations on the vendored snapshot. Authored by us, not copied from upstream.

## Why we vendored this

`yeachan-heo/oh-my-claudecode` (OMC) is an MIT-licensed multi-agent orchestration framework for Claude Code that overlaps heavily with our 7 Laws plugin. We vendored it as cold-storage so we can:

- Read its actual agent + skill definitions side-by-side with ours, without round-trips.
- Track upstream changes against pinned SHA.
- Eventually decide which OMC ideas (if any) to port into our 7 Laws — explicitly, with attribution.

## Status: Registered as optional install (PR A of 2026-05-07 train)

This snapshot is **registered in `.claude-plugin/marketplace.json`** as of PR A of the unified-dispatcher train. Users can install OMC with `/plugin install oh-my-claudecode@continuous-improvement`. Users who already have it from upstream via `/plugin marketplace add Yeachan-Heo/oh-my-claudecode` should keep that — our copy is a frozen pinned-SHA snapshot, theirs auto-updates.

The snapshot is **not loaded** into `plugins/continuous-improvement/` itself. Marketplace registration alone makes the 38 skills + 19 agents installable on demand; per-skill verbatim ports into the CI bundle remain single-concern PRs gated on user-pain triggers per the integration-candidates matrix below.

Activating the plugin installs OMC's agents and skills only — `hooks/` is intentionally stripped from this snapshot (see item 2 below). Be aware of the heavy overlap with `/ralph` and `/superpowers` called out in the matrix below — when both are installed, the unified `/superpowers` dispatcher (PR B) prefers the CI-bundled implementation for the autonomous-loop entry point and surfaces OMC's variants as alternatives in the routing table only.

## Overlap with the 7 Laws (read this before integrating anything)

| OMC asset | 7 Laws equivalent | Notes |
|---|---|---|
| `skills/ralph/` | `plugins/continuous-improvement/skills/ralph/SKILL.md` | Both are autonomous PRD-loop runners. Direct overlap. Different prompt structure. |
| `skills/plan/` | `superpowers:writing-plans` (Law 2) | Both restate goals + decompose. OMC's is heavier on PRD format. |
| `skills/verify/` | `plugins/continuous-improvement/skills/verification-loop/SKILL.md` (Law 4) | OMC bundles verify into autopilot/team flow. Ours stands alone. |
| `skills/debug/` | `superpowers:systematic-debugging` (Law 6) | Both follow hypothesis → repro → smallest fix. Loose overlap. |
| `skills/deep-interview/` | `superpowers:brainstorming` (Law 1 helper) | OMC's is more Socratic; ours is more divergent. |
| `skills/self-improve/` | `plugins/continuous-improvement/skills/continuous-improvement/SKILL.md` (Law 7) | Both extract reusable patterns from sessions. Different storage. |
| `skills/autopilot/` | (no direct equivalent) | OMC's single-agent autonomous mode. Gap in 7 Laws. |
| `skills/team/`, `skills/omc-teams/` | (no direct equivalent) | OMC's multi-agent stage pipeline (`plan → prd → exec → verify → fix`). 7 Laws is single-actor today. |
| `skills/hud/` | (no equivalent) | Real-time HUD statusline. UX feature we don't have. |
| `agents/` (19) | Various Claude Code built-in subagents | Most overlap with built-in agents we already use (planner, code-reviewer, debugger, etc.). Worth diffing prompt-by-prompt before adopting. |

## What is intentionally NOT integrated (and why)

1. **OMC's `ralph` skill.** Our `ralph` is already a Tier-1 skill under the 7 Laws and is shaped around the Mulahazah learning loop. Adopting OMC's would fork the contract. Stay on ours.
2. **OMC's hooks (removed from snapshot).** `hooks/hooks.json` was stripped from this snapshot — not just disabled. Reasons: (a) every entry calls `$CLAUDE_PLUGIN_ROOT/scripts/run.cjs`, which lives in upstream's `src/` and is explicitly excluded from vendoring per item 4 below, so the hooks throw `MODULE_NOT_FOUND` on every fire when the plugin is installed; (b) our `hooks/three-section-close.mjs` enforces a project-specific output contract and mixing OMC's hooks would create ordering surprises. The selective-scope and refresh recipe in `third-party/MANIFEST.md` reflect the strip.
3. **OMC's plugin manifest** (`.claude-plugin/plugin.json`). Vendored but **packaging-patched**: the `mcpServers: "./.mcp.json"` key was stripped because `.mcp.json` is excluded from vendoring per item 4 below (see `third-party/MANIFEST.md` exclusions), so leaving the pointer in would have Claude Code's plugin loader resolve a missing file on every install. The patch is one-key minimal; all other fields are verbatim upstream. Same precedent as the hooks/ strip in item 2 — a packaging correction for a pointer to an excluded-from-vendoring runtime, not a fork of upstream content.
4. **OMC's `src/` and `dist/` (and `.mcp.json`).** Not vendored. We have no intent to fork the runtime, and the `.mcp.json` MCP server registration is a per-install user opt-in surface that should not be pre-wired by a cold-storage snapshot. If we ever want OMC behavior, install from upstream.

## Ported from OMC into the 7 Laws

A focused port to our `ralph` skill landed in two commits on this branch:

- `e12848d feat(skill): ralph — PRD-discipline + final-checklist + do-not-use guard`
- `b7b2ed1 feat(skill): ralph — anti-patterns + Good/Bad examples`

Source: `third-party/oh-my-claudecode/skills/ralph/SKILL.md` at upstream SHA `1e9f197`.
Target: `skills/ralph.md` + plugin mirror `plugins/continuous-improvement/skills/ralph/SKILL.md`.
Result: 127 → 221 lines per file (+94). All edits agent-agnostic (no OMC verbs, no MCP dependencies, no `Task(subagent_type=...)` calls). Our ralph still works without OMC installed.

### Ideas adopted

| Idea | Section in our ralph | Rationale |
|---|---|---|
| Negative-form usage guidance | `## Do NOT Use When` | OMC's `<Do_Not_Use_When>` distinguishes ralph from sibling skills (one-shot edits, planning, manual control). We had no negative-form guidance; users were left to infer. |
| Force-refine PRD scaffold criteria | `### 1. Create a PRD` (CRITICAL block) | Auto-generated `["Implementation is complete"]` is theater. Our prior ralph did not guard against running iterations against meaningless criteria. |
| Per-criterion fresh-evidence verification | `## Ralph Loop Steps` step 4 (rewritten) | Replaced "typecheck, tests" with per-criterion verification plus the load-bearing rule that suite-level pass is not criterion-level proof. |
| Final Checklist as a hard gate | `## Final Checklist (Hard Gate)` | 8-item exit gate covering completion, criterion specificity, scope preservation, fresh evidence, no test-deletion, progress.txt, atomic commits, clean tree. OMC had this as `<Final_Checklist>`; we had nothing equivalent. |
| Anti-patterns table | `## Anti-patterns` | OMC explicitly calls out the polite-stop slip ("All stories pass, time to summarise" mid-loop). Generalizes across other 7 Laws skills. |
| Concrete Bad/Good example pairs | Inside PRD section + Ralph Loop step 4 | OMC's `<Examples>` blocks make rules sticky. We picked our own example domain (POST /api/users) so nothing is OMC-flavored. |

### Ideas rejected (and why)

| Idea | Why rejected |
|---|---|
| `Task(subagent_type="oh-my-claudecode:executor", model=...)` calls in workflow steps | Hard dependency on OMC being installed. Our 7 Laws ralph must run without OMC. |
| Mandatory `Skill("ai-slop-cleaner")` deslop pass (OMC Step 7.5) | Couples ralph to a separate skill we don't ship. Cleanup belongs in a different skill on a different track. |
| `--critic=architect\|critic\|codex` reviewer selection | Depends on `oh-my-claudecode:` namespaced agents we don't have. |
| `omc ask codex --agent-prompt critic` external-AI integration | Tooling-specific. Cross-AI verification is interesting but belongs in its own evaluation, not ralph. |
| Self-referential prompt-template format (`{{ITERATION}}/{{MAX}}/{{PROMPT}}`) | OMC's ralph IS the runtime prompt. Ours is a documentation skill that human + agent read. Different architecture; conflating is a category error. |
| `state_read` / `state_write` MCP tools for session persistence | OMC-specific runtime. We use `prd.json` + `progress.txt` + git history as state. |
| Session-scoped paths `.omc/state/sessions/{sessionId}/prd.json` | OMC-specific directory convention. We keep `prd.json` at project root. |
| `/oh-my-claudecode:cancel` cleanup step (OMC Step 8) | Namespaced command we don't own. Our ralph completes when the Final Checklist passes; no special cleanup needed. |
| "The boulder never stops" hook protocol | OMC-specific hook injection that collides with our `hooks/three-section-close.mjs` (different goals, ordering surprises). |
| Git commit trailers (`Constraint:` / `Rejected:` / `Confidence:` / `Scope-risk:`) | Interesting commit-discipline enhancement, but high blast-radius (touches every future commit) and unrelated to ralph. Parked for a separate focused evaluation, not bundled. |
| Tiered model routing in workflow text (haiku/sonnet/opus per task) | OMC's prompts assume the runner can dispatch with explicit model parameters. Our 7 Laws stays model-agnostic; the user picks the model. |
| Tool catalog (`state_*`, `notepad_*`, `lsp_*`, `python_repl`) referenced as required | All OMC-specific MCP tools. None portable to our context. |

### How to refresh this section

If a future port lands, append rows to "Ideas adopted" with the new commit SHA, and append rows to "Ideas rejected" if the port surfaced new rejections. Do not rewrite history — older rows stay. The matrix is a decision record, not a state snapshot.

## Deferred — do not port without concrete user pain

The three OMC surfaces below are explicitly **deferred**. The gating criterion is identical for all three: **a concrete reported user pain that the existing 7 Laws asset cannot solve**. Without that, porting is speculative and adds surface area we have to maintain.

- **`team` (multi-agent stage pipeline)** — current parallelism is driven by `superpowers:dispatching-parallel-agents`. Do not port until a real workflow demonstrates that the stage-pipeline shape (`plan → prd → exec → verify → fix`) is needed and not addressable by the existing dispatcher.
- **`hud` (real-time statusline)** — visibility today comes from the dashboard command and `verification-loop`. Do not port until users explicitly report blind-spots that a HUD would close.
- **Intelligent model routing (Haiku/Sonnet/Opus per task)** — our 7 Laws stays model-agnostic; the user picks the model. Do not port as a hook or as workflow text until a real cost or latency report justifies the added complexity.

If one of these gets revisited, append a row to the "Ideas adopted" matrix above with the new commit SHA. Do not silently delete this section.

## Refresh

See `third-party/MANIFEST.md` for the pinned SHA and the exact selective-copy recipe.
