Session Orchestrator

Session Orchestrator is a Claude Code and Codex plugin that brings structured, wave-based development sessions to any project. It handles session planning, parallel agent execution, VCS integration, quality gates, and session close-out — so you can focus on deciding what to build while it orchestrates how.

---

Table of Contents

1. Quick Start
2. Bootstrap Gate
3. Commands Reference
4. Session Types
5. Session Config Reference
6. The Wave Pattern
7. Workflow Walkthrough
8. VCS Integration
9. Quality Gates
10. Design-Code Alignment (Pencil Integration)
11. Ecosystem Health
12. Quality Discovery
13. Harness Audit
14. Session Persistence
15. Safety Features
16. Session Metrics
17. Cross-Session Learning
18. Adaptive Wave Sizing
19. Cheat Sheet
20. FAQ
21. Troubleshooting

---

1. Quick Start

Install the plugin

Claude Code

Claude Code installs plugins through slash commands inside a running session. There is no claude plugin shell CLI — run these commands in the Claude Code prompt:

From GitHub (recommended for end users):

/plugin marketplace add Kanevry/session-orchestrator
/plugin install session-orchestrator@kanevry

From a local clone (for contributors or offline work):

/plugin marketplace add /absolute/path/to/session-orchestrator
/plugin install session-orchestrator@kanevry

After installation, starting Claude Code will display:

🎯 Session Orchestrator v3.x — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]

Codex

Clone the repository, then run the installer from the plugin root:

git clone https://github.com/Kanevry/session-orchestrator.git
cd session-orchestrator
npm install
node scripts/codex-install.mjs
codex plugin list --available --json

The installer uses Codex's public plugin marketplace add and plugin add lifecycle. Marketplace configuration only makes the plugin discoverable; the list output must separately show session-orchestrator@kanevry as installed and enabled. Next, fully restart Codex or start a fresh task, run /hooks, and review the bundle before approving it. Hook trust is operator-controlled and is never written or bypassed by the installer.

Rerun the installer after pulling changes. It performs plugin add on every run to refresh the installed bundle. The committed .codex-plugin/plugin.json version uses +codex.<UTC timestamp> as an explicit invalidation marker; the installer validates that tracked version but never rewrites it. For the full lifecycle, hook subset, and troubleshooting steps, see docs/codex-setup.md.

Add Session Config to your project

Open your project's Session Config host file and add a ## Session Config section:

• CLAUDE.md on Claude Code
• AGENTS.md on Codex

A minimal configuration looks like this:

## Session Config

test-command: npm test
typecheck-command: npm run typecheck
lint-command: npm run lint
agents-per-wave: 6
waves: 5
persistence: true
enforcement: warn
vcs: github

If you skip this step, the plugin uses sensible defaults: feature type, 6 agents per wave, 5 waves, and auto-detected VCS. See docs/session-config-template.md for the full field walkthrough.

Run your first session

/session feature

The orchestrator researches your project state autonomously, presents findings with recommendations, and asks you to pick a direction. Once you agree on a plan, run /go to execute it across multiple parallel agents in structured waves. When done, run /close to verify, commit, and clean up.

---

2. Bootstrap Gate

The Bootstrap Gate ensures every repository has a minimal structure before any orchestrator command runs. It exists because LLMs will rationalize their way past soft warnings in empty repos — Codex was observed bypassing the /plan Phase-0 abort entirely by falling back to "pragmatic paths", leaving repos unstructured. The gate replaces soft warnings with a state-file-backed, non-bypassable check that works identically on Claude Code, Codex, and Cursor.

When the gate runs

Phase 0 of every orchestrator skill — /session, /go, /close, /plan, /discovery, and /evolve — checks for three conditions before doing anything else:

1. A CLAUDE.md (or AGENTS.md on Codex) exists in the project root
2. That file contains a ## Session Config section
3. .orchestrator/bootstrap.lock is committed to the repository

If all three are present, the gate passes silently in under a second. If any are missing, the bootstrap flow starts.

What happens in an empty repo

When the gate triggers, the orchestrator:

1. Reads your first prompt to infer what kind of project this is
2. Recommends an intensity tier (see below) with one sentence of rationale
3. Asks you to confirm with a single yes/no question (or choose a different tier)
4. Runs the bootstrap flow for your tier
5. Commits .orchestrator/bootstrap.lock and exits

You then re-run your original command and proceed normally. The gate never fires again for this repo unless you delete the lock file.

The three tiers

Tiers are cumulative — Standard includes everything Fast does, Deep includes everything Standard does.

Fast — demos, spikes, prototypes

Suitable for: a Glücksrad demo, a weekend prototype, a proof-of-concept you may throw away.

Sets up:

• Minimal CLAUDE.md with ## Session Config (3-4 fields)
• .orchestrator/bootstrap.lock

No VCS issues, no PRD, no test scaffolding required.

Standard — MVPs, internal tools, small SaaS

Suitable for: a small SaaS product, an internal admin tool, a personal project you intend to maintain.

Sets up everything in Fast, plus:

• Standard CLAUDE.md with full Session Config
• Baseline directory structure per archetype
• VCS labels created (priority::*, status:*, type:*)
• Initial STATUS.md SSOT file

Deep — customer-facing systems, team repos, production

Suitable for: a customer-facing product, a shared team repository, anything with SLAs or compliance requirements.

Sets up everything in Standard, plus:

• Full PRD scaffolding in docs/prd/
• CI configuration baseline
• Security policy stub
• Comprehensive label taxonomy
• CONTRIBUTING.md with session workflow conventions

Public path (no local baseline)

If you do not have a local projects-baseline directory configured, the gate falls back to plugin-bundled minimal templates. Five archetypes are available:

Archetype	Use for
_minimal	Any project not matching a specific archetype
static-html	Static sites, landing pages
node-minimal	Node.js scripts, CLI tools, Express APIs
nextjs-minimal	Next.js applications
python-uv	Python projects using uv

On Claude Code, claude init generates a baseline and then the gate proceeds normally. On Codex and Cursor, the plugin-bundled templates are used directly.

The /bootstrap command

You can also run the bootstrap flow explicitly, outside of any session:

/bootstrap                    # Auto-detect tier from project context
/bootstrap --fast             # Force Fast tier
/bootstrap --standard         # Force Standard tier
/bootstrap --deep             # Force Deep tier
/bootstrap --upgrade standard # Upgrade an existing Fast repo to Standard
/bootstrap --retroactive      # Bootstrap an existing repo without resetting it

--retroactive is the recommended path for existing repos that predate the Bootstrap Gate — it adds the missing CLAUDE.md structure and lock file without touching your existing code or configuration.

Anti-bureaucracy promise

• Normal flow: exactly 1 question (tier confirmation)
• Ambiguous public path: maximum 2 questions (archetype selection + tier confirmation)
• The gate is idempotent — re-running it on an already-bootstrapped repo is a no-op
• .orchestrator/bootstrap.lock is the mechanical truth — no external service, no network call

