From 5ee037a7c3ecd9bc41b9533d5fdaa1ada3b1828b Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Wed, 28 Oct 2026 16:33:24 -0300 Subject: [PATCH] docs: add an AI usage policy, AGENTS.md and CODEOWNERS Co-Authored-By: Claude Sonnet 5.5 --- .github/CODEOWNERS | 1 + .github/PULL_REQUEST_TEMPLATE.md | 5 +++ AGENTS.md | 69 ++++++++++++++++++++++++++++++++ AI_POLICY.md | 40 ++++++++++++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 4 +- README.md | 2 +- 7 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 AGENTS.md create mode 100644 AI_POLICY.md create mode 100644 CLAUDE.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..1f3706b --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @nxtime diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cc690c7..1ec0455 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,6 +6,10 @@ +## AI assistance + + + ## Screenshots @@ -17,3 +21,4 @@ - [ ] Follows [RULES.md](../RULES.md) (no overflow, data safety, one undo step per tool call) - [ ] Docs, tool descriptions and `PROGRESS.md` updated where needed - [ ] Conventional commit messages +- [ ] I read and understand every line of this change (AI-assisted or not) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..720eb05 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,69 @@ +# Guidance for coding agents + +PaperCraft is a native Rust design and whiteboard canvas (egui, wgpu, winit) that AI agents drive +over MCP and a CLI. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [RULES.md](RULES.md) first; this +file is the short version for agents, and [AI_POLICY.md](AI_POLICY.md) says what the person using +you is accountable for. + +## Commands + +```sh +cargo build --release +cargo fmt --all +cargo clippy --all-targets +cargo test --no-fail-fast # prefer one test: cargo test --test mcp name +cargo check --lib --target wasm32-unknown-unknown +``` + +`tests/update.rs` cannot run on Windows (it needs elevation); that failure is known. + +## Running the app safely + +Never run a test copy against the person's real projects or MCP port, and never close or restart +their running PaperCraft. Give yours its own folder and port, and keep its PID so you can stop only +your own process: + +```sh +PAPERCRAFT_HOME=/tmp/pc PAPERCRAFT_MCP_PORT=29998 ./target/release/papercraft +``` + +Do not stop processes by name. + +## Layout + +`src/model` (document), `src/editor` (tools and edits), `src/render` (wgpu), `src/mcp` (tools, +HTML/CSS mapping, lint), `src/ui` (egui panels), `src/io` (import and export), `src/project` +(store and formats), `tests/` (scenario tests), `specs/` (feature specs), `skills/` (agent +skills). The README's project layout lists the rest. + +## Conventions + +* Tests first; match the style of the tests next to yours, and check the behaviour is not already + covered. +* Changes to the document go through `Editor::edit`: one transaction, one undo step. +* Handle errors; do not `unwrap` user data and do not discard errors with `let _ =`. +* Comments explain *why*, never summarise the code. No dead code, debug prints or + commented-out blocks. +* Files stay under about 800 lines; split by feature. +* Reuse the shared UI kit and theme instead of one-off values. Nothing may overflow its container. +* Writes to projects are atomic and format changes ship a migration (see RULES.md, "Data safety"). +* Adding or removing an MCP tool means a test in `tests/mcp.rs`, a precise description, and the + tool count updated in the README and ROADMAP. +* Commits are conventional (`feat(scope): summary`) and focused. Do not commit, push or tag unless + the person asked you to. + +## Designing with PaperCraft (skills, examples, screenshots) + +* Themes are modes, never copies: one artboard per screen, a value per mode on each variable, and + `set_variable_mode` to switch. Never duplicate artboards for light and dark. +* Every colour on a themed screen is a variable. +* Check each artboard for overflow, programmatically and by screenshot in each mode, and run + `lint_design`. +* Release design locks when you finish. + +## Avoid + +* Creative additions nobody asked for; stay inside the task. +* Trivial tests, wide or optional types added to appease the compiler, and swallowed errors. +* Editing generated files, lockfiles or release artifacts by hand, or touching files unrelated to + the task. Leave other people's uncommitted work alone. diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 0000000..3a01c47 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1,40 @@ +# AI usage policy + +PaperCraft is built to be driven by AI agents, and many of its contributors use them too. AI tools +are welcome here. What we ask is that a person stays accountable for everything submitted. + +## For contributors + +* **You own what you submit.** Read every line of your pull request before asking for review. If + you cannot explain what a change does and how it fits the rest of the system without asking an + AI, do not submit it yet. +* **Disclose meaningful AI help.** Say which tool you used and roughly how much it wrote in the + pull request description (for example "drafted with Claude Code, reviewed and tested by me"). + Autocomplete and spell-checking do not need a note. +* **Write issues yourself.** An agent can help you research, but the report should be in your own + words, trimmed to what matters, with reproduction steps you ran. Long generated text that nobody + checked puts the burden on maintainers. +* **Think before you generate.** Agents jump to code and make their own job easy: trivial tests, + wide or optional types, swallowed errors, redundant comments, copied local patterns that do not + fit. Push back on all of it. [RULES.md](RULES.md) lists the standards to hold the output to. +* **Verify.** Run the checks in [CONTRIBUTING.md](CONTRIBUTING.md), use the app, and attach + screenshots for UI changes. "The agent said it works" is not a test result. +* **Answer automated review.** If a bot reviews your pull request, fix its findings or reply with + a one-line reason a finding does not apply. +* **No bulk or drive-by pull requests.** Many small generated changes across the tree, or changes + to something nobody asked for, will be closed. Open an issue first for anything beyond a small + fix. + +Pull requests that clearly skip these steps may be closed without a detailed review. Repeated +low-effort submissions can lead to a block, under the [Code of Conduct](CODE_OF_CONDUCT.md). + +## For coding agents + +Read [AGENTS.md](AGENTS.md). It holds the commands, conventions and guardrails an agent working in +this repository should follow. + +## Why + +Every issue and pull request is read by a person. Review time is the scarce resource, and a change +nobody understood costs more than it saves. AI that is reviewed, tested and understood by the +person submitting it is a good way to build PaperCraft; AI used to skip that work is not. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 530f62c..e36e91c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,9 @@ first contribution is low: a typo fix, a clearer error message, a missing test o fix are all welcome. Please read [RULES.md](RULES.md) before writing code: it holds the standards a change is judged by. -By taking part you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). +By taking part you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Using an AI tool is fine; +the [AI usage policy](AI_POLICY.md) says what you stay responsible for, and coding agents should read +[AGENTS.md](AGENTS.md). ## Ways to help diff --git a/README.md b/README.md index 1703869..d4ea49c 100644 --- a/README.md +++ b/README.md @@ -321,7 +321,7 @@ docs/ guides and screenshots ## Contributing -Bug reports, ideas, docs and code are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (setup, checks, commits, pull requests) and [RULES.md](RULES.md) (the standards a change is reviewed against). Security problems go through [SECURITY.md](SECURITY.md), and everyone follows the [Code of Conduct](CODE_OF_CONDUCT.md). +Bug reports, ideas, docs and code are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (setup, checks, commits, pull requests) and [RULES.md](RULES.md) (the standards a change is reviewed against). AI tools are welcome under the [AI usage policy](AI_POLICY.md), and coding agents should read [AGENTS.md](AGENTS.md). Security problems go through [SECURITY.md](SECURITY.md), and everyone follows the [Code of Conduct](CODE_OF_CONDUCT.md). ## License and credits