git:20260715.6876c9b to git:20260725.8d54a6b

- # 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-writer`, `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.

-