Session orchestration plugin for Claude Code, Codex CLI, and Cursor IDE — project planning, wave execution, VCS integration, quality gates.
Claude Code, Codex CLI, and Cursor IDE are agentic coding tools. This plugin adds structured session management on top — turning ad-hoc agent interactions into repeatable, quality-gated engineering workflows. No runtime code. Pure Markdown.
# Add as a Claude Code plugin
claude plugin add github:Kanevry/session-orchestrator# 1. Clone to a local directory
git clone https://github.com/Kanevry/session-orchestrator.git ~/.codex/plugins/session-orchestrator
# 2. Add Session Config to your project's AGENTS.md
# See docs/templates/AGENTS-session-config.md for the template
# 3. Enable hooks (optional, experimental)
# Add to .codex/config.toml: [features] hooks = true# 1. Clone the session-orchestrator repo
git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator
# 2. Install Cursor rules into your project
bash ~/Projects/session-orchestrator/scripts/cursor-install.sh /path/to/your/project
# Session Config goes in CLAUDE.md (Cursor reads it natively)- Claude Code, Codex CLI, or Cursor IDE — Claude Code | Codex CLI | Cursor IDE
- jq (recommended) — required for scope and command enforcement hooks
| Feature | Claude Code | Codex CLI | Cursor IDE |
|---|---|---|---|
| All 6 commands | Native slash commands | Instruction-based | Rules-based (.mdc) |
| Parallel agents | Agent tool | Multi-agent roles | Sequential only |
| Session persistence | .claude/STATE.md | .codex/STATE.md | .cursor/STATE.md |
| Shared knowledge | .orchestrator/metrics/ | .orchestrator/metrics/ | .orchestrator/metrics/ |
| Scope enforcement | PreToolUse hooks | Hooks (experimental) | afterFileEdit (post-hoc) |
| AskUserQuestion | Native tool | Numbered list fallback | Numbered list fallback |
| Quality gates | Full | Full | Full |
| Design alignment | Pencil integration | Pencil integration | Pencil integration |
All platforms share the same skills, commands, hooks, and scripts. Platform-specific adaptations are handled automatically via scripts/lib/platform.sh. See setup guides: Codex CLI | Cursor IDE.
Session Orchestrator provides a complete development session lifecycle — from project state analysis through structured wave execution to verified close-out. While other tools optimize for speed or cost, Session Orchestrator optimizes for session quality and engineering discipline.
A soul.md file defines the orchestrator's identity — communication principles, a decision-making hierarchy (safety > productivity > quality > ecosystem health > speed), and values (pragmatism, evidence, ownership). This shapes every interaction, not just tone.
Five typed waves: Discovery (read-only), Core Implementation, Polish & Integration, Quality & Testing, Finalization. The Quality wave includes a simplification pass that cleans AI-generated code patterns before tests are written. Each wave has a defined purpose and agent count that scales by session type.
A session-reviewer agent runs 8 review sections between waves (implementation correctness, test coverage, TypeScript health, OWASP security, issue tracking, silent failures, test depth, type design). Findings are confidence-scored (0-100) -- only >=80 make the report. Verification escalates progressively across waves.
When configured with a Pencil design file, the wave executor screenshots design frames after Impl-Core and Impl-Polish waves and compares them with the actual implementation — checking layout structure, component hierarchy, and visual elements. Results are classified as ALIGNED / MINOR DRIFT / MAJOR MISMATCH with automatic plan adaptation.
Auto-detects GitLab or GitHub from your git remote. Full lifecycle support for both: issue management, MR/PR tracking, pipeline/workflow status, label taxonomy, and milestone queries. No lock-in.
Checks configured service endpoints and scans cross-repo critical issues at session start. Know your ecosystem state before you start working.
Sessions persist across interruptions via STATE.md -- crash recovery, resume, and handover. PreToolUse hooks enforce agent scope and block dangerous commands. A circuit breaker detects execution spirals and recovers automatically.
Every session writes metrics (duration, agents, files per wave) and effectiveness stats (completion rate, carryover). After 5+ sessions, the system surfaces trends. Use /evolve analyze to extract cross-session patterns, /evolve review to curate learnings, or /evolve list to inspect them.
A complexity scoring formula (files x modules x issues) determines agent counts per role and session type. Dynamic scaling adjusts between waves based on actual performance.
/close verifies every planned item, runs a full quality gate, creates carryover issues for unfinished work, and commits with individually staged files. /discovery runs 23 modular probes across code, infra, UI, architecture, and session categories -- each finding confidence-scored.
| Feature | Session Orchestrator | Manual CLAUDE.md | Other Orchestrators |
|---|---|---|---|
| Session lifecycle (start → plan → execute → close) | Full, automated | Manual | Partial |
| Typed waves with quality gates | 5 roles, progressive verification | None | Batch execution |
| Session persistence & crash recovery | STATE.md + memory files | None | Partial |
| Scope & command enforcement hooks | PreToolUse with strict/warn/off | None | None |
| Circuit breaker & spiral detection | Per-agent, with recovery | None | Partial |
| Cross-session learning | Confidence-scored learnings | None | None |
| Adaptive wave sizing | Complexity-scored, dynamic | Fixed | Fixed |
| VCS integration (GitLab + GitHub) | Dual, auto-detected | Manual CLI | Usually GitHub only |
| Design-code alignment | Pencil integration | None | None |
| Session close with carryover | Verified, with issue creation | Manual | Partial |
Session Orchestrator optimizes for engineering quality -- every wave verified, every issue tracked, every session closed cleanly.
| Command | Purpose |
|---|---|
/session [type] |
Start session (housekeeping, feature, deep) |
/go |
Approve plan, begin wave execution |
/close |
End session with verification |
/discovery [scope] |
Systematic quality discovery and issue detection |
/plan [mode] |
Plan a project, feature, or retrospective |
/evolve [mode] |
Extract, review, or list cross-session learnings |
Session Orchestrator has two complementary workflows: planning (what to build) and execution (how to build it).
/plan [mode] → /session [type] → /go → /close → /plan retro
WHAT HOW DO VERIFY REFLECT
Run /plan before starting a session to define requirements and create issues:
/plan new— Full project kickoff: 3-wave requirement gathering, 8-section PRD, repo scaffolding, Epic + prioritized issues. Use when starting from scratch./plan feature— Compact feature PRD: 1-2 wave discovery, acceptance criteria, feature issues. Use when adding a feature to an existing project./plan retro— Data-driven retrospective: analyzes session metrics, surfaces trends, creates improvement issues. Use after completing significant work.
/plan is optional — you can create issues manually and jump straight to /session.
Run /session to implement existing issues across structured waves:
/session feature # Analyze project, pick issues, agree on scope
/go # Execute across 5 parallel waves
/close # Verify, commit, push, create carryover issues
/plan feature # 10 min: define requirements → PRD + 3 issues
/session feature # Pick those 3 issues → wave plan
/go # Execute: Discovery → Impl-Core → Polish → Quality → Finalize
/close # Verify + commit + push/evolve is a standalone command for deliberate reflection — it is not called automatically during sessions.
Why it exists: /close extracts learnings from the current session only. /evolve analyzes all session history to find cross-session patterns that only emerge over time.
/evolve analyze(default) — Readssessions.jsonl, extracts patterns across all sessions (fragile files, effective sizing, recurring issues, scope guidance, deviation patterns). Presents findings for confirmation before writing./evolve review— Interactive management: boost or reduce confidence, delete stale learnings, extend expiry./evolve list— Read-only display of active learnings grouped by type.
When to use:
- After 5+ sessions — enough data for meaningful patterns
- When Project Intelligence is empty despite running sessions
- Before a big feature — check if the system has useful sizing/scope recommendations
- Periodically for housekeeping — prune outdated or incorrect learnings
How it fits in the flow:
/session → /go → /close ← automatic learning (per-session)
...repeat 5+ times...
/evolve analyze ← deliberate learning (cross-session)
/session → /go → /close ← now session-start shows richer Project Intelligence
- housekeeping — Git cleanup, SSOT refresh, CI checks, branch merges (1-2 agents, serial)
- feature — Frontend/backend feature work (4-6 agents per wave x 5 waves)
- deep — Complex backend, security, DB, refactoring (up to 10-18 agents per wave x 5 waves)
Add to each repo's CLAUDE.md:
## Session Config
- **agents-per-wave:** 6
- **waves:** 5
- **pencil:** path/to/design.pen
- **cross-repos:** [related-repo-1, related-repo-2]
- **ssot-files:** [.claude/STATUS.md]
- **mirror:** github
- **ecosystem-health:** true
- **vcs:** github|gitlab (default: auto-detect)
- **gitlab-host:** custom-gitlab.example.com
- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}]
- **special:** "any repo-specific instructions"
- **persistence:** true
- **enforcement:** warn (strict|warn|off)
- **isolation:** worktree (worktree|none|auto)
- **max-turns:** auto (housekeeping=8, feature=15, deep=25)
- **learning-expiry-days:** 30
- **discovery-on-close:** true
- **agent-mapping:** { impl: code-editor, test: test-specialist, db: database-architect }When dispatching agents, Session Orchestrator uses a three-tier resolution:
- Project agents (
.claude/agents/) — highest priority, domain-specific - Plugin agents (
session-orchestrator:*) — generic base agents, work in any project general-purpose— fallback when no specialized agent matches
The agent-mapping config lets you explicitly bind roles to agents. Without it, session-plan auto-matches tasks to agents based on their descriptions.
For the complete field reference with types, defaults, and descriptions, see the User Guide — Session Config Reference.
Session Orchestrator auto-detects your VCS from the git remote URL:
- Remote contains
github.com→ usesghCLI - All other remotes → uses
glabCLI
Override with vcs: github or vcs: gitlab in Session Config.
Session Orchestrator handles the session layer (orchestration, VCS integration, waves, close-out). Superpowers handles the task layer (TDD, debugging, brainstorming per feature).
/plan → PRD + Issues (optional: define WHAT to build)
↓
/session → Research → Q&A → Plan (define HOW to build it)
↓
/go → 5 Waves → Inter-Wave Reviews (execute)
↓
/close → Verify → Commit → Mirror (verify + ship)
- 10 Skills: session-start, session-plan, wave-executor, session-end, ecosystem-health, gitlab-ops, quality-gates, discovery, plan, evolve
- 6 Commands: /session, /go, /close, /discovery, /plan, /evolve
- 6 Agents: code-implementer, test-writer, ui-developer, db-specialist, security-reviewer (generic base agents) + session-reviewer (inter-wave quality gate)
- Hooks: SessionStart notification + Clank Event Bus integration + PreToolUse enforcement (scope + commands)
- Output Styles: 3 styles (session-report, wave-summary, finding-report) for consistent reporting
.codex-plugin/— Codex CLI plugin manifest (config.toml) + 3 agent role definitions (explorer, wave-worker, session-reviewer)scripts/— 5 deterministic scripts (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit) + shared lib + 184 tests
- User Guide — installation, config reference, workflow walkthrough, FAQ
- CONTRIBUTING.md — plugin architecture, skill anatomy, development setup
- CHANGELOG.md — version history
- Example Configs — Session Config examples for Next.js, Express, Swift