From fb95c0ec72034f061bae3e882dabead603f84cd3 Mon Sep 17 00:00:00 2001 From: Anand Pant Date: Thu, 19 Nov 2026 00:04:18 -0600 Subject: [PATCH 1/3] docs: slim the always-loaded agent guidelines --- .ignore | 5 +- AGENTS.md | 199 +++++++++------------------------------- docs/preview-deploys.md | 5 +- 3 files changed, 50 insertions(+), 159 deletions(-) diff --git a/.ignore b/.ignore index 4b7f0d6f0..21525c5b1 100644 --- a/.ignore +++ b/.ignore @@ -1 +1,4 @@ -!.memory/** +!/.memory/ +!/.memory/** +.memory/**/node_modules/ +.memory/**/dist/ diff --git a/AGENTS.md b/AGENTS.md index ad86172da..ae6103e54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,175 +1,60 @@ -# Agent Guidelines +# Agent guidelines -## Scope +## Scope and priorities -This is the canonical Sketchi product repository. Keep one coherent Nx and -Cloudflare Workers architecture; do not reintroduce the retired Next.js, -Convex, Vercel, Bun, or Turborepo stack. - -## Priorities - -- Prefer readable, tested package boundaries over compatibility layers. -- Treat diagram generation as product-critical infrastructure: deterministic inputs, typed intermediate representation, and functional tests. Use the optional diagram family gallery for visual review. -- Delete obsolete approaches when replacing them. Do not carry parallel systems unless a migration step explicitly requires it. -- Frontierclimb owns the graded catalogs `sketchi` and `sketchi-generate`, and currently calls Sketchi's scenario CLI for case discovery and deterministic grading from `tools/scenarios`. Preserve that real caller; do not add a parallel eval system or assume the existing graders are already copied to Frontierclimb. -- Generation cost is product quality. A diagram that reads badly is a failure, and so is one that takes excess tokens, tool calls, retries or wall time to produce. Measure both before claiming an improvement. -- Diagrams are Excalidraw sketches: keep them simple and readable at a glance. Prefer fewer elements and standard stroke widths to fine detail or thin lines. Size limits are ceilings, not targets: draw what the request needs, and keep each family to the size that still reads as a sketch. +- Use Nx and Cloudflare Workers. Do not reintroduce Next.js, Convex, Vercel, Bun or Turborepo. +- Replace obsolete paths rather than adding compatibility layers. Keep package boundaries tested, generation inputs deterministic and the intermediate representation typed. +- Frontierclimb owns `sketchi` and `sketchi-generate`. It calls the `tools/scenarios` CLI for case discovery and deterministic grading. Preserve that contract; do not build a parallel eval system. +- Measure readability **and** generation cost: tokens, tool calls, retries and wall time. An improvement must account for both. +- Draw Excalidraw sketches that read at a glance. Prefer fewer elements and standard strokes; size limits are ceilings, not targets. ## Tests -A test stays only if it gives clear and obvious value. Keep one layer of -protection per behaviour, at the outermost point a caller touches. If a fuzz or -boundary test already fails when the behaviour breaks, inner tests of the same -thing go. +Keep one test layer per behaviour, at the outermost boundary the caller uses. When in doubt, leave it out. Keep: -1. Fuzz and property tests for layout and routing: one per family, plus routing and text-fit. -2. One end-to-end path per family: document in, valid Excalidraw file out. -3. Data safety: storage, share encryption, ownership, atomic writes, quotas and rate limits. -4. Contracts other software depends on, one test each: what the released CLI decodes, HTTP status mapping, the MCP tool list. -5. Spend bounds: retry, timeout and attempt caps on model calls. -6. A regression test for a real past bug, only when the fuzz or boundary test would not catch it. -7. One table per family validator: each issue code raised once by a minimal bad input, asserting the code only. Fuzz generates valid input, so nothing else notices a rule going missing. -8. One table per fuzz oracle: the layout-issue readout or file validator a fuzz test uses to pass or fail detects each issue kind once on a deliberately broken scene. Without it the fuzz cannot fail. +- Layout and routing properties: one fuzz suite per family, plus routing and text-fit. +- One end-to-end path per family: document in, valid Excalidraw file out. +- Data safety: storage, share encryption, ownership, atomic writes, quotas and rate limits. +- One test per external contract: released CLI decoding, HTTP status mapping, MCP tool list. +- Model spend bounds: retry, timeout and attempt caps. +- A past bug's regression test only if fuzz and boundary tests would miss it. +- One table per family validator: one minimal bad input per issue code; assert only the code. +- One table per fuzz oracle: break a scene for each issue kind its layout readout or file validator must detect. Do not add: -- Tests that restate a schema, pin wording (prompts, docs, help, error prose) or pin incidental output (coordinates, element counts, ordering nobody relies on). -- Inner-layer tests of helpers, normalisers or intermediate shapes a kept test already exercises. -- Per-family copies of a generic check, tests that are mostly mocks, component tests of static labels, tests of test helpers, or tests of the gate script beyond its sign-off and lock behaviour. +- Schema restatements, wording checks, or assertions on incidental coordinates, counts or ordering. +- Helper, normaliser or intermediate-shape tests for behaviour a kept test covers. +- Per-family copies of generic checks, mock-heavy tests, static label tests or tests of test helpers. +- Gate script tests beyond signoff and locking. -When unsure, leave it out; git history can bring a test back. A family has at -most `.test.ts`, `-fuzz.test.ts` and `regressions.test.ts`, in a -`tests/` folder beside its source. +Keep family tests beside the source in `tests/`: at most `.test.ts`, `-fuzz.test.ts` and `regressions.test.ts`. ## Delegated agents -- Fable is the coordinator and merger. It reviews architecture and merges each - accepted PR with `gh pr merge --rebase --match-head-commit `; never - squash. It does not implement, and no agent spawns another Fable. -- One primary coordinates and integrates. It routes work and reviews and reports - to Fable; it does not implement product or test changes. -- Authors: one fresh author and isolated Herdr worktree per PR. The author - pushes, opens the PR to `main`, then signs off that head with `pnpm ci:local`. - Authors do not merge. -- Reviewers: a separate, fresh, read-only session on a model the author did not - use, against the PR's base. Review tries to break the changed behaviour and sees - the tests fail. Findings go back to the author once; the primary decides after - recheck. Browser and render verification uses the actual product entrypoint. -- Models: the primary is Claude Opus 5.5 (`cliproxy/claude-opus-5-5`) or - `cliproxy/gpt-6.2-astra`. Authors and reviewers default to `cliproxy/gpt-6.2-sol` - and `cliproxy/gpt-6.2-astra` high, with the reviewer on a model the author did - not use. If a model returns 503 for five minutes, switch to another and say so; - Claude Opus 5.5 is the fallback for any role. Launch with - `/Users/anandpant/Library/pnpm/bin/pi --model --thinking high ''`. - Preserve explicit assignments. -- Messages between agents are at most five lines plus a file path. -- Anything touching production, and any failed pre-deploy check, goes to Fable - first. Only the user or Fable starts a production deploy, dispatches - `release.yml`, or merges a change that starts a release or a production deploy - (a push to main that reaches a Worker app's build; see below). On main, a push under - `.changeset/` runs `changesets.yml`, which merges the Version Packages PR and - dispatches `release.yml`; a push that changes `apps/cli/package.json` starts - `release.yml` directly. `release.yml` submits `npm publish` only for an untagged, - unpublished CLI version, and npm may hold it for 2FA approval. +- Fable coordinates, reviews architecture and merges accepted PRs with `gh pr merge --rebase --match-head-commit `; never squash. Fable does not implement. No agent spawns another Fable. +- One primary routes work and reviews, integrates and reports to Fable. It does not implement product or test changes. +- One fresh author per PR, in an isolated Herdr worktree. The author pushes, opens the PR to `main` and signs off the pushed head; authors never merge. +- Use a fresh, read-only reviewer on a model the author did not use. Review against the PR base; try to break the change and see the tests fail. Return findings to the author once; the primary decides after recheck. +- Primary: `cliproxy/claude-opus-5-5` or `cliproxy/gpt-6.2-astra`. Author/reviewer defaults: `cliproxy/gpt-6.2-sol` and `cliproxy/gpt-6.2-astra`, high. Preserve explicit assignments. +- Launch with `/Users/anandpant/Library/pnpm/bin/pi --model --thinking high ''`. After five minutes of 503s, switch models and report it. Opus 5.5 is the fallback for any role. +- Messages between agents: at most five lines plus a file path. +- Take production work and failed pre-deploy checks to Fable first. Only the user or Fable starts a production deploy, dispatches `release.yml` or merges a change that triggers either. ## Proof -Prove changes locally. Remote CI on a PR is one Nx-affected typecheck of the PR -head, covering changes since its merge-base with `main`; it does not check the -merge with the latest base. It is not the place for heavy suites or -timing-sensitive tests. If you find yourself fighting CI, verify -the change locally and slim CI instead of adding to it. - -Choose each check for a concrete failure it could catch. Changes that do not touch -layout, drawing or graph need no timing harness and no browser run unless they -change UI behavior; use focused tests, the gate and independent review. Changes -to layout, drawing or graph retain artifact identity, affected fuzz and timing. -Reuse unchanged proof by identity instead of repeating expensive checks. - -`pnpm ci:local` is the local CI gate (`tools/ops/src/ci-local/gate.ts`, started by the -`tools/ops/ci-local.mjs` install bootstrap). It defaults to -`origin/main`, including staged, unstaged and untracked changes. After a frozen -install and `nx sync:check`, native Nx affected targets own lint/format, tools -(including custom-rule, domain and font tests), deployment/process behavior, -scenario CLI smoke, typecheck/build/test, and root TypeScript references. Checks -reuse the native local task cache. To run the workspace lint, format or tools check -alone, use `pnpm nx run ops:check-lint`, `ops:check-format` or `ops:check-tools` -respectively. Workflow changes select the native actionlint -target. Full gates also run sampled routing. - -- Before pushing, run `pnpm ci:local --no-signoff`. `--base ` compares - with a verified base. To post `local-ci`, that ref must resolve to the same - commit as `origin/main`, even with `--all`. Documentation-only changes and unchanged patches do not require a - duplicate runtime gate. -- For signoff after the push, run `pnpm ci:local` on the pushed head. It refuses a dirty - worktree or a HEAD the PR does not have, and on success posts the `local-ci` - commit status that merging needs. -- A restack or retarget that leaves the PR's own patch unchanged keeps its - `local-ci` (the `local-ci carry` workflow re-posts it). A changed patch needs - new relevant verification and a full gate before signoff. -- Logs are in `.memory/ci-local/`. `--all` runs every project instead of the - affected graph. At most `CI_LOCAL_SLOTS` gates (default two) run at once per - machine. - -`diagrams:test` owns shared build/generation tests. `diagrams:test-`, -`diagrams:test-graph` and `diagrams:test-text-fit` own family, graph and cross-family -text-fit tests. `pnpm test` uses `diagrams:verify-tests` with wildcard dependencies; -the gate derives individual target names from their configuration so native Nx 24 -input selection keeps family changes narrow. Nx CLI target lists do not expand -wildcards, and an affected aggregate would pull every family dependency in. -`drawing:test` owns only drawing tests. `diagrams:routing-sample` is selected by -its native inputs in `--base` gates: graph, Flowchart, drawing, fonts and shared -runtime/config. Full `origin/main`, signoff and `--all` always run it once. - -Build, typecheck and test targets reuse Nx's native local cache across worktrees. -The installed Nx version shares task artifacts and its index outside the checkout; -project-graph data, Vite state and dependencies remain checkout-local. Do not clear -shared caches or force cache-directory overrides for routine gates. Keep actual -source, dependency, external fixture and environment inputs complete. Explicit -fuzz runs that write caller-selected diagnostic paths use `--skip-nx-cache`. - -These larger suites remain local proof when their inputs change: - -- `pnpm nx run drawing:corpus-renderer` -- `pnpm nx run diagrams:gantt-fuzz` (300 plans per Gantt fuzz; the gate runs 4) -- `pnpm nx run diagrams:chart-fuzz` (300 chart seeds; the gate runs 1–12 plus decimal seed 27) -- `pnpm nx run diagrams:mindmap-fuzz` (2,000 mindmap seeds; the gate runs 8) -- `pnpm nx run diagrams:routing-fuzz` (full flowchart, grouped, state, label and text-fit matrices; sample sizes vary by [routing test](packages/diagrams/src/graph/tests/)) -- `pnpm nx run diagrams:er-fuzz` (240 schemas; the gate runs 16) -- `pnpm nx run diagrams:class-fuzz` (240 models and 120 text-fit rounds; the gate runs 16 and 12) -- `pnpm nx run diagrams:org-chart-fuzz` (900 random charts across three seeds; the gate runs 6) -- `pnpm nx run diagrams:venn-fuzz` (900 random Venn diagrams across three seeds; the gate runs 12) -- `pnpm nx run diagrams:journey-fuzz` (900 random journeys across three seeds; the gate runs 8) -- `pnpm nx run diagrams:sankey-fuzz` (1,200 random flows across three seeds; the gate runs 10) -- `pnpm nx run diagrams:wireframe-fuzz` (1,200 random wireframes across three seeds; the gate runs 8) -- `pnpm nx run diagrams:sequence-fuzz` (400 sequences with self-messages; the gate runs 12) -- `pnpm nx run diagrams:quadrant-fuzz` (700 random quadrant charts; the gate runs 14) -- `pnpm run test:wrangler-dry-runs` after app builds - -Worker Previews are opt-in. Add the `preview` label to a PR to deploy the Worker -apps it affects on every push (closing the PR deletes them), or dispatch -`app-preview` with a PR number and `project` (`affected`, `all`, or one app) for a -stacked PR or a specific app such as `studio`; a dispatch also adds -the label. - -Keep the label off between proof runs: dispatch the project you need, then remove -the label the dispatch adds. Routing/rendering proof uses the preview MCP (`pr--sketchi-studio`), relevant scenario replay and a small -bounded set of inspected PNGs. - -A push to main deploys to production the Worker apps whose build it reaches -(`app-production-deploy`, filtered to `apps/`, `packages/`, `tools/scenarios/`, -`tools/build-config/` and Nx's shared root inputs). Nx checks which build -targets those changes reach. Test files, stories, project READMEs, Vitest -configs, snapshots, and `tsconfig.spec.json` are not Worker build inputs. -Changes to deploy commands alone do not select production builds; previews -still select all apps when preview tooling changes. Studio and Icons share one upload queue with their previews. There is no approval gate. Dispatch `app-production-deploy` to -deploy every app or one, or to attach or detach production domains. - -For UI-affecting changes, verify the changed flow against the real page with -`agent-browser` on the PR preview or production, headless (its default). Never open a visible browser window on the owner's machine (`--headed` or any automation that pops up). - -## Temporary Artifacts - -Use `.memory/` for local notes, logs, screenshots, and other temporary artifacts. It is gitignored but visible to agents through `.ignore`. +- Before pushing: `pnpm ci:local --no-signoff`. After opening the PR: `pnpm ci:local` from the clean, pushed head to post `local-ci`. Signoff requires the `origin/main` base commit. Logs: `.memory/ci-local/`. +- Restacks and retargets carry `local-ci` only for an unchanged patch. A changed patch needs fresh relevant proof and a full gate before signoff. PR CI typechecks the affected head, not a trial merge. +- For layout, drawing or graph changes, retain artifact identity, affected fuzz results and timing. The `*-fuzz` targets on `diagrams` are the full local suites; list them with `pnpm nx show project diagrams`. +- Run `pnpm nx run drawing:corpus-renderer` when its inputs change; use `pnpm run test:wrangler-dry-runs` after affected app builds. +- Verify rendering at the product entrypoint. For UI changes use headless `agent-browser` on the PR preview or production; never open a visible browser. See [Worker previews](docs/preview-deploys.md) for routing and rendering proof. + +## Deploy and release triggers + +- A push to `main` deploys Worker apps whose build inputs it reaches, without approval. Root Markdown and `docs/` alone do not trigger a production deploy. +- On `main`, `.changeset/` changes run `changesets.yml`, which merges the Version Packages PR and dispatches `release.yml`. +- Changing `apps/cli/package.json` on `main` triggers `release.yml` directly. It submits `npm publish` only for an untagged, unpublished CLI version; npm may require 2FA approval. + +Keep temporary notes, logs and screenshots in `.memory/`. Git ignores it; `.ignore` keeps notes searchable. diff --git a/docs/preview-deploys.md b/docs/preview-deploys.md index 4cb518dc0..bd6cea792 100644 --- a/docs/preview-deploys.md +++ b/docs/preview-deploys.md @@ -69,7 +69,10 @@ choices come from the workflow ref; the build and selectors come from the PR hea The workflow resolves the PR head SHA before checkout; that SHA appears in deploy metadata and comments. It also adds the `preview` label before anything uploads, so closing the PR cleans up even if no Preview comment exists yet, and later -pushes keep the PR's affected Previews current. +pushes keep the PR's affected Previews current. For a proof run, dispatch only the +project you need, then remove the label between runs to avoid deploying on each push. +For routing or rendering changes, replay the relevant scenarios against the Studio +preview MCP (`pr--sketchi-studio`) and inspect a small set of exported PNGs. - The shared mise setup uses the repository's exact Node/pnpm pins and a frozen lockfile. - Each build writes assets to `dist/apps//client` and the deploy snapshot From 5418ce9029afcea467bfa65546a037c0cb400674 Mon Sep 17 00:00:00 2001 From: Anand Pant Date: Thu, 19 Nov 2026 00:49:56 -0600 Subject: [PATCH 2/3] docs: clarify proof and preview cleanup requirements --- AGENTS.md | 8 +++++--- docs/preview-deploys.md | 4 ++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ae6103e54..bd381a6dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,15 +46,17 @@ Keep family tests beside the source in `tests/`: at most `.test.ts`, `-sketchi-studio`) and inspect a small set of exported PNGs. From 9b7f5a3a17cff62bbb93912378b4ca4e50874c5a Mon Sep 17 00:00:00 2001 From: Anand Pant Date: Thu, 19 Nov 2026 00:55:22 -0600 Subject: [PATCH 3/3] docs: match Worker selection to affected build targets --- AGENTS.md | 1 + docs/preview-deploys.md | 20 +++++++++----------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bd381a6dd..e995541c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,7 @@ Keep family tests beside the source in `tests/`: at most `.test.ts`, `