Agents

An agent that reads the notes first

The CLI enforces the mechanics. The process, which step comes next and how to do it well, lives in agent skills you can edit per project. A hook makes sure the agent sees the notes for a file before it touches it, whether or not a skill is loaded.

The skills

Seven skills ship in lore’s skills/ directory. Install them per project, or for every project with -g:

npx skills add apisandipas/lore

Each skill reads .lore/WORKFLOW.md first, so a project can change the flow, and ends with one line naming the next step:

Next: lore-build docs/efforts/due-dates.md (Add a due_date column to tasks, with a migration)

What you actually say

The agent does the writing. Your part is mostly answering questions and saying yes or no.

After the first message, it is mostly “go ahead”. In a fresh session, ask for lore-next.

Small work

A bug fix or a rename skips the flow: no spec, no effort, just lore context before each edit and lore check after. The Size section of .lore/WORKFLOW.md says where the line falls, and a project can move it.

The Claude Code hook

The skills tell the agent to run lore context before every edit. The hook makes it happen anyway. hooks/claude-code.sh runs on each file the agent reads or edits, and adds the notes that govern it to the agent’s context:

• Before the agent writes. It runs on Read as well as Edit and Write. Notes handed over at an edit arrive after the edit is made, so the agent writes the code once and then fixes it.
• Once per session. A note is shown again only if it changes, or after the conversation is compacted.
• Silent otherwise. Outside a repo with .lore/, or when lore or jq is missing, it does nothing.

Once per session

The hook calls lore context --session with the agent’s session id. The first read of a file gets its notes; the second gets nothing, because nothing is new:

lore context --session demo pkg/auth/session.ts
pkg/auth/session.ts: 3 notes

Rotating refresh tokens  (Decision, accepted)
  …
lore context --session demo pkg/auth/session.ts
(nothing: this session has seen all three)

The record of what a session has seen lives in the temp directory, not the repo. When Claude Code compacts the conversation, the hook runs --forget, and the agent is shown its notes again.

Install the hook

It needs lore and jq on PATH. In one project, so everyone who clones it gets the hook:

mkdir -p .claude/hooks
curl -fsSL https://raw.githubusercontent.com/apisandipas/lore/main/hooks/claude-code.sh -o .claude/hooks/lore-context.sh
chmod +x .claude/hooks/lore-context.sh

Then add this to .claude/settings.json, merging it with any hooks already there, and commit both files:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Read|Edit|MultiEdit|Write", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lore-context.sh" }] }
    ],
    "SessionStart": [
      { "matcher": "compact", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lore-context.sh" }] }
    ]
  }
}

For every repo you work in, put the script in ~/.claude/hooks/lore-context.sh and add the same hooks to ~/.claude/settings.json, with that path as the command. It stays silent in repos without .lore/.

Does it help?

We gave real Claude Code sessions a task in a repo whose only clue to a money rule is a decision anchored to the code, and checked whether the agent’s first edit followed it. Three runs of each setup:

Three runs is a small sample. test/agent/hook-trial.sh repeats the with-and-without comparison so you can run more, for example test/agent/hook-trial.sh 10; each run is a real session and costs about $0.20.