CLAUDE.md git:20260713.32df510A

Immutable. This exact content is served forever at /api/v1/blob/5eff96be03b44a8c.

# CLAUDE.md — working on oh-my-design with Claude Code

This file governs how Claude Code contributes to this repository. `AGENTS.md` covers the
Codex / GPT-5.6 path; both share the repository conventions at the bottom.

## Division of labour: stronger model plans, session model builds

The principle is that **planning quality dominates outcome** while most implementation is
mechanical once the plan is precise. A stronger model for planning and review; the session
model does the building.

- **Plan with a strong model.** Interrogating the request, choosing the approach, writing
  the spec, and reviewing the result benefit from a capable model. It decides *what* changes
  and *why*, and it holds the whole-repo context.
- **Build with the session model.** Each planned unit of work is dispatched to an executor
  with a self-contained spec: the files to touch, the rule to follow, the definition of done.
  The executor writes the code, the tests, and runs the gates.
- **The planner does not hand-write the implementation.** It writes the spec, spawns the
  executor, then verifies the result (tests pass, the change matches the spec, no scope
  drift). Verification is the planner's job precisely because it did not write the code.

Practically, in Claude Code: set the session model to Opus (or any strong model of your
choice) for the planning and orchestration turn, dispatch implementation to
`oh-my-claudecode:executor` with a written spec, and review its report against the spec
before committing.

A spec dispatched to an executor should carry: the exact files that are source-of-truth vs
generated, the narrowness discipline for any new linter rule (positive AND negative tests),
the baseline test count, and the definition of done (`npm test` clean, `tsc` clean,
`npm run build` succeeds).

### Role → model

| Role | Model | Why |
|---|---|---|
| **Orchestration · architecture · high-risk review (planner/critic)** | **Your strongest session model (e.g. Opus)** | Holds whole-repo context, decides what changes and why, reviews the diff it did not write. |
| **Precise code-edit executor** | **Session model (inherited)** | The builder — writes the code, the tests, and runs the gates from a written spec. |
| **Low-cost lane** | **A lighter session model** | Cheaper lane for lower-risk mechanical work when quality permits. |

**The pipeline's own agents inherit the session model.** `omd-framer`, `omd-scout`,
`omd-eye`, and `omd-hand` do **not** pin a model — they run on whatever model you selected
for the session. Planning and review agents benefit most from a stronger model; `omd-hand`
(which builds the committed structure) is the mechanical executor. The recommendation:
run a planning-heavy session on Opus or equivalent so the framer and eye have maximum
reasoning capacity; the model choice is yours, not the pipeline's. On the Codex host the
same applies — see `AGENTS.md`.

## Repository conventions

- **Source of truth is `src/`.** `src/agents/*.agent.yaml` and `src/skills/omd-*/SKILL.md`
  are the prompt originals. Root `agents/`, `skills/`, and `dist/` are generated by
  `npm run build` — never edit them directly.
- **Edited directly:** `core/`, `bin/`, `adapters/`, `test/`, `evals/`, `scripts/`,
  `README.md`, `README.ko.md`, `.github/`, and the theory/recipe packs under `core/`.
- **`.omd/` is the design record**, committed with the repo. `.omc/` is local session state
  and is gitignored.
- **New linter rules stay narrow.** Every pattern gets a positive AND a negative test; a
  tell that cannot be made safe goes to the prompt layer with the reason recorded in-file.
  Rules warn, never error — a deliberate choice can overrule one with a written reason.
- **Commits use conventional prefixes** (`feat:`, `fix:`, `docs:`, `chore:`). Do not add
  Claude/AI attribution footers to commit messages.
- **Branch → PR → squash-merge.** Every change lands on a feature branch and merges through
  a PR; `main` is protected (one approval; the admin, 3x-haust, may bypass).
- **Merge continuously, release on request only.** Feature branches merge to `main` as
  they finish — do not cut a version for every feature. A release happens **only when the
  user explicitly asks** for one ("버전 올려라" / "release it"). Work accumulates on `main`
  between releases.
- **Releasing (when asked):** bump all three manifests with `scripts/bump.ts`, merge the
  bump to `main`, and the release workflow tags and publishes structured notes
  automatically.
- **Definition of done for any change:** `npm test` 0 fail, `npx tsc --noEmit` clean,
  `npm run build` succeeds.