Setup Session Briefing

Set up Session Briefing

Get from zero to a working session briefing for this project — and, if you want it, a multi-project constellation. This is a prompt-driven skill: explore, present what you find, confirm with the user, then run the scaffolding. Don't dump every question at once; walk through them one at a time.

Assume the user is new to the method. Each decision below opens with a short explainer.

The mechanics are in the sibling agent-session-briefing skill's scripts/briefing.py (Claude Code: ~/.claude/skills/agent-session-briefing/scripts/briefing.py). Call it BP below.

1. Explore

Read the current state — don't assume:

• Hub — is $SESSION_BRIEFING_HUB set? Does ~/.session-briefings/ exist? Is it a git repo?
• Project repo — what's the current directory? git remote -v and git status. Is there a context file (AGENTS.md, CLAUDE.md, GEMINI.md) at the root? Does it already contain an <!-- agent-session-briefing --> pointer block?
• Existing briefing — does <hub>/<project>/SESSION_BRIEFING.md already exist? (If so, this is an update, not a setup — point the user at the agent-session-briefing skill instead.)
• Constellation hint — are there sibling repos that look related (a monorepo, a platform + services)? Note them; you'll offer a parent in Section B.

2. Present findings, then walk the decisions one at a time

Summarise what's present and what's missing. Then go section by section — present, get the answer, move on. Don't pick for the user where a real choice exists.

Section A — Hub location.

Explainer: The "hub" is one git repo that holds all your session briefings, one folder per project, separate from your code. Keeping it separate (not inside each repo) is what lets one parent briefing roll up many projects. Default: ~/.session-briefings/.

• Default ~/.session-briefings/ — fine for almost everyone.
• Custom path — offer if they want it elsewhere (e.g. a synced/backup location). It's set via the $SESSION_BRIEFING_HUB env var or --hub; mention they'll want it consistent across sessions.
• Recommend they git init the hub (and add a remote) so they get version history + hook validation. Offer to do it.

Section B — Single project or a constellation?

Explainer: If you're tracking one project, you just need one briefing. If you have several related projects (a platform and its services, a monorepo of packages), you can give them a shared parent briefing that auto-aggregates their status into one view. You don't have to decide forever — you can add a parent later.

• Single — just scaffold this project's briefing. (Most people start here.)
• Part of a constellation — ask for the parent's name. If the parent has no briefing yet, offer to create it too. This project will declare --parent <name>; optionally a --layer tag (a free-form dimension like visibility/ownership/maturity — leave unset if unsure).

Section C — Context file.

Explainer: The briefing pairs with your project's "agent context file" — the timeless doc your harness auto-loads (AGENTS.md is the cross-tool standard; Claude Code uses CLAUDE.md; Gemini CLI uses GEMINI.md). Timeless reference (build/run/conventions) lives there; timestamped state (status/decisions/next steps) lives in the briefing. The setup wires a one-line pointer from the context file to the briefing so a cold session knows where to look.

• If exactly one context file exists, use it (confirm).
• If several exist, ask which one the harness they use actually reads.
• If none exists, the scaffolder creates AGENTS.md (the standard) with the pointer. Offer that, or let them pick a name with --context-file.

Section D — Stop-hook validator (optional, Claude Code).

Explainer: An optional Stop-hook runs briefing.py check at the end of each turn and warns if a changed briefing is malformed (e.g. a section got dropped). Warn-mode by default; can be a hard gate.

• Offer to register agent-skills/agent-session-briefing/scripts/stop-validate.sh in settings.json under hooks.Stop. Skip if they'd rather not touch settings. (This one's Claude-Code-specific.)

3. Confirm, then scaffold

Show the user exactly what you'll run, then do it:

1. Ensure the hub exists; git init it if new and they agreed.
2. Scaffold the briefing — from the project repo (or pass --project-dir):
   • Single: python3 BP new <project> [--hub <hub>] [--context-file <name>]
   • Constellation: add --parent <parent> [--layer <tag>] (and new the parent first if needed).
3. Confirm the pointer landed in the context file (or that AGENTS.md was created with it).
4. If a parent is involved: python3 BP rollup <parent> and show the matrix.
5. python3 BP check <hub>/<project>/SESSION_BRIEFING.md — fix anything it flags.
6. If they opted in, register the Stop-hook.

Then help them fill the v1.0 briefing with real content (§1 context, §2 status, decisions already locked) — several sections will be thin at v1.0, which is fine.

4. Done

Tell them what now exists and the ongoing loop:

• The briefing lives at <hub>/<project>/SESSION_BRIEFING.md; the pointer is in their context file.
• Going forward they use the agent-session-briefing skill (not this one): after a work session, bump → replace §3 → update §2/§4/§5/§6 → pointer → rollup (if a parent) → check.
• Re-run this setup only to onboard another project into the constellation.