{"id":51223092,"url":"https://github.com/Kanevry/session-orchestrator","last_synced_at":"2026-07-09T07:00:30.922Z","repository":{"id":348771493,"uuid":"1199817646","full_name":"Kanevry/session-orchestrator","owner":"Kanevry","description":"Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi. MIT community plugin.","archived":false,"fork":false,"pushed_at":"2026-07-04T12:32:14.000Z","size":7301,"stargazers_count":41,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T14:15:11.497Z","etag":null,"topics":["agent-orchestration","agentic-ai","ai-agents","ai-coding","anthropic","claude","claude-code","claude-code-plugin","claude-code-plugins","claude-code-skills","code-review","codex","cursor","developer-tools","github","gitlab","mcp","quality-gates","session-management","subagents"],"latest_commit_sha":null,"homepage":"https://agenticbuilders.at","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kanevry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T18:34:17.000Z","updated_at":"2026-07-04T12:32:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kanevry/session-orchestrator","commit_stats":null,"previous_names":["kanevry/session-orchestrator"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/Kanevry/session-orchestrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanevry%2Fsession-orchestrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanevry%2Fsession-orchestrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanevry%2Fsession-orchestrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanevry%2Fsession-orchestrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kanevry","download_url":"https://codeload.github.com/Kanevry/session-orchestrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kanevry%2Fsession-orchestrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35290235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agentic-ai","ai-agents","ai-coding","anthropic","claude","claude-code","claude-code-plugin","claude-code-plugins","claude-code-skills","code-review","codex","cursor","developer-tools","github","gitlab","mcp","quality-gates","session-management","subagents"],"created_at":"2026-06-28T09:00:31.117Z","updated_at":"2026-07-09T07:00:30.912Z","avatar_url":"https://github.com/Kanevry.png","language":"JavaScript","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# Session Orchestrator\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-3.12.0-blue.svg)](CHANGELOG.md)\n[![Tests](https://img.shields.io/badge/tests-10%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)\n\nTurn ad-hoc agent sessions into a repeatable loop with verification gates — loop engineering for software work. You design the loop (`research → plan → execute in waves → close`); Session Orchestrator runs it on top of your existing agent, with the guards, telemetry, and cross-session memory that keep a long agent run honest. Inter-wave reviews catch regressions before they ship; carryover issues mean loose ends get tracked, not lost.\n\nWorks with **Claude Code, Codex CLI, Cursor IDE, and [Pi](docs/pi-setup.md)** — the same skills and commands across all four, with platform-adapted hooks and enforcement (see [Platform support](#platform-support)). Community plugin (MIT, community-maintained) for solo devs and small teams.\n\n## A session in three commands\n\n```text\n/session feature    # research + Q\u0026A — inspect git, issues, history, then agree on scope\n/go                 # execute in five typed waves (fixed roles), with a quality gate between each\n/close              # verify every item, commit cleanly, file carryover issues for the rest\n```\n\nThat is the whole loop. `/plan` and `/evolve` extend it (see [Lifecycle](#lifecycle-at-a-glance)), but you can start with just these three.\n\n## Install\n\n\u003e **Prerequisite:** Node.js 24 or later (`node --version`). v3.x runs as ES modules and needs a real Node runtime. [Install Node.js](https://nodejs.org/).\n\nThe two paths below differ only by **install mechanism**, not capability or tier: Claude Code pulls from the plugin marketplace; every other platform clones the repo. The same skills and commands ship to all four.\n\n### Claude Code (plugin marketplace)\n\nRun these two slash commands **inside** Claude Code (not in a shell):\n\n```text\n/plugin marketplace add Kanevry/session-orchestrator\n/plugin install session-orchestrator@kanevry\n```\n\nThen install Node dependencies **once** (hooks import `zx`) and restart Claude Code:\n\n```bash\ncd \"$(claude plugin dir session-orchestrator 2\u003e/dev/null || echo ~/.claude/plugins/session-orchestrator)\"\nnpm install\n```\n\n### Codex CLI, Cursor IDE \u0026 Pi (git clone)\n\n```bash\ngit clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator\ncd ~/Projects/session-orchestrator \u0026\u0026 npm install\nnode scripts/codex-install.mjs                          # Codex CLI\nnode scripts/cursor-install.mjs /path/to/your/project   # Cursor IDE\nnode scripts/pi-install.mjs    /path/to/your/project --settings-only   # Pi\n```\n\nSetup guides: [Codex](docs/codex-setup.md) · [Cursor IDE](docs/cursor-setup.md) · [Pi](docs/pi-setup.md). Per-IDE notes on `CLAUDE.md` vs `AGENTS.md`: [instruction-file-resolution](skills/_shared/instruction-file-resolution.md).\n\n## Quick Start\n\nAdd a `## Session Config` section to your project's `CLAUDE.md` (Claude Code and Cursor IDE) or `AGENTS.md` (Codex CLI and Pi) — see [instruction-file-resolution](skills/_shared/instruction-file-resolution.md) for which file each platform reads. The smallest valid config is seven fields:\n\n```yaml\n## Session Config\n\ntest-command: npm test\ntypecheck-command: npm run typecheck\nlint-command: npm run lint\nagents-per-wave: 6\nwaves: 5\npersistence: true\nenforcement: warn\n```\n\nEverything else is opt-in. See [`docs/session-config-template.md`](docs/session-config-template.md) for the full template and [`docs/session-config-reference.md`](docs/session-config-reference.md) for the canonical type and default reference.\n\n## What you get\n\n- **42 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, audits, and more\n- **22 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/test`, `/debug`, …)\n- **14 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …)\n- **10 hook event types** enforcing scope, blocking destructive commands, gating templates-first, capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged on the other platforms ([Platform support](#platform-support))\n- **10,000+ vitest tests** run on every commit ([telemetry methodology](docs/telemetry/telemetry-claims.md))\n\nFull component inventory: [`docs/components.md`](docs/components.md).\n\n## Lifecycle at a glance\n\n```mermaid\nflowchart TD\n    A[\"/plan [feature|retro]\"] --\u003e|optional, defines WHAT| B[\"/session [type]\"]\n    B --\u003e|research + Q\u0026A| C[\"/go\"]\n    C --\u003e|5 waves with quality gates| D[\"/close\"]\n    D --\u003e|verifies + commits| E[\"/evolve [analyze]\"]\n    E --\u003e|extracts cross-session learnings| B\n    style C fill:#1f6feb,color:#fff\n    style D fill:#238636,color:#fff\n```\n\n`/plan` is optional — you can create issues manually and jump straight to `/session`. `/evolve` runs deliberately after 5+ sessions, not automatically.\n\n## How it works\n\nMost agentic-coding tools jump straight into writing code. Session Orchestrator adds a structured loop on top: research first, agree on scope, then execute in five typed waves with verification gates between them.\n\n```mermaid\nflowchart LR\n    W1[\"1·Discovery\u003cbr/\u003eread-only audit\"] --\u003e G1{Gate}\n    G1 --\u003e W2[\"2·Impl-Core\u003cbr/\u003eprimary code\"]\n    W2 --\u003e G2{Gate}\n    G2 --\u003e W3[\"3·Impl-Polish\u003cbr/\u003eintegration, edges\"]\n    W3 --\u003e G3{Gate}\n    G3 --\u003e W4[\"4·Quality\u003cbr/\u003esimplify + tests\"]\n    W4 --\u003e G4{Full Gate}\n    G4 --\u003e W5[\"5·Finalization\u003cbr/\u003ecommit + close\"]\n    style G4 fill:#d29922,color:#000\n```\n\nWhen you type `/session feature`:\n\n1. **Phase analysis runs in parallel** — git state, open issues, recent commits, SSOT freshness, resource health, and prior-session memory are all inspected, then distilled into a structured Session Overview with a recommendation, not a wall of raw data.\n2. **You agree on scope** — through a tool-rendered picker (Claude Code) or a numbered list (Codex / Cursor / Pi). The orchestrator has an opinion and tells you what it would do.\n3. **The plan is decomposed into five waves** — Discovery (read-only), Impl-Core, Impl-Polish, Quality, Finalization. Each wave has a defined purpose and a deliverable; agent counts scale by session type.\n4. **`/go` executes** — agents work in parallel within a wave. A session-reviewer audits the output between waves on eight dimensions; only findings at confidence ≥ 80 reach you.\n5. **`/close` ships it** — every planned item is verified, quality gates run full, and unfinished work becomes carryover issues. Files are staged individually, so parallel sessions can't stomp each other.\n\nTwo complementary commands round out the loop: **`/plan`** runs *before* a session when you need a PRD or retrospective; **`/evolve`** runs occasionally to surface patterns across sessions and feed them back at the next start.\n\nThe system is markdown-driven config plus a thin Node runtime — skills, commands, and agents are Markdown with YAML frontmatter; `scripts/lib/*.mjs` and `hooks/*.mjs` handle dispatch, validation, and telemetry. Everything is plain text: if something goes wrong, you can read every file and see what happened.\n\n## Why this design\n\n- **Five typed waves, not one big batch.** Discovery first, so implementers start with shared context. Impl-Core before Impl-Polish, so architecture lands before integrations. Quality runs a *simplification pass* on AI-generated code **before** tests are written — otherwise tests pin the AI patterns into place.\n- **Inter-wave reviews, not just end-of-session.** Catching regressions between waves — not only at the end — stops a bad pattern from propagating into later work; the confidence floor filters speculative criticism so only high-signal findings reach you.\n- **State persists across crashes.** `STATE.md` records wave progress and deviations; the next `/session` offers to resume from the last completed wave.\n- **Hooks enforce, not just warn.** A pre-Bash guard blocks destructive shell commands, and pre-Edit scope enforcement blocks writes outside an agent's allowed paths — in main sessions and subagent waves alike (specifics in [Safety](#safety)). This hard enforcement is full on Claude Code; it degrades to experimental / post-hoc / bridged on Codex CLI, Cursor IDE, and Pi (see [Platform support](#platform-support)).\n- **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.\n- **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.\n\n## Recent highlights (v3.12.0)\n\nEvery release is additive and backward-compatible. Highlights of the v3.12.0 line:\n\n- **Gated session handover** — `/close` collects carryover candidates and routes them through an operator-triaged alignment gate instead of filing them scattered across phases; a new `## Open Questions` STATE.md channel carries a wave agent's unresolved questions across the session boundary, surfaced as a forced-read at the next session-start.\n- **Fail-loud wave dispatch** — small-batch `Agent()` dispatch by default (large fan-outs drop calls silently), planned-vs-started dispatch verification with re-dispatch, and git-diff edit-persistence evidence before any agent's `done` is accepted.\n- **Curated public docs** — 68 process records moved to the operator's private vault behind a sensitivity gate; three permanent guards (docs-parity drift check, docs-staleness probe, epic-close PRD archive routine) keep the public tree user-facing.\n- **Session-lock reliability** — heartbeat-first liveness ends the live-session-hijack incident class, a lock reaper sweeps orphaned registry claims, and STATE.md writes are size-guarded.\n- **Portable hooks** — all hook commands route through a node-resolver shim, fixing per-tool-call failures on nvm/volta/asdf/Homebrew setups where hook shells never source `~/.zshrc`.\n\nPrevious line (v3.11.0): self-healing session ledger, learning-store backup + expiry sweep, hardened CI mirror, tier-aware rule loading.\n\nFull version history: [CHANGELOG.md](CHANGELOG.md).\n\n## Comparison\n\n| Capability | Session Orchestrator | Manual `CLAUDE.md` | Other orchestrators |\n|---|---|---|---|\n| Session lifecycle (start → plan → execute → close) | Full, automated | Manual | Partial |\n| Typed waves with quality gates | 5 roles, progressive verification | None | Batch execution |\n| Session persistence and crash recovery | `STATE.md` plus memory files | None | Partial |\n| Scope and command enforcement hooks | PreToolUse with strict / warn / off | None | None |\n| Circuit breaker and spiral detection | Per-agent, with recovery | None | Partial |\n| Cross-session learning | Confidence-scored learnings | None | None |\n| VCS integration (GitLab + GitHub) | Dual, auto-detected | Manual CLI | Usually GitHub only |\n| Session close with carryover | Verified, with issue creation | Manual | Partial |\n\nThe design goal is engineering quality: every wave exits verified, every unfinished issue gets a carryover ticket, every session closes with a clean commit. A detailed head-to-head vs. [maestro-orchestrate](https://github.com/josstei/maestro-orchestrate) is in [`docs/components.md`](docs/components.md#comparison-vs-maestro-orchestrate).\n\n## Platform support\n\n| Feature | Claude Code | Codex CLI | Cursor IDE | Pi |\n|---|---|---|---|---|\n| All 22 commands | Native slash commands | Native plugin commands | Rules-based (.mdc) | Prompt templates |\n| Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |\n| Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |\n| Scope enforcement | PreToolUse hooks | Hooks (experimental) | `afterFileEdit` (post-hoc) | `tool_call` bridge |\n| AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback |\n| Quality gates | Full | Full | Full | Full |\n\nAll platforms share the same skills, commands, hooks, and scripts; platform-specific adaptation lives in `scripts/lib/platform.mjs`. **OS:** macOS and Linux are first-class and run in CI (`ubuntu-latest`, `macos-latest`). Windows runs natively (all paths via `path.join`, tmp via `os.tmpdir()`) but is **not** covered by CI — treat it as best-effort and run smoke tests locally when changing OS-sensitive code. Cursor and Pi have known event-coverage caveats — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).\n\n## Troubleshooting\n\n**\"'node' not found on the hook PATH — plugin hooks are skipped.\"** The harness executes hook commands via `/bin/sh -c` with its own PATH — that shell does not source `~/.zshrc`/`~/.bashrc`, so Node installed via Homebrew (`/opt/homebrew/bin`), nvm, volta, or asdf can be invisible to hooks even though `node` works fine in your terminal. All hook commands route through [`hooks/run-node.sh`](hooks/run-node.sh), which resolves Node via `$SO_NODE_BIN` → PATH → well-known install dirs → nvm and degrades gracefully when nothing is found: hooks are skipped with **one** warning per 6 hours instead of a shell error on every tool call. Fixes, in order of preference: launch the harness from a shell where `node` resolves; export `SO_NODE_BIN=/abs/path/to/node`; or install Node 24+ to a standard location.\n\n## Safety\n\n`hooks/pre-bash-destructive-guard.mjs` blocks destructive shell commands (`git reset --hard`, `rm -rf`, `git push --force`, and more) in the main session *and* in subagent waves. Policy lives in `.orchestrator/policy/blocked-commands.json`. Bypass per session only for intentional maintenance:\n\n```yaml\nallow-destructive-ops: true\n```\n\nThe rule source of truth is [`.claude/rules/parallel-sessions.md`](.claude/rules/parallel-sessions.md) (PSA-003), vendored to consumer repos via `/bootstrap`.\n\n## Development\n\n```bash\ngit clone https://github.com/Kanevry/session-orchestrator.git \u0026\u0026 cd session-orchestrator\nnpm install\nnpm test          # vitest\nnpm run lint      # ESLint v10 + Prettier\nnpm run typecheck # node --check on every .mjs file\n```\n\n`.npmrc` ships with `ignore-scripts=true` (supply-chain defence), so Husky git hooks don't auto-wire on install — run `npx husky` once after cloning. `git commit` then runs gitleaks → owner-privacy scan → lint-staged → commitlint. CI re-runs everything, plus more.\n\nContributor docs: [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [agent authoring spec](agents/AGENTS.md).\n\n## Support \u0026 scope\n\nSession Orchestrator is provided **as-is** — a community project with no SLA, no commercial support contract, and no guaranteed response time. Maintenance is best-effort.\n\n- Questions, ideas, show-and-tell → [GitHub Discussions](https://github.com/Kanevry/session-orchestrator/discussions)\n- Bugs and feature requests → [Issues](https://github.com/Kanevry/session-orchestrator/issues)\n\nWhat it is **not**:\n\n- **Not an official product of any agent vendor.** An independent, community-maintained project — not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)\n- **Not a replacement** for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs *on top of* your existing agent — you still need one of those installed.\n- **Not a hosted service.** Runs locally — no server, account, or cloud component.\n- **No guarantee that telemetry numbers transfer to your repo.** Reported test counts and metrics describe *this* repository under its own conditions ([details](docs/telemetry/telemetry-claims.md)). Your results will vary by stack, project size, and configuration.\n\n## Documentation\n\n- [docs/ Router](docs/README.md) — living reference vs. public decision history vs. active work documents; what moved to the private Meta-Vault and why\n- [User Guide](docs/USER-GUIDE.md) — installation, config reference, workflow walkthrough, FAQ\n- [Components \u0026 Reference](docs/components.md) — full skill/command/agent/hook inventory, repository anatomy, comparisons\n- [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) — contributor guide, layering, hook anatomy, testing\n- [Migration to v3](docs/migration-v3.md) — upgrade path from v2.x, known issues, rollback\n- [Telemetry claims](docs/telemetry/telemetry-claims.md) — how reported metrics are measured, and why they may not transfer\n- [Example Configs](docs/examples/) — Session Config examples for Next.js, Express, Swift\n- [CHANGELOG.md](CHANGELOG.md) — version history\n\nWe follow [Conventional Commits](https://www.conventionalcommits.org/) — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Learn the method behind it\n\nThis plugin is a methodology turned into code. If you want the reasoning behind it — why execution runs in waves, why every wave ends at a verification gate, how to make an autonomous loop that actually finishes — those playbooks are taught hands-on at **[agenticbuilders.at](https://agenticbuilders.at)**:\n\n- **[Multi-Agent Orchestration](https://agenticbuilders.at/orchestrierung)** — leading several agents in coordinated waves: when parallelism pays, briefing subagents cleanly, turning failures into firm gates.\n- **[Loop Engineering](https://agenticbuilders.at/loop-engineering)** — designing autonomous loops that finish verifiably: done-conditions, verification gates, kill-switches.\n\nThe plugin is free and MIT. The courses are for going deeper, not a requirement for using it.\n\n## Links\n\n- [Homepage](https://gotzendorfer.at/en/session-orchestrator) · [Privacy Policy](https://gotzendorfer.at/en/session-orchestrator/privacy)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKanevry%2Fsession-orchestrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKanevry%2Fsession-orchestrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKanevry%2Fsession-orchestrator/lists"}