rules.json

{
  "title": "engineering rules",
  "intro": "Shared rules for every AI coding tool in this repo. Generated into each tool's native format by `forge sync` — edit this source, not the generated files. Keep lean (tools cap the combined size).",
  "sections": [
    {
      "id": "workflow",
      "title": "Workflow",
      "rules": [
        "Explore -> plan -> code -> verify. For multi-file or unfamiliar changes, plan first; skip planning for one-line fixes.",
        "Never call work done without a check you can run: tests, build exit code, lint, or a diff against expected. Show the command + output, don't just assert success.",
        "Fix root causes, not symptoms. Never suppress an error to make a check pass."
      ]
    },
    {
      "id": "substrate",
      "title": "Cognitive substrate (run before acting)",
      "rules": [
        "Before ambiguous, expensive, multi-file, or mutating work, run `forge substrate \"<task>\" --json` (or call the MCP tool `substrate_check`). In Claude Code this fires automatically on each prompt; in other tools invoke it yourself.",
        "If it returns `okToProceed:false`, ask the returned `assumption.questions` before editing — do not guess an under-specified task.",
        "Start at the recommended `route.tier` (cheapest capable model); escalate only after an external verifier fails, never preemptively.",
        "Read `impact.impactedFiles` (predicted blast radius) before editing a named symbol/file, and split `scope.clusters` of independent work into separate sessions.",
        "Treat `memory.advisory` and minimality warnings as advisory; tests, graph membership, and human corrections always override the model.",
        "Run `verification.checklist` and show the output before claiming done."
      ]
    },
    {
      "id": "end-to-end",
      "title": "End-to-end completeness",
      "rules": [
        "A change is DONE only when code, tests, docs, and session state moved together: run `forge docs sync` to sweep the diff for stale doc mentions, and `forge handoff \"<done>\" --next \"<next>\"` before stopping. A Stop gate enforces this floor — code moved with nothing following blocks once, with the repair checklist.",
        "Never assume silently: answer preflight's clarifying questions, or proceed knowing the assumption is RECORDED to the session log and resurfaces in the handoff — verify it before claiming done.",
        "Record non-obvious choices with `forge decide \"<decision> — <reason>\"`; read `.forge/decisions.md` (or bare `forge decide`) before re-deciding anything a past session settled."
      ]
    },
    {
      "id": "reuse",
      "title": "Reuse & dependencies",
      "rules": [
        "Reuse an existing util/component/pattern before writing new; the smallest change that fits wins.",
        "Before adding a dependency, verify the current best option from live sources (docs, GitHub health) — prefer what the project already uses.",
        "Only build from scratch when reuse genuinely doesn't fit, and say why."
      ]
    },
    {
      "id": "code",
      "title": "Code style",
      "rules": [
        "Match the surrounding file's conventions over any personal default.",
        "Comment the non-obvious \"why\", never restate the \"what\".",
        "Guard array/object access; wrap fallible async in try/catch; handle errors explicitly (no empty catch).",
        "Keep functions small and single-purpose; separate pure logic from I/O so it's testable."
      ]
    },
    {
      "id": "testing",
      "title": "Testing",
      "rules": [
        "Write tests with the code. For a bug fix, write the failing test first, then fix.",
        "Cover the edge cases the task names: empty, error, boundary. Prefer real inputs over heavy mocking.",
        "Run the suite + typecheck + lint and show the output before claiming done."
      ]
    },
    {
      "id": "security",
      "title": "Security",
      "rules": [
        "Never write secrets, tokens, or keys into code or commits. `.env*` and key files are guard-protected — don't work around it.",
        "Validate and sanitize input at trust boundaries; use parameterized queries, never string-concatenated SQL.",
        "Check paths for traversal before file operations; prefer HTTPS for external requests."
      ]
    },
    {
      "id": "production",
      "title": "Production standards (2026)",
      "rules": [
        "Validate at trust boundaries with a schema (e.g. Zod): parse untrusted input (API, env, file, LLM output) into typed values before use — never trust it raw.",
        "Keep business logic in use-cases/domain, not controllers; hide the DB/ORM behind a repository interface; return DTOs, never raw DB models.",
        "Check ownership/authorization on every object access (OWASP API #1 — never trust a user-supplied ID); paginate every list; make retried mutations idempotent.",
        "Use a typed error model: typed codes, safe public messages, internal detail logged with a requestId. Never swallow errors or leak stack traces to clients.",
        "Emit structured logs (level, message, requestId, service, durationMs); for services add metrics/traces (OpenTelemetry) and track error rate, p95 latency, and AI token cost.",
        "Treat AI/LLM output as untrusted (OWASP LLM Top 10): verify it, never execute it directly, never put secrets/PII in prompts, give agent tools least privilege + human approval for destructive actions.",
        "Prefer boring, typed, maintained tech; contract-first APIs (OpenAPI 3.1) with a new version for every breaking change; don't over-pattern simple code."
      ]
    },
    {
      "id": "git",
      "title": "Git",
      "rules": [
        "Conventional commits: `type(scope): description` (feat, fix, refactor, docs, test, chore, perf).",
        "Stage specific files, not `git add .`. Never force-push shared branches.",
        "Ask before: push, commit, PR merge, history rewrite, `rm -rf`, dropping DB tables, or touching production."
      ]
    },
    {
      "id": "ui",
      "title": "UI",
      "rules": [
        "Build and check mobile AND desktop. Include clear loading/empty/error states; avoid layout shift.",
        "Follow DESIGN.md if present; keep one visual direction per project."
      ]
    },
    {
      "id": "ai-ux",
      "title": "AI interfaces & design quality",
      "rules": [
        "Commit to an aesthetic before coding; avoid AI-slop defaults (Inter/Roboto/Arial/system fonts, purple-gradient-on-white, generic card grids). Pick 2–3 typefaces and a 4–6 color palette with semantic roles.",
        "Meet WCAG: body text ≥4.5:1 contrast (large/UI ≥3:1), visible :focus-visible on every interactive element, tap targets ≥24×24px, alt text + form labels, and wrap animations ≥200ms in prefers-reduced-motion.",
        "Empty states are never dead ends: show a plain-language message + a clear next step. Error messages name the field, explain the problem, and suggest a fix — never 'Something went wrong'.",
        "For AI-driven UIs: show model confidence/uncertainty, make chain-of-thought and tool actions visible, give live preview/feedback over blind prompting, and provide fallback paths when the model fails.",
        "Pick the interaction pattern deliberately — a co-editing canvas or inline controls beat a wall-of-text chatbot when the user is steering structured output.",
        "When AI audits a UI, only ASSERT the deterministic (contrast math, missing focus ring/alt/label) — keep hierarchy/taste/pattern-fit advisory so the audit doesn't hallucinate false positives."
      ]
    }
  ]
}