session-orchestrator 3.22.0 → 3.24.0

package/.cursor/skills/npm-publish/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: npm-publish
+description: "Use when publishing this package to npm — a version release (npm publish), verifying the registry/pi.dev listing, or diagnosing npm auth failures (E403 2FA/token errors). Token-based flow via NPM_TOKEN in .env.local with a temp userconfig, the leakage gate before every publish, post-publish verification and marker/badge upkeep. Trigger on \"publish to npm\", \"npm release\", \"E403 publish error\"."
+---
+
+# npm-publish
+
+Canonical skill: `skills/npm-publish/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/npm-publish/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the npm-publish skill" as: Read `skills/npm-publish/SKILL.md`.

package/.cursor/skills/peekaboo-driver/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: peekaboo-driver
+description: "Use this skill when driving native-UI AX-tree snapshots and screenshots via steipete/peekaboo (MIT, macOS-only). Dispatched by `skills/test-runner/` to capture native-UI AX-tree snapshots + screenshots on macOS 15+ targets, and exits with deterministic JSON output the orchestrator can parse."
+disable-model-invocation: true
+---
+
+# peekaboo-driver
+
+Canonical skill: `skills/peekaboo-driver/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/peekaboo-driver/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the peekaboo-driver skill" as: Read `skills/peekaboo-driver/SKILL.md`.

package/.cursor/skills/persona-panel/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: persona-panel
+description: "Use this skill when you need multi-persona parallel content review — domain experts, buyer personas, compliance reviewers, or custom catalog entries reviewing a target file or output. Dispatches N persona agents in parallel, consolidates verdicts via a configurable mode (voting-quorum, hard-gate-threshold, or coordinator-summary), and writes a timestamped sidecar to .orchestrator/persona-panel/. Invoked via /persona-panel <target-path>."
+---
+
+# persona-panel
+
+Canonical skill: `skills/persona-panel/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/persona-panel/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the persona-panel skill" as: Read `skills/persona-panel/SKILL.md`.

package/.cursor/skills/plan/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: plan
+description: "Use this skill when performing structured project planning and PRD generation with three modes: new (project kickoff with repo scaffolding), feature (compact feature PRD), retro (data-driven retrospective). All modes share a researched Q&A engine that dispatches parallel Explore agents before each question wave, presents options via AskUserQuestion with recommendations, and produces documents with prioritized issue creation."
+disable-model-invocation: true
+---
+
+# plan
+
+Canonical skill: `skills/plan/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/plan/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the plan skill" as: Read `skills/plan/SKILL.md`.

package/.cursor/skills/playwright-driver/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: playwright-driver
+description: "Use this skill when executing web tests via the canonical `playwright` npm package (Microsoft, Apache-2.0). Dispatched by `skills/test-runner/` to execute web tests against a target, captures token-frugal AX-tree snapshots + screenshots + console output under `.orchestrator/metrics/test-runs/<run-id>/`, and exits with deterministic JSON output the orchestrator can parse."
+disable-model-invocation: true
+---
+
+# playwright-driver
+
+Canonical skill: `skills/playwright-driver/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/playwright-driver/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the playwright-driver skill" as: Read `skills/playwright-driver/SKILL.md`.

package/.cursor/skills/quality-gates/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: quality-gates
+description: Use this skill when referencing canonical quality check commands for typecheck, test, and lint. Defines 4 variants (Baseline, Incremental, Full Gate, Per-File) used by session-start, wave-executor, session-end, and session-reviewer. Reference skill — not invoked directly.
+disable-model-invocation: true
+---
+
+# quality-gates
+
+Canonical skill: `skills/quality-gates/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/quality-gates/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the quality-gates skill" as: Read `skills/quality-gates/SKILL.md`.