Troubleshooting: retroactively bootstrapping an existing repo

If you have an existing repo that was created before the Bootstrap Gate and every orchestrator command now stops at Phase 0:

/bootstrap --retroactive

This adds the required structure around your existing files without modifying them. It takes under a minute.

---

3. Commands Reference

This section introduces the core commands of the session lifecycle — the ones the subsections below document in detail. Session Orchestrator ships many more; the full command inventory lives in docs/components.md.

Command	Purpose	When to use
/session [type]	Start a new session	Beginning of a work session
/go	Approve the plan and begin wave execution	After reviewing the proposed wave plan
/close	End the session with verification and commits	When all waves are complete
/discovery [scope]	Systematic quality discovery and issue detection	Anytime, or automatically during /close
/plan [mode]	Structured project planning and PRD generation	Before starting a session, or standalone
/evolve [mode]	Extract and manage cross-session learnings	After 2+ sessions, or to review/prune learnings

/session [type]

Starts a new development session. Accepts one argument: housekeeping, feature, or deep. If omitted, the type is read from your Session Config or defaults to feature.

/session feature
/session housekeeping
/session deep

This triggers autonomous research: git state, open issues, SSOT freshness, CI status, cross-repo health, and more. You then review findings and pick a direction before any code changes happen.

/go

Approves the wave plan and begins execution. You can optionally pass additional instructions:

/go
/go focus on the API endpoints first

This dispatches parallel subagents wave by wave. You do not need to intervene during execution — the orchestrator handles inter-wave reviews and plan adaptation automatically.

/close

Ends the session. This runs a full verification against the agreed plan, creates issues for any gaps, runs quality gates, commits cleanly, pushes, mirrors (if configured), and presents a session summary.

/close

/plan [mode]

Structured requirement gathering, PRD generation, and issue creation. Accepts one argument: new, feature, or retro.

/plan new
/plan feature
/plan retro

/plan new — Full project kickoff. Gathers requirements across 3 waves of questions (core decisions, technical details, business scope), generates an 8-section PRD, optionally scaffolds the repository, and creates a prioritized Epic with sub-issues. Typically 30-45 minutes.

/plan feature — Compact feature planning. Gathers requirements in 1-2 waves, generates a 5-section PRD with acceptance criteria, and creates feature sub-issues. Typically 5-15 minutes.

/plan retro — Data-driven retrospective. Reads session metrics from .orchestrator/metrics/sessions.jsonl, surfaces trends and patterns, guides reflection, and creates improvement issues. Typically 10-20 minutes.

When to use /plan vs /session:

• /plan answers "What should we build?" — requirements, PRDs, issues
• /session answers "How do we build it?" — wave planning, agent execution, verification

/plan runs outside of sessions. Its output (PRD + issues) feeds into the next /session, which picks from those issues and executes them. You can skip /plan entirely and create issues manually — sessions work with any existing issues.

Optional: plan-baseline-path in Session Config (for /plan new repo scaffolding from your own baseline). When absent, /bootstrap falls back to plugin-bundled minimal templates. Not required for /plan feature or /plan retro.

---

4. Session Types

Housekeeping

Best for: git cleanup, SSOT refresh, CI fixes, branch merges, documentation updates.

• Execution model: Serial (no wave structure)
• Agents: 1-2 per task
• Typical duration: Short
• Use when: Your repo needs maintenance, not new features

/session housekeeping

Feature

Best for: frontend/backend feature work, implementing issues, standard development.

• Execution model: 5 waves with parallel agents
• Agents: 4-6 per wave (configurable)
• Typical duration: Medium
• Use when: You have feature issues to implement

/session feature

Deep

Best for: complex backend work, security audits, database refactoring, architecture changes.

• Execution model: 5 waves with parallel agents
• Agents: Up to 10-18 per wave (configurable)
• Typical duration: Longer
• Use when: The work requires extensive discovery, testing, or touches critical systems

/session deep

---

5. Session Config Reference

Skill authors: The authoritative field reference used by all skills is docs/session-config-reference.md. Update that file when adding or changing Session Config fields.

Add a ## Session Config section to your project's Session Config host file to configure how Session Orchestrator behaves in that repository:

• CLAUDE.md on Claude Code
• AGENTS.md on Codex

Example

## Session Config

- **agents-per-wave:** 6
- **waves:** 5
- **pencil:** designs/app.pen
- **cross-repos:** [api-service, shared-lib]
- **ssot-files:** [.claude/STATUS.md]
- **mirror:** github
- **ecosystem-health:** true
- **vcs:** gitlab
- **gitlab-host:** gitlab.company.com
- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}, {name: "Worker", url: "http://worker:8080/healthz"}]
- **special:** "Always run database migrations before testing"
- **test-command:** pnpm vitest run
- **stale-issue-days:** 14
- **persistence:** true
- **plan-baseline-path:** ~/Projects/projects-baseline
- **plan-default-visibility:** internal
- **plan-prd-location:** docs/prd/
- **plan-retro-location:** docs/retro/
- **memory-cleanup-threshold:** 5
- **enforcement:** warn
- **isolation:** auto
- **max-turns:** auto

Field Reference

