r/ reins
architecture & memory for coding agents

For Vite + React and Next teams · Node 22+

Hold the reins of your coding agents.

Agents write code fast, then forget. They violate your architecture one import at a time, and re-read your codebase from scratch every session. reins makes both problems a check.

  • ✓Architecture becomes a check — runs on every commit and PR, whatever agent wrote the code. When something breaks a rule, the commit is blocked with the reason and the fix, so the agent corrects it before you even review.
  • ✓Each module gets a short note — what it does, how it works, its decisions and traps. It reaches the agent when it opens a file of that module, and the task's notebook comes back on its own after a compaction.
npm install -D @agentreins/cli @agentreins/adapter-js

Works with Claude Code, Codex, Cursor, or any agent · plain markdown · no telemetry

git hook · commit blockedreins check
FIG. 00 · WHAT A BROKEN RULE LOOKS LIKE — SAME CHECK LOCALLY AND IN CI

01 · The difference

Without reins, the review is the safety net. With reins, the check is.

Every row is a failure mode of agent-driven development — and what changes when the rules leave the prompt and live in a tool.

Without reins
  • ✕A shared component imports from a feature. Someone spots it in review — or nobody does.
  • ✕A week later, the agent reads a whole module again to find out what it does and why.
  • ✕A long conversation gets compacted and the task's decisions are lost.
  • ✕Architecture rules live in a long prompt the agent skims.
  • ✕"Review the whole project" every few weeks, from scratch.
  • ✕Adopting rules means fixing all the old debt first.
With reins
  • ✓The commit is blocked; the agent reads the fix and corrects it.
  • ✓Its note — purpose, map, decisions with their why, traps — reaches the agent as soon as it opens the module.
  • ✓The notebook and the notes of the files in play come back right after the compaction.
  • ✓They live in architecture.yml, checked by a tool. The prompt stays at 30 lines.
  • ✓Findings stay in a backlog; the next audit rechecks them.
  • ✓Old debt is frozen in a baseline and can only shrink.

02 · The check

The core never opens your files. It checks the edges.

A language adapter turns the repo into a list of import edges; the core applies the rules declared in architecture.yml to that list. Deterministic, identical locally and in CI, whatever agent or model wrote the code.

your repoevery commit and pull request
adapter-jsturns the code into a list of import edges
architecture.ymllayers, domains, rules, exceptions
findingrule, reason and fix — as text or JSON
blockedthe hook fails fast; CI + branch protection is the real guarantee
Findings — pick a rule
Dependency diagram of the selected finding Diagram showing the import that breaks the selected rule, in red, next to the allowed direction, in green.
RuleWhat it prevents
layer-directionLayers importing from layers above — a component reaching into a feature.
domain-boundaryImporting a domain's internals instead of its public API.
no-cyclesModules importing each other in a loop.
next-server-clientoptional'use client' components importing server-only modules.
integritywarn by defaultA PR that changes architecture.yml or grows baseline.json instead of fixing the violation. Set it to error to make it block.
baseline.json

Adopt on an existing repo without a big-bang fix. reins init freezes today's violations in a baseline: start green, and from then on reins check fails only on new violations. The baseline can only shrink.

Agents pass through the reins check gate on the way to main An agent carrying a violation is blocked at the reins check gate, reads the reason and the fix, comes back with the code corrected and reaches main; a second agent with a clean commit passes straight through. Whatever agent wrote the code, it passes the same check. feature branch push · PR ✕ blocked reins check · hook + CI Why: features is above components. Fix: move it down, or invert the dependency. main ✕ layer-direction agent ✓ clean commit agent
FIG. 04 · THE GATE — WHATEVER AGENT WROTE THE CODE, IT PASSES THE SAME CHECK. THE HOOK FAILS FAST; CI AND BRANCH PROTECTION ARE THE REAL GUARANTEE.

03 · Context between sessions

Memory as plain markdown, not a service.

Two kinds of memory live in .reins/, both readable, versionable and optional. Notes are committed; the notebook stays local to the branch.

The note of the opened module is delivered to the agent Three modules have one note each. When the agent opens a file of the cart module, the PreToolUse hook delivers cart.md and only that one; when it opens a billing file, the cart note is detached and billing.md arrives. After a compaction, the notebook and the module notes come back, so the task continues where it stopped. .reins/notes/ · one note per module cart.md billing.md search.md your repo PreToolUse hook features/cart/ cartStore.js features/billing/ total.js features/search/ results.js notebook.md ✓ returns the conversation cart.md ✓ in context agent the agent is about to open a file claude code: PreToolUse hook · others: AGENTS.md index
FIG. 05 · ONE FILE IN, ONE NOTE OUT — AND AFTER A COMPACTION, THE NOTEBOOK AND THE NOTES COME BACK.
.reins/notes/billing.mdin git · lasts as long as the module

