AI Agent Core Rules

# Core Development Standards

*Assumes a capable agent. Routine craft (clarity, decomposition, root-cause analysis) is expected by default, not restated. Hard blocks on destructive/irreversible actions live in settings.json permissions + PreToolUse hooks — never trusted to this file.*

## 1. Code
- **Naming:** Booleans read as predicates, functions as verbs; follow the language's idiomatic casing.
- **Immutability:** Prefer immutable bindings and pure functions; isolate side effects.
- **Comments:** Explain *why*, never narrate *what*.
- **Dependencies:** Standard library first; justify every new dependency.

## 2. Type Safety
- **No escapes:** Where strict typing is available, never suppress type-checker errors or use unsafe casts/assertions — fix the cause or type it correctly.
- **Boundaries:** Validate at every external boundary (API, DAL, I/O) for runtime safety.
- **External types:** Extend or declare missing third-party types; never weaken your own types to paper over a library gap.

## 3. Shell & Filesystem
- **Search:** `rg` for content, `fd` for files (both respect .gitignore). With bare `find`, always exclude `node_modules`/`.git`.
- **Scope:** Stay inside the workspace — no absolute paths, no `../` escapes.
- **Destructive ops:** List and verify targets before any delete/overwrite.

## 4. Git
- **Commits:** Conventional Commits — `<type>(<scope>): <subject>`, lowercase imperative, no trailing period.
- **Staged only:** Commit exactly what is staged; never `add -A` unreviewed changes.

## 5. Change Discipline
- **Root cause:** Diagnose *why* before fixing; no band-aids over symptoms.
- **Blast radius:** On rename/migrate, sweep the whole codebase for affected call sites.
- **Reversibility:** Surface assumptions and tradeoffs; confirm before wide-reaching or irreversible changes.

## 6. Testing
- **Right level:** Match Unit/Integration/E2E to the stack and project phase.
- **Critical paths:** Core business logic is always covered.
- **Determinism:** No flaky tests.

## 7. Workflow
- **TDD by default:** Write the failing test that specifies the behavior first, then implement to green, then refactor. The test defines "done"; spikes are the only exception and are thrown away.
- **Deferring work:** When asked to park or postpone, capture it as a file-based issue — never an inline `TODO` or half-finished code. Issues are the backlog's source of truth.
- **Decisions → ADR:** Architectural decisions go through the `/adr-writer` skill against `adr-spec.md`, strictly — never ad hoc. ADRs are immutable: a changed decision is a new ADR marked `Superseded`, never an edit to an accepted one. The skill gates significance — not every choice warrants an ADR.

## 8. Tools & MCP — *only when authoring tools/servers*
- Rigid I/O schemas; structured, actionable errors (never raw stack traces).
- Least privilege; write-ops idempotent or explicitly confirmable.