What it actually
looks like.

A hook · it observes, it never decides

Keep the picture fresh, flag drift.

Hooks are deterministic shell scripts the harness fires automatically. This one runs at session start: it refreshes the reference material and surfaces a warning if the structure changed — then gets out of the way.

#!/usr/bin/env bash
# Fired by the harness at session start. Observes and surfaces —
# it does not make decisions. That is the agent's job, later.
set -euo pipefail

# 1. Pull the latest reference material so context is never stale
for repo in "${REFERENCE_REPOS[@]}"; do
  git -C "$repo" fetch --quiet && git -C "$repo" merge --ff-only --quiet || \
    echo "⚠  $repo could not fast-forward — review before trusting its specs"
done

# 2. Detect structural drift: has the folder map changed since last snapshot?
current=$(find . -maxdepth 2 -type d | sort | sha1sum)
if [[ "$current" != "$(cat .structure-snapshot 2>/dev/null)" ]]; then
  echo "⚠  Structure changed — the self-portrait diagram may need a refresh."
fi

# 3. Load cross-session memory (the last ~20 sessions) into context
cat memory/episode-index.md

The discipline that matters: a hook surfaces a warning. It never edits, never merges over a conflict, never decides what the drift means. Determinism stays in shell; judgement stays with the agent.

A policy · it judges a situation

Stop strategy drift before it ships.

Policies are plain-language rules, loaded only when their trigger fires. This is the one I leaned on most: whenever work touches strategy, walk a fixed set of alignment signals before it merges.

# Policy: strategy-alignment

**When this fires:** any change under `roadmap/` or `capabilities/`,
or whenever the strategy itself meaningfully changes.

**What to do:** walk all six signals. If any fails, flag it in the
PR and push back (player-coach style) — up to three rounds — before merge.

1. Pillar      — does this serve one of the named strategic pillars?
2. Core job    — can it trace to the core job the product is hired for?
3. Persona     — does it serve the *target* user, not a louder edge case?
4. Evidence    — is there a validated problem behind it, with a cited source?
5. Trade-off   — what are we explicitly choosing *not* to do, and why?
6. Constraints — does it respect the known platform & policy limits?

**Stand-in example (habit app):** "Add streak leaderboards" →
fails signal 3 (serves competitive power-users, not the tentative-beginner
target persona) and signal 5 (no stated trade-off). Flagged, not merged.

Encoding judgement once, in plain language, means the hundredth strategy decision gets the same rigor as the first — without re-explaining it to anyone, human or agent.

A skill · it executes a procedure

Interview → structured brief, every time.

Skills package a repeatable multi-step workflow you invoke on demand. The input is messy (raw research); the output is always the same disciplined shape, so briefs are comparable across the whole product.

# Skill: /interview-to-brief
trigger:  user pastes or points to interview notes
output:   a problem brief in the standard template

steps:
  1. extract every distinct pain point + the verbatim quote behind it
  2. cluster pains; keep only those that recur across participants
  3. for each cluster, draft: problem · evidence (cited) · who it hurts
  4. check each against the target persona — drop edge-case-only pains
  5. propose one starting direction + the trade-off it accepts
  6. emit the brief; never invent a quote that isn't in the source

# Problem brief: the "day-3 cliff"

Problem.   New users build a streak for two days, then vanish on day 3.
Evidence.  4 of 6 interviewees described the same drop-off.
           > "I did it Monday and Tuesday, then Wednesday got away from
           >  me and I just... never opened it again." — P2 (cited)
Who it hurts. The tentative-beginner persona — not power users, who
           recover streaks fine.
Starting direction. A forgiving "streak repair" on the first miss.
Trade-off accepted. Slightly softer accountability, in exchange for
           surviving the moment most users currently churn.

Same shape every time means briefs stack, compare, and compound — instead of each one being a fresh act of improvisation.

Putting it together · the anti-drift loop

Why the map never lies.

The governance idea, made concrete. Suppose I add a new skill. Here’s what the system forces to happen — or the change fails its own audit.