| name | engineering-reference |
| description | Lookup reference for executing a task already decided on — code style per language, test/mock boundaries, API conventions, the local CI sequence before push, merge discipline, how to resolve review comments, repo settings and git hooks. Read it when you are about to push, merge, review, or set up a repo; not before. |
| providers | ["claude","copilot","codex"] |
Engineering reference
Consultation material, pulled out of rules/best-practices.md (2026-07-14). It lived in the
always-loaded canon and cost tokens on every turn of every session in every repo, while none of it
changes what an agent decides — it tells you how to execute a task you have already chosen.
The canon's own rule sends exactly this to a skill: "knowledge that applies sometimes belongs in a
skill (progressive disclosure), never in the canon."
What stayed in the canon is what changes behaviour without being asked: No False Done, Wired
End-to-End, Carded End-to-End, Surgical Edits, the Persuasion Guardrails, token economy, and the
parallel-work rule. Those must be in the room before you know you need them. This must not.
Code Style
| Lang | Standard |
|---|
| Rust | cargo fmt, cargo clippy -- -D warnings, edition workspace, ? over unwrap, Result over panics |
| TS/JS | ESLint + Prettier, semicolons, single quotes, 100 chars, const > let, async/await, interface > type, .test.ts AAA |
| Python | Black 88, Google docstrings, type hints, pytest + fixtures |
| Bash | set -euo pipefail, quote vars, local, trap cleanup EXIT |
| CSS | Modules / BEM, rem / px borders, mobile-first, max 3 nesting levels |
| Config | 2-space indent |
Testing
Mock boundaries — ALLOWED: external APIs, network, filesystem, time. FORBIDDEN: auth, DB (use a test DB), the module under test.
Integration: new endpoint → real middleware. New consumer → realistic shape. Interface change → ALL consumers.
Test data: real names / shapes. No Studio A / Test Studio. Domains: example.com / example.org only.
Schema change: migration in the same PR. Field addition → update ALL fixtures.
Coverage: 80% business logic / 100% critical paths. Parameterized SQL.
API Conventions
Methods: GET / POST / PUT / PATCH / DELETE | Plural nouns /api/users | kebab-case | Max 3 levels.
Status: 200 / 201 / 204 | 400 / 401 / 403 / 404 / 409 / 422 / 429 / 500 / 503.
Error: {error: {code, message, details?, requestId, timestamp}}.
Pagination: ?page=1&limit=20 (max 100). Rate limit: 429 + headers. Auth: OAuth 2.0 / JWT.
Local CI Before Push
Before git push or PR creation, run the full local pipeline:
- Format:
cargo fmt --check / prettier --check / ruff format --check
- Lint:
cargo clippy -- -D warnings / eslint / ruff check
- Type-check:
cargo check / npx tsc --noEmit
- Tests:
cargo test / npm test / pytest
- Build:
cargo build / npm run build
If any step fails, fix and re-run ALL checks. Do NOT push with known failures.
Merge Discipline
You are autonomous on merges — but only after careful evaluation. Before merging:
- CI must be fully green (all required checks pass; never merge with anything pending or failing).
- PR must be
mergeable=MERGEABLE and mergeStateStatus=CLEAN.
- Diff must match the PR description (no surprises).
- Every review comment must be properly resolved — see § Review Comments below. No unresolved comments, no
requested-changes reviews, no "resolved a cazzo".
- Local pipeline (fmt / lint / type-check / tests / build) must have run clean before push.
- Merge type is merge commit only — never squash, never rebase (preserves history; parallel agents depend on it).
- If the PR touches
main branch protection, security policy, license, or release infrastructure → STOP and ask first.
- Force-pushes to
main are ALWAYS forbidden without explicit user confirmation.
After merging: delete the source branch, fast-forward main locally, and report the merge commit SHA. If anything in the eight checks above is uncertain, ask before merging — uncertainty is a signal to pause.
Review Comments
Every comment on a PR — human or bot — must be analyzed, understood, and resolved well, not dismissed.
For each comment:
- Read it fully. Don't skim. Re-read if the intent is unclear.
- Understand the underlying concern. A nitpick on naming may be a deeper concern about the abstraction; a "did you consider X?" is asking for evidence, not approval.
- Decide the right action: fix the code, push back with reasoning, mark wontfix with explanation, or escalate to the user. Never silent-resolve.
- Implement the fix correctly — same rigor as fresh work: tests, types, conventional commit, no half-measures. Don't game the comment with a token edit.
- Reply on the comment thread explaining what you did and why, then mark it resolved. The reply is the audit trail; "fixed" alone is not enough.
- Re-run the local pipeline before pushing the fix — review fixes break things as often as fresh code.
- If the reviewer is wrong, say so respectfully with evidence (link to docs / code / tests). Conviction over agreeableness; the reviewer would rather be corrected than silently overruled.
Never:
- Resolve a comment without addressing its substance.
- Push a "fix" that only touches the comment's quoted line while ignoring its actual point.
- Batch-resolve comments at the end as a clean-up gesture.
- Merge a PR with any unresolved comment, even one you believe is invalid — write the rebuttal first.
If you cannot resolve a comment yourself (architectural disagreement, scope question, missing context), STOP and ask the user. Better to pause than to merge over the disagreement.
Repository Setup
| Setting | Value | Why |
|---|
| Squash merge | DISABLED | Loses history; parallel agents overwrite each other's work |
| Rebase merge | DISABLED | Rewrites history, breaks parallel branch refs |
| Merge commit | ENABLED (only) | Preserves full history, safe for parallel agents |
| Branch protection | Require PR + CI pass | No direct push to main |
Apply to a repo: gh api repos/OWNER/REPO -X PATCH -f allow_squash_merge=false -f allow_rebase_merge=false -f allow_merge_commit=true
Recommended Git Hooks
Install per-repo when relevant:
| Hook | Blocks |
|---|
pre-commit MainGuard | commits on main in main checkout |
pre-commit FileSizeGuard | commits with files > 300 lines (.rs/.ts/.js/.sh) |
pre-commit SecretScan | commits containing API keys, tokens, passwords |
commit-msg CommitLint | non-conventional commit messages |
