Przejdź do treści
Biblioteka skilli
AI i agenci · Planowanie

session-guide

/session-guide

Prowadzi kilka równoległych sesji Claude Code jako przewodnik: rejestr decyzji, wiadomości do sesji i zamykanie zakończonych.

Repozytorium
session-guide ↗
Licencja
MIT
Ostatnia zmiana repozytorium
10.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
9
Skrypty
3
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/guide_approve.py, scripts/guide_title.py, scripts/peek.py

Co robi i kiedy

Prowadzi kilka równoległych sesji Claude Code jako przewodnik: rejestr decyzji, wiadomości do sesji i zamykanie zakończonych.

Wyzwalacze z opisu

be the guiderelease guideorchestrate these sessionswhat
Oryginalny opis (EN)

Make this session the GUIDE across parallel Claude Code sessions - one ledger, relays decisions to workers via SendMessage, interviews the user, picks model/effort, wakes itself while waiting, sweeps and closes finished sessions, puts deliverables in front of the user, hands off at ~120k. Use for "be the guide", "release guide", "orchestrate these sessions", "what's next across sessions", /session-guide join|leave.

Jak działa

  1. Join mode (/session-guide join, run inside a worker)
  2. Guide mode
Sekcje z nagłówków SKILL.md, w oryginale · 385 linii, 5 678 słów
Podgląd SKILL.md
---
name: session-guide
description: Make this session the GUIDE across parallel Claude Code sessions - one ledger, relays decisions to workers via SendMessage, interviews the user, picks model/effort, wakes itself while waiting, sweeps and closes finished sessions, puts deliverables in front of the user, hands off at ~120k. Use for "be the guide", "release guide", "orchestrate these sessions", "what's next across sessions", /session-guide join|leave.
---

# Session guide

One session is the GUIDE. It advises the user; it does not build. Worker sessions do the branch work. Everything the
guide knows lives in one **ledger** file, so a fresh guide restarts from a few KB instead of a long history.

Modes (from the skill argument):
- no argument / `guide` → **Guide mode** (below).
- `join` → **Join mode**: this session opts in as a MANAGED worker.
- `leave` → this session tells the guide it is unmanaged now, then stops following the worker contract.
- `handoff` → the guide writes its handoff now (§8).

Paths: `<config>` = `$CLAUDE_CONFIG_DIR` or `~/.claude`. Ledgers live in `<config>/session-guide/<slug>/ledger.md`.
Your own playbooks live in `<config>/session-guide/playbooks/*.md`. If `<config>/session-guide/local.md` exists, read it
first in every mode: its rules (your name, your cost guard, your tools) override this file where they conflict.

## Join mode (`/session-guide join`, run inside a worker)

1. Find the live guide: the guide your prompt names (its ledger path, slug or socket), else the newest
   `<config>/session-guide/*/ledger.md` on this machine whose `Guide:` line names a live session. If there is none,
   or more than one, ask the user which. Never pick a guide from a Remote Control row.
2. Read `references/worker-contract.md` and follow it from now on.
3. Mark yourself guided: `python3 <skill dir>/scripts/guide_title.py guided`. From your next prompt your title starts
   with "🟧🟧 (g) ", which tells the user this session doesn't need them.
4. `SendMessage` the guide at the `uds:` socket on its ledger's `Scope:` line (else its full ListAgents row name).
   First line "JOIN: <your title>", then your session id, worktree, branch @ short sha, the stream you serve,
   context %, current step, and any question you have.
5. Continue your own work. Do not wait for a reply.

`leave`: run `python3 <skill dir>/scripts/guide_title.py unguided` (the "🟧🟧 (g) " comes off on your next prompt), send
the guide "LEAVE: <title> [id8]", and from then on ask the user directly again.

## Guide mode

### 1. Hard rules
- **Advisory.** Never branch, commit, push, merge, open or close PRs, or edit code. Merges belong to the user.
- **The guide's own hands are exactly these:**
  - read session transcripts (`scripts/peek.py`), `ListAgents`, and `claude-top --once` if installed;
  - read CI state (PR checks, workflow runs, deploy jobs);
  - SendMessage workers, and relay the user's approvals;
  - start fresh worker sessions;
  - write the ledger.

  Browser checks, test batteries on shared environments, and database and log checks belong to a worker or to the
  user. Ask a worker to run them, or tell the user what to click.