package/.cursor/skills/reconcile/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: reconcile
+description: Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be generated from current session learnings. On-demand version of session-end Phase 3.6.8.
+---
+
+# reconcile
+
+Canonical skill: `skills/reconcile/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/reconcile/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the reconcile skill" as: Read `skills/reconcile/SKILL.md`.

package/.cursor/skills/remote-offload/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: remote-offload
+description: Use when local resource pressure would shrink or coordinator-direct a wave, a wave plan carries heavy build/test/audit roles (test, ui, perf), or the operator says offload, remote host, or auslagern — reference for routing that wave role to a declared SSH-reachable host instead of reducing agent count
+disable-model-invocation: true
+---
+
+# remote-offload
+
+Canonical skill: `skills/remote-offload/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/remote-offload/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the remote-offload skill" as: Read `skills/remote-offload/SKILL.md`.

package/.cursor/skills/repo-audit/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: repo-audit
+description: "Use this skill when the user wants to audit a repository for baseline compliance, check code quality, security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist categories and emits a Markdown report plus JSON sidecar at .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants a baseline compliance check. user: \"/repo-audit\" assistant: \"Running repo-audit across 9 categories — Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration (optional), and MCP Configuration. Will produce a Markdown checklist report and JSON sidecar.\" <commentary>The user wants a compliance check; this skill is appropriate because it runs all 9 categories with pass/fail/warn/skipped statuses and writes structured output.</commentary></example>"
+disable-model-invocation: true
+---
+
+# repo-audit
+
+Canonical skill: `skills/repo-audit/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/repo-audit/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the repo-audit skill" as: Read `skills/repo-audit/SKILL.md`.

package/.cursor/skills/session-end/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: session-end
+description: "Use this skill when performing a full session close-out: verifies all planned work against the agreed plan, creates issues for gaps, runs quality gates, commits cleanly, mirrors to GitHub, and produces a session summary. Triggered by /close command."
+disable-model-invocation: true
+---
+
+# session-end
+
+Canonical skill: `skills/session-end/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/session-end/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the session-end skill" as: Read `skills/session-end/SKILL.md`.

package/.cursor/skills/session-plan/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: session-plan
+description: "Creates a structured wave execution plan with role-based assignment after user alignment. Decomposes agreed tasks into configurable waves (default 5) with optimal agent assignment, dependency ordering, and inter-wave checkpoints. Activated by session-start after Q&A phase completes."
+disable-model-invocation: true
+---
+
+# session-plan
+
+Canonical skill: `skills/session-plan/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/session-plan/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the session-plan skill" as: Read `skills/session-plan/SKILL.md`.

package/.cursor/skills/session-start/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: session-start
+description: "Use this skill when initializing a session for any project repo. Autonomously analyzes git state, VCS issues, SSOT files, branches, environment, and cross-repo status. Then presents structured findings with recommendations for user alignment before creating a wave plan. Triggered by /session [housekeeping|feature|deep] command."
+disable-model-invocation: true
+---
+
+# session-start
+
+Canonical skill: `skills/session-start/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/session-start/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the session-start skill" as: Read `skills/session-start/SKILL.md`.

package/.cursor/skills/skill-creator/SKILL.md

@@ -0,0 +1,13 @@
+---
+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\"."
+disable-model-invocation: true
+---
+
+# skill-creator
+
+Canonical skill: `skills/skill-creator/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/skill-creator/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the skill-creator skill" as: Read `skills/skill-creator/SKILL.md`.

package/.cursor/skills/spinout/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: spinout
+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
+
+Canonical skill: `skills/spinout/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/spinout/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the spinout skill" as: Read `skills/spinout/SKILL.md`.

package/.cursor/skills/sunset-review/SKILL.md

@@ -0,0 +1,13 @@
+---
+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>"
+disable-model-invocation: true
+---
+
+# sunset-review
+
+Canonical skill: `skills/sunset-review/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/sunset-review/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the sunset-review skill" as: Read `skills/sunset-review/SKILL.md`.

package/.cursor/skills/test-runner/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: test-runner
+description: "Use this skill when orchestrating agentic end-to-end tests. Resolves target + profile, dispatches the right driver(s) (playwright for web today, peekaboo for macOS (issue #381)), invokes the ux-evaluator agent (opus, read-only) against driver artifacts, reconciles findings with the open issue tracker via scripts/lib/test-runner/issue-reconcile.mjs, and writes report.md + JSONL roll-up. Wraps upstream tools (no forks). Hard-gates Playwright MCP for browser drive (4× token cost vs CLI per Microsoft's own benchmark)."
+disable-model-invocation: true
+---
+
+# test-runner
+
+Canonical skill: `skills/test-runner/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/test-runner/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the test-runner skill" as: Read `skills/test-runner/SKILL.md`.

