Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 41 additions & 5 deletions .claude/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
{
"hooks": [
{
"command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2\u003e/dev/null); if [ -n \"$f\" ] \u0026\u0026 echo \"$f\" | grep -q \"/wiki/\"; then python3 tools/brain.py lint-page \"$f\" 2\u003e/dev/null || true; fi",
"command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2>/dev/null); if [ -n \"$f\" ] && echo \"$f\" | grep -q \"/wiki/\"; then python3 tools/brain.py lint-page \"$f\" 2>/dev/null || true; fi",
"type": "command"
}
],
Expand All @@ -16,7 +16,7 @@
{
"hooks": [
{
"command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2\u003e/dev/null); if [ -n \"$f\" ] \u0026\u0026 echo \"$f\" | grep -q \"/wiki/\"; then bash tools/ui-build.sh; fi",
"command": "f=$(jq -r \".tool_input.file_path // .tool_response.filePath // empty\" 2>/dev/null); if [ -n \"$f\" ] && echo \"$f\" | grep -q \"/wiki/\"; then bash tools/ui-build.sh; fi",
"type": "command"
}
],
Expand All @@ -30,24 +30,42 @@
}
],
"matcher": "Edit|Write|MultiEdit"
},
{
"hooks": [
{
"command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" record",
"type": "command"
}
],
"matcher": "Edit|Write|MultiEdit"
}
],
"PreToolUse": [
{
"hooks": [
{
"command": "cmd=$(jq -r '.tool_input.command // empty' 2\u003e/dev/null); case \"$cmd\" in *\"git push\"*|*\"gh pr create\"*) root=$(git rev-parse --show-toplevel 2\u003e/dev/null || echo .); script=\"$root/tools/preflight.sh\"; if [ -x \"$script\" ]; then \"$script\" \u003e\u00262 || { echo \"preflight blocked: $cmd\" \u003e\u00262; exit 2; }; fi ;; esac; exit 0",
"command": "cmd=$(jq -r '.tool_input.command // empty' 2>/dev/null); case \"$cmd\" in *\"git push\"*|*\"gh pr create\"*) root=$(git rev-parse --show-toplevel 2>/dev/null || echo .); script=\"$root/tools/preflight.sh\"; if [ -x \"$script\" ]; then \"$script\" >&2 || { echo \"preflight blocked: $cmd\" >&2; exit 2; }; fi ;; esac; exit 0",
"type": "command"
}
],
"matcher": "Bash"
},
{
"hooks": [
{
"command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" gate",
"type": "command"
}
],
"matcher": "Edit|Write|MultiEdit"
}
],
"SessionStart": [
{
"hooks": [
{
"command": "python3 tools/brain.py inbox summary 2\u003e/dev/null || true",
"command": "python3 tools/brain.py inbox summary 2>/dev/null || true",
"type": "command"
}
]
Expand Down Expand Up @@ -78,6 +96,24 @@
"type": "command"
}
]
},
{
"hooks": [
{
"command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" debt",
"type": "command"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"command": "\"${CLAUDE_PROJECT_DIR:-.}/tools/hooks/intent-first.sh\" reset",
"type": "command"
}
]
}
]
},
Expand Down Expand Up @@ -123,4 +159,4 @@
"mcp__claude_ai_Notion__notion-move-pages"
]
}
}
}
20 changes: 20 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1162,6 +1162,26 @@ or any other direct work in that codebase. Five rules.
next agent inheriting the area knows *why* a parallel pattern
was warranted instead of an extension of the existing one.

6. **Intent first.** Before code moves in a sibling repo, the
governing specs move — or are confirmed already aligned. Read
the trail with `brain.py enola govern <path>` (which names the
PRD/ADR/build-notes pages governing the code being touched) and
check the *intended* change against what those pages record. A
deviation is amended into the governing page **before** the
edit, not narrated into build notes afterwards; work nothing
governs is surfaced with the question of whether it should be
shaped. `tools/hooks/intent-first.sh` enforces both ends of the
loop mechanically. Entering: the first Edit/Write into each
sibling repo *per piece of work* is blocked once with the
file's governing trail injected into context, and the retry
proceeds — the gate re-arms on every user message. Leaving: a
Stop-time debt check blocks the turn's end once when sibling
code moved but no governing page did, demanding either the
spec amendment or an explicit statement of why the specs
already cover the change. The gates force the reading and the
accounting, never the verdict; an absent graph degrades to a
named skip.

These rules apply equally to autonomous agent runs and to
human-supervised ones. The brain agent operating in any sibling
repo is a guest in that codebase; the host repo's conventions are
Expand Down
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,22 @@ re-derivation (only pages the stamp itself touched) and the
commit — skip-when-absent; its voice is the non-blocking session
hook.

### Intent-first session hooks

`tools/hooks/intent-first.sh` (four modes, registered in
`.claude/settings.json`) is the mechanical half of AGENTS.md
§ Working inside a sibling repo, rule 6. *Entering* a piece of
work: the first Edit/Write into each sibling repo is blocked once,
with the file's governing specs (`brain.py enola govern`) injected
into context and the instruction to align the PRD/ADR/build-notes
before the code moves; the gate re-arms on every user message.
*Leaving* a turn: when sibling code moved and no wiki page did, the
stop is blocked once and the agent must amend the governing page or
state why the specs already cover the change. The gates force the
reading and the accounting, never the verdict; an absent graph
degrades to a named skip. Sibling detection honours
`$BRAIN_PROJECTS_ROOT` (default `~/projects`).

