Dev Handbook — Index (MOC)

The map of content for the dev-handbook: the single knowledge monorepo for
all projects (0009-one-knowledge-monorepo). Open this folder as an Obsidian
vault and the [[wikilinks]] render as a navigable graph.

What lives where

  • Generic decisions (would hold for any project) → core/, by area:
    workflow/, backend/, frontend/, infra/.
  • Where the proven code lives → docs/private/reference-implementations.md: for each
    generic concern, the governing ADRs and the classes that implement them in each project.
    A lookup page, not a decision record, and unpublished, since it names private repos’
    internals; browse it in the repo or the Obsidian vault.
  • Project-scoped decisions → the project’s folder, e.g. docs/expenses/
    (start at its index.md). Project folders are private — they are not
    published on the rendered site; browse them in the repo / Obsidian vault.
  • Behavior / SOPs (skills, agents, hooks) → the kit/ plugins:
    handbook (generic, manifest-driven) + one per project (e.g. expenses).
  • Workspace manifest → handbook.json at each workspace root (canonical
    copies in manifests/); generic kit skills read it instead of hardcoding
    repo names.
  • Claude’s recall → the per-user memory store, which should point at these
    ADRs rather than restate them.

Promotion convention: decisions are born in a project folder and move to
core/ when they prove generic — git mv + a generalization pass; the project’s
specifics stay as illustrations. Wikilinks are filename-based, so moves don’t
break them.

Reading these — and skipping the right parts

Most ADRs carry an Example section: a collapsed callout holding real code from the
repos, with its path. It is closed by default and it is not normative.

  • Humans: open it when the rule is clear but the shape isn’t — “what does a value
    object actually look like”, “how does the header do mobile-first”. These exist because
    theory alone leaves a reader with no idea how Expenses is built.
  • Agents: skip them. The Decision section is the specification; the example is
    illustration, and reading every one wastes tokens you will need for the work. Open one
    deliberately — when porting a pattern into a new project, or when a reviewer disagrees
    about what the rule looks like in practice.

The code is copied from the repos rather than written for the document, so it can drift.
Treat the path as the source of truth and the snippet as a sighting of it.

Core ADRs

