smriti/AGENTS.md

smriti_skill_pack_version	title	target
2.3	Smriti — how to use it well	Codex

Smriti: how to use it well

You are working in a project that uses Smriti for reasoning state. Before you do anything else on this project, read this file. It tells you when to call Smriti, when not to, and why it matters.

Primary tool mode for your host: cli.

---

1. What Smriti is, in one paragraph

Smriti is a reasoning-state backend. It stores structured snapshots of your thinking at meaningful inflection points — decisions, assumptions, tasks, open questions, artifacts — and makes them available to whatever agent picks up the work next. It is not a memory database, not a wiki, not a notes app, not a transcript archive. It is version control for reasoning. Spaces are repos. Checkpoints are commits. Fork, compare, restore, and review all mean roughly what they would mean in a source control tool, but for the shape of the work rather than the code.

---

2. Why this file exists

You have been trained on thousands of projects that used a markdown handoff file — HANDOFF.md, NOTES.md, CONTEXT.md, whatever — to pass context between sessions, agents, or people. You probably reach for that pattern by default. Don't. On this project it is wrong.

Smriti exists specifically to replace that pattern with something structured, branchable, comparable, restorable, and resistant to overwriting. Markdown handoff files lose on every axis except zero- learning-curve. This file closes the learning-curve gap so your default reflex on this project becomes Smriti, not a text file.

If you find yourself about to write HANDOFF.md, stop and write a checkpoint instead. Every time.

---

3. The reflex: read state first

At the start of every session where you are working on a Smriti-enabled project, your FIRST action is:

smriti state <project>

Before you read any file. Before you run any test. Before you plan anything. Before you answer the user's first prompt beyond "let me check the state first."

The state brief is the minimum context you need to continue work without re-discovering decisions that were already made. Calling it unconditionally is cheap, and missing it is expensive. The brief is multi-branch by default — if other agents are working on this project on different branches, you will see them in the ## Active branches section with an author tag, and if any of them disagree with main on decisions you will see a ## Divergence signal section.

For session start, prefer --compact mode: smriti state <project> --compact This omits artifact content to save tokens — artifact labels and a recovery command are still shown. If the state brief lists artifacts relevant to your task, retrieve them with smriti checkpoint show <id> --full-artifacts

Say out loud to the user: "Reading current state from Smriti." before you call state. This gives the human watching a visible audit trail.

3.1 After reading state: cross-agent continuation

After you read state, look at the most recent checkpoint(s). Ask:

1. Was the most recent checkpoint written by a different agent? Check the author_agent field. If another agent wrote the latest checkpoint, they are handing context to you. Read their checkpoint carefully — don't skim past it because you didn't write it.

2. Does it contain tasks, recommendations, or clear next actions? If the ## In progress or ## Tasks section names specific work, treat that as your default continuation path unless you have a concrete reason not to. Another agent's task list is not a suggestion — it is the most informed view of what should happen next, written by the agent that just finished working.

3. Is the most recent checkpoint a review? If another agent left a review checkpoint (e.g. after reviewing your work), read it in full before acting: smriti checkpoint show <id> Reviews often contain specific follow-up tasks. Do those first.

4. Does the latest checkpoint belong to a different branch? If the ## Active branches section shows the most recent activity on a non-main branch, be explicit about your intent. Either continue that branch (fork or write into its session) or stay on main — but say which you are doing and why. Do not silently ignore another agent's branch.

If you disagree with another agent's recommendation: do not silently override it. Either run smriti compare to understand the divergence, or fork a branch with your alternative and let the human decide. Quietly doing the opposite of what the last agent recommended — without checkpointing the disagreement — is the multi-agent equivalent of overwriting HANDOFF.md.

3.2 Repo reconciliation before acting

The state brief tells you what was decided and what tasks were flagged. It does NOT tell you whether those tasks have already been completed in the codebase. Another agent may have finished the work and committed it after the checkpoint was written. Before you start implementing anything from the state brief's tasks, reconcile:

