Contribution guide
The working procedure, from scoping a change to the pre-push review gate.
Setup and verification
make setup # install git hooks, generate local shims, create scratch directories
make check # run formatting, clippy, pre-commit hooks, docs validation, and tests
Run make help to see all available targets.
Working procedure
flowchart LR S["Scope in one sentence"] --> W["Worktree on fresh branch"] W --> P["Plan"] P --> I["Implement with tests and docs"] I --> C["make check"] C --> R["Skeptical review"] R --> H["Human approves push"]
| Step | Rule |
|---|---|
| Scope | One sentence naming unit of work, target, and outcome; split unrelated edits |
| Worktree | One worktree per change; conventional branch (feat/, fix/, docs/, refactor/, chore/) rebased on main |
| Commits | Conventional Commits, 50/72 limits, summary-only preferred, explicit paths, zero trailers |
| Bindings | Keep host-language wrappers thin; never duplicate wire, roster, or grant logic |
| Docs | Update spec/ and docs/ (including parent index.md and docs/logs/ via make docs/log) in the same commit |
| Verify | Run make check and confirm all hooks, lints, docs checks, and tests pass |
| Review | Run a skeptical maintainer review before requesting a push; humans approve outward actions |
| Security Audit | Run the two-wave security and privacy audit skill before release or protocol milestones (.agents/skills/security-privacy-audit/SKILL.md) |