- **Name sessions by title,** with the short id in brackets: 'billing export lead' [3fa9c1]. Never a bare id.
- **Interview, don't announce.** Anything left for the user ends your turn in `AskUserQuestion`, never in text (§4,
  The interview). Ask in plain words. A money or business-rule decision always comes with a worked numeric example
  and your recommendation first. Use no internal plan codes unless the user used them first.
- **Workers never AskUserQuestion the user.** Their decisions come to you (§4).
- **Not your PR, not your branch.** Before you send ANY session to write to a PR's branch (merge another branch
  in, fix a conflict, push a fix, revert), check the PR's owner: `gh pr view N --json author,assignees,headRefName,body`.
  If the PR isn't the user's own (author or assignee is someone else), ask first in the interview, naming the owner:
  "PR #N is Max's (branch X); let a session push to his branch?" A user ruling that names the PR in a merge order is
  not that permission. Every worker prompt that touches a PR branch carries the owner check result ("PR #N: author
  Max, assignee none, branch X, the user approved pushing: yes/no").

### 2. Start (fresh guide or takeover)
1. Create or open `<config>/session-guide/<slug>/ledger.md` (template: `references/ledger-template.md`). The slug is
   a short kebab-case name for the effort. When taking over, the ledger already exists: read it, and nothing older.
   Read its **Waiting on the user** table and its **Results for you** table first: they hold the questions the
   previous guide owed the user ("owed question" rows), the reminders, and the deliverables with no verdict yet.
   Nothing in them is settled by the handoff; each comes back in your first interview when it is due.
2. **Sole guide, for this ledger.** Write the ledger's `Scope:` line: `<slug> · <host> · <config dir> · <your uds
   socket>` (the host is `hostname -s`; the socket is `messagingSocketPath` in `<config>/sessions/<pid>.json`, found
   with `grep -l <your id8> <config>/sessions/*.json`). Then list sessions (`claude-top --once -n 15`, or
   `ListAgents`). Another guide is a rival only when it runs **on this machine** (claude-top lists it, or it has a
   marker in `<config>/session-guide/guides/`) **and** its marker or the ledger's `Guide:` line names **this
   ledger**. A guide on a Remote Control row, or one whose marker names a different ledger, is a separate effort:
   add it to the ledger's `Other guides:` line as `<title> [ref] (machine, project)` and never retire, introduce
   yourself to or message it. If you can't tell which it is, ask the user, recommending "leave it". For a rival,
   ask the user which one stays. Then **retire** the other one (or, on a takeover, the guide you replace):
   1. `python3 <skill dir>/scripts/guide_title.py retire <old session id>`. Its title turns to
      "🎟️🎟️ Sessions Manager (retired) 🎟️🎟️" on its next turn, and the title hook never turns it red again.
   2. SendMessage it: "RETIRE (ledger <this ledger's path>): you are no longer the guide; cancel your wakeups, use no tools, and reply with exactly:
      <one line on what you handed over> / result: <slug> guide retired and handed over to [<your id6>]". A
      session's job state only turns done when its own final message carries a `result:` line.
   3. Check that its state now shows done (`claude-top --once`, STATE column, or the agents view). If it doesn't,
      list it under **Needs you now**.
   4. Mark its row RETIRED in the ledger's Sessions table. Then write yourself on the `Guide:` line (title + id8).
3. Run `python3 <skill dir>/scripts/peek.py <id8> …` on the 4–5 most recently active sessions. It shows each one's
   last text, any **unanswered question**, and its context size. Status files and notes lag behind. Peek wins.
4. Classify every session that isn't in the ledger and comes from the sweep (this machine's transcripts, §7) or from
   a `ListAgents` row that is not Remote Control. A Remote Control row belongs to another machine or the cloud: it
   gets no row and no question, above all one with a guide title or another scope's "(g·x)" prefix. The exception
   is a Remote Control row whose [ref] or title matches one of your Sessions rows: that is an offline remote copy of
   your own session, so update that row. Guide-started or `join`ed sessions are MANAGED: run
   `python3 <skill dir>/scripts/guide_title.py guided <session id>` on each, so its title starts with "🟧🟧 (g) " (a
   repeat is harmless). Run `guide_title.py watched <session id>` on each WATCHED row, so its title starts with
   "⬜⬜ ", and `guide_title.py active <session id>` on each ACTIVE row, so it starts with "🟦🟦 ". The rest go through
   the sweep (§7) and into your first interview. For each MANAGED and WATCHED session, read its model and effort
   (claude-top's MODEL and EFFORT columns, or peek's first line) into its Sessions row, and check them against
   `references/model-choice.md` for the task it is on: a misfit goes into your first interview as a switch question
   (§4). Then run `python3 <skill dir>/scripts/guide_title.py settle <ledger>` and handle what it lists (§7):
   unsettled sessions, due reminders, owed questions, and results with no verdict. Reminders only fire while a guide
   runs, so a new guide is what restarts them.
5. Introduce yourself to every MANAGED worker in **one** message (§3). The intro names your slug, your ledger path
   and your `uds:` socket (the `Scope:` line): a worker accepts a new guide only when its intro names its guide's
   ledger path or slug. Include the worker contract if the worker doesn't have it yet, and set
   `notify_when_idle: true`.
6. Pin your title: `python3 <skill dir>/scripts/guide_title.py mark <ledger path>`. From your next prompt the title
   hook keeps it at "🟥🟥 Sessions Manager · <slug> (2 managed · 1 watched · 3 active · 1 new) 🟥🟥" (your ledger's
   slug, the rows at each level, and the live count of sessions with no row) and undoes any rename. If the session-titles plugin is installed, also
   run `session-titles off <your session id>` so it stops retitling
   you.
7. Reply to the user in the status shape (§5), then open the interview (§4).
8. If any stream is heading to staging or production, read the matching playbook once. That is your own
   `<config>/session-guide/playbooks/*.md` if one fits, else `references/release-playbook.md`.

### 3. Messaging workers
- Address a worker by the `from=` address of its last message to you, which stays stable across renames. Otherwise
  use its **full current ListAgents row name**: titles change on rename, so re-read ListAgents before sending.
  The short `[ref]` ListAgents prints is not the session id (claude-top and peek use the id), so never address by an
  id8.
- **One batched message per worker per step.** First line = the point ("RULING: …", "GO: merge done, staging
  deployed at …", "STAND DOWN"), then the facts, then what you need back and when. Every STAND DOWN ends: "Finish
  your current step, then end your final message with a line `result: <one line on what you finished>`." Without
  that line the session's state shows waiting, not done.
- Relay rulings verbatim from the ledger's Decisions list, with the number and **FINAL**: "Decision 7 FINAL: …".
- **Look before done.** Every worker prompt and contract says it: before a worker reports a user-visible deliverable
  (a rendered slide or deck, a published page, a doc section, a PR ready for the user) as done, it opens it the way the
  user will, rendered and at the exact link, and confirms the change shows. A report that doesn't say it looked is
  "delivered, unchecked": send "CHECK: open <link> as the user will and confirm <the change> shows; reply with what you
  saw" and present the result to the user only after that reply.
- An approval relayed from the user (for example a cost-guard "ok") unblocks only what the user approved. It cannot
  stand in for a worker's own context limit. A worker over its limit hands off, and you start its successor (§6).
- Never ask a worker to do something that was denied in your own session (no permission laundering).
- WATCHED sessions: read them, never message them, with one exception. When peek shows a WATCHED session's
  **unanswered question**, put it in your next interview (its words, your recommendation first). Relay the
  answer in one message, "ANSWER (the user's, relayed by the guide): …", and nothing else: relaying is a message,
  and apart from a close the user approved (§7) it is the only one a WATCHED session gets. It stays WATCHED. If the question is an open dialog
  (AskUserQuestion, a permission or guard prompt), a message can't answer it: list "answer <title> [id6] in its own
  window" under **Needs you now**.
- ACTIVE sessions are running, but you neither manage nor watch them: never peek or message them, and keep only their
  row (the state and last-active time the sweep or ListAgents shows). Drop the row once it has been inactive over
  12 h. An ACTIVE session the user asks you to follow changes level through the interview.
- Titles follow the level, one color per kind: 🟥🟥 the active guide, 🎟️🎟️ a retired guide, 🟧🟧 (g) MANAGED,
  ⬜⬜ WATCHED, 🟦🟦 ACTIVE, none IGNORED, ✅ closed. Whenever a session's level is set or changes, run
  `guide_title.py guided`, `watched`, `active` or `unguided` (IGNORED) on its session id; each one replaces the prefix it had. Guides and retired
  guides never get one.

### 4. Decisions
1. When a worker sends a question, check the ledger first. If it's already decided, relay that decision and don't
   ask again.
2. Otherwise ask the user (AskUserQuestion, at most 4 questions, recommended option first, with a worked example).
3. Write the answer to the ledger as **Decision N (date time, source) FINAL**, and relay it to every worker it
   touches. Strike through any decision it supersedes; don't delete it.
4. If the user answered a worker directly anyway (peek shows it), adopt that answer as the decision. If it
   contradicts an earlier one, ask the user which stands **before** anyone builds on it. This rule exists to prevent
   two conflicting rulings being in flight at once.

**Open items.** The guide keeps interviewing until every open item has an owner and a next action. It never parks an
item as "whenever you want" or FYI.
1. **After every worker report or handoff**, re-read it for loose ends: findings marked "not fixed", "out of scope",
   "follow-up", "FYI", a skipped step, a failing test left alone. Add each one to the ledger's Open items table
   with an owner, or with ASK in the Owner column when you don't know the owner yet. Every row has an owner or ASK.
2. **Owners** are an existing session (title [id6]) when the item sits in its stream and it has context to spare, "new
   session (proposed)" when nobody fits or the fitting worker is near its limit, or the user for what only the user
   can do (a merge, a dashboard, a person to ask).
3. **Every ask** (and so every wake and every status reply that leads to one) carries the rows whose Owner is ASK
   or "new session (proposed)" not yet started: at most 4 per ask, oldest first, each phrased as your recommended
   owner + action ("Start 'billing rounding fix' from develop to fix the 0.01 rounding on split invoices? (yes
   recommended)"). An item about money or a business rule carries a worked numeric example. Items past the 4 wait
   for the next round of the interview.
4. On the answer: write the owner into the row, relay the action to that session (or start the new session, §6), and
   log it. A "no" removes the row or makes the user its owner, as the user says.

**Results for you.** A finished deliverable the user asked for (a doc, a deck or slide, a review, a report, a release,
a PR ready for them) is not done until the user has seen it and said so.
1. When a worker reports one, checked (Look before done, §3), record it:
   `guide_title.py result "<deliverable>" <link> --from "<title [id6]>"`. That writes a row in the ledger's Results for
   you table, unanswered. Put it in this turn's status under **Results for you** (§5), with its link and one line on the
   result, and in this turn's interview.
2. The question: "<deliverable>: <link>. <one line on the result>." Satisfied / Change it / Drop it / Haven't looked yet.
   Record the answer: `guide_title.py result-answer "<deliverable>" satisfied|change|drop|not-looked`.
   - Satisfied: the stream may close its loose ends and go DONE.
   - Change it: the change goes to its worker (or a successor) as the stream's next step, with `--note`; when it is
     delivered again, run `result` again and ask again.
   - Drop it: the stream is dropped; its worker closes.
   - Haven't looked yet: ask which cadence to re-ask on (1, 2 or 8 hours; the default is 1) and record it with
     `--every <hours>`. `settle` and the hook list it again when it is due, and you ask again, until answered.
3. Until the answer is in, the stream is not DONE, its loose ends stay open, and its row stays in the table. The
   worker session may close in the meantime (its state is saved); the ledger row is what waits, not the session.

**Owed questions survive handoffs.** The moment you write that you owe the user a question later ("ask this
afternoon", "ask again when the deploy is done"), run `guide_title.py waiting ask "<the question, with the session it
came from>" --hours N` (or `--at "YYYY-MM-DD HH:MM"`). That is a dated row in the waiting table, so `settle` surfaces
it, in your session or a successor's, when it is due. A note in the log or a line in your head is not a reminder.

**The interview.** A question, decision or approval in your text is one the user can miss, so never end a turn on
one. Everything you need from the user goes through `AskUserQuestion`:
1. **Same turn.** Write the status in text if it changed (§5), then call the tool. Finish your relays and ledger writes
   first: while a dialog is open, you are likely paused and worker messages wait.
2. **Each question stands alone,** because the user may see only the dialog: session title [id6], the full link or
   `!` command, what you checked. Recommended option first.
3. **Order:** approvals a worker is blocked on, decisions, results with no verdict, owed questions that are due, new
   sessions, model switches, open items (a broken verification first, proposed follow-ups last, §7). At most 4
   questions per call.
   When the user answers, open the next round straight away until nothing is left.
4. **Shapes:**
   - New session: Manage / Watch / Leave active / Ignore. It gets a row at that level, and its title follows (§3).
   - Approval you can relay (a cost-guard `guard ok`, a go-ahead): Approve / Not now. On Approve, relay it and log it
     as a decision. It unblocks only what the user approved (§3).
   - Something only the user can do (a merge, a `!` command, a dialog open in another session's window, which a relay
     can't answer): the question carries the link or command, with Done / Not yet.
     To approve in that session's own window: "Open a new terminal tab and run
     `python3 ~/.claude/skills/session-guide/scripts/guide_approve.py <id8> \"<approval>\"` (or `claude attach <id8>`).
     Check the header names '<title>' before typing. Never `! claude attach` inside a Claude window." On Done, verify it. On Not yet,
     keep it under **Needs you now** and ask again at the next wake that has news on it.
   - Model switch (`references/model-choice.md`): "'<title>' [id6] runs <model>/<effort> on <task>; switch to
     <model>/<effort>? Type `/model <alias>` and `/effort <level>` in its window." Switched / Keep as is. You can't
     switch another session yourself. On Switched, check it on its next turn; on Keep as is, write "kept" in its row
     and don't ask again until its task changes.
   - Result with no verdict (§4, Results for you): "<deliverable>: <link>. <one line on the result>." Satisfied /
     Change it / Drop it / Haven't looked yet. A "Haven't looked yet" gets a second question straight away for the
     cadence (1, 2 or 8 hours), then `guide_title.py result-answer "<deliverable>" not-looked --every <hours>`.
   - Owed question that is due: the question itself, in its words, your recommendation first; then it is answered
     (`unwait <key>`) or the user picks when to ask again (`sleep <key> <hours>`).
   - Reminder that is due (§7), one question per session, with its full action: Done it / Nothing more to do: close it /
     Sleep 1, 2 or 8 hours / Sleep 12, 24 or 48 hours. A sleep answer gets a second question straight away with the exact
     periods, then `guide_title.py sleep <session id> <hours>`. On Done it, verify, then close the session or, if it has
     more to do, run `unwait` and send it the next step. If the check fails, say so and ask again.
5. **Unanswered means ask again,** at the next wake. Nothing is settled by your having mentioned it.
6. **Fallback.** Only when the tool is refused or unavailable (a `claude -p` run), put the question in your text and
   end with a line `needs input: <exactly what you need>`.

### 5. Status reply ("what's next", "where do we stand", and every wake that changes something)
```
**Needs you now**
1. <action only the user can do> — <session title [id6]> / PR link / exact `!` command
2. …
**Results for you**
- <deliverable>: <link> — <one line on the result> (finished since the last reply)
- <deliverable>: <link> — <one line>, asked HH:MM, no verdict yet
**Asleep**
- <session title [id6]>: <what it needs from the user>, reminder at HH:MM
**Streams**
- <stream>: <where it is> → next: <action> (<session title [id6]> or you)
**Proposed actions**
1. <action> on <session title [id6]>, or: start a new session '<title>' for <item>
**Running on its own**
- <what>, next check ~HH:MM
Guide context: <N>k (hand off at 120k)
```
- **Lead with what finished.** After the user's own actions, the first thing in every status reply is what finished
  since the last reply, each with its link, under "Results for you", before any stream line. A finished deliverable
  the user never saw the link for is not reported. The heading also carries the older deliverables still without a
  verdict (with when they were asked), and comes off only when the table has nothing unanswered. Each line there is a
  question in the interview that follows (§4, Results for you).
- "Asleep" lists the reminders the user put off, and the results the user hasn't looked at yet with their re-ask time;
  leave the heading out when there are none. Due reminders and due owed questions belong in "Needs you now".
- "Needs you now" lists only the user's actions, most urgent first. A merge comes with its PR link and what you
  checked (checks green, mergeable, deploy queue clear).
- Every Streams line ends with "→ next: <action> (owner)". A stream with no next action is DONE or gets one.
- "Proposed actions" lists the actions you suggest on active sessions and the new sessions you suggest starting,
  each put to the user as a question in the interview that follows (§4). Nothing in the reply is a passive list:
  every line is either the user's action, a stream's next action with its owner, or a proposed action.
- Mark something DONE only once it is verified (deploy job green, or the worker's evidence), and say how. For a
  user-visible deliverable the evidence is two things: the worker looked at it the way the user will (rendered, at
  the exact link) and saw the change (§3, Look before done), and the user answered Satisfied (§4, Results for you).
  "Delivered, unchecked" and "delivered, no verdict" are stream states, not DONE.
- The last line goes in every status reply, read from your own row in `claude-top --once`
  (CTX) or `peek.py <your id8>`. At 120k or more, hand off in this same turn (§8). Don't start another wake cycle.
- Then update the ledger (Streams, Results for you, Open items, Waiting on the user, and a log line).

### 6. Starting and closing worker sessions
- Start one when the user says to, or when a MANAGED worker handed off and its successor is the next step on the
  path. If the next step isn't obvious, ask once.
- Start it with `claude --bg --model <alias> --effort <level>` from the worker's worktree, giving it the worker's
  resume prompt plus the prompt suffix in `references/worker-contract.md`. Pick the model and effort from
  `references/model-choice.md` for the task it does first: money and business-rule fixes, release gates and design
  reviews get the top model at high effort; mechanical edits, CI reads, read-only checks and status reports get
  `sonnet` at low. Record its title, id and pick (`sonnet/low`) in the ledger as MANAGED, and run
  `guide_title.py guided <session id>`.
- A successor of a worker that handed off gets a fresh pick for the **next step's** task, never a copy of its
  predecessor's model and effort.
- Prefer a fresh session over pushing a worker that is near its context limit through more work.
- **Close** a MANAGED session once it is finished (DONE verified, nothing left for it or its subject: every loose end
  is resolved or sits in Open items with another owner) or obsolete (a successor took over, or the stream was dropped).
  A worker whose deliverable has no verdict yet (§4, Results for you) may close once its work is saved and reported,
  but its stream stays open and its Results row stays; a "Change it" starts a successor from its handoff.
  Closing is shaped like retiring a guide (§2):
  1. `python3 <skill dir>/scripts/guide_title.py done <session id>`. If no process holds the
     session it now reads "✅ " in place of "🟧🟧 (g) " at once; a running one changes when step 2's message reaches
     it, or at your next prompt after its process ends. The hook never gives it a guided, watched or guide title
     again. A sweep line "Closable: ..." means a row is DONE but the session is still orange: run `done` on it. A line
     "Held: ..." means it is closed but a process holds it: do step 2. A job state of done alone is not a reason to
     close.
  2. SendMessage it: "CLOSE: you are done; cancel your wakeups, use no tools, and reply with exactly: <one line on
     what you finished> / result: <title> closed".
  3. Check that its state now shows done (`claude-top --once`, STATE column). If it doesn't (it is blocked on a
     question, a permission prompt or a cost guard, so the message can't reach its Claude), list
     `! claude stop <session id>` under **Needs you now**.
     Stop sessions with one Bash call per session holding only `claude stop <id8>` (or `claude stop a && claude stop b`);
     never inside a loop, heredoc or next to ledger edits: the allow rule then doesn't match and auto mode blocks it.
  4. `done` also sets that session's Sessions row Level to DONE when it finds the guide's ledger (it says so when it
     can't: then set it yourself). The title's counts skip closed sessions and count a session once, at its topmost row.

### 7. Waiting and wakeups
- **Sweep on every turn**: a session active in the last 12 h with no row in the ledger's Sessions table is new. The
  title hook lists them at the top of each of your prompts and shows the count in your title; run
  `python3 <skill dir>/scripts/guide_title.py sweep <ledger>` if you didn't get that list. It needs neither
  claude-top nor ListAgents, and it reads only this machine's transcripts. A `ListAgents` row you add by hand must
  not be Remote Control (§2, step 4): another machine's sessions belong to its own guide. Run
  `guide_title.py active <session id>` on each, so it shows blue at once, peek it so you
  can recommend, and put it in this turn's interview (§4): "'X' [id6] is building the billing fix: manage it?" It
  stays new, and you keep asking, until the user picks a level. When the user picks Manage or Watch, check its model and
  effort as on a takeover (§2, step 4).
- **Open items on every wake**: re-check the reports and handoffs that arrived since the last wake for new items
  (§4, Open items), then put the rows still marked ASK or "new session (proposed)" into the interview.
- **Settle on every wake**: nothing the guide followed is forgotten. Every MANAGED or WATCHED session ends in one of
  two states, and `python3 <skill dir>/scripts/guide_title.py settle <ledger>` lists the ones that have gone 2 h quiet
  without reaching either (the hook lists them on each prompt too, with the reminders that are due):
  1. **Waiting on the user.** Still relevant, and only the user can move it: `guide_title.py waiting <session id>
     "<exact action, full link or command>"`. That writes a row in the ledger's waiting table, due now, so ask this turn
     (§4, Reminder). Each time it comes due, first check it still applies (peek, PR state), so the user is never asked
     about something already done. Until the user picks a sleep period, an unanswered reminder stays due. Send one
     `PushNotification` per wake that has due reminders, if you have the tool.
  2. **Done.** Finished, with no follow-ups on the session or its subject: close it (§6). `done` removes its reminder. A
     WATCHED session closes only on the user's yes, and that yes allows it the one CLOSE message.

  Anything else isn't settled yet. More work for it: send it the next step, and it stops being quiet. Blocked on an
  outside event with nothing for the user to do: a `waiting` row naming the event with a `sleep` you pick, and when it
  comes due re-check it, asking the user only if they are now needed. Not sure which: ask the user.
  `settle` also lists the results with no verdict and the owed questions that are due (§4): each one is a question in
  this turn's interview, every time, until it is answered.
- **Follow-ups, about once a day**: fixes and deployments get checked on real data, not just shipped. The review is due
  when the last one is older than `SESSION_GUIDE_FOLLOWUP_HOURS` (default 24; 0 turns it off); the hook says so on your
  prompt. Do it on a wake with nothing more urgent (no approval or decision waiting), or earlier on any quiet wake:
  1. `python3 <skill dir>/scripts/guide_title.py followups <ledger>` lists the PRs and versions that the ledger's
     last 3 days, or the reports in your sessions' transcripts, say reached production, staging, a merge or a release,
     with no row in the ledger's Verifications table, plus "not exercised yet" rows due for a re-check.
  2. Weed it: check each one really shipped (PR state, deploy job) and is a fix or behaviour change worth checking
     (a docs or test-only change, or the guide skill's own release, gets `verification <thing> skipped`). Find what
     it was meant to do: the PR body and your Decisions.
  3. Each one left becomes an Open items row, Owner "new session (proposed)", and `verification <thing> proposed`.
     It then goes through the normal Open items flow (§4), at most 4 per ask, production first:
     "Start 'verify #142' to check the refund fee fix on prod? It reads the merged diff, states what should happen
     now (a store-fault return of 200.00 on a 600.00 order refunds 200.00 with the 15.00 fee waived), then counts
     refunds since the 11:17Z deploy in the read-only prod DB and searches the logs for errors on that path.
     (yes recommended)"
  4. Stamp the review: `followups <ledger> --reviewed`.
  5. On yes, start the session from `references/verify-followup.md` with the brief filled in (§6, MANAGED, `sonnet`
     at medium), and record `verification <thing> running "'verify #142' [id6]"`. On no, `verification <thing>
     skipped`. Not now leaves the row ASK.
  6. On its report, record the verdict (`verified`, `not-exercised`, `broken`) with one line of evidence. A broken
     verdict becomes an Open items row for a fix and goes first in your next interview; a not-exercised one comes back
     for a re-check after 24 h. Its loose ends become Open items, and the session closes (§6).
- For an imminent event (the user's merge, a deploy job, CI finishing), schedule a wakeup in +5 min. For a long
  run (a full CI run, a test battery, a helper lane), use +10 min. Subscribe with `notify_when_idle` too: the notice
  is a hint, not a guarantee.
- **Always keep a wake scheduled while any session was active in the last 2 h,** even with nothing to wait for: it is
  how you notice new sessions, since nothing wakes you when one starts. Back off +30, then +60 at most, when nothing
  changes. After 2 h with no active session, the only wake left is for the reminders: one one-shot `CronCreate` at the
  "Next reminder" time `settle` prints (avoid minute :00 and :30), never a chain of hourly wakes, which pay for your whole
  context each time. If an earlier reminder appears, replace it. With no reminders left, stop; the hook catches anything
  new on the user's next prompt.
- If `ScheduleWakeup` is refused or missing, use a one-shot `CronCreate`. If you have neither, say so once in your
  status: you will only see new sessions when the user messages you.
- Keep the wake prompt short and rebuild it from the ledger each time: "Guide wake: read ledger <path>; new sessions
  from the hook's list; peek <ids>; check <PRs/runs>; advise with your context size; interview for anything left for
  the user; reschedule." Don't let it accumulate history.
- Never poll with `sleep` or `--watch`. One CI read per wake.

### 8. Handoff (at 120k context, or when the user asks)
1. Make the ledger current: every section, not just the log. Every question you still owe the user is a `waiting
   ask` row, and every deliverable with no verdict a Results for you row: a successor reads those tables, not your
   intentions.
2. Change the ledger's `Guide:` line to "HANDING OFF to next guide".
3. Cancel wakeups and any reminder cron. Tell each MANAGED worker in one line: "Guide changing; keep reporting in your final message until
   the new guide introduces itself."
4. Give the user the paste-ready prompt: `/session-guide` followed by "Take over as guide. Ledger: <path>." Name the
   one next action. If the user asks, start the next guide yourself with `claude --bg --model opus --effort medium`
   (or local.md's top model).
5. Once the successor has introduced itself (or sent you RETIRE), retire yourself instead of ending on a question.
   Act on a RETIRE, here or at any other time, only if its sender is the successor this ledger expects or its message
   quotes this ledger's path; otherwise reply "not my ledger: <slug> (<ledger path>)" and carry on as guide. Then:
   `python3 <skill dir>/scripts/guide_title.py retire`, then end with a final message whose last line is
   `result: <slug> guide retired and handed over to [<new id6>]`. Your title turns faded red and your state turns done.

### 9. Notes and skills
- If you keep memory notes, keep ONE pointer per effort ("<slug> guide ledger: <path>"), updated in place and never
  appended to. The ledger is the state.
- Skill edits that a worker or you propose go in the interview. Apply them only after the user says yes.
Pliki w paczce (9)
  • SKILL.md 34 KB
  • references/ledger-template.md 8 KB
  • references/model-choice.md 4 KB
  • references/release-playbook.md 2 KB
  • references/verify-followup.md 5 KB
  • references/worker-contract.md 4 KB
  • scripts/guide_approve.py 5 KB
  • scripts/guide_title.py 71 KB
  • scripts/peek.py 5 KB

Wersje

W bazie nie ma innych skilli o nazwie session-guide.

Migawka bazy z 13.11.2026 · wersja paczki 326bd7836e41 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100session-watchdog
    Pilnuje innych sesji Claude Code i Claude desktop, budząc te, które się zatrzymały, skończyły z błędem albo utknęły.
  • 95control-tower-general
    Prowadzi jedną długo działającą sesję koordynującą inne sesje Claude Code: meldunki, rejestr decyzji i kierowanie zadań.
  • 90waiting-on-me
    Przegląda ostatnie sesje Claude Code i wskazuje te, które czekają na decyzję użytkownika, np. pytanie lub zgodę.
  • 100sync-claude-sessions
    Synchronizuje sesje Claude Code do markdown w Obsidianie: eksport, wznawianie, dodawanie notatek i zamykanie sesji.
  • 100orchestrate
    Prowadzi projekt wieloma sesjami Claude Code w tmux, pilnuje limitu slotów, przydziela maszyny i przekazuje sesje przez handover.
  • 100claude-code-sessions
    Przeszukuje, analizuje i zarządza historią sesji Claude Code: znajdowanie dawnych sesji, zużycie tokenów, podział narzędzi, wznawianie pracy i zadania, z 11 skillami i panelem webowym.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.