CLAUDE.md · git:20261116.574db06 · 2026-11-16 · sha256 35148ae8367a3cb5

CLAUDE.md git:20261116.574db06A

Immutable. This exact content never changes and is served at /api/v1/blob/35148ae8367a3cb5.

# CLAUDE.md

This file records shared contributor guidance. Claude Code reads it directly;
Codex is pointed here by `AGENTS.md`.

## What this repo is

This repo **is a Claude Code and local Codex plugin** named `handoff`. It is not an application.
It ships a hook-driven **project-memory** system plus an owned **development
workflow layer** that other repos install. There is no build step and no
dependency tree — the deliverable is Python hook scripts (stdlib only), a skill
set, a template tree, and two read-only scripts: `scripts/handoff_lint.py` (run by
`setup`) and `scripts/context_inventory.py` (run by `context-audit`). CI (`.github/workflows/ci.yml`) runs the stdlib smoke
tests in `tests/test_hooks.py` on every push/PR.

The skill set (v1.2.0+): `setup` (scaffolding and drift lint), `context-audit`
(per-project plugin/MCP/skill budget, via `scripts/context_inventory.py`), `workflow` (the 6-phase,
risk-tiered pipeline — the constitution that owns sequencing), and thirteen
technique skills (`brief`, `plan`, `design`, `tdd`, `debug`, `architecture`,
`delegate`, `verify-done`, `security`, `browser-qa`, `ship`, `learn`,
`grill-me`) forked
from MIT-licensed superpowers, mattpocock-skills, gstack, and rampstack-skills
with all cross-pack orchestration stripped (see `ATTRIBUTION.md`). When editing
a technique skill, never reintroduce pack-style enforcement preambles or
cross-skill process handoffs — `workflow` alone decides sequencing and tiering.

Do not confuse the two layers:

- **The plugin** (`hooks/`, `skills/`, `.claude-plugin/`, `.codex-plugin/`) — what a developer
  installs into Claude Code or local Codex. Editing here changes behavior for every repo that uses it.
- **The `templates/` tree** — the *payload* the `setup` skill copies into a target
  repo as `.handoff/`. This is committed to the target repo so memory travels with
  the code. Editing here changes what newly-set-up repos get; it does **not** affect
  already-set-up repos.

The root **`tasks/`** folder (`inbox|now|done`, see `tasks/WORKFLOW.md`) is this
repo's own development backlog. It is not plugin payload and no hook reads it —
don't confuse it with `templates/tasks/`.

## Runtime model (how the pieces connect)

Everything is driven by three hooks registered in `hooks/hooks.json` (auto-loaded
because it lives at `hooks/hooks.json` — the plugin manifest deliberately does **not**
declare a `hooks` field; see commit 1844000). Each hook is a thin `python3` entry that
imports shared logic from `hooks/_common.py`:

- **`sessionstart.py`** (SessionStart) — if the target repo has `.handoff/`, injects
  `STATUS.md` + `RULES.md` in full plus an on-demand pointer and a one-line list of
  open overflow notes in `.handoff/handoffs/` (with age from the date prefix), captures a git baseline
  for the session (**HEAD sha + dirty paths with status codes** — so the Stop hook sees
  committed work too; kept on `resume`/`compact` if one exists), and checks `.handoff/VERSION` against the plugin version
  (template-drift nag; missing stamp nags once per repo). If no `.handoff/`, emits a
  **one-time** "run setup" tip per repo (marker file in `~/.cache/handoff/`) and stays
  silent forever after.
- **`pre_edit_context.py`** (PreToolUse: Edit/Write/MultiEdit/NotebookEdit/apply_patch) — walks up
  from the file being edited to find the nearest `CONTEXT.md` and injects it once per
  session; also corrects task files about to be written to the `tasks/` ROOT (they
  belong in `inbox|now|done`). Injects `additionalContext` **only** — never a
  `permissionDecision` — so it can't silently auto-approve edits.
  Codex supplies patch text in `tool_input.command`; every add/update/delete/move
  header is considered, with patch paths resolved against the hook's `cwd`.
- **`stop.py`** (Stop) — nudges when the session made new repo changes (**committed or
  uncommitted** — session-changed = commits since baseline HEAD + dirty paths whose
  code changed) but didn't update durable state: `STATUS.md` / `CHANGELOG.md` /
  `MAP.md` (structural changes only) / a folder's `CONTEXT.md`. Also flags: task files
  stranded in the `tasks/` root (shown once per session per stray-set), `STATUS.md`
  over 40 lines, **sentinel paths** (auth/migration/billing/… — configurable via
  `.handoff/SENTINELS`, forces the T3 question into the transcript), and an open
  `.handoff/GATE` (machine-readable T3 stall). The nudge says STATUS.md must let a
  fresh session continue, and gives one computed line of commit advice: same
  commit as pending code; else amend if HEAD is an unpushed, non-merge commit
  since the baseline (hedged "if it is your work"); else a follow-up commit.
  Separately, once per 200k-token step of session context (read from the
  latest usage record in `transcript_path`, never file size; Claude and Codex
  formats; absent/unreadable → skipped), it asks for a next-session handoff even
  with no repo changes. It has its own per-step marker and still sits behind
  `stop_hook_active`.
  The same hook also reminds the agent to commit completed, verified session
  changes, including Handoff-only edits, even when documentation is current.
  It never stages or commits; user instructions and open gates take priority.
  Stop emits `decision: block` plus `reason`, the supported continuation response
  for both hosts. Context-only `hookSpecificOutput` is for SessionStart/PreToolUse.

