* 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>
4.6 KiB
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.mdbefore 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/kerneluses 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,
modlines, 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.txtonly shrinks):skills/solidcraft-commands/SKILL.md. - New UI strings go in
assets/locales/pending/<slug>.json, ATTRIBUTION rows inattribution/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 withmain: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 cibefore every commit, without switching branches while it runs.cargo xtask skillskeeps this file andskills/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 |