CLAUDE.md · git:20261008.0e07558 · 2026-10-08 · sha256 627c6d46835111d1
CLAUDE.md git:20261008.0e07558A
Immutable. This exact content never changes and is served at /api/v1/blob/627c6d46835111d1.
# 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).
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.
## 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.