setup
Verify the session-flow observer's runtime prerequisites and configuration for this machine, and write the repository's docs/conventions/session-flow.yaml after confirmation. Use when: 'set up session-flow', 'configure the observer', 'is the observer working', 'set worker_continuation for this repo', the SessionStart observer isn't arming, or the observer hook reported a missing prerequisite. Actions: check (read-only, default), apply (writes docs/conventions/session-flow.yaml only). Installs nothing. Re-runnable.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- description
- Verify the session-flow observer's runtime prerequisites and configuration for this machine, and write the repository's docs/conventions/session-flow.yaml after confirmation. Use when: 'set up session-flow', 'configure the observer', 'is the observer working', 'set worker_continuation for this repo', the SessionStart observer isn't arming, or the observer hook reported a missing prerequisite. Actions: check (read-only, default), apply (writes docs/conventions/session-flow.yaml only). Installs nothing. Re-runnable.
- argument-hint
- [check|apply] [<key>=<value> ...]
- user-invocable
- true
- disable-model-invocation
- true
02 资源文件 3
- 参考文档evals/evals.json6.1 KB
- 脚本scripts/setup-apply.mjs1.1 KB
- 脚本scripts/setup-apply.test.sh18.2 KB
03 SKILL.md 正文
Purpose
Two kinds of configuration. The detached observer (see
${CLAUDE_PLUGIN_ROOT}/reference/observer.md) has
runtime prerequisites (Node.js, Python 3.10+, jq) and native userConfig tunables; setup reports
both and writes neither (writing pluginConfigs is what the setup contract forbids). The plugin
also owns one tracked consumer file, docs/conventions/session-flow.yaml, the repository layer of
the keys skills read in their own text (keys, values and layers:
${CLAUDE_PLUGIN_ROOT}/reference/config.md; schema:
${CLAUDE_PLUGIN_ROOT}/schemas/session-flow.schema.json). check reports that file; apply
writes it and nothing else.
Action routing: no argument or check runs the check; apply runs the check, then writes.
Re-running either reads the current state again.
check (read-only)
The hook and launcher are the single source of truth for what they require and how they degrade:
${CLAUDE_PLUGIN_ROOT}/hooks/observer-arm.sh, ${CLAUDE_PLUGIN_ROOT}/skills/running-retro/scripts/arm_observer.py,
and observer.py beside it.
Read it first. Probe what it actually does, don't recite this file. Then run each probe via Bash and report a PASS/FAIL/INFO table with one remediation line per FAIL. Do not modify anything.
When the observer is disabled (observer_enabled off AND no arm invocation in use), every
prerequisite absence downgrades from FAIL to INFO, the hook exits through its opt-in gate before
touching anything, so a deliberately disabled plugin is not broken. Report the probes informationally
and note that re-enabling restores the FAIL semantics.
- Node.js on PATH, every hook row runs through
node ${CLAUDE_PLUGIN_ROOT}/hooks/exec-bash.mjs. Probenode --versionthrough Bash. FAIL if absent: the hook does not launch, so the observer never arms. Remediation: install Node.js on PATH (https://nodejs.org/en/download). - Python 3.10+, the launcher and tailer are stdlib-only Python 3.10+. Probe the same interpreter
detection the hook uses (
python3thenpython, requiringsys.version_info >= (3, 10)). FAIL if none qualifies: without it the hook silently skips arming. Remediation: install Python 3.10+ on PATH. jq, the SessionStart hook parses its stdin (session_id,transcript_path,source,agent_type) withjq. FAIL (auto-arm path only) if absent: the hook exits early and never arms. The manualarmaction resolves inputs withoutjq, so absence is INFO for that path. Remediation: installjq(https://jqlang.org/download/).claudeCLI on PATH, the autonomous analysis leg invokesclaude -p. INFO if absent: the observer still distills and retains observations under its plugin work dir; the analysis run is skipped and nothing is written to the ledger.- Observer config. Report the effective value of each native key (an unexpanded
${user_config.…}token or empty means the default):${user_config.observer_enabled}(default off),${user_config.observer_analysis_enabled}(default on),${user_config.observer_analysis_model}and${user_config.observer_analysis_effort}(defaults: read each key'sdefaultfrom${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.jsonuserConfig, never from memory),${user_config.observer_analysis_bare}(default off),${user_config.observer_idle_seconds}(default 900),${user_config.observer_poll_seconds}(default 5),${user_config.observer_max_seconds}(default 86400). Call out two hazards:observer_analysis_bareon is a FAIL on an OAuth-login install (what bare mode does with OAuth credentials: https://code.claude.com/docs/en/headless#start-faster-with-bare-mode);observer_idle_secondsbelow the machine's longest expected single turn risks firing analysis on a partial transcript. - Hook registration. INFO: confirm the plugin is enabled for this project (
/plugin→ Installed) rather than parsing settings files. The SessionStart hook only auto-arms whenobserver_enabledis on. - Repository settings. Run
node "${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" --checkfrom the project root. INFO whendocs/conventions/session-flow.yamlis absent (every key comes fromuserConfigor its default); PASS with each key's value when the file validates; WARN, never FAIL, when it does not (an invalid value, an unknown or repeated key, an empty or non-scalar value, or a path that is not a plain file), quoting the line the script prints. An invalid value never stops a session-flow skill: the skill names it and drops that layer. An unknown key is named and ignored, and the valid keys still print.applyoverwrites only a value that is out of the list, empty or null; it refuses every other shape (a repeated key, an unknown key holding a map or list, a map or list, an empty quoted string), which the operator fixes by hand.
apply (writes docs/conventions/session-flow.yaml only)
-
Run
checkand show its table. -
Resolve the values. With complete
<key>=<value>arguments, use them. Otherwise ask one key at a time, recommendation first, from the table in${CLAUDE_PLUGIN_ROOT}/reference/config.md(worker_continuation:resume, the default, unless the team wants each new unit in a fresh worker;wip_commit:false, the default, unless the team wants a pause handoff to make one localchore(wip):commit, an unquotedtrueorfalse;transcript_scope: leave it unset unless the team wants to narrow every member's/session-flow:find-handoffand/session-flow:recallscans toworktreeorrepo, since this key can only narrow a user's option, never widen it). Never invent a key the schema does not list. -
Write. One call with every value:
node "${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" worker_continuation=respawnPass a key the operator accepts at the plugin default as
--default <key>instead of<key>=<value>, so a later change to that default reaches it;<key>=<value>records the team's choice, which the script never changes. The script also recordswritten_againstandprovenance:, so a file with no record, or one written against another plugin version, shows a diff even when no value changes.The script checks each value against the schema, refuses a key given twice, validates the existing file first (refusing it unless every problem is a value out of the list, empty or null, or an unknown key it names in one warning and keeps as written), and validates the whole resulting file (no repeated key, one non-empty scalar per key) before it writes; any refusal exits 1 and writes nothing. It writes only
<git toplevel>/docs/conventions/session-flow.yaml: it resolves a symlinked root first, then refuses a root that is$HOMEor an ancestor of it, a symlink on that path, ondocsor ondocs/conventions, a directory resolving outside the repository, and a target with more than one hard link, and writes through a temp file renamed into place. A missing file is created. A value already in place printsalready configuredand writes nothing. -
An existing file that would change exits 3 and prints a unified diff without writing. Show the operator that diff and ask whether to write it. Only on an explicit yes, re-run the same call with
--yes; on anything else, stop with the file unchanged. A request to "set it" is not a yes to a diff the operator has not seen. When the convention-home offer prints below the diff, ask about it too (the next step) before any re-run, since--yeswrites both. -
The convention-home offer. When the repository's
AGENTS.mdorCLAUDE.mdbinds no convention home, the script prints an offer: with the operator's confirmation it adds a convention-home pointer region to that instruction file (creatingAGENTS.mdwhen neither exists orCLAUDE.mdonly imports it) and the personal override ignore linedocs/conventions/**/*.local.*to.gitignore, the only filesapplywrites outsidedocs/conventions/. It prints the offer at the end of an exit 0 run and below the diff of an exit 3 run, so show the operator stdout on exit 0 too. Ask whether to add the region and the ignore line. Only on an explicit yes, re-run the same call with--yes, which also writes any diff shown with it. On a no, runnode "${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" --declinealone: it records the decline in the instruction file, and the next run does not offer again. To write a shown diff without the region, run--declinefirst, then the same call with--yes. When the instruction file or.gitignoreis a symlink or hard link the script will not write through, it prints a one-line refusal in place of the offer, with the same exit code: show it, and do not re-run with--yes, which that refusal stops with exit 1. A refused instruction file refuses--declinetoo, so the operator fixes the link or adds the region by hand. -
Verify. Re-run
checkand report the value from its table, not from the write. Then the tracked-file pair:git check-ignore -v docs/conventions/session-flow.yamlreports no match (a match means the team never receives the file: say so, and leave.gitignoreto the operator), andgit ls-files --error-unmatch docs/conventions/session-flow.yamlexits 0. Non-zero right after a fresh write means "written but untracked: commit it to share with the team", never success.
Remediation guidance (printed by check; the operator applies it)
For the observer there is no write path. For each FAIL, check closes by offering the remediation: install the missing
tool, or route observer reconfiguration through Claude Code's native flow.
Do not write the plugin cache, Claude Code user settings, or pluginConfigs.
Reconfigure the observer's userConfig keys through Claude Code's native flow, interactively with
/plugin configure session-flow@<marketplace> or by a headless route, as the marketplace's
plugin-reconfiguration convention gives them in
§ The routes
(it owns the verified-version record). Apply the scope and failure-signal caveats in its
§ Caveats every setup skill's short form carries.
Read both sections and print what they give, the fallback route, its behavior on an
already-installed plugin and the scope to pass included, rather than only naming them, and
leave out the verified-version record.
Never uninstall to reconfigure; that section links what an uninstall deletes. Afterwards rerun
check in a fresh session, since a same-session check can still show the old value, and
report the observed effective value, never an unobserved change.
- Pointer: for the headless command's flags, how it reports a saved or refused value, and when a saved value applies, fetch plugin CLI reference § plugin configure live.
Output
check: the PASS/FAIL/INFO/WARN table with one remediation line per FAIL. apply: the table
before and after, the diff when one was shown, the written path, and whether the file is tracked.
Next
/session-flow:orchestrate, which reads worker_continuation; /session-flow:retro, whose session mode
reads retro_lenses; /session-flow:handoff, which reads
wip_commit; /session-flow:find-handoff and /session-flow:recall, which read transcript_scope;
/session-flow:recall, which also reads recall_report_kinds and recall_doc_paths.
Gotchas
- Prerequisites are the observer's, plus
jqfor retro's docs reads andghfor/session-flow:recall's pull request reads./session-flow:find-handoffuses Python 3.10+ when present and lists fewer transcript directories without it. The other session-flow skills need no installed tool. The repository settings areworker_continuation, read by/session-flow:orchestrate,retro_lenses, read by/session-flow:retrosession mode,wip_commit, read by/session-flow:handoff, andtranscript_scope, read by/session-flow:find-handoffand/session-flow:recall, where the narrower layer wins, andrecall_report_kindsandrecall_doc_paths, read by/session-flow:recall. - The repository file reaches the team only once committed.
applyleaves it uncommitted on purpose, and the tracked-file pair says so. observer_analysis_bareand auth. Leave it off unless auth is an env-var API key (why: the bare-mode pointer incheckstep 5). Full detail in${CLAUDE_PLUGIN_ROOT}/reference/observer.md.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').