CLAUDE.md · diff
git:20261008.0e07558 to git:20261014.76bd7a9
5 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# 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, and a template tree. 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), `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.
## 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, captures a git baseline
for the session (**HEAD sha + dirty paths with status codes** — so the Stop hook sees
committed work too), 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 instructs that state
updates ride in the SAME commit as the code (amend only if unpushed AND the last
commit is this session's own work).
+ 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 nudge.
+ 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 **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, `/compact` re-baselining,
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.