session-orchestrator 3.16.0

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: skill-creator
+description: Use when creating a new skill from scratch, modifying an existing skill, or optimizing a skill's triggering description. Guides intent capture, structure, writing patterns, and progressive-disclosure organization so skills reliably trigger and stay maintainable. Trigger on phrases like "turn this into a skill", "write a skill for X", "improve this skill", "my skill isn't triggering".
+model: sonnet
+---
+
+# Skill Creator
+
+A process skill for writing skills well.
+
+Adapted from [anthropics/skills/skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) — we keep the authoring workflow and progressive-disclosure guidance but drop the Python eval-viewer harness (not part of our stack).
+
+## The loop
+
+1. **Capture intent** — what should the skill do? When should it trigger?
+2. **Draft** SKILL.md with frontmatter + body
+3. **Test** — 2–3 realistic prompts, see if Claude triggers + executes right
+4. **Improve** based on failures (wrong trigger, wrong output, over-verbose, etc.)
+5. **Optimize description** if triggering is unreliable
+
+## 1. Capture Intent
+
+If the user said "turn X into a skill", extract from conversation history: the tools used, the sequence of steps, corrections the user made, input/output formats observed. Confirm gaps before proceeding.
+
+Ask explicitly:
+1. What should this skill enable Claude to do?
+2. When should it trigger? (user phrases / contexts)
+3. What's the expected output format?
+4. Does this skill have objectively verifiable outputs? (if yes, test cases help; if subjective like writing style / art, skip them)
+
+## 2. Write the SKILL.md
+
+### Frontmatter
+
+```yaml
+---
+name: kebab-case-name
+description: One or two sentences covering what it does AND when to trigger. Mention multiple trigger phrases/contexts (Claude tends to UNDER-trigger — err on "pushy").
+---
+```
+
+**Description anti-patterns:**
+- ❌ "How to build a dashboard." (no triggers)
+- ✅ "Use when building a dashboard, visualizing data, or displaying metrics — trigger even if the user doesn't say 'dashboard' but mentions charts, KPIs, or metric displays."
+
+### Body anatomy
+
+```
+skill-name/
+├── SKILL.md           (required — frontmatter + body, <500 lines ideal)
+├── scripts/           (optional — executable code for deterministic/repetitive tasks)
+├── references/        (optional — docs loaded into context only when needed)
+└── assets/            (optional — templates, fixtures)
+```
+
+### Progressive disclosure
+
+Skills load in three levels:
+1. **Frontmatter** — always in Claude's context (~100 tokens)
+2. **SKILL.md body** — loaded when skill triggers (keep <500 lines)
+3. **Reference files** — loaded on demand (unlimited size, cite with clear "read when X" guidance)
+
+If SKILL.md exceeds 500 lines, split by domain:
+
+```
+cloud-deploy/
+├── SKILL.md              (workflow + "if AWS: read references/aws.md")
+└── references/
+    ├── aws.md
+    ├── gcp.md
+    └── azure.md
+```
+
+## 3. Writing patterns
+
+### Imperative voice
+
+Prefer "Write tests for X" over "Tests should be written for X". Agents respond better to direct instruction.
+
+### Explain the WHY
+
+LLMs are smart. When you write a rule, explain why — the agent can then handle edge cases intelligently. If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag: reframe and explain.
+
+**Bad:** "ALWAYS use parameterized queries."
+**Good:** "Use parameterized queries. Reason: string-concatenation SQL is the #1 injection vector in our incident history."
+
+### Output format blocks
+
+When the skill produces structured output:
+
+```markdown
+## Report structure
+Always use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+```
+
+### Examples
+
+```markdown
+## Commit message format
+**Example 1:**
+Input:  Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+## 4. Test cases
+
+Write 2–3 realistic test prompts — the kind a real user would actually type (include file paths, specific contexts, casual speech, typos). Run Claude with + without the skill and compare.
+
+**Bad test prompts:** "Format this data", "Create a chart" — too abstract.
+**Good test prompts:** "ok so my boss sent me Q4_sales_FINAL_v2.xlsx and wants a profit-margin column (revenue col C, cost col D)" — concrete, realistic.
+
+Coordinator-direct in our harness: dispatch two Agent() calls (one with skill-path, one without) and compare outputs qualitatively. We do NOT run the upstream Python eval viewer — that's over-engineered for our workflow.
+
+## 5. Description optimization
+
+If the skill doesn't trigger reliably, the description is usually at fault.
+
+Generate 20 eval queries:
+- 8–10 **should-trigger** (different phrasings, casual/formal, edge cases)
+- 8–10 **should-not-trigger** — near-misses that share keywords but need different handling
+
+Score the current description against these queries. Rewrite → re-score → iterate.
+
+**Key insight:** Claude only consults skills for tasks it can't easily handle on its own. Simple queries ("read this file") won't trigger skills regardless of description quality. Write eval queries that are substantive enough to actually benefit from the skill.
+
+## Improvement heuristics
+
+When revising based on failures:
+
+1. **Generalize from feedback** — one user's test case is a proxy for millions of invocations. Don't overfit.
+2. **Keep it lean** — remove instructions that aren't earning their token cost. Re-read transcripts to see where the model wastes time.
+3. **Explain the WHY** — always.
+4. **Look for repeated work** — if every invocation writes the same helper script, bundle it in `scripts/`.
+
+## Anti-patterns
+
+- ❌ MUSTs and NEVERs without explanation
+- ❌ Monolithic SKILL.md >500 lines without reference-file split
+- ❌ Description that only lists what the skill does, without trigger phrases
+- ❌ Test prompts that are too abstract to be realistic
+- ❌ Skills that duplicate what existing tools already do well
+
+## Model Tier Selection
+
+When adding `model:` frontmatter to a new skill, apply these criteria:
+
+| Tier | When to use | Examples |
+|---|---|---|
+| `opus` | Complex multi-step reasoning, planning, architecture, open-ended synthesis | session-plan, plan, architecture |
+| `sonnet` | Workhorse tasks: orchestration, analysis, code generation, aggregation | session-start, wave-executor, discovery, evolve, skill-creator |
+| `haiku` | Routing, lookup, triage, reference reads, driver wrappers, simple file writes | gitlab-ops, quality-gates, mode-selector, daily, peekaboo-driver |
+| `inherit` | Skill runs inside coordinator's context and should match the coordinator's tier; also for `disable-model-invocation: true` skills | session-start, session-end, domain-model, ubiquitous-language |
+
+Decision rule: if the skill reasons over many options or produces a structural plan, use `opus`. If it executes defined steps, use `sonnet`. If it reads a config and emits a fixed output, use `haiku`. If it is a pass-through that the coordinator controls, use `inherit`.
+
+## Checklist
+
+- [ ] Frontmatter has `name` + `description` with explicit trigger phrases
+- [ ] Frontmatter has `model:` set per the Model Tier Selection table above
+- [ ] Body uses imperative voice
+- [ ] WHYs explained for any rules
+- [ ] Large sections split into `references/` if >500 lines
+- [ ] At least 2 realistic test prompts drafted
+- [ ] Examples in input/output format where relevant

package/skills/spinout/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: spinout
+user-invocable: true
+model: sonnet
+description: Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
+---
+
+# spinout — Guided Project-Extraction Runbook
+
+## Status: Deliberately Not Scripted
+
+This is a 5-phase interactive runbook, not a CLI wrapper. Automate only after 2-3 hand-runs have stabilized the pattern — spinout is a low-frequency, high-stakes operation (new remote, fresh history, a frozen marker left behind in the source repo), and premature scripting bakes wrong defaults (wrong sphere, wrong sanitize scope, wrong remote layout) into something expensive to undo. See #730 / H2.
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
+
+## Phase 1: Target + Sphere (AUQ)
+
+Ask via `AskUserQuestion` (per `.claude/rules/ask-via-tool.md` AUQ-001):
+- **Destination path** — where the new repo will live on disk.
+- **Sphere** — which account/host the new repo belongs to. Sphere conventions are **host-local**, not hardcoded here: read the operator's global `CLAUDE.md` (e.g. `~/.claude/CLAUDE.md`) for the "Verzeichnis = Account" mapping (private vs. org vs. ventures trees, or whatever the host documents) and offer those as options.
+- **Extraction type** — `venture-spinout` (a product leaving its incubator repo, gets a live remote and its own backlog) or `sanitized-snapshot` (a frozen, sanitized fork of content/code with no independent forward development expected).
+
+Do not proceed to Phase 2 without explicit confirmation of all three.
+
+## Phase 2: Confidentiality / Sanitize Check (HARD-GATE)
+
+<HARD-GATE>
+No copy happens until this checklist is confirmed by the operator. Do not rationalize past it because "it's all internal anyway."
+</HARD-GATE>
+
+Checklist:
+- **Secrets/tokens** — run gitleaks (or the repo's existing pre-commit scanner) over the target sub-path before copying.
+- **Live-infra references** — hostnames, internal URLs, deploy targets that should not leak into a spun-out repo.
+- **Internal-only docs** — anything under a private-only doc tree that should not travel.
+- **PII** — names, emails, customer data in fixtures or sample content.
+
+**Inertness declaration pattern:** infra-coupled scripts that will simply run empty in the new repo without their source tokens/infra (not broken, just inert there) get TABULATED in the FORK-NOTES (Phase 4) rather than silently deleted — deletion loses information a future maintainer needs; the table makes the inertness an explicit, reviewable fact.
+
+## Phase 3: Copy + Fresh git init
+
+- Directory copy of the target sub-path — deliberately **not** `git subtree split` or `git filter-repo`. No shared history travels with the spinout by design; the new repo starts clean.
+- Exclude build/dependency artifacts the same way a worktree would (`node_modules`, `dist`, `.git`, lockfile-derived caches).
+- `git init` fresh in the destination.
+- Add a provenance header to the new repo's `README.md` / `CLAUDE.md` (or `AGENTS.md` on Codex CLI): source repo, source path, extraction date, extraction type.
+
+## Phase 4: SNAPSHOT-FREEZE Marker in the Source Repo
+
+Write a `FORK-NOTES.md` (or `SNAPSHOT.md`) at the **original location** in the source repo — the copy left behind, not the new repo. Contents:
+- Provenance: source path, spinout date, "frozen — SSOT moved to `<new-repo>`".
+- Remote map: where the new repo now lives (sphere + URL).
+- Inertness table from Phase 2 (script → why it's inert here, not broken).
+
+The corpus left behind at the original location is FROZEN from this point — cross-reference `.claude/rules/development.md` § Corpus Freeze Marker for the convention.
+
+## Phase 5: Remotes + Registration (AUQ)
+
+Confirm each write via `AskUserQuestion` before executing:
+- Create the new repo's remote(s) per sphere (push-URL discipline — any helper remote used only for cross-host fetch should have push `DISABLED` where that pattern applies).
+- Register the new repo in the vault/portfolio index if one exists.
+- Optionally seed an initial issue backlog in the new repo.
+
+## Anti-Patterns
+
+- Scripting this runbook before the pattern has stabilized over 2-3 hand-runs.
+- Skipping the Phase 2 sanitize gate "because it's internal anyway."
+- Carrying shared git history into the spinout (`subtree`/`filter-repo`) — the new repo starts clean by design.
+- Continuing to develop the source copy after Phase 4 instead of treating it as frozen.
+
+## See Also
+
+- `commands/spinout.md` — slash-command entry point.
+- `skills/_shared/bootstrap-gate.md` — Phase 0 gate contract.
+- `.claude/rules/ask-via-tool.md` — AUQ-001 (every user decision goes through the tool, not prose).
+- `.claude/rules/parallel-sessions.md` § PSA-003 — destructive-action safeguards apply to any write in Phase 3/4/5.

package/skills/sunset-review/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: sunset-review
+description: Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision." <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
+model: inherit
+color: amber
+---
+
+# Sunset Review Skill
+
+Identify which skills, agents, and commands in the plugin surface are still earning their keep, and which are candidates to **Demote** (downgrade docs/tier) or **Retire** (remove). The skill is advisory: it produces a ranked candidate list and a sidecar artifact. **It never deletes anything.**
+
+## Why this is a distinct skill (not /repo-audit)
+
+`/repo-audit` answers "does this repo match the ecosystem baseline?" — a pass/fail compliance check. `/sunset-review` answers a different question — "which parts of OUR surface are unused?" — with different inputs (dispatch telemetry + static ref scanning), a different cadence (quarterly, not per-session), and a different output (prune candidates, not compliance status). Folding it into repo-audit would muddy both.
+
+## Core data contract (read this before trusting any verdict)
+
+The walker — `scripts/lib/sunset/walker.mjs` — is **read-only** and was built against the following grep-verified telemetry facts. Do not override them:
+
+1. **Both agent dispatch and skill-invocation telemetry are now consumed.** `subagents.jsonl` records agent dispatches; `skill-invocations.jsonl` records Skill tool selection events (L1 telemetry, epic #645). Agents are assessed by agent-dispatch counts; **skills are assessed by real selection counts from `skill-invocations.jsonl`, supplemented by static reference scanning.** Commands still have no invocation telemetry and are assessed by static reference scanning only. Skills with zero invocations in the window receive a zero-count (not null), so the low-coverage guard still applies and can downgrade Retire → Investigate when the telemetry window is short.
+2. **Only `event === "start"` records count.** `agent_type` is `null` on every `stop` event. A stop event must never mark an agent cold. The walker filters to start events.
+3. **Telemetry only spans ~18 days.** A 90-day window cannot be satisfied by 18 days of data. **MANDATORY GUARDRAIL:** when `coverageDays < windowDays`, every `Retire` verdict is downgraded to `Investigate` and `meta.lowConfidence` is set true. Retiring on sub-window data is unsafe — treat any cold finding as "investigate", not "delete".
+4. **Zero ≠ near-zero.** A never-dispatched agent (e.g. `memory-proposal-collector`, a by-design reference doc) is a Retire candidate; a once-dispatched agent (`db-specialist`, `ui-developer` at n=1) is a Demote candidate. The walker distinguishes them.
+
+## Verdict tiers
+
+| Verdict | Meaning | Action posture |
+|---|---|---|
+| **Active** | Agent dispatch above floor, OR skill invoked-by-command / command invokes-a-live-skill, OR ≥2 non-boilerplate refs | Keep |
+| **Investigate** | Coverage < window (low-confidence), OR conflicting signals — **default-safe bucket** | Manual review |
+| **Demote** | Single dispatch (n=1), OR a skill with a single cross-ref and no command linkage | Consider downgrading docs/tier |
+| **Retire** | `dispatch===0` AND `nonBoilerplateRefs===0` AND `coverage>=window` | Strong remove candidate (verify first) |
+
+## Phases
+
+### Phase 1 — Resolve config + window
+- Read Session Config for any `sunset-review.window-days` override; default to 90 (`DEFAULT_WINDOW_DAYS`).
+- The window is the period over which dispatch counts are tallied. Keep the default unless the operator has a reason to narrow it.
+
+### Phase 2 — Run the walker (JSON mode)
+Run the read-only walker and capture its JSON:
+
+```bash
+node scripts/lib/sunset/walker.mjs --json --window-days 90 > /tmp/sunset-walk.json
+```
+
+Exit 0 = walk completed (cold findings are exit 0, **not** an error). Exit 1 = bad args / surface dir missing. Exit 2 = system error. The walker writes no files — it is pure analysis.
+
+Optionally scope to one kind for focused review:
+
+```bash
+node scripts/lib/sunset/walker.mjs --json --kind agent
+```
+
+### Phase 3 — Classify & present (NEVER auto-delete)
+- Group the `items[]` array by `verdict`, ordered Retire → Demote → Investigate → Active.
+- Lead with `meta.lowConfidence`. If true, state plainly: "telemetry covers only N days (< window); all Retire candidates were downgraded to Investigate — do not retire anything this run."
+- For each Retire/Demote candidate, show its `reasons[]` and `signals{}` so the operator can sanity-check the verdict against their own knowledge (a low-traffic-but-load-bearing item should be spared).
+
+### Phase 4 — Emit report + sidecar
+Mirror the repo-audit sidecar convention. Write both:
+- **Markdown report:** `.orchestrator/metrics/sunset-review-<unix-timestamp>.md` — the grouped, human-readable verdict list with reasons.
+- **JSON sidecar:** the walker's full JSON output, persisted alongside for trend tracking.
+
+```bash
+mkdir -p .orchestrator/metrics
+```
+
+The sidecar is the durable record; the Markdown is the readable summary.
+
+**Skill Health (advisory)** — render a per-skill health advisory block into the report.
+- **Source:** per-skill verdicts come from `scoreSkillHealth()` in `scripts/lib/skill-health/score.mjs`, computed over the L2 join (`scripts/lib/skill-health/join.mjs`) plus any optional L3 judgments — the same telemetry the walker already surfaces on `item.signals.judge`. The mechanical/CI surface for this data is harness-audit `category9` ("Skill-Health Surfacing").
+- **Rendering:** add a `## Skill Health` section to the Markdown report. List each skill that has sufficient samples with its `verdict` (`insufficient signal` | `trigger description unclear` | `instructions wrong`) and its `diagnosis` string. Skills below the sample threshold (`MIN_SAMPLES_FOR_VERDICT`, ~20) are NOT scored per-skill — collapse them into a single line: "Insufficient signal (N skills)".
+- **Firewall (MANDATORY):** the health advisory NEVER edits any skill file and NEVER pushes a skill toward Retire or Demote on health data alone. It may only annotate the existing verdict, or trigger the existing Active→Investigate downgrade the walker already applies — never an escalation. This mirrors the walker's advisory-only judge firewall: annotate or downgrade-to-Investigate, never escalate toward Retire/Demote.
+- **Default-empty:** when telemetry is absent or insufficient (the common case today), render exactly "Skill Health: insufficient signal across all skills (no action)". This is a healthy state, not a finding — do not surface it as a candidate.
+
+### Phase 5 — Cadence note (the SKILL writes last-run, NOT the walker)
+- Sunset review runs **quarterly**. The walker is stateless and writes no runtime file — recording the last-run timestamp is **this skill's** responsibility, so a session-start nudge can fire when a quarter has elapsed.
+- After writing the report, record the run time (e.g. into `.orchestrator/metrics/sunset-review-last-run.json` with an ISO timestamp). This keeps the walker free of mutable runtime state and concurrency surface.
+
+## Draft-issue creation (coordinator-side only — AUQ-004)
+
+If the operator wants to file removal/demotion issues for the surfaced candidates, that decision **must be made by the coordinator via `AskUserQuestion`** — a dispatched agent cannot call `AskUserQuestion` (AUQ-004). When this skill runs inside a dispatched agent, it surfaces the candidate list and defers issue creation to the coordinator thread. Never auto-file issues and never auto-delete surface items.
+
+## Output Summary
+- Grouped verdict list printed to the user (Retire/Demote/Investigate/Active).
+- Markdown report at `.orchestrator/metrics/sunset-review-<timestamp>.md`.
+- JSON sidecar (walker output) alongside.
+- Last-run timestamp recorded for the quarterly cadence nudge.
+- **Zero deletions. Zero auto-filed issues.**
+
+## See Also
+- `scripts/lib/sunset/walker.mjs` — the read-only walker (CLI + exported functions).
+- `skills/repo-audit/SKILL.md` — the sibling compliance audit (different question).
+- `.claude/rules/cli-design.md` — JSON-first / exit-code contract the walker follows.
+- `.claude/rules/ask-via-tool.md` — AUQ-004 (agents cannot call AskUserQuestion).