Without `CLAUDE_PROJECT_DIR`, root discovery uses git from the hook's `cwd`;
without git, it looks for an ancestor `.handoff/`. Codex's native `PLUGIN_DATA`
is preferred for persistent markers, with the Claude alias as fallback. Codex
also sets `CLAUDE_PLUGIN_ROOT`, so the shared registered commands work in both.

The push/pull principle behind all of it: always-relevant state (STATUS+RULES) is
**pushed** every session; everything else (`BOOT.md`, `MAP.md`, `context/*`, `tasks/`,
`CHANGELOG.md`, folder `CONTEXT.md`) is **pulled on demand**, zero cost until read.

## Invariants — do not break these when editing hooks

These are the load-bearing correctness properties. Most of the git history is fixing
regressions against them.

1. **Fail-safe always.** Every hook wraps `main()` so any exception prints nothing and
   exits 0. A hook bug must never break a user's session. New code paths must preserve this.
2. **`_common.py` helpers swallow errors** (return `None`/`{}`/default) rather than raise.
   Keep that contract; callers assume it.
3. **`stop.py` has three independent loop-breakers** — do not remove any:
   `stop_hook_active` guard, the **session git baseline** (only flags changes made *this*
   session, not pre-existing dirt), and the **nudge-signature cooldown** (never repeats the
   same unresolved nudge). Removing one risks an infinite Stop-continuation loop.
4. **PreToolUse injects context only, no permission decision.**
5. **Path safety in `pre_edit_context.py`:** edits outside the project root are ignored,
   Claude relative file paths resolve against the project root; Codex patch paths
   resolve against `cwd`. Resolve symlinks before checking the boundary, and stop
   the walk-up at the root. Preserve these checks (original fix: commit d6810e4).
6. **Changes under `.handoff/` are excluded** from the Stop hook's "new work" set, so
   updating state doesn't itself trigger a documentation nudge. New uncommitted
   state edits can trigger the separate commit reminder in the same Stop hook.

## Working / testing the hooks

Run `python3 tests/test_hooks.py` — the same stdlib smoke suite CI runs (fixture
repos piped through all three hooks, including the fail-safe garbage-stdin
checks). Hooks are plain `python3` reading a JSON payload on stdin and emitting
JSON context or a Stop continuation response on stdout. Poke one by hand by piping a payload:

```sh
# SessionStart against a target repo that has .handoff/
echo '{"cwd":"/abs/path/to/target-repo","session_id":"t1"}' | python3 hooks/sessionstart.py

# PreToolUse — nearest CONTEXT.md for a file about to be edited
echo '{"cwd":"/abs/path/to/target-repo","session_id":"t1","tool_input":{"file_path":"src/foo.ts"}}' | python3 hooks/pre_edit_context.py

# Stop — needs a baseline first (run sessionstart with the same session_id, then make
# a change); after that, a second identical run stays silent (signature cooldown).
echo '{"cwd":"/abs/path/to/target-repo","session_id":"t1","stop_hook_active":false}' | python3 hooks/stop.py
```

No output + exit 0 is the common (correct) result — most invocations are intentionally
silent. Session state (git baseline, nudge signature, per-CONTEXT.md dedup markers) lives
in `<tmp>/handoff-session-<hash>/`; delete that dir to reset a "session" between tests.

Keep hooks and `scripts/` **stdlib-only** — no third-party imports. `templates/` is markdown plus
`.gitkeep` files only.

## The setup skill

`skills/setup/SKILL.md` is the guided-discovery flow (`set up handoff` /
`/handoff:setup`). Its contract: copy `templates/` → `.handoff/`, read the real
codebase to *draft* STATUS/MAP/TECH_STACK/PRODUCT, **confirm with the user before saving**
(never invent project facts — RULES rule 5), optionally seed folder `CONTEXT.md`, and
append a thin-fallback block to the target repo's host instruction file (`CLAUDE.md`
for Claude, `AGENTS.md` for Codex). Preserve both files if present and keep their
handoff blocks consistent. It must refuse to overwrite an existing `.handoff/`
(offer refresh instead). Codex setup must explain hook trust and cloud limitations.

## Releasing

`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and
`.claude-plugin/marketplace.json` carry the version — **bump all three together**
(never hardcode the current number in docs; check the manifests).
Release-bump commit subjects follow `type: summary (vX.Y.Z)`; non-release commits omit
the version suffix. The marketplace registration reads GitHub, not the local clone —
a release is only live after `git push`.

## Further reading

- `README.md` — install/use, design notes, and the documented **known limitations**
  (Bash edits bypass CONTEXT injection, `git status` 10s timeout, baseline lost if temp is cleared,
  non-git repos disable the Stop nudge).
- `docs/SKILL-WORKFLOW.md` — how handoff (the state/context layer) composes with other
  skill families rather than replacing them.
- `docs/CODEX.md` — Codex installation, hook contracts, trust, and host limitations.