Purpose

What the module does for whom, in one or two lines.

Map

Public API and key files.

How it works

The main data flow, in a few lines.

Decisions

Why choices were made, with dates — stops the agent "fixing" intentionally designed code.

Traps

What looks wrong but is intentional.

.reins/progress/<branch>.mdlocal · lasts as long as the task

Goal

What this branch is trying to land.

Done criteria

How you know it is finished; the agent checks them off one by one.

Subtasks

What is finished and what is next.

Next step

Where the work stopped, so the next session starts there.

Returns after compaction

The notebook and the notes of the files in play come back after a compaction.

STEP 1Agent opens a fileAGENTS.md points the path to its module note; the note arrives with the file.
STEP 2Session grows longOld turns get compacted; raw history is lost.
STEP 3Notebook returnsGoal, criteria and next step re-enter the context, plus the notes of the files in play.
STEP 4Work continuesThe agent starts from existing knowledge instead of rediscovering it.

04 · The core idea

Everything falls on one side of a line: enforced or instructed.

What a machine refuses to let through, and what it hands the agent as guidance. Both matter; only one of them can't be ignored.

Enforced by a machine
  • ▸reins check in the git hook and CI
  • ▸baseline.json — existing violations frozen
  • ▸Integrity of architecture.yml, baseline.json and generated files
  • ▸Branch protection: PR with human approval + CI green
  • ▸Claude Code permissions denying git commit / push (a first line of defense)
Guidance for the agent
  • ▸Announcing the task level (triage)
  • ▸Progress notebook
  • ▸Module notes, policies, skills, agents
  • ▸Audit backlog
  • ▸Multi-agent rules

05 · Skills for your agent

Commands installed by reins install.

In Claude Code, type them directly or ask in your own words. Other agents read the same instructions in .reins/skills/.

SkillWhat it doesWhen to use
/reins-doneCloses a task: runs the checks, updates the notebook and the notes of the modules it touched, says what was and wasn't verifiedWhen a task is done
/reins-backlogShows what is pending in the backlog, proposes what to do next"What's pending?"
/reins-notesReads each module and fills in its note, writing only what it can back up; the rest become - ? question lines for youAfter init or notes new
/reins-notes reviewChecks notes against the code and fixes what is no longer trueEvery few weeks, or when doctor flags notes
/reins-archReviews architecture.yml against the code and proposes changes with evidence. Applies nothing until you approve each oneAfter init, and every few months
/reins-auditLooks for new improvements and adds only new findings to the backlog"Review the whole project"
/reins-agentCreates a new subagent in .reins/agents/ (read-only by default)New needs: a tester, an a11y checker...

06 · Status

Stable core, honest edges.

The enforcement core is stable. Agent-assisted workflows are documented as experimental — verify current behavior in the repository before relying on it in production CI.

Stable

  • reins check
  • reins init
  • adapter-js
  • next-server-client (optional)
  • git hook + CI

The deterministic core: rules, findings, baseline.

Experimental

  • reins install
  • reins sync
  • notes management
  • reins doctor
  • audit / progress / review
  • skill templates

reins doctor sits in the middle: it warns locally about agent-written artifacts but never blocks and never runs in CI. Current status: docs/STATUS.md ↗

07 · Quick start

Green on the first commit, from the root of your project.

Node 22 or newer. Four commands, and only new violations can fail.

01
npm install -D @agentreins/cli @agentreins/adapter-js

Add the CLI and the JS/TS language adapter as dev dependencies (pnpm: pnpm add -D).

02
npx reins install

Sets up the git hook, the CI job, AGENTS.md and .claude/. Additive and idempotent: it never overwrites your files, and never installs packages.

03
npx reins init

Drafts the architecture plan, the baseline and the module notes. Review them: in Claude Code type /reins-arch (the agent proposes changes with evidence, you approve each one); otherwise read .reins/init-report.md and edit .reins/architecture.yml yourself. Then /reins-notes — or ask your agent to fill in the notes' TODO lines.

04
npx reins check --update-baseline

Freezes today's violations. From now on, npx reins check fails only on new ones. Commit everything and make the "reins" job required in branch protection.

Updating later: bump both packages, then run npx reins sync, npx reins doctor, npx reins check and npx reins notes stale to review out-of-date notes. Nothing is overwritten: install and init only add files or ask first.

Ready to try it?

Start with the README. Pilot it on a branch. Keep the final call yours.

Explore reins on GitHub ↗