Contributing: claim an issue with a draft PR (#1565)

Check gh pr list --search "#N", then open a draft titled "<summary> (#N)" with an empty claim commit; the lowest-numbered open PR for an issue wins, and a draft with no pushes for 72 hours may be taken over after a comment. Agents on a shared machine check the load before a big build.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

AGENTS.md

@@ -123,6 +123,16 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
   keep monitoring it while the task is active and make its pending status clear at handoff;
   do not claim it merged without checking.
 
+## Claim = a draft PR
+- Before working on issue #N, check nobody has it: `gh pr list -R bherbruck/solidcraft --state open --search "#N"`.
+- If none, branch from the latest `origin/main`, `git commit --allow-empty -m "claim: #N"`, push,
+  and open a **draft** PR titled `<summary> (#N)` right away. **The lowest-numbered open PR for an
+  issue wins**; if yours lost, close it. Don't claim by commenting or by editing files.
+- Push work in progress at least daily. A draft with no pushes for 72 hours may be taken over:
+  comment on it first, then open your own claim (you may start from its branch).
+- On a shared build machine, check the load before a big build (`cut -d' ' -f1 /proc/loadavg`)
+  and wait while it is over 24; build with `nice`.
+
 ## Design file format
 A change that saves something new in a design adds ONE file, `crates/doc/src/format/pending/<name>.rs`
 (a `//!` note, and `pub fn step` if older designs must be rewritten). Never edit `FORMAT`,

CLAUDE.md

@@ -96,6 +96,16 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
 - **Never break wasm**: everything below the apps must build for `wasm32-unknown-unknown`
   (`cargo xtask wasm`, part of `cargo xtask ci`).
 
+## Claim = a draft PR
+- Before working on issue #N, check nobody has it: `gh pr list -R bherbruck/solidcraft --state open --search "#N"`.
+- If none, branch from the latest `origin/main`, `git commit --allow-empty -m "claim: #N"`, push,
+  and open a **draft** PR titled `<summary> (#N)` right away. **The lowest-numbered open PR for an
+  issue wins**; if yours lost, close it. Don't claim by commenting or by editing files.
+- Push work in progress at least daily. A draft with no pushes for 72 hours may be taken over:
+  comment on it first, then open your own claim (you may start from its branch).
+- On a shared build machine, check the load before a big build (`cut -d' ' -f1 /proc/loadavg`)
+  and wait while it is over 24; build with `nice`.
+
 ## Design file format
 A change that saves something new in a design adds ONE file, `crates/doc/src/format/pending/<name>.rs`
 (a `//!` note, and `pub fn step` if older designs must be rewritten). Never edit `FORMAT`,

CONTRIBUTING.md

@@ -245,9 +245,17 @@ and a fresh CI run:
 ## Sending a change
 
 1. Work is tracked in [GitHub issues](https://github.com/bherbruck/solidcraft/issues), labelled
-   by area (`area:kernel`, `area:sketch`, `area:doc`, `area:ui`, `area:infra`). Before starting,
-   comment on the issue so it gets the `in progress` label and two people don't build the same
-   thing. For anything bigger than a bug fix that has no issue yet, open one first.
+   by area (`area:kernel`, `area:sketch`, `area:doc`, `area:ui`, `area:infra`). For anything
+   bigger than a bug fix that has no issue yet, open one first. **Claim the issue with a draft
+   PR** before you start, so two people don't build the same thing:
+   - Check nobody has it: `gh pr list -R bherbruck/solidcraft --state open --search "#N"`.
+   - Branch from the latest `main`, commit `git commit --allow-empty -m "claim: #N"`, push, and
+     open a **draft** PR titled `<summary> (#N)`, e.g. `Fillet: variable radius along a chain (#123)`.
+   - **The lowest-numbered open PR for an issue wins.** If yours lost, close it (or offer to help
+     on the other one).
+   - Push work in progress at least daily. A draft with no pushes for 72 hours may be taken over:
+     comment on it first, then open your own claim.
+   - Mark the PR ready for review when it is done.
 2. Branch from `main` and keep the PR to one topic.
 3. Run `cargo xtask ci` before pushing. It runs fmt, the asset, licence and layer checks,
    clippy (`-D warnings`), then the tests with the wasm build check alongside. A PR has to pass it.