git:20260731.69763b0 to git:20260801.afeffa3

# CLAUDE.md — design-os-figma-plugin

Guidance for agents working in this repository (the Figma plugin + agent bridge of DESIGN:OS,

extracted from jangtrinh/design-os).

## Task workflow (GitHub Projects driven)

Work is planned on the project board: https://github.com/users/jangtrinh/projects/2 — one

GitHub issue = one Sonnet-ready task. The standard lifecycle, using installed ak-* skills:

1. **Pick up**: claim an issue from the board (Status → In Progress).

2. **Plan**: `/ak:issue-to-plan <issue-url>` — reads the issue, scouts this codebase, runs the

brainstorm gate + red-team, produces the validated plan branch. Specs referenced by issues

may live in the monorepo's `plans/` (paths are cited in the issue body).

3. **Implement**: test-first, in an isolated worktree for parallel work (`/ak:worktree`).

Deviations from the plan get reported up, never improvised.

4. **Ship**: `/ak:ship` from the feature branch — merge-main, test, review, commit, push, PR.

5. **Review**: `/ak:review-pr <pr> --reply` — the stage-4 adversarial review posts back to

GitHub as a formal PR review. REQUEST_CHANGES loops back to step 3; findings are fixed

test-first (each fix's test must fail against the pre-fix code).

6. **Audit + merge**: final audit gate confirms direction + gates, then merge. Issue → Done.

## Gates (all must pass before any PR)

- `npm run typecheck` · `npm run build` · `npm test` (includes the panel gate,

`tests/figma-plugin-panel.test.ts`, which needs `git submodule update --init --depth 1`).

- The panel gate runs the kernel's own linters from the pinned `kernel/design-os` submodule —

a bridge until `ease-design/lint` is published (issue #9). Bump the pin deliberately.

## House rules (carried from the design-os studio)

- **Nothing vanishes silently.** Every eviction, prune, rotation, or drop leaves a counter,

an archive, or an audit record. A wrong fact is worse than an absent one.

- **Honest reporting.** Panel/CLI output never fabricates — a name appears only when the

reply carried one, a count only when one parsed.

- **One mutation per file.** Mutations are jobs in a per-file FIFO; read-only traffic

declares itself and bypasses. Every mutating command states its undo-bracket behavior.

- **Respect the project's own artifacts.** Never overwrite a file the target project

generates itself (see the foreign-registry yield pattern).

- **Test-first for behavior changes**; a mock must encode the external API's refusals, not

just its happy path (Figma's dynamic-page getters throw; permissive mocks are green lights

that mean nothing).

- **Count before you target** — a headline number in an issue is a hypothesis; measure on

real data before optimizing or capping.

- Conventional commits, no AI references in commit messages or PR bodies.

- The deterministic broker/CLI stays model-free: pure transforms, no network beyond the

loopback WS, no LLM calls.

## Layout

- `cli/` — figma-agent CLI + broker (job table, per-file queues, binding index, feeds).

- `plugin/` — Figma plugin (main-thread executors + panel UI). `plugin/code.js` and

`plugin/ui.html` are committed build outputs the manifest loads.

- `shared/` — protocol, edit-feed schema, mutating-command classification.

- `tests/` — the full suite (900+); daemon-harness tests cover the broker seams pure unit

tests cannot see.

- `kernel/design-os` — pinned submodule (panel-gate linters only; see issue #9).

The studio this belongs to: https://github.com/jangtrinh/design-os