dot-claude-iff

What agent work usually does — and what this makes it do

Six failure modes, each replaced by a mechanism rather than a reminder.

• forgets

  remembers

  journal + pointer

• works unseen

  shows itself

  live console

• asks badly

  asks with context

  needs-human queue

• rots

  regenerates

  one ritual

• repeats mistakes

  evolves

  lessons + retro

• locks you in

  adopts anywhere

  merge, never overwrite

The loop

You and Claude Code talk; hooks record every event into a local record; tools project the record onto the console; the console hands your answers back with full context attached.

What’s inside

Runs on bash, python3 and git. Installs nothing, imports nothing, sends nothing.

5 hooks

heartbeat each turn, resume block at session start, event capture, a policy gate on writes, JSON validation on writes

7 tools

continuity, observation, system map, console build, ritual runner, distribution — bash + python3 stdlib, zero pip packages

console

one HTML page + a tiny server on 127.0.0.1; reads only, buttons emit commands for you to paste

3 agents

anatomist (keeps the map true), retro-analyst (evolution proposals), verifier (claim checking) — run inside Claude Code

Privacy, plainly: the hooks and tools make zero network calls — no telemetry, no update check, no CDN. Raw captured events live in a sibling folder outside the repo, so a git push structurally cannot publish a prompt, a file body, or a secret. Don’t trust it — grep it: the tour hands you the verification commands and a risk map of every file location.

The six decisions it is built on

1. 1

   Communication carries context, both ways. The agent cannot open a question without stating what is going on and what to do. The console renders each one with a copy-context button, so your two-word answer lands with the full situation attached.

2. 2

   Memory is managed, not accumulated. An append-only journal is the single source of truth. Decisions land in a log, mistakes become lessons with prevention rules, and a resume pointer is written to disk before risky work.

3. 3

   Progress beats like a pulse. A heartbeat marks every turn, hooks capture every event, and token usage is counted per model. Verbatim history lives in a sibling folder outside the repo, so git push structurally cannot leak it.

4. 4

   One command stops, publishes, learns, and evolves. /project-memory runs check → polish → publish → evolve under one transaction. It proposes at most three evidence-backed changes, which land only with your approval.

5. 5

   The system explains itself. Every component has a card with curated relations, compiled into a clickable map. An anatomist agent keeps the cards true; a lint fails the ritual on a wrong edge.

6. 6

   Adoption is a merge, never a takeover. The fresh zip seeds a new repo; the adopt kit installs into an existing one. A pre-existing .claude/ is the designed case — every conflict is reported and your version wins by default.

Adopt it in one paste

Paste this to Claude Code (or any capable coding agent) inside the repo you want it in. An existing .claude/ is the designed case — it merges, never overwrites.

Clone https://github.com/Sdamirsa/dot-claude-iff to a sibling folder outside this repo, then
adopt its system into this repo by following the cloned repo's .claude/skills/adopt/SKILL.md
end to end. This repo may already have a .claude directory: merge, never overwrite, and report
every conflict to me before deciding.

Prefer a download? The latest release ships a fresh-start zip and an adopt-kit zip. The Partner Guide covers your half of the collaboration: five learnable habits.