ADRTitleAreaStatus
0001-three-step-git-flowThree-step Git flow (feature → develop → main)workflowAccepted
0003-collaboration-working-agreementsCollaboration & git working agreementsworkflowAccepted
0004-version-keyed-changelogVersion-keyed changelog, written at release timeworkflowAccepted
0009-one-knowledge-monorepoOne knowledge monorepo, folders per project, promote to coreworkflowAccepted
0001-status-as-source-of-truthLifecycle status is an explicit enum, not derived at runtimebackendAccepted
0002-clean-architecture-and-use-casesClean Architecture with single-responsibility use casesbackendAccepted — amended 2026-09-10 (transactional web services, whitelisted sort input, a catch-all only for server faults; a write that must survive a refusal commits on its own)
0003-ddd-intent-methodsDomain entities own their invariants via intent-expressing methodsbackendAccepted — amended 2026-09-19 (a domain guard belongs where input cannot reach it)
0006-disambiguate-beans-by-concrete-typeDisambiguate Spring beans by concrete type, not field @QualifierbackendAccepted
0010-schema-changes-via-migrationsSchema changes only via versioned migrations; profile-gated dev seedsbackendAccepted — amended 2026-09-10 (the dev profile runs Flyway out of order)
0011-dto-design-rulesDTO design — complete top-level representations, slim embedded children; collections return summariesbackendAccepted — amended 2026-09-10 (collections return summaries)
0012-profile-switched-outbound-gatewaysProfile-switched outbound gateways — dev needs zero credentialsbackendAccepted — amended 2026-09-10 (required settings have no base-profile default; notifications are sent after commit, or through an outbox — Expenses since v1.80.0)
0013-value-objects-for-domain-primitivesValue objects for domain primitives — self-validating, with a converterbackendAccepted
0013-sessions-and-refresh-tokensSessions & refresh tokens — revocable auth, rotation, one door into “logged in”backendAccepted — promoted 2026-09-10 (from expenses/); amended 2026-10-11 (§7: only a refused refresh ends the session; anonymous auth calls never refresh)
0016-stable-pagination-tiebreakerEvery paginated query needs a unique sort tiebreakerbackendAccepted
0017-persistent-entity-baselinePersistent-entity & new-backend baseline — generated id, protected no-arg ctor, audit base, Lombok subsetbackendAccepted — amended 2026-09-10 (on Boot 4, the starter, not the library)
0018-resource-access-session-scoped-or-actor-declaredWho may touch a user’s resource — session-scoped or actor-declared, chosen at project startbackendAccepted
0019-llm-features-prompts-shape-code-enforcesLLM features — the prompt shapes the answer, code enforces the boundarybackendAccepted
0022-llm-changes-are-measured-on-a-held-out-evalLLM changes are measured — fixed scenarios, a held-out TEST set, a judge that sees the evidencebackendAccepted
0023-model-facing-data-is-a-catalogWhat a model reads is a catalog — one read tool, an index always present, rules computed by the domainbackendAccepted
0024-model-writes-are-proposals-the-user-confirmsA model never writes — it proposes, the server proves it, a person confirmsbackendAccepted
0025-prompt-cache-spend-every-breakpoint-most-stable-firstPrompt caching — most-stable-first, every breakpoint spent, byte-stable requestsbackendAccepted
0026-llm-usage-is-metered-in-money-pinned-to-a-reference-modelLLM usage is metered in money — credits pinned to a reference model’s pricebackendAccepted
0027-instructions-teach-a-method-and-checks-accept-correct-workInstructions teach a method, tools carry their rules, output checks accept correct workbackendAccepted
0028-calls-to-systems-we-do-not-ownCalls to systems we do not own — egress guard, signed and keyed, recorded before sentbackendAccepted
0029-a-models-tier-is-chosen-by-its-job-cheapest-firstA model’s tier is chosen by its job, cheapest first, moved up on evidencebackendAccepted
0002-i18n-both-localesEvery user-facing string lives in both localesfrontendAccepted
0006-frontends-are-mobile-firstFrontends are mobile-firstfrontendAccepted
0001-feature-vertical-slicesFeature vertical slices + folder-per-componentfrontendAccepted
0003-masked-inputs-for-formattable-valuesMasked inputs for every formattable valuefrontendAccepted
0004-component-state-hygiene-and-shared-form-logicComponent state hygiene & shared form logicfrontendAccepted — amended 2026-08-03 (unmount reused modals, don’t reset them)
0013-centralized-api-layer-and-server-stateCentralized API layer & server-state disciplinefrontendAccepted
0014-theme-tokens-not-hexSemantic theme tokens, not hex literalsfrontendAccepted
0015-design-system-as-single-visual-sourceThe design system is the only visual source — never hand-rollfrontendAccepted
0020-clients-disclose-nothing-the-privacy-policy-does-not-nameA client sends nothing the privacy policy does not name — self-hosted assets, image metadata stripped, unused permissions blockedfrontendAccepted
0021-failures-are-shown-not-guardedFailures are shown, not guarded — failed is a render state, boundaries catch render errors, one handler reports failed queriesfrontendAccepted
0007-rate-limiting-at-the-edgeRate limiting & abuse protection live at the edge, not in the appinfraAccepted — promoted 2026-09-10 (from expenses/); exception list updated 2026-10-11 (Expenses’ per-code limits)

The handbook’s own ADR sequence is global — next is 0028 regardless of
area. Backend 0001/0002/0003/0006/0013 (sessions), frontend 0001/0003/0004 and
infra 0007 kept their numbers when promoted from the expenses/ folders
(0009-one-knowledge-monorepo); project folders imported from code repos
likewise keep their original folder-scoped numbering. New decisions: copy
_adr-template.md, fill it in, add a row here (or in the project index).