## Workflow — slash commands

| Command | What it does |
Expand Down
127 changes: 127 additions & 0 deletions tools/hooks/intent-first.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
#!/bin/bash
# Intent-first hooks — the mechanical half of AGENTS.md § Working
# inside a sibling repo, rule 6 (intent first).
#
# Modes (all read the Claude Code hook JSON from stdin):
# gate PreToolUse on Edit|Write|MultiEdit — block the first edit
# into each sibling repo *per piece of work* (re-armed on
# every user prompt), surfacing the file's governing specs
# (brain.py enola govern). The retry proceeds: the gate
# forces the reading, never the verdict. Absent graph
# degrades to a named skip.
# record PostToolUse on Edit|Write|MultiEdit — record what moved
# this turn: sibling code vs brain wiki pages (specs).
# reset UserPromptSubmit — a new user message begins a new piece
# of work: clear gate acks and the turn record.
# debt Stop — if sibling code moved this turn and no spec moved,
# block the stop once and demand the accounting: amend the
# governing page, or state why the work is already aligned.
set -u

mode="${1:-}"
input=$(cat 2>/dev/null || true)
sid=$(jq -r '.session_id // "nosession"' <<<"$input" 2>/dev/null)
statedir="${TMPDIR:-/tmp}/brain-intent-first"
mkdir -p "$statedir"

brain_dir=$(cd "${CLAUDE_PROJECT_DIR:-.}" && pwd -P)

classify() {
local f="$1" probe top
case "$f" in
"${BRAIN_PROJECTS_ROOT:-$HOME/projects}"/*) ;;
*) return 1 ;;
esac
probe=$(dirname "$f")
while [ ! -d "$probe" ] && [ "$probe" != "/" ]; do
probe=$(dirname "$probe")
done
top=$(git -C "$probe" rev-parse --show-toplevel 2>/dev/null) || return 1
top=$(cd "$top" && pwd -P)
if [ "$top" = "$brain_dir" ]; then
case "${f#"$top"/}" in
wiki/_views/*|wiki/_archive/*|wiki/_state/*) return 1 ;;
wiki/*.md) printf 'spec\t%s\t%s\n' "$top" "${f#"$top"/}"; return 0 ;;
*) return 1 ;;
esac
fi
printf 'code\t%s\t%s\n' "$top" "${f#"$top"/}"
}

case "$mode" in
gate)
f=$(jq -r '.tool_input.file_path // empty' <<<"$input" 2>/dev/null)
[ -z "$f" ] && exit 0
line=$(classify "$f") || exit 0
kind=$(cut -f1 <<<"$line")
[ "$kind" = "code" ] || exit 0
top=$(cut -f2 <<<"$line")
rel=$(cut -f3 <<<"$line")
repo=$(basename "$top")
ack="$statedir/${sid}-${repo}.ack"
[ -e "$ack" ] && exit 0
touch "$ack"

govern=$(cd "$brain_dir" && timeout 30 python3 tools/brain.py enola govern "$rel" 2>&1 | head -40)
[ -n "$govern" ] || govern="(enola govern unavailable — named skip; consult the wiki/<repo>/ shelves manually)"

cat >&2 <<EOF
intent-first gate (${repo}): first edit for this piece of work.

The contract is intent first. Before this code moves: read the
governing specs below and check the intended change against them. If
the work deviates from what the PRD/ADR/build-notes record, amend the
page first (then 'brain.py intent stamp'); if nothing governs this
work, surface that and ask whether it should be shaped.

Governing intent for ${rel}:
${govern}

Retrying the edit proceeds. This gate re-arms on every user message;
within one piece of work it will not fire again.
EOF
exit 2
;;

record)
f=$(jq -r '.tool_input.file_path // .tool_response.filePath // empty' <<<"$input" 2>/dev/null)
[ -z "$f" ] && exit 0
line=$(classify "$f") || exit 0
printf '%s\n' "$line" >> "$statedir/${sid}.turn"
exit 0
;;

reset)
rm -f "$statedir/${sid}"-*.ack "$statedir/${sid}.turn" "$statedir/${sid}.debt-blocked"
exit 0
;;

debt)
turn="$statedir/${sid}.turn"
[ -f "$turn" ] || exit 0
[ -e "$statedir/${sid}.debt-blocked" ] && exit 0
grep -q '^code' "$turn" || exit 0
grep -q '^spec' "$turn" && exit 0
touch "$statedir/${sid}.debt-blocked"

summary=$(awk -F'\t' '$1 == "code" { n = split($2, a, "/"); print " " $3 " (" a[n] ")" }' "$turn" | sort -u | head -15)

cat >&2 <<EOF
intent debt: sibling code moved this turn, and no governing page did.

Changed without a spec moving:
${summary}

Before finishing: either amend the governing PRD/ADR/build-notes to
match what was just built (then 'brain.py intent stamp'), or state
explicitly — in your reply — why the change is already covered by the
specs as written. This check blocks once per turn.
EOF
exit 2
;;

*)
printf 'usage: %s {gate|record|reset|debt}\n' "$0" >&2
exit 64
;;
esac
Loading