AGENT SKILL

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

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.

  1. Node.js on PATH, every hook row runs through node ${CLAUDE_PLUGIN_ROOT}/hooks/exec-bash.mjs. Probe node --version through 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).
  2. Python 3.10+, the launcher and tailer are stdlib-only Python 3.10+. Probe the same interpreter detection the hook uses (python3 then python, requiring sys.version_info >= (3, 10)). FAIL if none qualifies: without it the hook silently skips arming. Remediation: install Python 3.10+ on PATH.
  3. jq, the SessionStart hook parses its stdin (session_id, transcript_path, source, agent_type) with jq. FAIL (auto-arm path only) if absent: the hook exits early and never arms. The manual arm action resolves inputs without jq, so absence is INFO for that path. Remediation: install jq (https://jqlang.org/download/).
  4. claude CLI on PATH, the autonomous analysis leg invokes claude -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.
  5. 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's default from ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json userConfig, 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_bare on 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_seconds below the machine's longest expected single turn risks firing analysis on a partial transcript.
  6. Hook registration. INFO: confirm the plugin is enabled for this project (/plugin → Installed) rather than parsing settings files. The SessionStart hook only auto-arms when observer_enabled is on.
  7. Repository settings. Run node "${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" --check from the project root. INFO when docs/conventions/session-flow.yaml is absent (every key comes from userConfig or 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. apply overwrites 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)

  1. Run check and show its table.

  2. 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 local chore(wip): commit, an unquoted true or false; transcript_scope: leave it unset unless the team wants to narrow every member's /session-flow:find-handoff and /session-flow:recall scans to worktree or repo, since this key can only narrow a user's option, never widen it). Never invent a key the schema does not list.

  3. Write. One call with every value:

    node "${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" worker_continuation=respawn
    

    Pass 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 records written_against and provenance:, 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 $HOME or an ancestor of it, a symlink on that path, on docs or on docs/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 prints already configured and writes nothing.

  4. 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 --yes writes both.

  5. The convention-home offer. When the repository's AGENTS.md or CLAUDE.md binds no convention home, the script prints an offer: with the operator's confirmation it adds a convention-home pointer region to that instruction file (creating AGENTS.md when neither exists or CLAUDE.md only imports it) and the personal override ignore line docs/conventions/**/*.local.* to .gitignore, the only files apply writes outside docs/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, run node "${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" --decline alone: 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 --decline first, then the same call with --yes. When the instruction file or .gitignore is 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 --decline too, so the operator fixes the link or adds the region by hand.

  6. Verify. Re-run check and report the value from its table, not from the write. Then the tracked-file pair: git check-ignore -v docs/conventions/session-flow.yaml reports no match (a match means the team never receives the file: say so, and leave .gitignore to the operator), and git ls-files --error-unmatch docs/conventions/session-flow.yaml exits 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.

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 jq for retro's docs reads and gh for /session-flow:recall's pull request reads. /session-flow:find-handoff uses Python 3.10+ when present and lists fewer transcript directories without it. The other session-flow skills need no installed tool. The repository settings are worker_continuation, read by /session-flow:orchestrate, retro_lenses, read by /session-flow:retro session mode, wip_commit, read by /session-flow:handoff, and transcript_scope, read by /session-flow:find-handoff and /session-flow:recall, where the narrower layer wins, and recall_report_kinds and recall_doc_paths, read by /session-flow:recall.
  • The repository file reaches the team only once committed. apply leaves it uncommitted on purpose, and the tracked-file pair says so.
  • observer_analysis_bare and auth. Leave it off unless auth is an env-var API key (why: the bare-mode pointer in check step 5). Full detail in ${CLAUDE_PLUGIN_ROOT}/reference/observer.md.

04 同仓库更多 Skills

melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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.

★ 30
melodic-software
melodic-software/claude-code-plugins

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').

★ 30