session-orchestrator 3.16.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "kanevry",
+  "owner": {
+    "name": "Bernhard Goetzendorfer",
+    "email": "office@gotzendorfer.at"
+  },
+  "metadata": {
+    "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.",
+    "version": "3.16.0"
+  },
+  "plugins": [
+    {
+      "name": "session-orchestrator",
+      "source": "./",
+      "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.",
+      "author": {
+        "name": "Bernhard Goetzendorfer",
+        "email": "office@gotzendorfer.at"
+      },
+      "homepage": "https://session-orchestrator.com",
+      "repository": "https://github.com/Kanevry/session-orchestrator",
+      "license": "MIT",
+      "keywords": ["session", "orchestration", "waves", "gitlab", "github", "quality-gates", "subagents"],
+      "category": "productivity",
+      "tags": ["session-management", "wave-execution", "vcs-integration", "code-review", "agent-orchestration"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "session-orchestrator",
+  "version": "3.16.0",
+  "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.",
+  "author": {
+    "name": "Bernhard Goetzendorfer",
+    "email": "office@gotzendorfer.at",
+    "url": "https://gotzendorfer.at"
+  },
+  "homepage": "https://session-orchestrator.com",
+  "repository": "https://github.com/Kanevry/session-orchestrator",
+  "license": "MIT",
+  "keywords": ["session", "orchestration", "waves", "gitlab", "github", "quality-gates", "verification-gates", "multi-agent", "codex", "cursor", "pi"],
+  "experimental": {
+    "monitors": "./monitors/monitors.json"
+  }
+}

package/.codex-plugin/agents/explorer.toml

@@ -0,0 +1,14 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are a read-only codebase explorer. Your job is to gather evidence and report findings.
+
+Rules:
+1. Stay in exploration mode — do NOT propose or make changes
+2. Trace real execution paths, cite files and line numbers
+3. Prefer targeted search (Grep, Glob) over broad scans
+4. Report structure: files found, patterns observed, potential issues
+5. Do NOT use Edit or Write tools
+"""

package/.codex-plugin/agents/session-reviewer.toml

@@ -0,0 +1,23 @@
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are a quality gate agent. Your job is to verify work quality — NOT to implement or fix anything.
+
+## Review Checklist
+1. Implementation Correctness — verify implementation matches task, check for TODOs/placeholders
+2. Test Coverage — check corresponding test files exist and test actual behavior
+3. TypeScript Health — run typecheck, errors must be 0
+4. Security Basics — no hardcoded secrets, input validation, parameterized SQL, auth checks
+5. Issue Tracking — verify acceptance criteria are met
+6. Silent Failure Analysis — catch blocks that swallow errors, fallback values hiding data loss
+7. Test Depth — meaningful assertions, edge cases, proper mock boundaries
+8. Type Design — union types over string, constrained generics, discriminated unions
+
+## Confidence Scoring
+Only report findings with confidence >= 80. Group 50-79 in "Possible Issues" section.
+
+## Output Format
+Report per category: PASS/WARN/FAIL with findings. End with JSON summary block.
+"""

package/.codex-plugin/agents/wave-worker.toml

@@ -0,0 +1,15 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are an implementation agent dispatched as part of a wave-based execution plan.
+
+Rules:
+1. Follow the task prompt EXACTLY — implement what is described, nothing more
+2. Only modify files within your assigned scope
+3. Write tests for your changes
+4. Do NOT commit — the coordinator handles commits
+5. Follow existing code patterns and conventions
+6. If blocked, report the blocker clearly — do not work around it silently
+"""

package/.codex-plugin/config.toml

@@ -0,0 +1,20 @@
+# Session Orchestrator — Codex CLI Plugin Config
+# Equivalent of .claude-plugin/plugin.json for OpenAI Codex CLI
+
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[features]
+multi_agent = true
+
+[agents.session-reviewer]
+description = "Inter-wave quality gate agent — verifies implementation correctness, test coverage, TypeScript health, security, and issue tracking"
+config_file = "agents/session-reviewer.toml"
+
+[agents.wave-worker]
+description = "Implementation agent for wave execution — handles feature work, bug fixes, and refactoring"
+config_file = "agents/wave-worker.toml"
+
+[agents.explorer]
+description = "Read-only codebase explorer — gathers evidence, traces execution paths, analyzes patterns"
+config_file = "agents/explorer.toml"

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "session-orchestrator",
+  "version": "3.16.0+codex.20260719182053",
+  "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.",
+  "keywords": [
+    "session",
+    "orchestration",
+    "waves",
+    "gitlab",
+    "github",
+    "quality-gates",
+    "codex"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks-codex.json",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Session Orchestrator",
+    "shortDescription": "Structured engineering sessions for Codex",
+    "longDescription": "Adds reusable session workflows to Codex: project analysis, wave planning, guided execution, quality gates, persistence, and clean session close-out.",
+    "developerName": "Bernhard Goetzendorfer",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "composerIcon": "./assets/icon.svg",
+    "websiteURL": "https://session-orchestrator.com",
+    "privacyPolicyURL": "https://gotzendorfer.at/en/session-orchestrator/privacy",
+    "termsOfServiceURL": "https://gotzendorfer.at/en/session-orchestrator/terms",
+    "defaultPrompt": [
+      "Start a structured feature session for this repo",
+      "Plan a feature PRD and turn it into waves",
+      "Close the current session with verification"
+    ]
+  }
+}

package/.cursor/rules/000-session-orchestrator.mdc

@@ -0,0 +1,73 @@
+---
+description: "When working in any project with Session Orchestrator capabilities"
+globs: ""
+alwaysApply: true
+---
+
+# Session Orchestrator — Cursor IDE
+
+You have Session Orchestrator capabilities. This plugin provides structured session management for development work.
+
+## Platform Context
+
+- Platform: Cursor IDE (SO_PLATFORM=cursor)
+- State directory: `.cursor/` (STATE.md, wave-scope.json)
+- Config: Session Config in `CLAUDE.md` under `## Session Config`
+- Shared knowledge: `.orchestrator/metrics/` (sessions.jsonl, learnings.jsonl)
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| /session [type] | Start a session (housekeeping, feature, deep) |
+| /go | Execute the agreed session plan |
+| /close | End session with verification and commits |
+| /discovery [scope] | Run quality analysis probes |
+| /plan [mode] | Create project plan or PRD (new, feature, retro) |
+| /evolve [mode] | Extract session learnings (analyze, review, list) |
+
+## Cursor-Specific Adaptations
+
+**No parallel agents**: Execute wave tasks sequentially. Complete one task fully before starting the next. The `agents-per-wave` config is ignored on Cursor.
+
+**No AskUserQuestion tool**: Present choices as numbered Markdown lists:
+```
+Choose one:
+1. Option A — description
+2. Option B — description
+Reply with the number of your choice.
+```
+
+**No TaskCreate/Update**: Use plain-text checklists to track progress:
+```
+- [x] Task 1 — done
+- [ ] Task 2 — in progress
+- [ ] Task 3 — pending
+```
+
+**No EnterPlanMode**: When planning, state "I will focus on analysis only. No files will be modified until you approve the plan."
+
+**Web search**: Use `@web` in Cursor chat instead of WebSearch tool.
+
+**Web fetch**: Use `curl` via Bash instead of WebFetch tool.
+
+## Quality Gates
+
+Standard quality commands (read from Session Config, defaults below):
+- **Typecheck**: `tsgo --noEmit` (or `npx tsc --noEmit`)
+- **Test**: `pnpm test --run`
+- **Lint**: `pnpm lint`
+
+If a command is set to `skip` in Session Config, skip that check entirely.
+
+## Agent Dispatch
+
+Agents are resolved in priority order: project agents (`.cursor/agents/`) > plugin agents (`agents/`) > general-purpose. Use the `agent-mapping` Session Config field to bind roles explicitly to specific agents.
+
+See `.orchestrator/metrics/model-selection.md` for model choice guidance (haiku/sonnet/opus per task type).
+
+## Shared Knowledge
+
+- Read `.orchestrator/metrics/learnings.jsonl` for cross-session intelligence. Only apply learnings with confidence >= 0.5.
+- Write session metrics to `.orchestrator/metrics/sessions.jsonl` with `"platform": "cursor"`.
+- Metrics directory: `.orchestrator/metrics/` (not `.claude/metrics/`).

package/.cursor/rules/010-session-workflow.mdc

@@ -0,0 +1,170 @@
+---
+description: "When the user types /session, starts a development session, types /go to execute, or /close to end a session"
+globs: ""
+alwaysApply: false
+---
+
+# Session Workflow
+
+Three-phase workflow: Start -> Execute -> Close.
+
+## Phase 1: Session Start (`/session [type]`)
+
+Session types:
+- **housekeeping** — git cleanup, docs, CI health, dependency updates
+- **feature** — implementation of issues/features
+- **deep** — thorough work requiring extended focus
+
+### Step 1: Read Session Config
+
+Parse `## Session Config` from project's `CLAUDE.md`. Store as `$CONFIG`.
+
+### Step 2: Session Continuity
+
+If `persistence` is enabled, check `.cursor/STATE.md`:
+- `status: active` — crashed session. Ask: "Found unfinished session. Resume or start fresh?"
+- `status: paused` — intentional pause. Offer to resume or start fresh.
+- `status: completed` — note summary for context, continue normally.
+- Missing — first session, continue normally.
+
+### Step 3: Git Analysis
+
+Run in parallel:
+```bash
+# Branch state
+git branch -a && git log --oneline -20
+
+# Unpushed/uncommitted work
+git status --short
+git log origin/main..HEAD --oneline
+
+# Stale branches (no commits in 7+ days)
+git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative)' refs/heads/
+```
+
+### Step 4: VCS Deep Dive
+
+Query open issues, recent closures, milestones, MRs/PRs, CI status:
+```bash
+# GitLab
+glab issue list --per-page 50
+glab issue list --closed --per-page 10
+glab mr list --per-page 20
+
+# GitHub
+gh issue list --limit 50
+gh pr list --limit 20
+```
+
+Group issues by priority (critical/high first) and session-type relevance.
+
+### Step 5: Environment Check
+
+```bash
+# Quality baseline (non-blocking)
+{typecheck-command} 2>&1 | tail -5
+{test-command} 2>&1 | tail -5
+```
+
+Check SSOT file freshness. Flag files older than 5 days.
+
+**Plugin freshness**: Check the session-orchestrator plugin's last commit date. If older than `plugin-freshness-days` (default: 30) days, flag a non-blocking warning in the overview.
+
+### Step 5.5: Pattern Recognition
+
+Look across gathered data for:
+- **Blocking chains**: issues blocked by other issues
+- **Quick wins**: low-effort issues closable alongside main work
+- **Synergies**: issues sharing code paths that can be combined
+
+### Step 5.6: Memory Recall
+
+> Skip if `persistence` is `false`.
+
+1. Look for session memory files at `~/.claude/projects/<project>/memory/session-*.md`
+2. Read the 2–3 most recent files (newest first)
+3. Extract: accomplishments, carryovers, patterns or warnings
+4. Surface under **Previous Sessions** in the overview
+
+### Step 5.7: Project Intelligence
+
+> Skip if `persistence` is `false` or `learnings.jsonl` does not exist.
+
+Read `.orchestrator/metrics/learnings.jsonl` and surface active learnings (confidence > 0.3, not expired):
+- Fragile files, effective sizing, recurring issues, scope guidance
+- Config field: `learning-expiry-days` (default: 30) controls expiry window
+
+**Effectiveness analysis** (requires 5+ sessions in `sessions.jsonl`):
+- Completion rate trend, discovery probe value, carryover pattern
+- If fewer than 5 sessions: "Effectiveness analysis: not enough data yet ([N]/5 sessions)."
+
+### Step 7: Present Findings
+
+Present a structured Session Overview with:
+- Git state summary
+- Issue recommendations (grouped by priority)
+- Quality baseline results
+- Previous sessions context (if available)
+- Project intelligence insights (learnings + effectiveness if 5+ sessions)
+- Recommended focus areas
+
+On Cursor, present scope confirmation as a numbered Markdown list (no AskUserQuestion tool). Ask the user to confirm scope before proceeding.
+
+---
+
+## Phase 2: Session Execution (`/go`)
+
+### Step 1: Create Wave Plan
+
+Distribute tasks across waves (see `030-wave-execution.mdc` for full details on roles, scope manifests, and quality checks).
+
+### Step 2: Execute Sequentially
+
+On Cursor, execute all tasks one by one (no parallel agents). For each task:
+1. State what you are doing and which wave/role it belongs to
+2. Execute the task fully
+3. Report status with checklist update
+4. Run incremental quality checks after implementation waves
+5. Move to next task
+
+### Step 3: Update STATE.md
+
+If persistence is enabled, update `.cursor/STATE.md` after each wave with wave status, files changed, and quality check results.
+
+---
+
+## Phase 3: Session End (`/close`)
+
+### Step 1: Plan Verification
+
+For each planned item:
+- **Done**: Verify with `git diff`, confirm acceptance criteria met
+- **Partially done**: Create carryover issue with `[Carryover]` prefix
+- **Not started**: Document why, ensure issue stays open
+- **Emergent work**: Document unplanned tasks that were completed
+
+### Step 2: Full Quality Gate (BLOCKING)
+
+```bash
+# All must pass before committing
+{typecheck-command}    # 0 errors required
+{test-command}         # exit code 0 required
+{lint-command}         # errors NOT OK, warnings OK
+
+# Check for debug artifacts
+grep -rn 'console\.log\|debugger\|TODO: remove' --include='*.ts' --include='*.tsx' src/
+```
+
+Do NOT commit if any check fails. Fix quick issues (<2 min) inline. For longer fixes, create a `priority:high` issue.
+
+### Step 3: Commit and Push
+
+Stage specific files, commit with Conventional Commit format, push to origin. Mirror to GitHub if configured.
+
+### Step 4: Session Metrics
+
+If persistence is enabled, append session metrics to `.orchestrator/metrics/sessions.jsonl` with `"platform": "cursor"`. Include: session_id, session_type, timestamps, wave/file counts, and effectiveness stats (planned/completed/carryover/completion_rate).
+
+### Step 5: Cleanup
+
+Remove `.cursor/wave-scope.json` and update `.cursor/STATE.md` with `status: completed`.

package/.cursor/rules/020-quality-gates.mdc

@@ -0,0 +1,128 @@
+---
+description: "When running quality checks — typecheck, test, lint — during development or session execution"
+globs: ""
+alwaysApply: false
+---
+
+# Quality Gates
+
+Four quality gate variants for different session phases. Commands are read from Session Config in `CLAUDE.md` (field defaults shown below).
+
+## Config Fields
+
+| Field | Default | Notes |
+|-------|---------|-------|
+| `test-command` | `pnpm test --run` | Set to `skip` to disable |
+| `typecheck-command` | `tsgo --noEmit` | Set to `skip` to disable |
+| `lint-command` | `pnpm lint` | Set to `skip` to disable |
+
+## Variant 1: Baseline
+
+**When**: Session start (Phase 3)
+**Purpose**: Quick health check — non-blocking.
+
+```bash
+{typecheck-command} 2>&1 | tail -5
+{test-command} 2>&1 | tail -5
+```
+
+- Report results but do NOT block the session
+- Store error counts as the session baseline for later comparison
+
+## Variant 2: Incremental
+
+**When**: After implementation waves (Impl-Core, Impl-Polish)
+**Purpose**: Verify implementation did not break anything.
+
+```bash
+# Run tests on changed files only
+{test-command} -- <changed-test-files>
+
+# Full typecheck (always full — partial typecheck is unreliable)
+{typecheck-command}
+```
+
+- Report failures but do NOT block wave progression
+- If issues found, add fix tasks to the next wave automatically
+
+## Variant 3: Full Gate
+
+**When**: Session end (Phase 2) — before committing
+**Purpose**: Final quality gate — BLOCKING.
+
+```bash
+# 1. Typecheck — must produce 0 errors
+{typecheck-command}
+
+# 2. Tests — must pass (exit code 0)
+{test-command}
+
+# 3. Lint — errors NOT OK, warnings OK
+{lint-command}
+
+# 4. Debug artifact scan
+grep -rn 'console\.log\|debugger\|TODO: remove' \
+  --include='*.ts' --include='*.tsx' --include='*.js' \
+  src/ lib/ 2>/dev/null || true
+```
+
+**Rules**:
+- Do NOT commit if any check fails
+- Fix quick issues (<2 min) inline
+- For longer fixes: create a `priority:high` issue and exclude affected files from commit
+
+## Variant 4: Per-File
+
+**When**: Session review (reviewer agent)
+**Purpose**: Targeted check on specific changed files.
+
+```bash
+# Run tests for specific files
+{test-command} -- <specific-file-paths>
+
+# Full typecheck
+{typecheck-command}
+```
+
+- Report per-file pass/fail status
+- Used by reviewers to annotate findings
+
+## Decision Table
+
+| Phase | Variant | Blocking? | Scope |
+|-------|---------|-----------|-------|
+| Session start | Baseline | No | Quick health check |
+| After impl wave | Incremental | No | Changed files + full typecheck |
+| Before commit (/close) | Full Gate | **Yes** | All checks, all files |
+| Review | Per-File | No | Specific files |
+
+## Graceful Degradation
+
+Handle missing tools without failing:
+
+- `command not found` for typecheck → skip, note "No TypeScript configured"
+- `command not found` for test → skip, note "No test runner configured"
+- `command not found` for lint → skip, note "No linter configured"
+- Non-TypeScript projects: set `typecheck-command: skip` in Session Config
+
+Always continue with remaining checks — never abort because one tool is missing.
+
+## Script Alternative
+
+If the Session Orchestrator plugin is installed, prefer the script for structured JSON output:
+
+```bash
+# Baseline
+bash "$SO_PLUGIN_ROOT/scripts/run-quality-gate.sh" --variant baseline
+
+# Incremental
+bash "$SO_PLUGIN_ROOT/scripts/run-quality-gate.sh" --variant incremental --files file1.ts,file2.ts
+
+# Full Gate
+bash "$SO_PLUGIN_ROOT/scripts/run-quality-gate.sh" --variant full-gate
+
+# Per-File
+bash "$SO_PLUGIN_ROOT/scripts/run-quality-gate.sh" --variant per-file --files specific-file.ts
+```
+
+Exit codes: 0=pass, 1=error, 2=gate-failed.