Skip to content

Latest commit

 

History

History
79 lines (64 loc) · 4.98 KB

CLAUDE.md

File metadata and controls

79 lines (64 loc) · 4.98 KB

Repo conventions for Claude Code agents working in kernelCAD-web

Every feature and tool

Follow AGENTS.md: check current comparable websites and the existing kernelCAD website before implementation, update discovery/docs, and produce and visually inspect a short MP4 demonstration for every new or materially changed feature/tool. This expands the release-only demo rule below. Keep dated competitor comparisons private; retain source, verification and truthful demo provenance.

Deployment

Before deploying anything, read docs/DEPLOY.md. Short version: one trunk (develop, no main); the Studio (src/) auto-deploys to app.kernelcad.com on push to develop; eligible pushes to develop also trigger the private marketing deploy for kernelcad.com, including docs/guide/** blog sources and docs/demos/** media. The listed top-level prose files and unrelated docs-only changes do not trigger it. Manual gh workflow run deploy-kernelcad-com.yml -R w1ne/kernelCAD-server -f web_ref=develop remains available as an override. Blog drafts still require editorial approval before publication. Verify the actual deploy and live URLs; upload success does not prove the separate cache purge passed. A v* tag is a full npm release, not a per-surface deploy. Don't guess the deploy path — match the changed surface to the runbook.

CAD authoring discipline

For any task that creates or modifies CAD output, use the bundled kernelcad skill first and load kernelcad-authoring before editing a .kcad.ts model. The source file is the design source of truth; generated PNG/MP4/STEP/STL/score artifacts are evidence or deliverables, not files to hand-edit.

Adopt this loop:

  1. Classify the job and write down the engineering intent before coding.
  2. Plan the .kcad.ts source, parameters, imports, explicit output artifacts, and verification commands.
  3. Edit source and provenance only.
  4. Generate named targets only; do not refresh whole artifact directories unless the task is explicitly a release/demo rebuild.
  5. Validate with deterministic commands before relying on screenshots.
  6. If a rendered artifact is produced, inspect it visually and report concrete visible evidence. Do not mark visually broken CAD done because tests passed.
  7. When visual evidence matters, run kernelcad render inspect <file> <outDir> to produce a deterministic inspection bundle with a manifest and canonical RGB views. Add --channels rgb,mask,depth,normals when machine-readable object masks, depth, or view-space normals are needed. Use --focus <names> or --hide <names> to isolate feature ids or assembly part names when clutter would obscure the check. Keep richer channels in the same manifest packet; do not replace the canonical RGB views.

Prefer lib.fromSTEP(...) for real purchased components such as servos, bearings, motors, fasteners, sensors, PCBs, and connectors. Hand-modeled placeholder boxes/cylinders are acceptable for blockouts, but final review must either replace them with vendor/catalog geometry or label the limitation.

Demo discipline (v0.X.0-tag PR review rule)

When reviewing a PR that ships a v0.X.0 tag (cuts a per-module release):

  1. Verify docs/demos/v0.X/<task>/whats-new.md contains a ## Hero artifact section, a ## Why memorable section with all three bullets filled (no TODO:), and a ## What's new section.
  2. Verify docs/demos/v0.X/<task>/meta.json contains heroArtifact, catalogSource, and overrideApprovedBy keys.
  3. Judge the artifact itself, not the prose. From v0.18 the hero must be a real user job taken end to end (for example a Pi 5 case with heat-set inserts, a motor mount, a coupler with set screws), and meta.json.proof must name that job and point at a passing verify report or a photo of the printed or fabricated part. Fail the review if the hero is a bare primitive (box, cube, cylinder), if the new tool isn't visibly central to the build, or if the proof doesn't show the part working. A recognisable object with no proof is not enough.
  4. If meta.json.overrideApprovedBy is non-null, the override path was used. Surface this to the controller for traceability — it is not automatically a fail, but should not be a default.

This rule binds the superpowers:code-reviewer agent and any human reviewer working in this repo.

Quality ratchet

scripts/lib/qualityBaseline.json and scripts/lib/cycleBaseline.json may only shrink over time; a value going back up (even to an old baselined value) fails CI. After reducing findings or cycles, run npx tsx scripts/qualityBaselineRegen.ts to regenerate both baselines — it refuses to write (exit 1) if any finding is new or grew, unless you pass --allow-new. eslint.config.js also enforces a one-way import layering (shared -> kernel -> modeling -> kinematic -> agent -> studio); a no-restricted-imports/no-restricted-syntax error there means you imported from a higher layer — move the code down or add it to that block's allowlist with a follow-up ticket, don't silence the rule.