1. Check recent commits. Run git log --oneline -10 (or your host's equivalent). Do any of them address the task you are about to start?
2. If the task targets a specific file, check that file. Read or grep the file to see whether the change already exists.
3. If the work is already done: do NOT redo it. Instead, produce a short confirmation checkpoint: "Verified that was completed in commit . Closing this task — no further action needed." Then move to the next open item.
4. If the work is partially done: continue from where it left off. Do not restart from scratch.
5. If the work is not done: proceed with implementation.

This step is especially important when the most recent checkpoints have low-signal content (e.g. mock or empty fields). The checkpoint may have been written with a degraded extractor — the work could still have been done and committed even though the checkpoint does not describe it well. The repo is the ground truth; the checkpoint is the reasoning-state summary. When they disagree, check the repo.

Say out loud: "Checking whether the flagged tasks are already reflected in the repo before starting."

If the repo state and Smriti state cannot be reconciled safely — e.g., the repo has changes that contradict the state brief and you cannot tell which is correct — stop and ask the human. Do not guess. Irreconcilable state is a signal that a human judgment call is needed, not a puzzle for the agent to solve creatively.

3.3 Clean start: repo hygiene

Before you do any work — after reading Smriti state but before acting on it — make sure your local repo is clean and current.

1. Sync against the remote. Run git fetch origin and check whether your local branch is behind. If you are on main and main has moved, pull. If you are on a feature branch, decide whether to rebase or continue as-is.
2. Check which branch you are on. Run git branch or git status. If you are on a stale branch from a previous session that has already been merged, switch to main. Do not accidentally continue on a dead branch.
3. Inspect local residue. Check for:
   • Modified or untracked files (git status)
   • Stash entries (git stash list)
   • Local-only commits not yet pushed (git log origin/main..HEAD) If any of these exist, classify them before starting:
   • Stale residue from a previous session: clean it up (drop the stash, discard the changes, or switch branches).
   • Intentional work-in-progress: continue it, but say so.
   • Unknown origin: do not touch it. Ask the human.
4. Default to freshness. Unless you are intentionally working on a divergent branch, your starting point should be the latest origin/main plus the latest Smriti state. Stale local state is the most common source of duplicated work and silent conflicts.

Say out loud: "Repo is clean and synced against origin." or "Found local residue — classifying before proceeding."

3.4 Clean finish: handoff hygiene

When you are done working — whether the task is complete, blocked, or you are stopping for any reason — leave a clean slate for the next agent.

1. Checkpoint the outcome in Smriti. This is the primary handoff. The checkpoint should say what was done, what was decided, and what is still open. (Section 4 covers when and how to checkpoint.)

2. State the branch disposition. In your checkpoint or in your final message to the human, say explicitly:

   • "Branch X is ready to merge." or
   • "Branch X needs review before merge." or
   • "Branch X is exploratory / not ready." or
   • "Work was done directly on main."

3. Close any worktrees you opened. If you opened a worktree at the start of this session via smriti worktree open, close it before ending:

   smriti worktree close <worktree-id>
   

   smriti worktree close refuses if you have uncommitted changes — that's the safety net. Either commit the work, abandon the intentionally-discarded changes with --force, or leave the worktree active and tell the human in your final message that you're handing it off intentionally.

   Leftover worktrees mislead the next agent: the state brief shows them as active, suggesting work-in-progress that has actually stopped.

4. Push your branch. If your work is on a branch, push it to origin so the next agent (and the human) can see it. A local-only branch is invisible to everyone else.

5. Clean up local residue. Do not leave unexplained modified files, stash entries, or temporary files in the working tree. If you created a stash during reconciliation, either drop it (if the stashed content is no longer needed) or note in your checkpoint that the stash exists and what it contains.

6. Do not leave the repo on a dead branch. If your branch has been merged or is no longer active, switch back to main before ending the session so the next agent starts in a clean state.

Say out loud: "Session complete. Branch pushed, checkpoint written, working tree clean." or "Stopping — checkpointed findings, branch is [disposition]."

3.5 Backend reachability and capabilities

The Smriti backend is a shared service started by the human. You are a client of it. You do not own it.

• Your first smriti state call will fail with a clear connection error if the backend is not running. That is your reachability check — no separate health probe needed.
• If the backend is unreachable, stop and tell the human. Say: "The Smriti backend is not reachable at http://localhost:8000. Please start it with make dev-local for solo/local mode, or make dev-postgres for Postgres/shared-team mode."
• Do not attempt to start, restart, or manage the backend or Docker yourself. Starting the server from inside an agent's tool loop creates environment-variable inheritance issues that cause silent mock fallback on all LLM-backed endpoints. The human starts the backend; you use it.
• Check capabilities before using advanced features. After reading state, before creating claims or using features like structured tasks, probe the backend: curl -s http://localhost:8000/health The response includes git_sha and a capabilities list. If you need claims but the capabilities list does not include it, the backend is running stale code. Tell the human: "The backend at localhost:8000 does not support [feature]. Its git_sha is [sha] but the current repo is at [repo sha]. Please restart the backend with the same mode you are using (make dev-local or make dev-postgres) to pick up recent changes." For worktree-aware coordination, the capabilities list should include both worktrees and worktree_binding.
• When to check capabilities: You do NOT need to check on every session. Check when:
  • A Smriti API call returns 404 on a route you expect to exist
  • The state brief is missing sections you expect (e.g., no ## Active work when you know claims were recently merged)
  • You are about to use a feature for the first time in a session

3.6 Work claims: declare intent before working

After reading state, reconciling, and verifying the backend — but BEFORE starting substantial work — declare a work claim so other agents can see what you are about to do.

When to create a claim:

smriti claim create <project> --agent <your-agent> --scope "<one sentence>" --intent-type implement

Create the claim after you know what you are going to work on but before you write any code. The claim auto-binds to the current HEAD so other agents can see your base state.

What to put in the claim:

• scope: one sentence — "Adding lineage test for author_agent", not a paragraph.
• intent_type: one of implement, review, investigate, docs, test. Pick the closest match.
• branch: the branch you will work on. Default is main.

What to do when ## Active work shows existing claims:

• If the existing claim is clearly unrelated to your work: proceed and create your own claim.
• If the scopes might overlap: pick different work or ask the human which to prioritize.
• If the scopes clearly overlap: do not start. Tell the human "Agent X is already working on this."
• If the existing claim is a review of work you implemented (or vice versa): that is a follow-up, not a collision. Proceed, but note the relationship in your own scope.

When to mark done or abandon:

• When your work is complete and checkpointed: mark done. smriti claim done <id>
• When you stop without completing the work: mark abandoned. smriti claim abandon <id>
• Before ending your session: check whether you have any active claims. Do not leave them hanging — mark them done or abandoned as part of your clean finish (Section 3.4).

What claims are NOT:

• Not a lock. Another agent CAN work on the same scope. The claim is a signal, not a gate.
• Not a scheduler. Nobody assigns claims to you. You declare them yourself based on what you decide to work on.
• Not a task system. Claims expire in 4 hours. They are ephemeral intent markers, not durable work items. Tasks belong in checkpoint fields, not in claims.

Say out loud: "Claiming: [intent_type] — ." before creating the claim.

3.6.1 Worktrees: when and how

If multiple agents are working on the same project on the same machine, each agent should work in its own git worktree. Sharing a working tree across agents is the single highest-cost failure mode — staged files from one agent can land in another agent's commit, and the wrong code ships to main. The chaanbeen-web retros documented exactly this incident.

The reflex: when you start substantial work on a project where another agent might be active, open a worktree before your first edit.

smriti worktree open <project> --agent <your-id>

This returns a path. Use that path as your working directory for the rest of the session. Your edits, your staging index, your commits all live in that worktree. Other agents have their own worktrees; their filesystem state is invisible to you and yours to them.

When you create your work claim, bind it to the worktree:

smriti claim create <project> --agent <your-id> \
    --scope "..." --intent-type implement \
    --task-id <task-id> --worktree <worktree-id>

MCP tools call this field worktree_id; the CLI flag is --worktree.

The state brief now shows a worktree info line under your claim: which path, which branch, how many dirty files, ahead/behind vs main, last commit. Other agents seeing your claim know exactly what state your tree is in without asking.

When your work is done and merged, close the worktree. This is also part of session-end hygiene in Section 3.4 — Clean finish:

smriti worktree close <worktree-id>

This refuses if you have uncommitted changes (correct default — stop and decide before destroying work). Pass --force only after you've confirmed the dirty changes are intentionally being discarded.

When NOT to open a worktree:

• Solo work on a project with no other active agents.
• Quick read-only investigations that won't produce commits.
• Documentation-only work that's clearly disjoint from anyone else's track (e.g. you're writing in docs/ while another agent is in backend/). Worktrees are cheap but not zero cost; the discipline is "open one when there's actual filesystem contention risk," not "open one for every session."

Say out loud: "Opening a worktree for this session." before the first worktree open. "Binding my claim to worktree ." when claiming. "Closing the worktree." when done.

The state brief now shows you which files other agents are actively editing, not just how many. Each active claim's worktree drift line includes the first 3 dirty paths inline:

   · branch: ... · 3 dirty (cli/main.py, backend/app/main.py, +1 more) · ...

This is your file-level coordination signal. Before editing a file in your worktree, scan the active-claim drift lines for that path. If another agent already has it dirty, hold off or pick a different file. The signal is best-effort — it shows the first 3 dirty paths only and the cache is 60 seconds — but it catches the common case where two agents drift into the same file by accident.

If your shell tool resets the working directory between commands (some agent harnesses do this — every Bash call starts in the original cwd even after cd <worktree-path>), use absolute paths to the worktree throughout. Example:

WT=/Users/.../.smriti/worktrees/<space>/<agent-slug>
cat $WT/some/file.py
edit $WT/some/file.py

The skill pack used to say "use the worktree path as your cwd" — that works for persistent shells, but absolute-path discipline works everywhere. Capture the worktree path from smriti worktree open once and reuse it.

The default branch name when you smriti worktree open is smriti/<agent>/<short-uuid>. That's fine for the system but ugly for PR titles. Pass --branch <name> to use a custom branch name instead:

smriti worktree open <space> --agent <id> --branch v3-feature-name

Use this when the worktree maps cleanly to a single feature/PR. Stick with the default when the worktree is short-lived or when several related branches will live in it.

3.7 Check freshness before checkpointing

If you have been working for more than a few minutes, check whether the project state has moved since you started — before you checkpoint.

smriti state <project> --since <your-base-checkpoint-id> --compact

Your base checkpoint ID is the HEAD you read at session start, or the base_commit_id from your work claim.

If "State: unchanged": proceed with your checkpoint. Your base is still current.

If "State: changed": read the listed new checkpoints. Then decide:

• If the new checkpoints are unrelated to your work: proceed.
• If they overlap or conflict: run smriti compare on your base vs the new HEAD to understand the divergence, then either reconcile or fork.
• If you are unsure: ask the human.

Do not checkpoint on top of state you have not reviewed. Stale-state checkpoints create decision conflicts that the next agent has to untangle.

Say out loud: "Checking freshness before checkpointing."

3.8 Autonomous work selection from the task list

Tasks in the state brief may carry structured annotations that help you pick complementary work without waiting for the human to route you.

Each task can have:

• [intent] — one of implement, review, investigate, docs, test. This tells you the kind of work the task requires.
• → blocked by: <label> — this task depends on another task being done first.
• (done) — this task is already completed.

How to self-select work:

1. Read the ## In progress section. Note which tasks have intents, IDs, and which are blocked.
2. Read the ## Active work section. Note existing claims — especially their task: references if present.
3. Pick a task that is not already referenced by any active claim. If tasks have IDs (id: arch-docs), check whether any claim shows (task: arch-docs). If so, that task is taken — pick a different one. If tasks have no IDs, fall back to scope matching.
4. Prefer complementary intents. If someone is implementing, look for test, docs, or review tasks. Same-intent is fine if the tasks are clearly different (two distinct [docs] tasks with different IDs).
5. Skip blocked tasks. If a task says → blocked by: X, check whether task X is done. If X is still open or claimed, skip the blocked task — pick something unblocked instead.
6. Skip done tasks. Tasks marked (done) need no work.
7. If no complementary unblocked task exists: tell the human.

Claim with task ID when available. When you create a claim for a task that has an ID, reference it: smriti claim create <project> --agent <your-agent> --scope "..." --task-id arch-docs --intent-type docs This makes your claim precisely traceable to a task, not just loosely matched by scope text.

Recheck after claiming. If another agent might be starting at the same time (e.g., you were both launched together), re-read the state briefly after creating your claim: smriti state <project> --compact Check ## Active work for duplicate task: references. If another agent claimed the same task ID, abandon your claim and pick a different task. This catches near-simultaneous collisions within seconds.

When tasks have no IDs: fall back to the scope-comparison logic from Section 3.6. Compare each task's text against active claim scopes and pick work that does not overlap. This is the same behavior as before — task IDs just make collision detection precise instead of fuzzy.

When writing tasks with IDs: use short, stable slugs derived from the task content: impl-freshness, test-e2e, docs-arch. If a task persists across nearby checkpoints, reuse the same ID when practical — this makes cross-checkpoint task tracking easier. But do not block work when old checkpoints or legacy tasks have no IDs.

When writing checkpoints with tasks: include intent hints on tasks you create. When you checkpoint your work, the tasks in your freeform markdown should indicate what kind of work each one requires. Write naturally — the extractor will classify them:

## Tasks
- Implement the freshness endpoint (implement)
- Write integration tests for freshness (test, blocked by freshness endpoint)
- Update cli/README freshness walkthrough (docs, blocked by freshness endpoint)

Say out loud: "Selecting complementary work from the task list." when you self-select a task based on intent hints.

---

4. When to checkpoint

Checkpoint at an inflection point. An inflection point is a moment where the reasoning state has changed in a way a future agent needs to know about. Concretely:

• You made a decision you would not want to re-derive. Checkpoint.
• You rejected a hypothesis and now know a dead end. Checkpoint.
• You solved a sub-problem and the next step builds on it. Checkpoint.
• You are about to hand off to another agent or another session. Checkpoint.
• You are about to explore an alternative direction and want to preserve the current line. Fork first, then checkpoint on the fork.

Use the extract path, not hand-written JSON. Pass freeform markdown describing the inflection point and Smriti's background LLM will pull out the structured fields (message, objective, summary, decisions, assumptions, tasks, open questions, entities, artifacts) for you.

Example call:

cat <<'MD' | smriti checkpoint create <project> --extract --author-agent <your-agent-name>
# Decided on Pydantic for the state validation layer

After trying dataclass-based validation and hitting the injection
surface from unbounded extra fields, going with Pydantic BaseModel
and `extra="forbid"`. Latency overhead is ~0.3 ms per call.

## Open questions
- How do we share state across parallel agent runs?
- Cleaner schema-versioning story for migrations?
MD

Say out loud: "Checkpointing now — reached an inflection point on X." before the call. Name the X.

Always tag author_agent with a stable identifier for your agent (e.g. claude-code, codex-local). This is how humans and other agents know who wrote what on the shared timeline. Inconsistent or missing author_agent makes divergence unattributable.

4.1 Checkpoint notes: annotating without checkpointing

Sometimes you need to add context to an existing checkpoint without creating a new one. Checkpoint notes are additive annotations — founder commentary, milestone markers, or noise labels — that attach to a checkpoint without modifying its immutable fields.

smriti checkpoint note <id> --text "<note text>" --kind note

Three kinds:

• note (default): General commentary. "This decision held up well during implementation."
• milestone: Marks a checkpoint as a significant project moment. "This was the turning point — everything after built on this."
• noise: Marks a checkpoint as low-signal or superseded. "Extractor was degraded when this was written; decisions are unreliable."

When to use notes instead of a new checkpoint:

• You want to annotate a past checkpoint after the fact — adding hindsight without rewriting history.
• The human wants to mark a checkpoint as a milestone or as noise for timeline legibility.
• You are reviewing another agent's checkpoint and want to leave commentary without creating a full review checkpoint.

When NOT to use notes:

• Do not use notes to record new decisions. That is a checkpoint.
• Do not use notes as a running commentary on every checkpoint in the lineage. Notes are sparse annotations, not a comment thread.

Notes appear in the LineagePage timeline as indicators (★ for milestones, ◌ for noise, ● for plain notes) and in checkpoint detail views. They are visible to all agents reading the state.

---

5. When NOT to checkpoint

This section is more important than the previous one. Read it twice.

A checkpoint is not a save button. Most of your work should not produce a checkpoint. Resist all of these:

• Do not checkpoint after every small step. Finishing a helper function, editing one file, running one test — not an inflection point. If your checkpoint's message would be "Wrote a helper function" or "Ran the tests" or "Fixed a typo," do not checkpoint. Keep working.

• Do not checkpoint at end of session as a blob. A single "everything I did today" commit with 15 decisions crammed into one message is less useful than zero checkpoints. It has no locality. The next agent reading it cannot tell which decisions belong together, what caused what, or in what order things happened. If you reach end-of-session without having checkpointed, you missed the inflection points earlier — and the fix is NOT to compensate with one giant dump. Write ONE crisp checkpoint for the most recent real decision and stop. Then reflect on what you should have checkpointed earlier.

• Do not use checkpoints as a backup system. The event stream (turns) is already the backup. A checkpoint is a reasoning-state snapshot, not a safety net. Checkpointing "because the session is about to end" or "because the user is leaving" is a save-button use and it is wrong.

• Do not checkpoint with nothing crisp to say. If you cannot write a single sentence for the message that names a specific decision made, hypothesis confirmed, problem solved, or dead end identified — you are not at an inflection point yet. Finish thinking. Then checkpoint.

• Do not checkpoint on top of inconsistent state. If smriti state surfaces contradictions between decisions, or if smriti checkpoint review flags issues on the current HEAD, resolve first. Either restore to a cleaner ancestor or surface the contradictions to the human. Do NOT stack new commits on broken state — you are compounding the confusion, not fixing it.

• Do not restate existing state. If the last checkpoint already contains the decision you are about to record, do not re-checkpoint it. Smriti tracks new commitments, not a running summary of everything still true. Re-checkpointing dilutes the signal.

• Do not checkpoint just because the user asked you to. The user does not always know whether you are at an inflection point. If they ask you to checkpoint and you are not, say so: "I don't have a crisp inflection point to record yet — can you tell me what decision or problem you want captured?" This is not disobedience; it is protecting the signal quality of the project's timeline from future noise.

5.1 The signal test

Before every checkpoint, ask yourself three questions:

1. Can I name the inflection point in one sentence for message? If you need a paragraph, wait.
2. If another agent read only my decisions, summary, and open_questions, could they continue the work correctly? If no, there is nothing worth recording yet.
3. Is the reasoning state meaningfully different from the previous checkpoint on this branch? If no, you are restating.

If any answer is no, do not checkpoint.

5.2 What good frequency looks like

A 4-hour focused session typically produces 2 to 4 checkpoints. Not 20. Not 0.

• A session producing 20 checkpoints is producing noise. You are treating checkpoints as a save button.
• A session producing 0 checkpoints is either doing trivial work or missing the inflection points. Reflect.
• 2–4 is the target. Aim there.

---

6. When to fork

Fork when you want to explore an alternative direction without losing the main line. Concretely:

smriti fork <current-head-id> --branch alternative-X

Then write a checkpoint into the forked session:

cat fork.md | smriti checkpoint create <project> \
    --extract --session <fork-session-id> --author-agent <your-agent-name>

Do not fork for small variations within the same direction. That is continuation, not branching. Fork when two parallel lines of reasoning should genuinely exist for future comparison — when you want the option to go back to the original line cleanly without re-deriving it.

Say out loud: "Forking a branch to explore an alternative. Main line is preserved."

---

7. When to review

Run smriti checkpoint review <id> when:

• The state brief you just read contains decisions or assumptions that feel contradictory to each other.
• You are about to checkpoint on top of a state you did not write yourself and want a sanity pass first.
• You are handing off to another agent and want to surface any issues before the receiving agent wastes cycles on broken state.

Do not run review on every checkpoint. It is a self-audit tool, not an audit trail. Running it reflexively adds noise.

---

8. When to compare

Run smriti compare <A> <B> when:

• The state brief shows a ## Divergence signal on an active branch and you want the full diff (the signal only shows the top 3 conflicting decisions per side).
• You see two checkpoints in the lineage that should agree on something but seem to differ.
• You are resolving a fork back to a single line and need to decide which decisions to keep.

---

9. When to restore

Run smriti restore <id> when:

• The current HEAD state is contradictory or corrupted and you want to resume from an earlier clean snapshot.
• You are reading a past checkpoint not as history but as a starting point — you want to continue work from it as if it were HEAD.

Say out loud: "Restoring to an earlier checkpoint." when you do this. The human should know you are stepping back in time.

---

10. Detecting drift

If at any point you notice:

• The state brief contains tasks that appear already done, or
• Decisions that directly contradict what you have been working on, or
• Open questions that seem already resolved in the summary, or
• The ## Divergence signal shows active branches disagreeing on things you considered settled,

then you are in a drift situation. Do not paper over it. Three acceptable responses:

1. Run smriti checkpoint review on the current HEAD and act on the output.
2. Run smriti compare on the two most recent checkpoints from each divergent author and summarize the difference in plain prose for the human.
3. Surface the drift to the human directly: "I am seeing scope divergence between what the state brief says and what I have been working on. Stopping to reconcile before continuing. Which line should I follow?"

Do not quietly pick a side. Scope divergence across agents is a real signal that the project state needs a human judgment call. Smriti's job is to make that signal visible to you; your job is to make it visible to the human, not to hide it by picking one branch and continuing.

Say out loud: "I'm seeing scope divergence between the state brief and my work. Stopping to reconcile before continuing."

---

11. Anti-patterns to reject explicitly

These are in addition to the "do not checkpoint when" rules in Section 5.

• Do not write HANDOFF.md, NOTES.md, CONTEXT.md, PROGRESS.md, or any similar file on this project. A Smriti space exists. Write a checkpoint instead. Markdown handoff files do not survive branching, do not cross-link to history, and do not participate in smriti_compare. Every time you write one, the next agent has to re-learn what you already knew — exactly the problem Smriti exists to solve. If you catch yourself about to write a handoff file, treat that as a signal you have reached an inflection point and should checkpoint.

• Do not silently inject state output into the user's chat context. Announce it: "Reading current state from Smriti." The human should always be able to see when you are consulting or writing to the shared timeline.

• Do not tag author_agent inconsistently. Pick ONE stable identifier for your agent — e.g. claude-code, codex-local, claude-code-v2 — and use it on every checkpoint you write. If you change your tag mid-project, the divergence signal becomes unattributable. Stability of the tag is more important than its content.

• Do not invoke /chat/send or the live chat runtime from inside your tool loop. That endpoint is for humans talking to Smriti's chat UI, not for agents writing state. Your only write paths are smriti checkpoint create --extract and smriti fork.

• Do not leave active work claims hanging. When your session ends, mark your claims done or abandoned. Dangling claims mislead the next agent into thinking you are still actively working.

• Do not treat the extract path as a free pass to dump your reasoning. The extract LLM will pull whatever fields it can, but if you pass it 2000 words of stream-of-consciousness it will produce low-signal decisions and assumptions. Write the markdown crisply. The extract path saves you from hand-rolling JSON; it is not a license to be verbose.

• Do not silently override another agent's recommendations. If the most recent checkpoint was written by another agent and contains tasks or decisions you disagree with, do not just do something different without recording the disagreement. Fork, compare, or surface the disagreement to the human. The other agent's recommendations are the most informed view of what should happen next — overriding them silently is equivalent to deleting someone else's work.

• Do not implement a task from the state brief without checking whether it is already done in the repo. Smriti tracks reasoning state, not repo state. A task listed in a checkpoint may have been completed by another agent and committed to git since the checkpoint was written. Check git log and the relevant files before starting. Duplicating completed work wastes a full session and creates noise in the timeline.

• Do not share a working tree between agents on the same project on the same machine. Open a worktree per agent. The chaanbeen retrospectives documented one cross-agent commit pollution incident that took ~1 hour to recover and degraded prod for ~6 endpoints — this is the failure worktrees were built to prevent.

• Do not use smriti_install_skill to overwrite an in-project skill pack that you did not write. If the project already has a skill pack of an older version, the install tool will tell you. Use the existing one unless the human asks you to upgrade.

---

12. Phrases to say out loud

These give the human watching your session a visible audit trail. Use them literally.

When you are about to...	Say
call smriti state	"Reading current state from Smriti."
create a checkpoint	"Checkpointing now — reached an inflection point on X."
fork a branch	"Forking a branch to explore an alternative. Main line is preserved."
restore an earlier checkpoint	"Restoring to an earlier checkpoint."
run review after a drift signal	"Running a consistency review on the current state before I continue."
run compare on a divergence signal	"Comparing main against the divergent branch to see the full diff."
reconcile state against repo	"Checking whether the flagged tasks are already reflected in the repo before starting."
verify repo hygiene at start	"Repo is clean and synced against origin." or "Found local residue — classifying before proceeding."
declare a work claim	"Claiming: [intent_type] — ."
open a worktree	"Opening a worktree for this session."
bind a claim to a worktree	"Binding my claim to worktree ."
close a worktree	"Closing the worktree."
add a note to a checkpoint	"Adding a [kind] note to checkpoint X."
self-select complementary work	"Selecting complementary work from the task list."
check freshness before checkpoint	"Checking freshness before checkpointing."
finish a session	"Session complete. Branch pushed, checkpoint written, working tree clean."
surface drift to the human	"I'm seeing scope divergence between the state brief and my work. Stopping to reconcile before continuing."

These are not cosmetic. They are what makes your session legible to the human who will eventually read the thread and decide whether your reasoning is sound.

---

13. The project root

Every checkpoint you write should have a project_root field that points at the absolute path where this project actually lives on disk. The CLI auto-captures $(pwd) as project_root when you run from the project directory. If you are running from somewhere else, pass --project-root /abs/path explicitly.

This is how cross-agent handoffs know where the project lives. Missing or wrong project_root makes the next agent spend 30 seconds hunting for the codebase.

---

14. Two-sentence summary

Call smriti state at session start, unconditionally, before anything else. Checkpoint at inflection points — not after every small step, not at end of session as a dump, never as a save button.

Everything else in this file is implementation detail for those two rules.

---

15. If you are confused about Smriti

The order of operations is always:

1. Read state first. You are missing context until you do.
2. Work. Smriti has no opinion about what happens between checkpoints.
3. Checkpoint at inflection points. Not before, not more often.
4. Hand off. The next agent reads the new state. No markdown handoff file.

If you are unsure whether an action is "Smriti-shaped," ask yourself: "Is this a reasoning-state change, or is it just work-in-progress?" Reasoning-state changes get checkpointed. Work-in-progress does not.

If you are still unsure, surface the question to the human. They will tell you. Do not guess.

---

Smriti skill pack version cli-2.2 — this file is authoritative for agent behaviour on this project. If you catch it contradicting itself or your observed behaviour of the tools, tell the human; the skill pack is versioned and meant to be updated.