diff --git a/AGENTS.md b/AGENTS.md index 8e27b26b4..cbd819226 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/.json`, ATTRIBUTION rows in `attribution/pending/.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.md index f23b1799a..5d38c496b 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/.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 environment Explain what you are checking and why, in everyday language. Run: