Files
solidcraft/AGENTS.md
T
bherbruckandClaude Opus 5.5 927a5c3733 PR rules: a title has to make sense to someone who never saw the chat (#11202)
* PR rules: a title has to make sense to someone who never saw the chat

Agents write PR titles from inside their own context, or copy the issue's title, so a maintainer reading the list can't tell what a PR does. AGENTS.md, the contributing skill, CONTRIBUTING.md and the PR template now say who a title is for and show an unclear and a clear one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K14jA88xLsBfMkWo4Da5uh

* PR rules: write PR text in plain, literal English, and use a clearer example title

The first example still said "that window", the kind of pointing word the rule bans. The new rule takes the useful parts of Simplified Technical English without its approved-word list, which doesn't fit CAD terms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K14jA88xLsBfMkWo4Da5uh

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 16:02:56 +00:00

4.6 KiB

SolidCraft: instructions for agents

SolidCraft is a clean-room, pure-Rust parametric 3D CAD app (sketch solver, feature timeline, B-rep kernel, an egui UI that agents drive). This file is a router: the hard rules, then the skill to read for your task. Humans: CONTRIBUTING.md.

Start here

Work: ROADMAP.md, "Where help is wanted most" in CONTRIBUTING.md, issues labelled help wanted, good first issue, needs-triage; architecture in docs/architecture.md. Act when the code, docs and rules settle a question; ask only when it changes what users see. Local plan/ notes are optional.

Hard rules (what enforces each)

  • Independent: never copy another product's code, icons, text or templates; never drive or take data from commercial CAD. skills/solidcraft-ground-rules/SKILL.md.
  • No GPL/LGPL/AGPL code, not even reading it (OpenCASCADE, FreeCAD, SolveSpace, CadQuery, LibreCAD, QCAD): cargo xtask licences --check.
  • Every asset is original or openly licensed with a row in ATTRIBUTION.md; read assets/AGENTS.md before icon work: cargo xtask assets, cargo xtask icons.
  • Never crash: no unwrap/expect/panic/unsafe in non-test code (unsafe allowlist in crash-safety), errors are Result, input is hostile: clippy -D warnings, hostile_params_never_panic.
  • Everything is a command and programmatic calls never open dialogs: skills/solidcraft-commands/SKILL.md.
  • Layering (geom, sketch/kernel/render, doc, io, engine, ui-egui, apps); only crates/kernel uses truck: cargo xtask layers.
  • One outer UI container, one camera path (navigation::handle), colours from theme tokens: cargo xtask ui-containers.
  • Application code is Rust only and builds for wasm: cargo xtask wasm, cargo xtask web-offline-test.
  • The product name is SolidCraft; the old name lives only in docs/compatibility.md.
  • Sorted lists (message catalogs, mod lines, languages) stay sorted: cargo xtask lists. Never edit generated files (docs/features.md, THIRD-PARTY-LICENSES.txt) in a PR.
  • A design-format change is ONE new file in crates/doc/src/format/pending/: scripts/test-format-pending.sh.
  • A command has input and output schemas (will become required; schema/unconverted.txt only shrinks): skills/solidcraft-commands/SKILL.md.
  • New UI strings go in assets/locales/pending/<slug>.json, ATTRIBUTION rows in attribution/pending/<slug>.md: cargo xtask lists.
  • A changed default keeps the old behaviour behind a preference and fills the PR's Changes a default: line, and no second PR for an issue a lower-numbered one closes: pr-checks.yml.
  • A regression test goes in the area's existing test file, never a per-bug file (#3226).
  • Look at open PRs first, claim with a draft PR (lowest number wins), one topic per PR, never force-push main, no pushes just to catch up with main: skills/solidcraft-contributing/SKILL.md.
  • A PR's title and first sentence make sense to someone who never saw your chat or the issue: skills/solidcraft-contributing/SKILL.md.
  • Show observable changes with real screenshots or a recording, captured yourself.
  • Run cargo xtask ci before every commit, without switching branches while it runs. cargo xtask skills keeps this file and skills/ honest.

Working on X: read the skill first

Working on Read
A PR, a claim, review, CI or evidence skills/solidcraft-contributing/SKILL.md
Licences, assets, clean-room, the name skills/solidcraft-ground-rules/SKILL.md
Non-test Rust, hostile input, a crash report skills/solidcraft-crash-safety/SKILL.md
A command, a crate boundary skills/solidcraft-commands/SKILL.md
A dialog, panel, camera, icon, colour skills/solidcraft-ui/SKILL.md
Labels, messages, translations skills/solidcraft-ui-text/SKILL.md
Saving something new in a design, import, export skills/solidcraft-file-formats/SKILL.md
Preferences, a changed default skills/solidcraft-preferences/SKILL.md
Writing or running tests skills/solidcraft-tests/SKILL.md
Slow work, the window thread, wasm skills/solidcraft-performance/SKILL.md
Releases, installers, packages skills/solidcraft-packaging/SKILL.md
Running the app, control channel, MCP tools skills/solidcraft-agent-tools/SKILL.md
Building a part over MCP skills/solidcraft-modeling/SKILL.md
Changing an existing design skills/solidcraft-editing/SKILL.md
A bug report, a crash, a wrong result skills/solidcraft-reporting/SKILL.md
Checking, porting, designs in git skills/solidcraft-checking/SKILL.md
Assemblies, joints, motion skills/solidcraft-mechanisms/SKILL.md