How to onboard the inter-session protocol onto a new project¶
Goal: take a repository that has no parallel-session protocol and leave it able to run 2–3 coordinating Claude Code sessions safely.
Time: ~15–20 minutes. Prerequisites: the target repo is a git repo with
an origin remote and a main branch; you can run bash and (optionally)
install lefthook. You are copying from a project
that already has the protocol (po-platform is the reference donor).
Throughout, replace <project> with your repo's directory basename (e.g.
acme-app). If you are an AI agent doing this autonomously, use the
CSF snapshot
instead — it is the same procedure in agent-consumable form.
Two levels of adoption. The minimum viable install (Steps 1–6) gives you the working mechanics: worktree isolation, the scoreboard, queues, the ack chain, presence. The full install (Step 7) also copies the normative ADR and the layered doctrine so future sessions have the complete playbook. Do the minimum first; add the doctrine once the mechanics prove out.
Step 1 — copy the three scripts¶
Copy these from the donor repo into infrastructure/scripts/ (or wherever your
repo keeps scripts — adjust paths consistently afterward):
mkdir -p infrastructure/scripts
cp <donor>/infrastructure/scripts/start-session.sh infrastructure/scripts/
cp <donor>/infrastructure/scripts/session-heartbeat.sh infrastructure/scripts/
cp <donor>/infrastructure/scripts/check-worktree-prefix.sh infrastructure/scripts/
chmod +x infrastructure/scripts/*.sh
check-worktree-prefix.shis portable verbatim — it derives the-sXsuffix generically and contains no project name.start-session.shandsession-heartbeat.shhardcode the project name and must be adapted in Step 2.
Step 2 — adapt the project name in the two scripts¶
Both scripts assume the worktree is named <project>-sX. Replace the donor's name
with yours:
sed -i 's/po-platform/<project>/g' \
infrastructure/scripts/start-session.sh \
infrastructure/scripts/session-heartbeat.sh
That fixes the directory-name checks (<project>-s[A-Z]), the worktree path
(../<project>-sX), and the prefix-stripping in the heartbeat. Verify nothing was
missed:
grep -n 'po-platform' infrastructure/scripts/start-session.sh infrastructure/scripts/session-heartbeat.sh
# → should print nothing
Tip (optional): if you'd rather not hardcode at all, replace the literal in the
case "$BASENAME"blocks with a dynamic base derived from the repo root. The hardcoded form is simpler and what the donor ships; either works.
Step 3 — define your name pool¶
Open infrastructure/scripts/start-session.sh and edit the NAME_POOL array to a
theme that fits your project. The rules are firm (validated by the script):
plain ASCII letters [A-Za-z] only, ≤ 12 chars, no spaces, no accents/diacritics,
unique within the pool. The theme is yours.
# Examples of valid pools (pick one theme, ~10–15 names):
NAME_POOL=(Orion Lyra Vega Rigel Altair Sirius Polaris Antares Capella Deneb) # constellations
# NAME_POOL=(Basil Thyme Sage Dill Mint Fennel Tarragon Chervil Lovage Sorrel) # herbs
# NAME_POOL=(Ada Linus Grace Dennis Edsger Barbara Alan Donald Ken Margaret) # computing pioneers
Provide at least as many names as the max sessions you expect (5 letters
sA–sE is the protocol ceiling, so ~5+ names is plenty; more gives variety).
Step 4 — create the claim scoreboard¶
Create docs/ai/sessions/active.md. The structure matters: start-session.sh
inserts rows under a ## Active heading, and session-heartbeat.sh only bumps
rows above the first <!-- sX self-closed --> history marker.
mkdir -p docs/ai/sessions/queue
cat > docs/ai/sessions/active.md <<'EOF'
---
audience: developers
category: reference
last_updated: 2026-01-01
related_docs:
- ../parallel-sessions.md
---
# Active session claims
Live scoreboard of orchestrator sessions currently working on this repo. Read this
file at session start before claiming work. Append your row when you claim. Remove
it (or mark it paused) when you stop.
**Reap rule:** rows older than 6 hours with no commits on the named branch (or no
`[sX]` commits on main in that window) can be removed by any session. Log the reap
in the "Reaped" section below.
## Active
| Session · Name | Riff / Task | Branch / Commit prefix | Claimed (UTC) | Presence (last_seen · caps) | Scope |
|---|---|---|---|---|---|
## Reaped / closed (rolling 7 days)
EOF
The empty table (header + separator, no data rows) is correct — sessions add their
own rows via start-session.sh.
Step 5 — set up the message queue directory¶
Queue files (to-<sX>.md) are created on demand, but seed the directory with a
short README so it survives and is discoverable:
cat > docs/ai/sessions/queue/README.md <<'EOF'
# Cross-session message queue
One file per recipient: `to-sA.md`, `to-sB.md`, … (and `to-all.md` for broadcast).
Each message is a markdown block:
· from: · to: · type: · ref: · status:sent¶
→ status:seen The recipient advances the `→ status:` line in their own commit. See
`docs/developers/inter-session-comms/reference.md` for the full grammar.
EOF
commit-msg:
commands:
worktree-prefix-match:
run: bash infrastructure/scripts/check-worktree-prefix.sh "{1}"
post-commit:
commands:
session-heartbeat:
run: bash infrastructure/scripts/session-heartbeat.sh
cd ../<project>-sA
grep '^| sA' docs/ai/sessions/active.md # your row, with a name from YOUR pool
git commit --allow-empty -m "[sB] test: wrong prefix" # MUST be rejected by the hook
git commit --allow-empty -m "[sA] test: correct prefix" # MUST pass
grep '^| sA' docs/ai/sessions/active.md # Presence timestamp bumped by post-commit hook
git reset --hard HEAD~1 # drop the empty test commit
cd .. && git worktree remove <project>-sA && git branch -D session-sA
# and remove the sA claim row from active.md on main if it was pushed
## Parallel orchestrator sessions
When 2–3 Claude Code sessions run concurrently against this repo, follow
`docs/developers/inter-session-comms/` (start with `explanation.md`).
**At session start (mandatory if session > 30 min):**
`bash infrastructure/scripts/start-session.sh` — auto-claims an unused `sX`,
creates the per-session worktree at `../<project>-sX`, commits your claim row.
Then `cd` into the printed worktree and work there. Every commit/PR/Riff carries
`[sX]`. At end: remove your row (or mark `paused — resuming <ETA>`).