Field	Type	Default	Description
agents-per-wave	integer	6	Maximum number of parallel subagents per wave. Higher values increase parallelism but use more resources.
waves	integer	5	Number of execution waves for feature and deep sessions.
pencil	string	none	Path to a .pen design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves.
cross-repos	list	none	Related repositories under ~/Projects/. The orchestrator checks their git state and critical issues during session start.
ssot-files	list	none	Single Source of Truth files to track for freshness (e.g., STATUS.md, STATE.md). Flagged if older than 5 days.
mirror	string	none	Mirror target after push. Set to github to automatically push to a GitHub remote after every session commit.
ecosystem-health	boolean	false	Enable service health checks at session start. Requires health-endpoints to be configured.
vcs	string	auto-detect	Version control platform: github or gitlab. Auto-detected from git remote URL if not set.
gitlab-host	string	from remote	Custom GitLab hostname. Only needed if the host cannot be inferred from the git remote URL.
health-endpoints	list	none	Service URLs to check health. Each entry is an object with name and url fields.
special	string	none	Repo-specific instructions. Freeform text that the orchestrator reads and follows during sessions.
test-command	string	npm test	Custom test command. Used by quality gates for all test invocations.
typecheck-command	string	npm run typecheck	Custom TypeScript check command. Set to skip for non-TS projects.
lint-command	string	npm run lint	Custom lint command. Used by the Full Gate quality check at session end.
ssot-freshness-days	integer	5	Days before an SSOT file is flagged as stale during session start.
plugin-freshness-days	integer	30	Days before the plugin itself is flagged as potentially outdated.
recent-commits	integer	20	Number of recent commits to display during session start git analysis.
issue-limit	integer	50	Maximum issues to fetch when querying VCS during session start.
stale-branch-days	integer	7	Days of inactivity before a branch is flagged as stale.
stale-issue-days	integer	30	Days without progress before an issue is flagged for triage.
discovery-on-close	boolean	false	Run discovery probes automatically during /close.
discovery-probes	list	[all]	Probe categories to run: all, code, infra, ui, arch, session, audit, vault, feature.
discovery-exclude-paths	list	[]	Glob patterns to exclude from discovery scanning (e.g., vendor/**, dist/**).
discovery-severity-threshold	string	low	Minimum severity for reported findings: critical, high, medium, low.
discovery-confidence-threshold	integer	60	Minimum confidence score (0-100) for discovery findings to be reported. Findings below this threshold are auto-deferred.
issue-budget.max-per-session	integer	12	Per-session cap on non-exempt issue creations. A quantity gate — unlike the two discovery-*-threshold filters above, which score individual findings and cannot bound volume. priority::critical, the carryover class and broken-window issues are exempt.
issue-budget.mode	string	strict	strict blocks over-cap creations and parks them; warn allows with a stderr notice; off disables the gate.
issue-budget.overflow	string	collect-issue	Where parked creations are drained at session-end: collect-issue (one [Backlog-Sammel] issue) or vault-note (one file under vault/00-inbox/).
persistence	boolean	true	Enable session resumption via STATE.md and session memory files.
plan-baseline-path	string	none	Path to projects-baseline directory (e.g., ~/Projects/projects-baseline). Optional. When absent, /bootstrap falls back to plugin-bundled minimal templates. Only required if you want to scaffold from your own baseline during /plan new.
plan-default-visibility	string	internal	Default repo visibility for /plan new: internal, private, or public.
plan-prd-location	string	docs/prd/	Directory where PRD documents are saved (relative to project root).
plan-retro-location	string	docs/retro/	Directory where retrospective documents are saved (relative to project root).
memory-cleanup-threshold	integer	5	Recommend /memory-cleanup after N accumulated session memory files.
memory-cleanup-soft-limit	integer	180	Hard ceiling on accumulated memory files before the cleanup nudge escalates from soft suggestion to strong recommendation. PRD F2.2 / issue #502.
vault-mirror.quality.min-narrative-chars	integer	400	Minimum body length (characters) before a learning or session note is mirrored to the vault. Notes shorter than this threshold are skipped. PRD F1.2 / issue #504.
vault-mirror.quality.min-confidence	float	0.5	Minimum learning confidence (0.0..1.0) before a learning note is mirrored. Set to 0.0 to mirror every learning regardless of confidence. PRD F1.2 / issue #504.
cold-start.enabled	boolean	true	Master toggle for the cold-start detector. When false, no idle-time nudges fire at session-start. PRD F1.3 / issue #500.
cold-start.nudge-after-hours	integer	1	Hours of wall-clock idle (since the last session-end) before the cold-start detector fires a nudge. PRD F1.3 / issue #500.
cold-start.silence-after-sessions	integer	1	Consecutive silent sessions (no commits, no learnings) before the cold-start detector fires a nudge. PRD F1.3 / issue #500.
enforcement	string	warn	Hook enforcement level for scope and command restrictions: strict, warn, or off.
isolation	string	auto	Agent isolation mode: worktree, none, or auto. auto resolves per-wave via the graduated default (#194): ≤2 agents → none, 3–4 agents on feature/deep → worktree, ≥5 agents → worktree, housekeeping 3–4 → none. See Section 15 "Isolation Graduation" below.
max-turns	integer or string	auto	Max agent turns before PARTIAL. Auto: housekeeping=8, feature=15, deep=25.

Security: Do not embed credentials, API keys, or auth tokens in Session Config fields — especially health-endpoints URLs. These values are stored in your config host file (CLAUDE.md / AGENTS.md) which may be committed to version control. Use header-based auth or separate secret management instead.

Minimal Config

If you add no Session Config at all, the orchestrator uses these defaults:

• Session type: feature
• Agents per wave: 6
• Waves: 5
• VCS: auto-detected from git remote
• Everything else: disabled/none

See examples for project-specific configurations (Next.js, Express API, Swift iOS).

---

6. The Wave Pattern

Feature and deep sessions execute work in structured waves, each assigned one of 5 roles. Each wave has a specific purpose, and agents within a wave run in parallel.

Wave Structure

Role	Purpose	Agents modify code?
Discovery	Understand the current state before changing anything	No (read-only)
Impl-Core	Core feature work — the primary implementation	Yes
Impl-Polish	Polish, fix Impl-Core issues, integration, edge cases	Yes
Quality	Tests, TypeScript checks, lint, security review	Yes (tests only)
Finalization	Documentation, issue cleanup, commit preparation	Minimal

Role-to-Wave Mapping

Roles map dynamically to the configured wave count (default: 5):

waves	Mapping
3	W1=Discovery+Impl-Core, W2=Impl-Polish+Quality, W3=Finalization
4	W1=Discovery, W2=Impl-Core+Impl-Polish, W3=Quality, W4=Finalization
5	W1=Discovery, W2=Impl-Core, W3=Impl-Polish, W4=Quality, W5=Finalization
6+	W1=Discovery, W2-W3=Impl-Core (split), W4-W5=Impl-Polish (split), W6=Quality+Finalization

Wave Details

Discovery Agents audit affected code paths, verify assumptions from the plan, check existing test coverage, and identify edge cases. This wave is read-only: no files are modified. If discoveries warrant it, the plan is adjusted before Impl-Core begins.

Impl-Core The primary implementation wave. Agents write core feature code, database changes, API endpoints, and primary UI components. Each agent has a clearly scoped set of files and acceptance criteria. Output: a working (possibly rough) implementation.

Impl-Polish Agents fix issues discovered during Impl-Core, implement secondary features, handle integration between Impl-Core outputs, and address edge cases. If Pencil design review is configured, a design-code alignment check runs after this wave.

Quality Before test writers run, the orchestrator dispatches 1-2 simplification agents that scan all files changed in the session (excluding test files) and clean up common AI-generated code patterns — unnecessary try-catch wrappers, over-documentation, re-implemented stdlib functions, and redundant boolean logic. These agents reference slop-patterns.md (produced by the discovery skill) and do not change functionality. After simplification, the remaining agents write and update tests, run quality checks per the quality-gates skill, and perform a security review. Goal: all tests passing, zero TypeScript errors, no lint violations.

Finalization One or two agents update SSOT files, close or update issues, write session handover documentation, and prepare clean commits. No new feature work happens here.

Agent Counts by Session Type

Session Type	Discovery	Impl-Core	Impl-Polish	Quality	Finalization
housekeeping	2	2	1	1	1
feature	4-6	6	4-6	4	2
deep	6-8	6-10	6-8	6	2-4

The agents-per-wave config value caps the maximum. These counts are guidelines — the orchestrator adjusts based on task complexity.

The Quality column is a cap, not a target: since this version, test-writing capacity is need-gated on measured demand — roughly one test-writer per three HIGH/MED gaps the review panel actually found, capped by the number above. If no gaps were measured, the Quality wave writes no tests and is skipped (the read-only review panel still runs); with no measurement signal at all, the orchestrator allocates a conservative 1-2 rather than the full cap.

Inter-Wave Checkpoints

Between each wave, the orchestrator:

1. Reviews all agent outputs
2. Checks for file conflicts between agents
3. Runs verification based on wave role (Incremental after Impl-Core/Impl-Polish, Full Gate after Quality)
4. Runs design review if configured (after Impl-Core and Impl-Polish roles)
5. Adapts the plan for the next wave if needed (adds fix tasks, re-scopes)
6. Reports progress to you

---

7. Workflow Walkthrough

Here is what happens step by step when you run a full feature session.

Step 1: Start the session

/session feature

The orchestrator autonomously researches your project:

• Git analysis: Branch state, recent commits, unpushed changes, stale branches
• VCS deep dive: Open issues (categorized by priority), recently closed issues, open MRs/PRs, CI pipeline status, active milestones
• SSOT check: Freshness of tracked files, TypeScript error count, test baseline
• Cross-repo status: Git state and critical issues in related repositories
• Ecosystem health: Service endpoint checks (if configured)
• Pattern recognition: Recurring issue patterns, blocking chains, quick wins, synergies

Step 2: Review findings and pick a direction

The orchestrator presents a structured overview:

## Session Overview
- Type: feature
- Repo: my-app on branch main
- Git: 0 uncommitted, 0 unpushed, 3 open branches
- VCS: 12 open issues (2 high, 4 medium), 1 open PR
- Health: TypeScript: 0 errors | Tests: passing | CI: green
- SSOT: STATUS.md fresh (2 days)

## Recommended Focus
Option A (recommended): Issues #42 + #45 — high synergy, shared code paths
Option B: Issue #38 — standalone deep work, can be done independently
Option C: Issues #50 + #51 + #52 — quick wins, clean up the backlog

You pick an option (or propose your own). The orchestrator does not proceed until you confirm.

Step 3: Review the wave plan

After you choose a direction, the orchestrator decomposes the work into a role-based wave plan:

## Wave Plan (Session: feature)

### Wave 1: Discovery (4 agents)
- Agent 1: Audit API endpoint structure → src/api/ → map current routes
- Agent 2: Verify database schema → prisma/schema.prisma → check relations
...

### Wave 2: Impl-Core (6 agents)
- Agent 1: Implement new API route → src/api/users.ts → endpoint returns 200
...

### Inter-Wave Checkpoints
- After Impl-Core: Design review (Pencil configured)
- After Quality: Full quality gate

Ready to execute? Use /go to begin.

You can request changes to the plan. When satisfied:

Step 4: Execute

/go

Waves execute automatically. Agents within each wave run in parallel. Between waves, the orchestrator reviews results, runs checks, and adapts the plan if needed. You see progress updates after each wave:

## Wave 2 (Impl-Core) Complete ✓
- Agent 1: done — API route implemented, returns correct schema
- Agent 2: done — Database migration created
- Agent 3: done — Frontend form component built
- Tests: 3 new passing | TypeScript: 0 errors
- Design: ALIGNED
- Adaptations for Impl-Polish: none

Step 5: Close the session

After the Finalization wave completes:

/close

The orchestrator:

1. Verifies every planned item against the agreed plan (with evidence)
2. Creates issues for any work that was not completed (carryover issues)
3. Runs quality gates: TypeScript (0 errors), tests (passing), lint (clean), no debug artifacts
4. Updates SSOT files with current metrics
5. Commits using Conventional Commits format, staging files individually
6. Pushes to origin
7. Mirrors to GitHub (if configured)
8. Closes/updates issues on your VCS platform
9. Presents a session summary with completed items, carryovers, new issues, metrics, and recommendations for the next session

---

8. VCS Integration

Session Orchestrator works with both GitHub and GitLab. It manages issues, merge requests / pull requests, labels, milestones, and CI status throughout the session.

Auto-Detection

The VCS platform is detected from your git remote URL:

• Remote contains github.com --> uses gh CLI
• All other remotes --> uses glab CLI

To override auto-detection, set vcs in your Session Config:

- **vcs:** github

or

- **vcs:** gitlab
- **gitlab-host:** gitlab.company.com

What the orchestrator does with your VCS

At session start:

• Lists open issues, categorized by priority and status labels
• Lists recently closed issues (context from last session)
• Checks active milestones
• Lists open MRs/PRs
• Checks CI pipeline status

During execution:

• Marks selected issues as status:in-progress
• Adds comments to issues noting which wave is working on them

At session end:

• Closes resolved issues with a summary comment
• Updates issue labels to reflect actual state
• Creates carryover issues for partially-completed work
• Creates new issues for discovered problems
• Updates milestone progress

Label Taxonomy

The orchestrator uses a structured label system for issue management. For the complete label taxonomy (priority, status, area, and type labels), see the Label Taxonomy section of the gitlab-ops skill (skills/gitlab-ops/SKILL.md).

Create these labels in your VCS platform if they do not already exist. The orchestrator will use them automatically during session start (categorizing issues), execution (marking in-progress), and close-out (updating status).

GitHub Mirroring

If your primary VCS is GitLab but you also maintain a GitHub mirror, configure:

- **mirror:** github

The orchestrator pushes to the github remote after every session commit. The remote must already be configured in your git config.

---

9. Quality Gates

Session Orchestrator enforces quality at two levels: inter-wave checks during execution, and a full quality gate at session end.

Session Reviewer Agent

The session-reviewer is a dedicated agent that verifies work quality. It runs between waves (especially before Impl-Polish and after Quality) and at session end. It checks:

1. Implementation correctness — Changed files match task descriptions. No incomplete implementations, placeholder values, or hardcoded data. Error handling follows project patterns.

2. Test coverage — Every changed source file has a corresponding test file. Tests cover the new behavior (not just boilerplate). Tests pass when run.

3. TypeScript health — typecheck per quality-gates skill reports zero errors. This is non-negotiable.

4. Security basics (OWASP quick check):

   • No hardcoded secrets or API keys
   • User input validated at boundaries (e.g., with Zod)
   • No unjustified any types
   • No console.log in production code (except warn/error)
   • SQL uses parameterized queries
   • Auth checks present in server actions

5. Issue tracking accuracy — Claimed issues have the correct status labels. Acceptance criteria from issues are actually met.

6. Silent failure analysis — Catch blocks that swallow errors, empty error handlers, and fallback returns that hide failures.

7. Test depth check — Tests exercise changed behavior (not just boilerplate), edge cases are present, assertion quality is adequate, and mock boundaries are correct.

8. Type design spot-check — String parameters that should be unions, overly broad any types, and unused generics.

Each finding includes a confidence score (0-100). Only findings with confidence >= 80 appear in the main report. Findings scored 50-79 are listed in a separate "Possible Issues" section for manual review.

Review Output

The reviewer produces a structured verdict:

## Quality Review — Impl-Core

### Implementation: PASS
### Tests: WARN — missing test for src/api/users.ts
### TypeScript: PASS — 0 errors
### Security: PASS
### Issues: PASS

### Verdict: PROCEED (address test gap in Quality wave)

Possible verdicts:

• PROCEED — quality is acceptable, continue to next wave
• FIX REQUIRED — specific items must be addressed before continuing

Session-End Quality Gate

Before any code is committed, /close runs all checks:

Check	Requirement
TypeScript	0 errors
Tests	All passing
Lint	No errors (warnings acceptable)
Debug artifacts	No console.log, debugger, or TODO: remove in changed files
Git status	All changes accounted for

If any check fails and cannot be quickly fixed, the orchestrator creates a priority::high issue for immediate follow-up rather than committing broken code.

Deterministic Scripts

Session Orchestrator includes bash scripts for critical workflow paths. These provide deterministic, testable alternatives to agent-interpreted instructions:

• scripts/parse-config.mjs — Parses ## Session Config from a config host file, outputs validated JSON with all 40+ fields and defaults applied. Run: node scripts/parse-config.mjs [path/to/CLAUDE.md|AGENTS.md]
• scripts/run-quality-gate.mjs — Runs quality gates with structured JSON output. Supports 4 variants: baseline, incremental, full-gate, per-file.
• scripts/validate-wave-scope.mjs — Validates wave-scope.json before enforcement hooks consume it. Checks for path traversal, absolute paths, and required fields.

Run npm test to execute the vitest suite.

---

10. Design-Code Alignment (Pencil Integration)

If your project uses Pencil (.pen) design files, the orchestrator can automatically compare your implementation against the design after each implementation wave.

Setup

Add the path to your .pen file in Session Config:

- **pencil:** designs/app.pen

The path is relative to your project root. The orchestrator verifies the file exists during session start.

How it works

After Impl-Core and Impl-Polish waves, the orchestrator:

1. Opens the .pen file via Pencil MCP
2. Finds design frames relevant to the current wave's UI work
3. Screenshots those frames
4. Reads the actual UI files changed in the wave
5. Compares: layout structure, component hierarchy, visual elements (headings, buttons, inputs, cards), responsive behavior

Alignment Reports

Each design review produces one of three verdicts:

Verdict	Meaning	Action
ALIGNED	Implementation matches design	Proceed as planned
MINOR DRIFT	Small differences (spacing, colors, minor layout)	Fix tasks added to next wave automatically
MAJOR MISMATCH	Significant deviation from design	User informed, revised plan proposed

Example output

## Wave 2 (Impl-Core) Complete ✓
...
- Design: MINOR DRIFT — card grid uses 3 columns instead of designed 2-column layout
- Adaptations for Impl-Polish: Agent 2 assigned to fix card grid layout

Without Pencil

Pencil integration is entirely optional. If no pencil path is configured, design reviews are skipped with no impact on the rest of the session workflow.

---

11. Ecosystem Health

For projects with deployed services or multiple related repositories, the orchestrator can check ecosystem health at session start.

Setup

Enable ecosystem health and configure your endpoints in Session Config:

- **ecosystem-health:** true
- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}, {name: "Dashboard", url: "http://localhost:3000/api/health"}]
- **cross-repos:** [api-service, shared-lib]

What gets checked

Service health endpoints: Each configured endpoint is queried with a simple HTTP check. If the endpoint returns JSON with a status field, that value is reported. Otherwise, the check reports OK or unreachable.

Cross-repo critical issues: For each related repository, the orchestrator queries open issues with priority::critical or priority::high labels. This surfaces blocking problems in other parts of your ecosystem before you start working.

CI pipeline status: The latest CI pipeline runs are checked for the current repository.

Health Report

The report appears in the session overview:

## Ecosystem Health
| Service   | Status      |
|-----------|-------------|
| API       | OK          |
| Dashboard | unreachable |

Critical issues: 2 across cross-repos
CI: green

Any service that is down or any critical issue count above zero is flagged as requiring attention.

Graceful Degradation

If health-endpoints is not configured, the service table is omitted. If cross-repos is not configured, the cross-project issue scan is omitted. The orchestrator does not fail — it simply skips the unconfigured checks.

---

12. Quality Discovery

The /discovery command runs systematic quality probes to find issues that don't have VCS issues yet.

Usage

/discovery              # Scan all categories
/discovery code         # Code quality only
/discovery session      # Session gap analysis only
/discovery code,session # Multiple categories

Scope Options

Scope	Probes	Focus
all	23 probes	Everything (default)
code	8 probes	Hardcoded values, dead code, AI slop, type safety, tests, security
infra	4 probes	CI pipelines, env config, dependencies, deployments
ui	3 probes	Accessibility, responsive design, design drift
arch	3 probes	Circular deps, complexity hotspots, dependency security
session	5 probes	Gap analysis, hallucination check, stale issues, dependency chains, claude-md audit

How It Works

1. Stack Detection -- Detects your tech stack (JS/TS, Python, Docker, etc.) and activates relevant probes
2. Probe Execution -- Runs probes in parallel as read-only subagents
3. Verification -- Re-reads files to confirm findings, discards false positives
4. Interactive Triage -- Critical/High findings reviewed individually; Medium/Low batched by category
5. Issue Creation -- Approved findings become VCS issues with type:discovery label

Embedded Mode

Set discovery-on-close: true in Session Config to automatically run discovery during /close. In embedded mode, critical/high findings become issues; medium/low are listed in the session report.

Confidence Scoring

Each verified finding receives a confidence score from 0 to 100 that reflects how trustworthy the detection is. The score starts at a baseline of 40 and adds points from three factors: pattern specificity (how specific the match pattern is — generic patterns score lower), file context (whether surrounding code reinforces the finding), and historical signal (whether the same issue has appeared in prior discovery runs). Each factor contributes 0, 10, or 20 points, so scores range from 40 to 100 in practice.

Findings below the confidence threshold are auto-deferred — they skip interactive triage entirely and appear in a collapsed summary instead. The threshold is controlled by discovery-confidence-threshold in your Session Config (default: 60). Raise it if you are seeing too many false positives in triage; lower it if you want more aggressive detection. Auto-deferred findings are not lost — you can review them anytime with /discovery --include-deferred.

One exception: findings with critical severity always receive a minimum confidence of 70, regardless of how the three factors score. This ensures that critical issues — potential security holes, data-loss risks — are never silently deferred. They always appear in interactive triage.

## Session Config
discovery-confidence-threshold: 60   # default; raise to reduce noise

---

13. Harness Audit

The harness audit scores this repository against the session-orchestrator rubric — a structured set of checks that verify the repo is set up correctly and the orchestrator has what it needs to run reliably. Run it whenever you want a baseline health reading or after making structural changes to the project setup.

How to run

/harness-audit

Or directly from the shell:

node scripts/harness-audit.mjs

No flags. The script always audits the current working directory / repo root.

What it produces

• stdout — a JSON record matching the audit schema (see below)
• stderr — a concise human-readable summary
• .orchestrator/metrics/audit.jsonl — the same record appended as a single JSONL line for historical tracking

The 9 categories

Category	What it checks
Session Discipline	STATE.md lifecycle, session-type usage, turn-limit compliance
Quality Gate Coverage	Test command configured, typecheck command configured, lint command configured
Hook Integrity	All registered hook handlers point to existing files
Persistence Health	sessions.jsonl present and parseable, learnings.jsonl consistent
Plugin-Root Resolution	Plugin path resolves correctly; bootstrap.lock committed
Config Hygiene	Session Config fields are valid types; no unknown fields; no embedded secrets
Policy Freshness	blocked-commands.json present; rubric_version matches 2026-06
Large-Codebase Readiness	Layered instruction files, a navigable codebase map, LSP/language-server tooling, scoped test/lint commands, a version-controlled destructive-command deny-list, and a lean delegated root
Skill-Health Surfacing	Skill-invocation telemetry hygiene, the skill-health scorer module wired correctly, and an advisory (never-scored) verdict tally — absence of adoption is a healthy state, not a defect

Severity escalation

Score	Level	Action
≥ 7/10	Info	No action required
5–7/10	Medium finding	Review and address in next session
< 5/10	High finding	Surfaces automatically via /discovery audit

Rubric version and bump policy

The current rubric version is 2026-06. It is embedded in every audit record as the rubric_version field. When session-orchestrator releases a minor version that changes the rubric, the version string is bumped via a conventional commit (chore: bump rubric version to YYYY-MM). Older records in audit.jsonl retain their original rubric_version and remain valid — use the field to filter when comparing across versions.

Related commands

/discovery audit runs only the harness-audit probe within the discovery framework, without the full multi-category scan.

---

14. Session Persistence

Session Orchestrator persists session state so you can resume after crashes, pauses, or context window exhaustion.

STATE.md

Lives at .claude/STATE.md in your project. Contains YAML frontmatter (session-type, branch, issues, started, status, current-wave, total-waves) and a Markdown body tracking the Current Wave, Wave History, and any Deviations from the plan. Written by the wave-executor after each wave; read by session-start on the next /session invocation.

Session Continuity

When you run /session, the orchestrator checks for an existing STATE.md:

• status: active -- Crashed or interrupted session detected. You are offered the choice to resume from the last completed wave or start fresh.
• status: paused -- Intentional pause (e.g., you closed Claude Code mid-session). Resume picks up where you left off.
• status: completed -- Normal end state. No resume offered; a new session starts cleanly.

Session Memory

After each session, /close writes a memory file to ~/.claude/projects/<project>/memory/session-<date>.md containing Outcomes, Learnings, and Next Session recommendations. On the next /session, the orchestrator reads the last 2-3 session memory files for context continuity across sessions.

When memory files accumulate past the memory-cleanup-threshold (default: 5), the orchestrator recommends running /memory-cleanup to consolidate them.

Disabling Persistence

Set persistence: false in your Session Config to disable STATE.md writing and session memory. Sessions will not be resumable and will not carry context forward.

---

15. Safety Features

Scope Enforcement

Before each wave, the wave-executor writes .claude/wave-scope.json defining the allowed file paths and blocked commands for that wave's agents. PreToolUse hooks validate Edit/Write operations against allowedPaths and Bash commands against blockedCommands.

Enforcement levels (configured via enforcement):

Level	Behavior
strict	Out-of-scope operations are denied
warn	Out-of-scope operations are allowed but logged with a warning
off	No enforcement; agents have full access

Prerequisites

Scope and command enforcement hooks require jq to be installed. If jq is not available, hooks degrade gracefully — all operations are allowed with a warning to stderr. Install jq for enforcement to be active:

• macOS: brew install jq
• Ubuntu/Debian: sudo apt-get install jq
• Alpine: apk add jq

Circuit Breaker

The orchestrator enforces turn limits per session type to prevent runaway execution:

Session Type	Default Max Turns
housekeeping	8
feature	15
deep	25

Override with max-turns in Session Config, or set to auto for these defaults.

The circuit breaker also detects execution spirals: a file edited 3+ times within a single agent's execution, repeated identical errors, or self-reverts. Recovery depends on the failure mode:

• FAILED -- A fix task is created for the next wave
• PARTIAL -- Completed work is carried forward; remaining tasks become carryover issues
• SPIRAL -- Changes are reverted and the scope is narrowed before retrying

Worktree Isolation

When isolation is set to worktree, each subagent gets its own git worktree. This prevents file conflicts between agents working in parallel within the same wave. When set to none, all agents work in the coordinator's working tree in-place.

Isolation Graduation (#194)

isolation: auto (the default) is not a session-type switch — it is resolved per wave using the graduated default:

agentCount	sessionType	resolved
≤ 2	any	none
3–4	housekeeping	none
3–4	feature / deep	worktree
≥ 5	any	worktree

The reason: worktrees are a tax, not a free lunch. Two full repo copies per wave, build artifacts duplicated, and merge-back risk when the coordinator commits inline. On small waves (1–2 agents on partitioned scopes) the tax is not worth paying — in-place dispatch is cleaner. On larger waves the isolation actually matters.

Overrides:

• Explicit isolation: worktree or isolation: none in Session Config disables the graduation entirely.
• Session-plan may emit collision-risk: high on a wave spec to force worktree even at ≤2 agents — use it when agents will touch the same file.

Enforcement auto-promote: when isolation resolves to none, enforcement: warn auto-promotes to strict for that wave. Worktrees provide filesystem-level isolation; in-place dispatch relies solely on the scope hook, so it must be hard. Explicit enforcement: off is respected.

Base-Ref Freshness (#195)

Even with graduated isolation, worktree dispatch still carries a subtle risk: if the coordinator commits inline to main AFTER a worktree agent was created, the agent's merge-back silently overwrites those inline commits (the agent's base-ref is stale). This is not theoretical — it happened twice consecutively on 2026-04-20.

The fix: wave-executor persists worktree meta at creation time (.orchestrator/tmp/worktree-meta/<suffix>.json) recording baseSha, baseRef, and createdAt. Before each merge-back, it checks whether main has advanced. Four outcomes:

• pass — base matches current main. Merge-back proceeds normally.
• warn — main advanced, but drift does not overlap the agent's scope. Log and proceed.
• block — main advanced AND drift overlaps the agent's scope. Merge-back is refused; coordinator reconciles manually or rebases.
• no-meta — meta missing/corrupted. Falls back to manual diff review.

You do not configure this guard — it runs automatically for every isolation: worktree dispatch when persistence is enabled. The freshness events are logged to .orchestrator/metrics/events.jsonl as event: freshness_check for post-hoc analysis.

---

16. Session Metrics

Session Orchestrator tracks metrics across sessions to provide historical trends and inform future planning.

What is tracked

• Per-wave: duration (wall-clock), agent count, files changed, quality check result
• Per-session: total duration, total waves, total agents, total files changed, agent summary (complete/partial/failed/spiral)

Storage

Metrics are stored in .orchestrator/metrics/sessions.jsonl — one JSON line per session, append-only. This file is created automatically on first session close.

Historical Trends

During session-start (Phase 7), the last 5 sessions are displayed as a trend table:

Session	Type	Duration	Waves	Agents	Files Changed

If fewer than 2 sessions exist, the message "Not enough history for trends (need 2+)" is displayed.

Quality Gates Output

Quality gates (Incremental and Full Gate variants) produce structured JSON output for metrics integration, including duration, check status, and error details.

Effectiveness Tracking

After 5 or more completed sessions, session-start automatically computes effectiveness metrics from sessions.jsonl and surfaces them in the Project Intelligence section of the session overview. Three metrics are tracked:

• Completion rate trend — averages effectiveness.completion_rate over the last 5 sessions. If the rate is below 0.6, the orchestrator suggests reducing scope. If above 0.9, it confirms that current sizing works well.
• Discovery probe value — if the ratio of actioned findings to total findings stays below 0.1 across 3 or more sessions for a probe category, that category is flagged as low-value and may be excluded from future discovery runs.
• Carryover pattern — if the ratio of carryover issues to planned issues exceeds 0.3 across 3 or more sessions, the orchestrator suggests smaller scope or switching to deep sessions to reduce persistent overflow.

These metrics are only displayed once enough session history exists; projects with fewer than 5 sessions see the standard trend table instead.

Requires: persistence: true (default) in Session Config.

---

17. Cross-Session Learning

The learning system captures patterns from completed sessions and surfaces them in future sessions as "Project Intelligence."

What is learned

• Fragile files: files that needed 3+ iterations or caused cascading failures
• Effective sizing: which agent counts worked for different complexity levels
• Recurring issues: issue patterns that appear across waves (type errors, missing imports)
• Scope guidance: how many issues fit comfortably in one session
• Deviation patterns: plan adaptations that recur across sessions (scope changes, unexpected blockers)

Storage

Learnings are stored in .orchestrator/metrics/learnings.jsonl — one JSON line per learning.

Confidence System

Each learning has a confidence score (0.0 to 1.0):

• New learnings start at 0.5
• Confirmed by a subsequent session: +0.15
• Contradicted by a subsequent session: -0.2
• Learnings at 0.0 are removed
• Learnings expire after 90 days
• Only learnings with confidence > 0.3 are surfaced

Lifecycle

1. Collection (session-end Phase 3.5a): analyze completed session, extract learnings
2. Consumption (session-start Phase 5.6 + session-plan Step 1): read and apply learnings
3. Pruning (session-end Phase 3.6): remove expired and zero-confidence entries

Requires: persistence: true (default) in Session Config.

Managing Learnings with /evolve

The /evolve command gives you manual control over the learning system.

Analyze Mode (default)

/evolve
/evolve analyze

Reads sessions.jsonl, extracts patterns (fragile files, sizing, scope, recurring issues, deviations), deduplicates against existing learnings, and presents candidates for your approval via interactive selection. Only confirmed learnings are saved.

When to use: After 2-3 sessions to validate the tool, or when you suspect the learning system is missing patterns.

Review Mode

/evolve review

Displays all active learnings in a formatted table grouped by type. You can:

• Boost confidence (+0.15) for learnings you've validated
• Reduce confidence (-0.2) for learnings that seem wrong
• Delete specific learnings
• Extend expiry (+90 days) for learnings you want to keep longer

When to use: When Project Intelligence suggestions seem off, or to prune stale learnings.

List Mode

/evolve list

Read-only display of all active learnings with confidence scores and expiry dates. Shows high-confidence (>0.7) and expiring-soon (<14 days) counts.

When to use: Quick check of what the system has learned, without making changes.

---

18. Adaptive Wave Sizing

Instead of fixed agent counts, the orchestrator scores session complexity and adjusts agent allocation dynamically.

Complexity Scoring

Three factors are scored (0-2 points each):

Factor	0 points	1 point	2 points
Files to change	1-5	6-15	16+
Cross-module scope	1 directory	2-3 directories	4+ directories
Issue count	1 issue	2-3 issues	4+ issues

Complexity Tiers

• Simple (0-1 points): fewer agents per wave
• Moderate (2-3 points): standard allocation
• Complex (4-6 points): maximum agents per wave

Dynamic Scaling Between Waves

After each wave, agent count is adjusted based on performance:

• All agents fast + no issues → reduce next wave
• Failures or broken code → add fix agents
• Scope expansion → scale up
• Quality regressions → targeted fix agents

The agents-per-wave config value always caps the maximum.

Note: Housekeeping sessions skip complexity scoring and use fixed counts.

---

19. Cheat Sheet

Commands

/session feature       Start a feature session
/session housekeeping  Start a cleanup/maintenance session
/session deep          Start a deep work session (complex, many agents)
/go                    Approve plan, begin wave execution
/go <instructions>     Approve plan with additional guidance
/close                 Verify all work, commit, push, clean up issues
/discovery             Run quality probes across all categories
/discovery code        Scan code quality only
/discovery code,arch   Scan multiple categories
/plan new              Plan a new project (PRD + repo setup + issues)
/plan feature          Plan a feature (compact PRD + issues)
/plan retro            Run a data-driven retrospective
/evolve                Analyze sessions, extract learnings (default: analyze)
/evolve analyze        Extract patterns from session history
/evolve review         Interactively manage existing learnings
/evolve list           Display active learnings

Session Config (add to CLAUDE.md or AGENTS.md)

## Session Config

- **agents-per-wave:** 6
- **waves:** 5
- **vcs:** github
- **gitlab-host:** gitlab.company.com
- **mirror:** github
- **pencil:** designs/app.pen
- **cross-repos:** [other-repo]
- **ssot-files:** [.claude/STATUS.md]
- **ecosystem-health:** true
- **health-endpoints:** [{name: "API", url: "https://api.example.com/health"}]
- **special:** "Run migrations before testing"
- **discovery-on-close:** true
- **discovery-probes:** [code, arch]
- **discovery-severity-threshold:** medium
- **persistence:** true
- **enforcement:** warn
- **isolation:** auto
- **max-turns:** auto

Typical Session Flow

/plan feature             # (Optional) Define requirements → PRD + issues
/session feature          # Research + recommendations → pick issues
  (pick a direction)      # User chooses focus
  (review wave plan)      # Orchestrator proposes role-based wave plan
/go                       # Execute waves with parallel agents
  (role-based waves execute) # Automatic, with inter-wave reviews
/close                    # Verify, commit, push, summarize
/plan retro               # (Optional) Retrospective → improvement issues

Wave Quick Reference

Discovery       Validation & read-only audit
Impl-Core       Primary implementation (core work)
Impl-Polish     Fix, integrate, polish, edge cases
Quality         Tests, TypeScript, lint, security
Finalization    Documentation, issues, commits

---

20. FAQ

Can I use this with GitHub?

Yes. The orchestrator auto-detects your VCS platform from the git remote URL. If your remote points to github.com, it uses the gh CLI. You can also force it with vcs: github in Session Config. Both GitHub and GitLab are fully supported for issues, PRs/MRs, CI status, and milestones.

What if an agent fails during a wave?

The wave executor does not ignore failures. If an agent produces broken code or reports errors, the orchestrator adds fix tasks to the next wave. If an agent times out, it is re-dispatched with a smaller scope. If there is a major blocker, the orchestrator informs you and proposes a revised plan for the remaining waves.

Can I change the plan mid-session?

Yes. Between each wave, the orchestrator reviews results and can adapt the plan. If you need to change direction, you can communicate that and the remaining waves will be re-scoped. The orchestrator documents every deviation from the original plan so the session summary remains accurate.

How many agents run in parallel?

This is controlled by the agents-per-wave setting in your Session Config. The default is 6. For deep sessions, you can increase this to 10-18. All agents within a single wave run in parallel; the orchestrator waits for all of them to complete before starting the next wave.

Do I need Pencil?

No. Pencil design integration is entirely optional. If you do not configure a pencil path in Session Config, design-code alignment reviews are simply skipped. Everything else works the same.

What is the Soul system?

The Soul is a personality layer that shapes how the orchestrator communicates and makes decisions. It defines the orchestrator as a seasoned engineering lead who drives outcomes — direct, opinionated, systems-thinking, pragmatic. It affects communication style (recommendations first, not analysis), decision-making priorities (user safety > productivity > code quality > ecosystem health > speed), and values (pragmatism over perfection, evidence over assumptions). You do not need to configure it; it is built into the plugin.

Does the orchestrator commit automatically?

No. The orchestrator never commits code until you run /close. During wave execution, agents do not commit independently — the coordinator handles all commits at session end after running quality gates. This ensures only verified, clean code is committed.

What happens to unfinished work?

During /close, any work that was planned but not completed is documented. The orchestrator creates carryover issues on your VCS platform with the title prefix [Carryover], including context on what was done and what remains. Nothing is silently dropped.

Can I use this across multiple repos?

Yes. Configure cross-repos in your Session Config with the names of related repositories (located under ~/Projects/). The orchestrator checks their git state and critical issues at session start, giving you ecosystem-wide awareness.

When should I use /plan vs creating issues manually?

/plan provides structured requirement gathering with parallel research agents, auto-prioritization, and PRD documents for reference. Use it when you want a thorough requirements process. Skip it when you already know exactly what to build — just create issues manually and run /session.

What's the difference between /plan new and /plan feature?

/plan new is for brand-new projects — it scaffolds a repository, creates a full PRD, and generates an Epic with sub-issues. /plan feature is for adding a feature to an existing project — it produces a compact PRD and feature issues. Use /plan new once per project, /plan feature once per feature.

Can I run /plan during an active session?

No. /plan runs outside of sessions. The session scope is locked after /session + user alignment + /go. If new requirements emerge during a session, create them as issues for the next session or let /close generate carryover issues.

---

21. Troubleshooting

"glab: command not found" or "gh: command not found"

The orchestrator needs the appropriate VCS CLI tool installed:

• GitLab: Install glab — https://gitlab.com/gitlab-org/cli
• GitHub: Install gh — https://cli.github.com

After installing, authenticate:

glab auth login
# or
gh auth login

"No issues found" when issues exist

This usually means the CLI tool is not authenticated or is pointing at the wrong host.

• Run glab auth status or gh auth status to verify authentication
• For GitLab with a custom host, ensure gitlab-host is set in Session Config or that your .env / .env.local contains the correct GITLAB_HOST
• Check that git remote get-url origin returns the expected URL

Plugin not loading

For Codex, start with the public state view:

codex plugin list --available --json

Confirm that session-orchestrator@kanevry appears exactly once with installed: true, enabled: true, and the version committed in .codex-plugin/plugin.json. If it is only available, run codex plugin add session-orchestrator@kanevry. If it is missing or stale, run codex plugin marketplace list --json, remove the exact target with codex plugin remove session-orchestrator@kanevry when present, and rerun node scripts/codex-install.mjs from the clone. A healthy install still needs a fresh task plus operator review in /hooks; installation does not grant hook trust.

The installer removes only the allowlisted legacy IDs session-orchestrator@openai-curated and session-orchestrator@local; those exact IDs can also be removed through codex plugin remove. For a conflicting kanevry source, use codex plugin marketplace remove kanevry and rerun the installer from the intended clone. Any other pre-public plugin/config/cache/hook-state residue is unsupported: do not modify private Codex files; file an issue with codex --version plus the public plugin and marketplace list output.

For Claude Code, run these commands inside a Claude Code session, not in your shell:

/plugin marketplace add /absolute/path/to/session-orchestrator
/plugin install session-orchestrator@kanevry

"tsgo: command not found"

The default typecheck command is npm run typecheck. If your project's typecheck script invokes tsgo, install it or change typecheck-command to the runner your project actually uses:

npm install -g @anthropic-ai/tsgo

Agents timing out

If agents consistently time out during wave execution:

• Reduce agents-per-wave in Session Config (fewer parallel agents = less resource contention)
• Switch from deep to feature session type if you do not need the extra agent count
• Check that your machine has sufficient resources for parallel agent execution

Design review skipped unexpectedly

If you configured pencil but design reviews are not running:

• Verify the .pen file exists at the configured path (relative to project root)
• Ensure the Pencil MCP server is running and accessible
• Check the wave progress output for messages like "Pencil review skipped — .pen file unavailable"

Session Config not being read

The orchestrator looks for a ## Session Config section in your project's config host file. Ensure:

• The file is named exactly CLAUDE.md on Claude Code or AGENTS.md on Codex, and is in the project root
• The section heading is exactly ## Session Config
• Fields use the exact format: - **field-name:** value

Mirror push fails

If mirror: github is configured but mirroring fails:

• Verify a github remote exists: git remote get-url github
• If not, add it: git remote add github git@github.com:user/repo.git
• Ensure you have push access to the GitHub repository

---

License

Session Orchestrator is released under the MIT License. See the project repository for details: https://github.com/Kanevry/session-orchestrator