SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
AGENTS.md and the contributing skill: say how to work as an agent (#8059)
Homero Thompson06a8a9b7d292
diff --git a/AGENTS.md b/AGENTS.mdindex 8e27b26b4d..cbd8192262 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -3,13 +3,13 @@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.+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`. 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`.+- Never crash: no unwrap/expect/panic/unsafe in non-test code, errors are `Result`, input is hostile: clippy `-D warnings`, `hostile_params_never_panic`.- Model decisions (what an operation does, which bodies it touches, which face or edge a point or name means, depths, nearness) use exact geometry; a mesh is for display, export, previews and mesh bodies (`xtask/mesh-decisions.txt` only shrinks): `cargo xtask mesh-decisions`.- New kernel cases go to solidcore: `cargo xtask lists`.- Everything is a command and programmatic calls never open dialogs: `skills/solidcraft-commands/SKILL.md`.@@ -21,12 +21,14 @@ Work: ROADMAP.md, "Where help is wanted most" in CONTRIBUTING.md, issues labelle- 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 changed default keeps the old behaviour behind a preference and fills the PR's `Changes a default:` line: `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`.+- Look at open PRs first, claim with a draft PR (lowest number wins), one topic per PR: `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`.+- Code, comments, commit messages and docs are in English, always: `skills/solidcraft-contributing/SKILL.md` ("Working as an agent").+- Independent work runs in parallel, dependent work stays sequential: `skills/solidcraft-contributing/SKILL.md` ("Working as an agent").- 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.+- Run `cargo xtask ci` before every commit. `cargo xtask skills` keeps this file and `skills/` honest.## Working on X: read the skill first| Working on | Read |diff --git a/skills/solidcraft-contributing/SKILL.md b/skills/solidcraft-contributing/SKILL.mdindex f23b1799ac..5d38c496be 100644--- a/skills/solidcraft-contributing/SKILL.md+++ b/skills/solidcraft-contributing/SKILL.md@@ -76,6 +76,26 @@ not modelling a part through MCP.- **Do not open a second PR** for an issue a lower-numbered open PR already closes, and keep the `Changes a default:` line filled in: `pr-checks.yml` fails both.- **The gate reads the working tree.** Do not switch branches while `cargo xtask ci` runs: it compiles the other branch's code and fails on a change not in the PR. Run it in the background and wait for its log.+## Working as an agent++- **The code is English. The comments are English. Always.** Identifiers, doc comments,+ inline comments, commit messages, branch names, test names, error messages and+ documentation are all in English. This is not a preference: a comment in another+ language is a defect, it is not reviewable by the people who maintain this code, and a+ reviewer rejects it. If something is not obvious, write it in English and keep it+ short. A user-visible string is not inline in the code: it goes to the message+ catalogs in `assets/locales/` (a new one to `assets/locales/pending/<slug>.json`),+ and `skills/solidcraft-ui-text/SKILL.md` says how to name and translate it.+- **Parallel work runs in parallel.** When a task splits into independent parts (several+ files, several areas, several checks that do not depend on each other), dispatch one+ subagent per part and let them run concurrently instead of walking the list one item at+ a time. Give every subagent a self-contained brief: what to change, what not to touch,+ and what to report back. Read the answers before you continue; a subagent's report is+ not a result you can assume.+- **Do not parallelize what depends on itself.** A fix and the test that proves it, a+ refactor and the callers it breaks, two edits to the same file: those stay sequential.+ One subagent per independent unit of work, and no two units may write the same file.+## 1. Check the environmentExplain what you are checking and why, in everyday language. Run: