From 60360be53a4de6a3161ce196372fb81dce14681b Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Thu, 16 Jul 2026 22:47:36 -0400 Subject: [PATCH] feat(session-flow)!: rename orchestration-brief skill to orchestrate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What - Rename the session-flow skill `orchestration-brief` to `orchestrate` (`git mv` preserves history): directory, frontmatter `name`, every `/session-flow:orchestration-brief` slash token, eval `skill_name` and prompts, the plugin.json skill enumeration, and both READMEs. The invocation is now `/session-flow:orchestrate`. - Add a seventh standing imperative, CALIBRATE TO CONDITIONS: size the whole orchestration (whether to delegate at all, fan-out width, nesting depth) to the active model's capability, advisor/verifier availability, context pressure, and concurrent-session / rate-limit headroom, with small/medium/large fan-out sizing and single-agent as the floor. Backed in context/sources.md with per-factor sourcing (canonical vs authoring convention marked, like imperative 6). - Bump session-flow 0.5.0 to 0.6.0 and record both changes in the plugin CHANGELOG. ## Why - The old name foregrounded the secondary export brief and undersold the skill's default action — arm/prime the current session. `orchestrate` is an action verb, matching this repo's action-skill naming convention (docs/MIGRATION-PLAYBOOK.md). Export modes (`handoff` / `worker`) are unchanged, and the exported document is still an orchestration brief. - The six imperatives specified how to delegate but not how to size delegation to the conditions in play; the calibration imperative closes that gap. Fresh-docs mandate: the skill invocation token derives from the directory name (https://code.claude.com/docs/en/skills, fetched 2026-07-16), so the rename is a directory move plus a matching display-`name`. Version-bump-as- delivery and the per-plugin CHANGELOG follow docs/MIGRATION-PLAYBOOK.md. BREAKING CHANGE: `/session-flow:orchestration-brief` no longer resolves; use `/session-flow:orchestrate`. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_013QfME4XhdvpZXAUinfomr5 --- README.md | 2 +- .../session-flow/.claude-plugin/plugin.json | 4 ++-- plugins/session-flow/CHANGELOG.md | 20 ++++++++++++++++ plugins/session-flow/README.md | 16 ++++++------- .../SKILL.md | 21 +++++++++++----- .../context/sources.md | 24 +++++++++++++++++++ .../evals/evals.json | 24 +++++++++---------- 7 files changed, 82 insertions(+), 29 deletions(-) rename plugins/session-flow/skills/{orchestration-brief => orchestrate}/SKILL.md (80%) rename plugins/session-flow/skills/{orchestration-brief => orchestrate}/context/sources.md (75%) rename plugins/session-flow/skills/{orchestration-brief => orchestrate}/evals/evals.json (61%) diff --git a/README.md b/README.md index a2ccab0b2..c6ddb6834 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace ### Workflow -- [`session-flow`](plugins/session-flow) — Session-lifecycle toolkit of four skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear, with optional --bg background-agent launch), retro (structured session retrospective with transcript metrics and learning codification), and orchestration-brief (arm a session or worker with proactive-orchestration imperatives). +- [`session-flow`](plugins/session-flow) — Session-lifecycle toolkit of four skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear, with optional --bg background-agent launch), retro (structured session retrospective with transcript metrics and learning codification), and orchestrate (arm a session or worker with proactive-orchestration imperatives). ### Project Management diff --git a/plugins/session-flow/.claude-plugin/plugin.json b/plugins/session-flow/.claude-plugin/plugin.json index f91c7a3a6..a52fcb0a6 100644 --- a/plugins/session-flow/.claude-plugin/plugin.json +++ b/plugins/session-flow/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "session-flow", - "version": "0.5.0", - "description": "Session-lifecycle toolkit of four skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear, with optional --bg background-agent launch), retro (structured session retrospective with transcript metrics and learning codification), and orchestration-brief (arm a session or worker with proactive-orchestration imperatives).", + "version": "0.6.0", + "description": "Session-lifecycle toolkit of four skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear, with optional --bg background-agent launch), retro (structured session retrospective with transcript metrics and learning codification), and orchestrate (arm a session or worker with proactive-orchestration imperatives).", "author": { "name": "Melodic Software", "email": "info@melodicsoftware.com" diff --git a/plugins/session-flow/CHANGELOG.md b/plugins/session-flow/CHANGELOG.md index 0c4330a47..ad2b29529 100644 --- a/plugins/session-flow/CHANGELOG.md +++ b/plugins/session-flow/CHANGELOG.md @@ -1,5 +1,25 @@ # Changelog — session-flow plugin +## 0.6.0 — 2026-07-16 + +Changed: + +- orchestration-brief renamed to `orchestrate`. The default action + arms/primes the current session — the skill's primary job — which the old + name undersold by foregrounding the secondary export brief; the verb also + matches the action-skill naming convention. Invocation is now + `/session-flow:orchestrate`; the old `/session-flow:orchestration-brief` + token no longer resolves. Export modes are unchanged (`handoff` / `worker` + args), and the exported document is still an orchestration brief. + +Added: + +- orchestrate: seventh imperative CALIBRATE TO CONDITIONS — size the whole + orchestration (whether to delegate at all, fan-out width, nesting depth) to + the active model's capability, advisor/verifier availability, context + pressure, and concurrent-session / rate-limit headroom, with + small/medium/large fan-out sizing and single-agent as the floor. + ## 0.5.0 — 2026-07-15 Added: diff --git a/plugins/session-flow/README.md b/plugins/session-flow/README.md index 6d4c71c8a..1d4e8bb0d 100644 --- a/plugins/session-flow/README.md +++ b/plugins/session-flow/README.md @@ -9,7 +9,7 @@ how to arm it for delegation-heavy tasks. | `/session-flow:workflow` | Where am I in the staged dev workflow, and what comes next? | | `/session-flow:handoff` | How do I save this session's state so a fresh `/clear` session resumes without rediscovery? | | `/session-flow:retro` | What happened this session, what did we learn, and how do we codify it? | -| `/session-flow:orchestration-brief` | How do I arm this session (or a spawned worker) with proactive-orchestration imperatives? | +| `/session-flow:orchestrate` | How do I arm this session (or a spawned worker) with proactive-orchestration imperatives? | ## What each skill does @@ -61,17 +61,17 @@ codifies user-approved learnings. Health scores persist across sessions for tren /session-flow:retro quick # abbreviated, for limited context ``` -### orchestration-brief +### orchestrate -Arms the current session for an orchestration-heavy task by loading six proactive-orchestration +Arms the current session for an orchestration-heavy task by loading seven proactive-orchestration imperatives (delegate/fan-out, spec-every-spawn, fresh-context verify, run-workers-well, nested -subagents, surface drift) as standing instructions — or exports them as a paste-ready, tool-agnostic -brief for a spawned worker or fresh session. +subagents, surface drift, calibrate-to-conditions) as standing instructions — or exports them as a +paste-ready, tool-agnostic brief for a spawned worker or fresh session. ```shell -/session-flow:orchestration-brief # prime this session -/session-flow:orchestration-brief worker # paste-ready worker brief -/session-flow:orchestration-brief handoff compact # headline-only fresh-session brief +/session-flow:orchestrate # prime this session +/session-flow:orchestrate worker # paste-ready worker brief +/session-flow:orchestrate handoff compact # headline-only fresh-session brief ``` ## Consumer conventions diff --git a/plugins/session-flow/skills/orchestration-brief/SKILL.md b/plugins/session-flow/skills/orchestrate/SKILL.md similarity index 80% rename from plugins/session-flow/skills/orchestration-brief/SKILL.md rename to plugins/session-flow/skills/orchestrate/SKILL.md index 41b537d6e..dccfd6de4 100644 --- a/plugins/session-flow/skills/orchestration-brief/SKILL.md +++ b/plugins/session-flow/skills/orchestrate/SKILL.md @@ -1,6 +1,6 @@ --- -name: orchestration-brief -description: "Arm the CURRENT session for an orchestration-heavy task by loading six proactive-orchestration imperatives (delegate/fan-out, spec-every-spawn, fresh-context verify, run-workers-well, nested subagents, surface drift) as active standing instructions; optionally export them as a paste-ready brief for a spawned worker or fresh session. Use when: 'orchestration brief', 'prime this session', 'arm for orchestration', 'about to do heavy delegation', 'worker spawn prompt', 'delegation preamble'." +name: orchestrate +description: "Arm the CURRENT session for an orchestration-heavy task by loading seven proactive-orchestration imperatives (delegate/fan-out, spec-every-spawn, fresh-context verify, run-workers-well, nested subagents, surface drift, calibrate-to-conditions) as active standing instructions; optionally export them as a paste-ready brief for a spawned worker or fresh session. Use when: 'orchestrate', 'orchestration brief', 'prime this session', 'arm for orchestration', 'about to do heavy delegation', 'worker spawn prompt', 'delegation preamble'." argument-hint: "[] | handoff [compact] | worker [compact]" user-invocable: true disable-model-invocation: false @@ -9,7 +9,7 @@ disable-model-invocation: false ## Purpose Invoking this skill **arms the current session** for an orchestration-heavy task: it loads the -expanded six-imperative operational form into active working context, and it declares deliberate +expanded seven-imperative operational form into active working context, and it declares deliberate intent to orchestrate the work about to start, so the triggers get evaluated actively rather than sitting passively in background rules. That is the default — no paste, no rails, just preloaded context. @@ -57,6 +57,15 @@ told: nesting level. 6. SURFACE DRIFT — the moment you notice a stale reference, broken citation, or convention conflict adjacent to your task, flag it in one line; don't fix it silently, don't deep-dive. +7. CALIBRATE TO CONDITIONS — size the whole orchestration (whether to delegate at all, fan-out + width, nesting depth) to the conditions in play, never a fixed recipe: the active model's + capability (a stronger model reaches further single-agent; a weaker one needs more decomposition + and tighter specs), whether a capable advisor/verifier is on hand, current context pressure + (delegate to protect a filling window; stay inline when it is roomy), and concurrent-session load + / rate-limit headroom (thin headroom caps how many workers you run at once). Sizing is + small/medium/large — a small ask stays single-agent, a medium one fans out a few, only a large + genuinely-independent surface earns a wide or nested tree. Single-agent is the floor, not the + fallback. Discipline: trigger-evaluation is mandatory; the ACTION stays calibrated (delegate on value + parallelism, not convenience). Treat every worker's return as unverified synthesis — verify @@ -70,7 +79,7 @@ surfaces. ## Export modes (handoff / worker) — paste-ready brief -Only for a target that LEAVES the session. Emit the six imperatives above between two full-width +Only for a target that LEAVES the session. Emit the seven imperatives above between two full-width `─` (U+2500) dashed rails — top rail, brief, bottom rail, nothing else between them; the `/clear`/paste instruction or any commentary sits above the top rail or below the bottom rail, never between (NOT a code fence — the user copies the text between the rails, not fence markers). @@ -82,7 +91,7 @@ Live shape: bare `─` rails, no fence — shown inside a fence here for display ORCHESTRATION BRIEF — standing instructions for the whole task, regardless of which model or tool runs you. At each decision boundary, evaluate these and ACT on a match without waiting to be told: -[the six numbered imperatives above, verbatim] +[the seven numbered imperatives above, verbatim] Discipline: [the Discipline line above, verbatim] ────────────────────────────────────────────────────────── @@ -92,7 +101,7 @@ Discipline: [the Discipline line above, verbatim] - `worker` — insert as the FIRST line between the rails: `You are a spawned worker and did NOT inherit the parent session's context or the repo's conditional rules — these instructions are your only copy.` -- `compact` — emit only the six numbered HEADLINES (`1. DELEGATE / FAN OUT`, `2. SPEC EVERY +- `compact` — emit only the seven numbered HEADLINES (`1. DELEGATE / FAN OUT`, `2. SPEC EVERY SPAWN`, …) plus the closing Discipline line; drop every sub-clause. ## What this skill does NOT do diff --git a/plugins/session-flow/skills/orchestration-brief/context/sources.md b/plugins/session-flow/skills/orchestrate/context/sources.md similarity index 75% rename from plugins/session-flow/skills/orchestration-brief/context/sources.md rename to plugins/session-flow/skills/orchestrate/context/sources.md index 90f43344c..ea9bbbe36 100644 --- a/plugins/session-flow/skills/orchestration-brief/context/sources.md +++ b/plugins/session-flow/skills/orchestrate/context/sources.md @@ -88,3 +88,27 @@ reliability degradation with depth plus the platform caps above. Authoring convention, NOT canonical Anthropic orchestration guidance (it appears in none of the multi-agent sources). Kept in the brief because drift-flagging is useful for any worker: a one-line flag preserves the signal without derailing the task. + +## Imperative 7 — CALIBRATE TO CONDITIONS + +Part-sourced, part authoring convention — the boundary is called out per factor. + +- **Size effort to complexity (S/M/L).** "Simple fact-finding requires just 1 agent with 3–10 tool + calls … complex research might use more than 10 subagents." *(paraphrase — same quote backing + imperative 2)* — +- **Single-agent is the floor; multi-agent is spent, not defaulted.** The 3–10× cost multiplier and + "coordination costs typically exceed the benefits" outside context-protection / parallelization / + specialization (both quotes backing imperative 1) are the reason a small ask stays single-agent. + *(paraphrase)* — + + + +- **Model capability shifts the sizing.** The Fable 5 guide frames delegation as a capability the + orchestrator wields deliberately (async dispatch, long-lived subagents, monitor-and-steer — the + quotes backing imperative 4), which presumes a model strong enough to orchestrate well; a weaker + model needs more decomposition and tighter specs. *(interpretation of the same guide)* — + +- **Advisor / verifier availability, context pressure, and concurrent-session / rate-limit + headroom** are operational authoring convention, NOT canonical Anthropic orchestration guidance — + they scale the same underlying trade-offs (a fresh-context verifier is worth leaning on when one + is on hand; a filling window is itself the context-protection trigger imperative 1 names; thin + rate-limit headroom is a hard ceiling on parallel workers). diff --git a/plugins/session-flow/skills/orchestration-brief/evals/evals.json b/plugins/session-flow/skills/orchestrate/evals/evals.json similarity index 61% rename from plugins/session-flow/skills/orchestration-brief/evals/evals.json rename to plugins/session-flow/skills/orchestrate/evals/evals.json index d729150f2..21aa70bcd 100644 --- a/plugins/session-flow/skills/orchestration-brief/evals/evals.json +++ b/plugins/session-flow/skills/orchestrate/evals/evals.json @@ -1,11 +1,11 @@ { - "skill_name": "orchestration-brief", + "skill_name": "orchestrate", "evals": [ { "id": 1, "name": "default-primes-no-paste", - "prompt": "Orchestration brief — I'm about to fan out a big multi-file audit across the codebase.", - "expected_output": "The default action PRIMES the current session: it acknowledges tersely that the six orchestration imperatives are now active for the upcoming task, with one line orienting to the audit. It does NOT re-emit the imperatives as paste text and does NOT print dashed rails — loading them into context IS the priming.", + "prompt": "Orchestrate — I'm about to fan out a big multi-file audit across the codebase.", + "expected_output": "The default action PRIMES the current session: it acknowledges tersely that the seven orchestration imperatives are now active for the upcoming task, with one line orienting to the audit. It does NOT re-emit the imperatives as paste text and does NOT print dashed rails — loading them into context IS the priming.", "files": [], "expectations": [ "The response is a terse acknowledgment that the orchestration imperatives are now active for the upcoming task", @@ -16,11 +16,11 @@ { "id": 2, "name": "handoff-export-rails", - "prompt": "/orchestration-brief handoff — give me the brief to paste into a fresh session after I /clear.", - "expected_output": "The handoff export emits the six orchestration imperatives plus the closing Discipline line between two full-width U+2500 dashed rails, framed for a fresh session, with any /clear-or-paste commentary above the top rail or below the bottom rail — never between.", + "prompt": "/orchestrate handoff — give me the brief to paste into a fresh session after I /clear.", + "expected_output": "The handoff export emits the seven orchestration imperatives plus the closing Discipline line between two full-width U+2500 dashed rails, framed for a fresh session, with any /clear-or-paste commentary above the top rail or below the bottom rail — never between.", "files": [], "expectations": [ - "The six imperatives and the Discipline line are emitted between two full-width U+2500 dashed rails, not a markdown fence", + "The seven imperatives and the Discipline line are emitted between two full-width U+2500 dashed rails, not a markdown fence", "Nothing sits between the rails except the brief — commentary/instructions are above the top rail or below the bottom rail", "The brief is framed for a fresh session (handoff framing), not a spawned worker" ] @@ -28,23 +28,23 @@ { "id": 3, "name": "worker-export-inherit-line", - "prompt": "/orchestration-brief worker — I'm spawning a subagent and need the standing instructions for it.", - "expected_output": "The worker export inserts, as the FIRST line between the rails, the did-not-inherit-context line ('You are a spawned worker and did NOT inherit the parent session's context...'), then the six imperatives and Discipline line, all between two dashed rails.", + "prompt": "/orchestrate worker — I'm spawning a subagent and need the standing instructions for it.", + "expected_output": "The worker export inserts, as the FIRST line between the rails, the did-not-inherit-context line ('You are a spawned worker and did NOT inherit the parent session's context...'), then the seven imperatives and Discipline line, all between two dashed rails.", "files": [], "expectations": [ "The first line between the rails is the did-not-inherit-context notice for a spawned worker", - "The six imperatives and the Discipline line follow between the same two dashed U+2500 rails", + "The seven imperatives and the Discipline line follow between the same two dashed U+2500 rails", "The export omits the priming addendum about agent teams / dynamic workflows (a spawned worker cannot reach those surfaces)" ] }, { "id": 4, "name": "compact-headlines-only", - "prompt": "/orchestration-brief handoff compact", - "expected_output": "The compact modifier emits only the six numbered HEADLINES (1. DELEGATE / FAN OUT, 2. SPEC EVERY SPAWN, ...) plus the closing Discipline line between the rails, dropping every sub-clause.", + "prompt": "/orchestrate handoff compact", + "expected_output": "The compact modifier emits only the seven numbered HEADLINES (1. DELEGATE / FAN OUT, 2. SPEC EVERY SPAWN, ...) plus the closing Discipline line between the rails, dropping every sub-clause.", "files": [], "expectations": [ - "Only the six numbered headlines plus the Discipline line appear between the rails", + "Only the seven numbered headlines plus the Discipline line appear between the rails", "The per-imperative sub-clauses are dropped", "It is still emitted as a paste-ready dashed-rail export (handoff framing)" ]