package/.cursor/skills/tmux-layout/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: tmux-layout
+description: "Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: \"tmux layout\", \"split panes for ci watch\", \"visualize session side-channels\", \"show me state-md tail and ci\"."
+disable-model-invocation: true
+---
+
+# tmux-layout
+
+Canonical skill: `skills/tmux-layout/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/tmux-layout/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the tmux-layout skill" as: Read `skills/tmux-layout/SKILL.md`.

package/.cursor/skills/ubiquitous-language/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: ubiquitous-language
+description: "Use when the user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions \"domain model\" or \"DDD\". Extracts a DDD-style glossary from the current conversation into UBIQUITOUS_LANGUAGE.md, flags ambiguities and synonyms, and proposes opinionated canonical terms."
+disable-model-invocation: true
+---
+
+# ubiquitous-language
+
+Canonical skill: `skills/ubiquitous-language/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/ubiquitous-language/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the ubiquitous-language skill" as: Read `skills/ubiquitous-language/SKILL.md`.

package/.cursor/skills/using-orchestrator/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: using-orchestrator
+description: "Use this skill when dispatching implicit slash-command intent from the user's first message. Inspects the user's first message for implicit slash-command intent and dispatches to the highest-confidence matching entry-point skill via the Skill tool. Only active when `auto-skill-dispatch: true` in Session Config. Silent no-op otherwise."
+disable-model-invocation: true
+---
+
+# using-orchestrator
+
+Canonical skill: `skills/using-orchestrator/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/using-orchestrator/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the using-orchestrator skill" as: Read `skills/using-orchestrator/SKILL.md`.

package/.cursor/skills/vault-mirror/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: vault-mirror
+description: "Use when you need to populate the Meta-Vault with machine-generated notes derived from session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when `vault-integration.enabled=true` and `vault-integration.mode != \"off\"`. Idempotent: re-runs safely; skips hand-authored notes. Triggers: \"mirror to vault\", \"sync session notes to vault\", \"write learning notes to vault\", \"vault-mirror failed at session close\". <example>Context: session-end is finalizing, vault-integration.mode is \"warn\". user: \"/close\" assistant: \"Running vault-mirror to write 50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped.\"</example>"
+disable-model-invocation: true
+---
+
+# vault-mirror
+
+Canonical skill: `skills/vault-mirror/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/vault-mirror/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the vault-mirror skill" as: Read `skills/vault-mirror/SKILL.md`.

package/.cursor/skills/vault-sync/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: vault-sync
+description: "Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes: `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: \"vault validation failed at session close\", \"fix vault frontmatter errors\", \"check vault wiki-links\", \"why is session-end blocked by vault-sync\". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true, vault-sync.mode=\"hard\". user: \"/close\" assistant: \"vault-sync found 2 frontmatter errors in vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close.\"</example>"
+disable-model-invocation: true
+---
+
+# vault-sync
+
+Canonical skill: `skills/vault-sync/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/vault-sync/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the vault-sync skill" as: Read `skills/vault-sync/SKILL.md`.

package/.cursor/skills/wave-executor/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: wave-executor
+description: Use this skill when executing the agreed session plan in waves with role-based execution and parallel subagents. Handles inter-wave quality checks, plan adaptation, and progress tracking. Core orchestration engine for feature and deep sessions. Triggered by /go command.
+disable-model-invocation: true
+---
+
+# wave-executor
+
+Canonical skill: `skills/wave-executor/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/wave-executor/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the wave-executor skill" as: Read `skills/wave-executor/SKILL.md`.

package/.cursor/skills/write-executable-plan/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: write-executable-plan
+description: "Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects \"TBD\", \"TODO\", \"add error handling\", \"similar to Task N\"."
+disable-model-invocation: true
+---
+
+# write-executable-plan
+
+Canonical skill: `skills/write-executable-plan/SKILL.md`
+
+Read that file and follow it exactly. Resolve relative links against `skills/write-executable-plan/`, not this wrapper.
+
+Cursor has no Skill tool. Treat "invoke the write-executable-plan skill" as: Read `skills/write-executable-plan/SKILL.md`.