Numbers therefore repeat across areas: core holds three 0013s (backend value
objects, backend sessions, frontend API layer). Wherever a bare number would be
ambiguous, cite the ADR by its slug.

Projects

Most workspaces live under the add-projects/ umbrella (AI Driven
Development), side by side with the single shared dev-handbook/ checkout.
A standalone workspace sits elsewhere and is its own repo root — it still
reads this handbook, via the handbook/projectDocs paths in its manifest:

ProjectDocs (private)PluginWorkspace
AllSensisdocs/allsensis/— (inherits core)add-projects/allsensis/
Expensesdocs/expenses/expensesadd-projects/expenses/
Barbershopdocs/barbershop/— (inherits core)add-projects/barbershop/
Ticketsdocs/tickets/— (inherits core)add-projects/tickets/
Dracomaniadocs/dracomania/— (inherits core)~/projects/dracomania/ (standalone)
Savebridge (working name)docs/savebridge/— (inherits core)add-projects/savebridge/
Game moddingdocs/game-modding/— (inherits core)~/Projects/mods/ (standalone; not yet git repos)
Agents (working name)docs/agents/— (inherits core)~/projects/whitelabel-agents/ (standalone)

The kit

Two plugins hosted by this repo’s marketplace (see the repo README.md for
install commands):

Plugin handbook (generic, namespace handbook:)

Skills:

SkillDoesEnforces
handbook:i18n-parityDiffs en.json vs pt.json across all apps in the workspace0002-i18n-both-locales
handbook:releaseGit-flow release: bump + CHANGELOG + tag (repos from handbook.json); for a repo whose manifest entry declares storeBuild, ends by starting that store build and handing over the link0001-three-step-git-flow, 0004-version-keyed-changelog
handbook:changelog-backfillBackfills a repo’s CHANGELOG from git tags0004-version-keyed-changelog
handbook:feature-kickoffRecap + branch off develop in each affected repo0001-three-step-git-flow, 0003-collaboration-working-agreements

Agents (independent reviewers, read-only; all read handbook.json + the
project’s docs for context): handbook:ask-dev, ask-ba, ask-designer,
ask-finance, ask-marketing, ask-mobile (enforces
0006-frontends-are-mobile-first), ask-legal. They challenge, they don’t create.

ask-legal is split from the curator on purpose — they ask opposite questions.
The curator asks “is what we wrote still true?” (authority: the codebase).
ask-legal asks “does what we shipped create a disclosure/consent
obligation we haven’t met?”
(authority: the live Terms of Use and Privacy Policy + the data the
code actually collects + the third parties it actually sends it to). An agent
tuned to code-fidelity reliably under-notices a new category of personal data.
It drafts clauses for human review; it never publishes legal text.

Maintainer (write-capable, no git): handbook:docs-curator — audits the ADR set

  • each repo’s CLAUDE.md for redundancy, wrong scope, drift, gaps and broken
    links, and drafts the fixes in place; commits stay with the human.

Hooks: a Stop hook runs i18n-parity after every turn — advisory (silent on
parity, warns on gaps, never blocks), self-enforcing 0002-i18n-both-locales.

Plugin expenses (project-specific, namespace expenses:)

SkillDoes
expenses:new-use-caseScaffold a backend use case (Clean Architecture + validation strategy)
expenses:new-pageScaffold a frontend vertical slice (i18n + mobile-first)

Maintainer (write-capable, no git): expenses:assistant-curator — owns the
model-facing surface, where docs-curator owns the human-facing one: the
ChatTool set and their descriptions, the CHAT_ASSISTANT system prompt (which
carries no tool routing since 2026-10-15), and the analysis sandbox schema. It exists
because ChatToolRegistry auto-discovers tools, so a new tool is callable the
moment it is written while the model only reaches it if its description says which
questions it answers — a capability can ship orphaned, as get_budget_status did in
v1.63.0. It drafts
the fixes in place; commits stay with the human.