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)

Connections

Local graph

Linked from