kanevry

Session Orchestrator

Claude Code plugin for session-level orchestration — project planning, wave execution, VCS integration, quality gates.

Claude Code is Anthropic's agentic coding CLI. This plugin adds structured session management on top — turning ad-hoc agent interactions into repeatable, quality-gated engineering workflows. No runtime code. Pure Markdown.

Install

# Add as a Claude Code plugin
claude plugin add github:Kanevry/session-orchestrator

Prerequisites

• Claude Code — Anthropic's agentic coding CLI
• jq (recommended) — required for scope and command enforcement hooks. Install via brew install jq (macOS) or apt install jq (Linux). Without jq, enforcement hooks allow all operations.

Why Session Orchestrator

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.

Soul Personality System

A soul.md file defines the orchestrator's identity as a seasoned engineering lead — with communication principles ("be direct"), a decision-making hierarchy (safety > productivity > quality > ecosystem health > speed), and values (pragmatism, evidence, ownership). This shapes every interaction, not just tone.

5-Wave Execution Pattern

Work flows through 5 typed waves: Discovery (read-only validation), Core Implementation, Polish & Integration, Quality & Testing, Finalization. The Quality wave includes a simplification pass that cleans AI-generated code patterns (unnecessary try-catch, over-documentation, redundant logic) before tests are written. Each wave has a defined purpose and agent count that scales by session type. This isn't just batching — it's structured engineering workflow.

Inter-Wave Quality Gates

A dedicated session-reviewer agent runs 8 review sections between waves: implementation correctness, test coverage, TypeScript health, OWASP security basics, issue tracking, silent failure analysis (catch blocks that swallow errors), test depth (assertion quality, mock boundaries), and type design (overly broad types, missing unions). Every finding is confidence-scored (0-100) — only high-confidence issues (>=80) make it into the report. Verification escalates progressively: changed-file tests after Impl-Core, full integration tests after Impl-Polish, complete quality suite after Quality.

Design-Code Alignment

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.

VCS Dual Support

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.

Ecosystem Health Monitoring

Checks configured service endpoints and scans cross-repo critical issues at session start. Know your ecosystem state before you start working.

Session Persistence & Safety

Sessions persist across interruptions via STATE.md — crash recovery, resume from pause point, and clean handover between sessions. PreToolUse hooks enforce agent scope (file paths) and block dangerous commands. A circuit breaker detects execution spirals (thrashing, repeated errors, self-reverts) and recovers automatically.

Metrics & Cross-Session Learning

Every session writes quantitative metrics (duration, agents, files changed per wave) plus effectiveness stats (completion rate, discovery probe value, carryover patterns) and extracts qualitative learnings (fragile files, effective sizing, recurring issues). After 5+ sessions, the system surfaces trends: low-value probes to disable, scope adjustments for high carryover, and completion rate analysis. The system gets smarter over time.

Adaptive Wave Sizing

Agent counts scale with session complexity. A scoring formula (files × modules × issues) determines simple/moderate/complex tier, which maps to concrete agent counts per role and session type. Dynamic scaling adjusts between waves based on actual agent performance.

Verified Session Close-Out