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.
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.
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:
- Classify the job and write down the engineering intent before coding.
- Plan the
.kcad.tssource, parameters, imports, explicit output artifacts, and verification commands. - Edit source and provenance only.
- Generate named targets only; do not refresh whole artifact directories unless the task is explicitly a release/demo rebuild.
- Validate with deterministic commands before relying on screenshots.
- If a rendered artifact is produced, inspect it visually and report concrete visible evidence. Do not mark visually broken CAD done because tests passed.
- 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,normalswhen 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.
When reviewing a PR that ships a v0.X.0 tag (cuts a per-module release):
- Verify
docs/demos/v0.X/<task>/whats-new.mdcontains a## Hero artifactsection, a## Why memorablesection with all three bullets filled (noTODO:), and a## What's newsection. - Verify
docs/demos/v0.X/<task>/meta.jsoncontainsheroArtifact,catalogSource, andoverrideApprovedBykeys. - 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.proofmust 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. - If
meta.json.overrideApprovedByis 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.
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.