package/.mcp.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "session-orchestrator": {
       "command": "bash",
-      "args": ["-c", "exec bash \"${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(git rev-parse --show-toplevel)}}/scripts/mcp-server.sh\""]
+      "args": [
+        "-c",
+        "# Tier order MIRRORS resolvePluginRoot() — see scripts/lib/plugin-root.mjs § TIER ORDER (the single source of truth). That list is the original, this is the mirror: change both together. The env list, the CODEX_HOME trim, the package.json{name} test and the newest-wins-by-mtime tiebreak are all mirrored EXACTLY; only tier 6 (walk up from import.meta.url) has no shell analogue.\nr=\"\"; ch=\"$CODEX_HOME\"; ch=\"${ch#\"${ch%%[![:space:]]*}\"}\"; ch=\"${ch%\"${ch##*[![:space:]]}\"}\"; [ -n \"$ch\" ] || ch=\"$HOME/.codex\"; for c in \"$PLUGIN_ROOT\" \"$CLAUDE_PLUGIN_ROOT\" \"$CODEX_PLUGIN_ROOT\" \"$CURSOR_RULES_DIR\" \"$PI_PLUGIN_ROOT\" \"$(git rev-parse --show-toplevel 2>/dev/null)\"; do if [ -n \"$c\" ] && [ -f \"$c/scripts/mcp-server.sh\" ]; then r=\"$c\"; break; fi; done; if [ -z \"$r\" ]; then r=\"$(NODE_PATH=\"$(npm root -g 2>/dev/null)\" node -e 'import(require(`node:url`).pathToFileURL(require.resolve(`session-orchestrator/scripts/lib/plugin-root.mjs`))).then(m=>process.stdout.write(m.resolvePluginRoot()))' 2>/dev/null)\"; fi; if [ -z \"$r\" ]; then for b in \"$ch\" \"$HOME/.claude\"; do for c in \"$b\"/plugins/cache/*/session-orchestrator/*; do if [ -f \"$c/scripts/mcp-server.sh\" ] && node -e 'process.exit(JSON.parse(require(\"fs\").readFileSync(process.argv[1],\"utf8\")).name===\"session-orchestrator\"?0:1)' \"$c/package.json\" 2>/dev/null && { [ -z \"$r\" ] || [ \"$c\" -nt \"$r\" ]; }; then r=\"$c\"; fi; done; done; fi; if [ -n \"$r\" ] && [ -f \"$r/scripts/mcp-server.sh\" ]; then exec bash \"$r/scripts/mcp-server.sh\"; fi; { echo \"session-orchestrator: cannot locate the plugin root — the MCP server did not start.\"; echo \"  Tried: PLUGIN_ROOT=${PLUGIN_ROOT:-(unset)}, CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT:-(unset)}, CODEX_PLUGIN_ROOT=${CODEX_PLUGIN_ROOT:-(unset)}, CURSOR_RULES_DIR=${CURSOR_RULES_DIR:-(unset)}, PI_PLUGIN_ROOT=${PI_PLUGIN_ROOT:-(unset)}, git rev-parse --show-toplevel (cwd=$PWD), node resolve of session-orchestrator/scripts/lib/plugin-root.mjs, plugin caches $ch/plugins/cache/*/session-orchestrator/* and $HOME/.claude/plugins/cache/*/session-orchestrator/*.\"; echo \"  Fix: reinstall the plugin so its cached copy is refreshed (codex plugin marketplace add Kanevry/session-orchestrator), or set CLAUDE_PLUGIN_ROOT / CODEX_PLUGIN_ROOT to the plugin directory in this server's env block.\"; echo \"  Note: CODEX_PLUGIN_ROOT is session-orchestrator's own compatibility export, not a variable Codex provides. See docs/codex-setup.md § Troubleshooting.\"; } >&2; exit 1"
+      ]
     }
   }
 }