| name | session-start |
| description | Open a work session: allocate a session id, seed a live session doc at sessions/NNNN-slug/session.md by scanning the repo for everything relevant (in-scope tickets, research, tools, prior sessions, git/PR state), and generate a TDD-first checklist. The session doc is the central live state for the session. Use when the user runs /session-start "<goal>" or asks to kick off a work session. |
/session-start — Open a session and seed its live doc
Creates the central live-state document for a work session and front-loads
all the context needed to work well. Invoked as:
/session-start "Tackle the vault tickets 0012–0014"
The argument is the session goal (verbatim → goal: in frontmatter). The
session doc lives at sessions/<id>-<slug>/session.md and follows the strict
schema in SESSION_EXAMPLE.md. It is the single source
of truth for the session — every later skill (and /session-end) reads and
updates it.
Process
1. Allocate the session id
ROOT="$(git rev-parse --show-toplevel)"
id=$("$ROOT/.claude/skills/session-start/bin/next-session-id")
Never hand-edit sessions/.next-id. Derive a kebab slug (≤ 6 words) from the
goal. Create the directory: mkdir -p "sessions/${id}-${slug}".
2. Seed context (the high-value step)
This is what makes a session start well. Scan the repo read-only and gather
everything relevant to the goal. Run these in parallel where possible:
- In-scope tickets —
"$ROOT/.claude/skills/ticket/bin/tickets" open and
... in-progress. Pull the ones matching the goal (by id if the user named
them, else by keyword). For each, capture the one-line title + acceptance
criteria. These drive the checklist.
- Research & docs — grep
research/, docs/ (and any project notes dir)
for the goal's keywords. List relevant ADRs (docs/decisions/), runbooks
(docs/runbooks/), learnings (docs/learnings/), and docs/architecture.md
sections.
- Existing tools / skills — note which
.claude/skills/ and repo bin/
tools apply to this goal so we reuse instead of rebuild.
- Prior sessions —
"$ROOT/.claude/skills/session-start/bin/sessions".
Read the most recent / related session docs, especially their Follow-ups
sections — unfinished work and suggested tickets carry forward. Link them in
prior_sessions.
- Git / PR state — current branch,
git log --oneline -10, and open PRs
(gh pr list). Note anything in flight that this session interacts with. If
any merged PRs are still linked to non-closed tickets, suggest running
/merge-sync to reconcile before starting.
3. Generate the checklist (TDD-first)
From the in-scope tickets' acceptance criteria, write a concrete, ordered TODO
list. TDD is mandatory and explicit: every behavior change gets a "write the
failing test" item before its implementation item, then a "make it pass" item.
End each ticket's run with "open PR + link to ticket". Example:
- [ ] 0012 — write failing test: vault create rejects spend over cap
- [ ] 0012 — implement vault-create to make the test pass
- [ ] 0012 — open PR + link PR url into ticket 0012 prs:
Keep it realistic for one session; defer the rest to Follow-ups. If planning
surfaces new work items that aren't ticketed yet, file them via /ticket into
the canonical backlog — never as loose markdown files or an ad-hoc tickets
directory.
4. Write the session doc
Write sessions/<id>-<slug>/session.md using the SESSION_EXAMPLE schema.
Populate all frontmatter fields — id, slug, anchor: SES-<zero-padded id>, title (a short headline from the goal — the listers display it), status: active, started: now, ended: null, goal (verbatim), tickets,
branches: [], prs: [], related_research, related_docs, prior_sessions
— then the [1] Goal,
[2] Context & pointers, and [3] Checklist sections. Leave [4]–[8] as
stubs for the session and /session-end to fill. Anchor every heading
([N] / [N.M]) per the anchoring convention so the doc stays greppable as it
grows — see CLAUDE.md and SESSION_EXAMPLE.
Exactly one session should be active. If bin/sessions active shows another
active session, surface it and ask whether to close it first (it likely needs
/session-end).
5. Mirror the checklist into tasks
If the task tool is available, create one task per checklist item via
TaskCreate so progress is tracked live in the session, and keep the session
doc's checkboxes and the task list in sync as work proceeds. (If it isn't, the
session doc's [3] Checklist remains the source of truth — no-op this step.)
6. Mark the in-scope tickets in-progress
For every ticket this session commits to working, set status: in-progress and
bump updated: to today (/ticket update, or edit the frontmatter directly).
This keeps the lifecycle gap-free (CLAUDE.md [4.1]) — bin/tickets in-progress
should equal the work actually in flight. Don't flip tickets you're only
referencing, and leave future/icebox ones as-is.
7. Refresh the live status + announce
Refresh the human-facing snapshot: .claude/bin/status > .status.md (gitignored;
the at-a-glance state for whoever is managing agents in this repo).
Point the user at sessions/<id>-<slug>/session.md and give a tight summary:
the goal, the in-scope tickets, the key context pointers (notable research /
prior-session follow-ups), and the first 3 checklist items. Then start work (or
wait, if the user only wanted the session seeded).
Quality bar
- Context is specific, not generic. "Reviewed tickets 0012–0014, ACs below"
beats "looked at the backlog". Cite ids, paths, PR numbers.
- The checklist is testable and TDD-ordered. No "implement X" without a
preceding "write failing test for X".
- One active session at a time. The session doc is central state; two active
docs means ambiguous state.
What NOT to do
- Don't allocate ids by hand-editing
sessions/.next-id — use the script.
- Don't start writing code before the session doc exists — the doc is the
central state, seed it first.
- Don't dump the entire backlog into Context — only what's relevant to the goal.
Activity
After seeding the session doc, emit a feed event:
.claude/bin/activity session-start "Session · <goal>" "<slug>"
