@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "exarchos",
-  "description": "Structure for agentic development — durable SDLC workflows with convergence gates, agent teams, and full audit trail.",
-  "version": "2.4.3",
+  "description": "A local-first SDLC workflow harness — structured, durable state for coding agents, with convergence gates, agent teams, and full audit trail.",
+  "version": "2.6.0",
   "author": {
     "name": "LevelUp Software"
   },
@@ -18,6 +18,11 @@
     "audit-trail",
     "code-review"
   ],
+  "agents": [
+    "./agents/implementer.md",
+    "./agents/fixer.md",
+    "./agents/reviewer.md"
+  ],
   "commands": "./commands/",
   "skills": "./skills/",
   "mcpServers": {

package/AGENTS.md

@@ -11,7 +11,7 @@ Exarchos is local agent governance for Claude Code. It provides event-sourced SD
 - **Testing:** Vitest (co-located `*.test.ts`), bash integration tests (co-located `*.test.sh`)
 - **MCP Framework:** `@modelcontextprotocol/sdk` + `zod`
 - **Build:** `tsc` for type checking, `bun build` for bundling MCP server and CLI
-- **Tools:** Claude Code CLI, Graphite CLI (stacked PRs)
+- **Tools:** Claude Code CLI, GitHub CLI (`gh`) for PRs
 
 ## Code Organization
 
@@ -48,7 +48,7 @@ Single server at `servers/exarchos-mcp/` exposing 5 composite tools:
 
 ## Known Tech Debt
 
-- `docs/follow-ups/` — Empty directory, pending cleanup
+- `docs/follow-ups/` contains 73+ design/plan files, many likely completed — needs per-file triage
 - Some design docs reference completed/superseded features (Jules integration, pre-Exarchos architecture)
 
 ## Scan Preferences

package/README.md

@@ -2,75 +2,77 @@
   <img src="exarchos-logo.svg" alt="Exarchos" width="280" />
 
   **Your agents forget. Exarchos doesn't.**<br>
-  Durable SDLC workflows for Claude Code — checkpoint any task, rehydrate in seconds, ship verified code.
+  A local-first SDLC workflow harness — structured, durable state for coding agents.
 
   [![CI](https://github.com/lvlup-sw/exarchos/actions/workflows/ci.yml/badge.svg)](https://github.com/lvlup-sw/exarchos/actions/workflows/ci.yml)
   [![npm version](https://img.shields.io/npm/v/@lvlup-sw/exarchos)](https://www.npmjs.com/package/@lvlup-sw/exarchos)
   [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
   [![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-  [Install](#install) · [What You Get](#what-you-get) · [Workflows](#workflows) · [Docs](docs/)
+  [Install](#install) · [What you get](#what-you-get) · [Architecture](#agent-first-architecture) · [Workflows](#workflows) · [Docs](https://lvlup-sw.github.io/exarchos/)
 </div>
 
 ---
 
-<!-- TODO: Hero demo — uncomment the block below after creating docs/assets/demo-rehydrate.gif
-     What to record:
-       1. Mid-feature workflow: show /checkpoint saving state
-       2. New session: show /rehydrate restoring phase, tasks, artifact pointers
-       3. Agent continues exactly where it left off
-     Tools: vhs (https://github.com/charmbracelet/vhs) or asciinema + agg
-     Specs: 720px wide, 15-20s, dark terminal, no typing delays > 50ms
-     See docs/assets/PRODUCTION-GUIDE.md for full instructions
+## You already manage this by hand
 
-<div align="center">
-  <a href="docs/assets/demo-rehydrate.gif">
-    <img src="docs/assets/demo-rehydrate.gif" alt="Checkpoint a workflow mid-feature, rehydrate in a new session — full awareness restored in ~2k tokens" width="720" />
-  </a>
-  <br>
-  <sub>Checkpoint mid-feature. Rehydrate next day. Full workflow restored in ~2k tokens.</sub>
-</div>
--->
-
-## You probably already do this
-
-You have a plan.md. Maybe a spec file per feature. You iterate with Claude, tell it to execute, commit the artifacts alongside the code. It works.
-
-Until context compaction wipes the session halfway through. Or the agent drifts from the spec and you don't catch it until review. Or you come back tomorrow and spend 30 minutes re-explaining what the agent already knew.
-
-Developers keep reinventing this on their own: iterate on a plan file, execute it, commit the artifacts. Skill-based workflow tools try to systematize it with markdown files loaded into context. But they're stateless. Nothing persists across context compaction, suggestions get ignored as conversations grow, and there's no verification that the agent followed through.
-
-The plan-file workflow is the right instinct. Markdown files just can't persist state across sessions, enforce phase gates, or prove that the agent actually did what you asked.
+A plan file per feature, CLAUDE.md updated between sessions, summaries written out before `/clear` so the next context window has something to work with. Maybe you enforce your own phases — design, plan, implement, review. It works. It's also manual, and nothing holds the agent to it once the window gets long enough that your instructions start getting ignored.
 
 ## Your plan.md workflow, with teeth
 
-Exarchos replaces markdown files with an event-sourced MCP server. An HSM state machine enforces phase transitions — design, plan, implement, review, ship — with quality gates between each step. Parallel agents execute in isolated git worktrees while the verification flywheel continuously validates output.
+Exarchos is a local-first SDLC workflow harness. It gives your agent structured, durable state that lives outside the context window. Phase transitions are enforced by a state machine. Deterministic convergence gates run as TypeScript checks against your diff and git history, not prompts. You approve the design, you approve the merge — everything between runs on its own.
 
-When context compaction hits (or you close your laptop and come back Monday), run `/rehydrate`. Design docs, plans, and PR links persist as references, never inlined into context. Your workflow picks up where it left off.
+`/clear` whenever you want. `/rehydrate` when you're back. State persists.
+
+It ships as a Claude Code plugin and a standalone MCP server with a CLI adapter. Install it and run `/ideate`.
 
 <div align="center">
   <a href="docs/assets/architecture.svg">
-    <img src="docs/assets/architecture.svg" alt="Exarchos architecture: workflow pipeline, HSM state machine, agent teams in worktrees, verification flywheel with evals and benchmarks, layered quality gates" width="720" />
+    <img src="docs/assets/architecture.svg" alt="Exarchos architecture: workflow pipeline, state machine, agent teams in worktrees, quality gates" width="720" />
   </a>
   <br>
-  <sub>Click to view animated version — workflow phases, agent dispatch, verification flywheel, quality gates.</sub>
+  <sub>Architecture: workflow phases, agent dispatch, convergence gates.</sub>
 </div>
 
 ## Install
 
+**Claude Code plugin:**
 ```bash
-# From the Claude Code marketplace
-/plugin marketplace add lvlup-sw/exarchos
+/plugin marketplace add lvlup-sw/.github
 /plugin install exarchos@lvlup-sw
 ```
 
-That's it. Installs the MCP server, all workflow commands, lifecycle hooks, and validation scripts.
+**Standalone MCP server:**
+```bash
+npx @lvlup-sw/exarchos mcp
+```
 
-**Dev companion** (optional — adds GitHub, Serena, Context7, Microsoft Learn MCP servers):
+**Interactive installer** (installs Exarchos + optional companions):
 ```bash
-npx @lvlup-sw/exarchos-dev
+npx create-exarchos
 ```
 
+### Installing skills for your agent
+
+Exarchos ships its skills as platform-agnostic source. To materialize the
+rendered bundle for a specific agent runtime, use `install-skills`:
+
+```bash
+exarchos install-skills --agent claude
+exarchos install-skills --agent codex
+exarchos install-skills --agent opencode
+exarchos install-skills --agent copilot
+exarchos install-skills --agent cursor
+exarchos install-skills --agent generic
+exarchos install-skills             # auto-detect from PATH + env vars
+```
+
+Auto-detection checks for known agent binaries on your `PATH` and for
+runtime-specific environment variables. If nothing is found, the generic
+bundle is installed and a message explains the fallback. If multiple
+agents are detected, an interactive prompt asks which one to target (or
+you can pass `--agent` explicitly).
+
 <details>
 <summary>Development setup</summary>
 
@@ -80,47 +82,79 @@ npm install && npm run build
 claude --plugin-dir .
 ```
 
-Requires Node.js >= 20. Migrating from the legacy installer? See the [migration guide](docs/migration-from-legacy-installer.md).
+Requires Node.js >= 20.
 </details>
 
 ## What you get
 
-**Structured SDLC workflows.** Design, plan, implement, review, ship. Three workflow types (feature, debug, refactor) with enforced phase transitions. You approve twice: the design and the merge. Everything between auto-continues.
+Three workflow types (feature, debug, refactor) with enforced phase transitions. You approve the design and you approve the merge. Everything between auto-continues.
+
+**Checkpoint and resume.** `/checkpoint` saves mid-task. `/rehydrate` restores it in ~2-3k tokens.
+
+**Typed agent teams.** Implementer, fixer, reviewer — each with scoped tools, hooks, and worktree isolation. Fixers resume failed tasks with full context instead of starting over.
+
+**Runbooks.** Machine-readable orchestration sequences served via MCP. Agents request the steps for a given phase, get back ordered tool calls with schemas and gate semantics. Any MCP client can use them.
+
+**Two-stage review.** Spec compliance first (does it match the design?), then code quality (is it well-written?). Deterministic convergence gates, not prompts.
+
+**Audit trail.** Every transition, gate result, and agent action goes into an append-only event log. When something breaks, trace what happened.
 
-**Checkpoint + rehydrate.** Save mid-task, resume days later. `/rehydrate` restores full awareness in ~2-3k tokens instead of re-explaining your project from scratch.
+**Token-efficient.** Lazy schema registration keeps MCP startup under 500 tokens. Field projection trims state queries by 90%. Review sends diffs, not full files.
 
-**Native Task delegation.** Delegate to parallel Claude Code instances (subagents or agent teams), each in its own git worktree.
+### Agent-first architecture
 
-**Two-stage review.** Spec compliance first (does it match the design?), then code quality (is it well-written?). Deterministic verification scripts, not vibes.
+Exarchos ships as a single binary (`exarchos`) with an `mcp` subcommand. Claude Code spawns it as a stdio MCP server and talks to it with structured JSON. Four composite tools cover the surface:
 
-**Audit trail.** Every transition, gate result, and agent decision goes into an append-only event log. When something breaks, you can trace what happened.
+| Tool | What it does |
+|------|-------------|
+| `exarchos_workflow` | Workflow lifecycle: init, get, set, cancel, cleanup, reconcile |
+| `exarchos_event` | Append-only event store: append, query, batch |
+| `exarchos_orchestrate` | Team coordination: task dispatch, review triage, runbooks, agent specs |
+| `exarchos_view` | CQRS projections: pipeline status, task boards, stack health |
 
-**Token-efficient.** State queries use field projection (90% fewer tokens). Code review sends diffs, not full files (97% savings on large repos).
+All four tools support lazy schema loading via `describe`. At startup, only slim descriptions and action enums are registered. Full schemas load on demand.
 
-Your Claude Code session is the orchestrator. Exarchos manages state; you make decisions at each checkpoint. Teammates execute in isolated git worktrees.
+Every tool input is a Zod-validated discriminated union keyed on `action`. The same `dispatch()` function backs both the MCP transport and the CLI, so `exarchos workflow get --featureId my-feature` from a terminal returns the same result the agent gets.
 
+Structured input over natural language. Strict schema validation over loose parsing. One binary, same behavior whether an agent or a human is driving it.
 
 ### Integrations
 
 | Component | Source | Purpose |
 |-----------|--------|---------|
-| **Exarchos** | Core plugin | Workflow orchestration, event log, team coordination, quality gates |
-| **GitHub** | [Dev companion](companion/) | PRs, issues, code search, stacked PR management |
-| **Serena** | [Dev companion](companion/) | Semantic code analysis |
-| **Context7** | [Dev companion](companion/) | Up-to-date library documentation |
-| **Microsoft Learn** | [Dev companion](companion/) | Official Azure/.NET documentation |
+| Exarchos | Core plugin | Workflow state, event log, team coordination, convergence gates |
+| Serena | Optional companion (`npx create-exarchos`) | Semantic code analysis |
+| Context7 | Optional companion (`npx create-exarchos`) | Up-to-date library documentation |
+| Microsoft Learn | Optional companion (`npx create-exarchos`) | Azure and .NET documentation |
 
 ## Workflows
 
 > Commands shown in short form (`/ideate`). As a plugin, they're namespaced: `/exarchos:ideate`, `/exarchos:plan`, etc.
 
-| Start here | Command | What it does |
-|:-----------|:--------|:-------------|
-| New feature | `/ideate` | Design exploration → TDD plan → parallel implementation |
-| Bug fix | `/debug` | Triage → investigate → fix → validate (hotfix or thorough) |
-| Code improvement | `/refactor` | Scope → brief → implement (polish or full overhaul) |
-| Resume anything | `/rehydrate` | Restore workflow state after compaction or session break |
-| Save progress | `/checkpoint` | Persist current state for later resumption |
+**Start a workflow:**
+
+| When you need to... | Command | What it does |
+|:---------------------|:--------|:-------------|
+| Build a feature | `/ideate` | Design exploration, TDD plan, parallel implementation |
+| Fix a bug | `/debug` | Triage, investigate, fix, validate (hotfix or thorough) |
+| Improve code | `/refactor` | Assess scope, brief, implement (polish or full overhaul) |
+
+**Lifecycle commands:**
+
+| Command | What it does |
+|:--------|:-------------|
+| `/plan` | Create TDD implementation plan from a design doc |
+| `/delegate` | Dispatch tasks to agent teammates in worktrees |
+| `/review` | Run two-stage review (spec compliance + code quality) |
+| `/synthesize` | Create PR from feature branch |
+| `/shepherd` | Push PRs through CI and reviews to merge readiness |
+| `/cleanup` | Resolve merged workflow to completed state |
+| `/checkpoint` | Save workflow state for later resumption |
+| `/rehydrate` | Restore workflow state after compaction or session break |
+| `/reload` | Re-inject context after degradation |
+| `/autocompact` | Toggle autocompact or set threshold |
+| `/tag` | Attribute current session to a feature or project |
+| `/tdd` | Plan implementation using strict Red-Green-Refactor |
 
 ## Build & test
 

package/agents/fixer.md

@@ -0,0 +1,62 @@
+---
+name: exarchos-fixer
+description: |
+  Use this agent when a task has failed and needs diagnosis and repair with adversarial verification.
+  
+  <example>
+  Context: A delegated task failed its quality gates or tests
+  user: "Task-005 failed TDD compliance — fix it"
+  assistant: "I'll dispatch the exarchos-fixer agent to diagnose and repair the failure."
+  <commentary>
+  Failed task requiring root cause analysis and targeted fix triggers the fixer agent.
+  </commentary>
+  </example>
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: opus
+color: red
+disallowedTools: ["Agent"]
+skills:
+  - tdd-patterns
+hooks:
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "npm run test:run"
+---
+
+You are a fixer agent. Your job is to diagnose and repair failures.
+
+## Failure Context
+{{failureContext}}
+
+## Task
+{{taskDescription}}
+
+## Files
+{{filePaths}}
+
+## Adversarial Verification Protocol
+1. Reproduce the failure first — confirm you can see it fail
+2. Identify root cause — do not guess, trace the actual error
+3. Apply minimal fix — change only what is necessary
+4. Verify fix — run the failing test and confirm it passes
+5. Run full test suite — ensure no regressions
+6. If fix introduces new failures, revert and try again
+
+Rules:
+- NEVER apply a fix without first reproducing the failure
+- NEVER suppress or skip failing tests
+- Prefer targeted fixes over broad changes
+- Document what caused the failure and why the fix works
+
+## Completion Report
+When done, output a JSON completion report:
+```json
+{
+  "status": "complete",
+  "implements": ["<design requirement IDs>"],
+  "tests": [{"name": "<test name>", "file": "<path>"}],
+  "files": ["<created/modified files>"]
+}
+```

package/agents/implementer.md

@@ -0,0 +1,68 @@
+---
+name: exarchos-implementer
+description: |
+  Use this agent when dispatching TDD implementation tasks to a subagent in an isolated worktree.
+  
+  <example>
+  Context: Orchestrator is dispatching a task from an implementation plan
+  user: "Implement the agent spec handler (task-003)"
+  assistant: "I'll dispatch the exarchos-implementer agent to implement this task using TDD in an isolated worktree."
+  <commentary>
+  Implementation task requiring test-first development triggers the implementer agent.
+  </commentary>
+  </example>
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: opus
+color: blue
+disallowedTools: ["Agent"]
+isolation: worktree
+memory: project
+skills:
+  - tdd-patterns
+  - testing-patterns
+hooks:
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "npm run test:run"
+---
+
+You are a TDD implementer agent working in an isolated worktree.
+
+## Worktree Verification
+Before making ANY file changes:
+1. Run: `pwd`
+2. Verify the path contains `.worktrees/`
+3. If NOT in worktree: STOP and report error
+
+## Task
+{{taskDescription}}
+
+## Requirements
+{{requirements}}
+
+## Files
+{{filePaths}}
+
+## TDD Protocol (Red-Green-Refactor)
+1. **RED**: Write a failing test that defines the expected behavior
+2. **GREEN**: Write the minimum code to make the test pass
+3. **REFACTOR**: Clean up while keeping tests green
+
+Rules:
+- NEVER write implementation before its test
+- Each test must fail before writing implementation
+- Run tests after each change to verify state
+- Keep commits atomic: one logical change per commit
+
+## Completion Report
+When done, output a JSON completion report:
+```json
+{
+  "status": "complete",
+  "implements": ["<design requirement IDs>"],
+  "tests": [{"name": "<test name>", "file": "<path>"}],
+  "files": ["<created/modified files>"]
+}
+```

package/agents/reviewer.md

@@ -0,0 +1,50 @@
+---
+name: exarchos-reviewer
+description: |
+  Use this agent when performing read-only code review for quality, design compliance, and test coverage.
+  
+  <example>
+  Context: Feature implementation is complete and needs review
+  user: "Review the agent spec handler for code quality"
+  assistant: "I'll dispatch the exarchos-reviewer agent to analyze code quality and design compliance."
+  <commentary>
+  Code review request triggers the reviewer agent for read-only analysis.
+  </commentary>
+  </example>
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: opus
+color: green
+disallowedTools: ["Write", "Edit", "Agent"]
+---
+
+You are a code reviewer agent. You analyze code for quality, correctness, and design compliance.
+
+## Review Scope
+{{reviewScope}}
+
+## Design Requirements
+{{designRequirements}}
+
+## Review Protocol
+1. Read all changed files in scope
+2. Check design requirement compliance
+3. Verify test coverage for new code
+4. Check for common anti-patterns
+5. Produce structured review verdict
+
+Rules:
+- You have READ-ONLY access — do not modify any files
+- Bash is restricted to read-only commands only (e.g., git diff, git log, test runners in dry-run mode). NEVER use Bash to create, edit, or delete files.
+- Be specific in findings — include file paths and line references
+- Categorize findings: critical, warning, suggestion
+
+## Completion Report
+When done, output a JSON completion report:
+```json
+{
+  "status": "complete",
+  "implements": ["<design requirement IDs>"],
+  "tests": [{"name": "<test name>", "file": "<path>"}],
+  "files": ["<reviewed files>"]
+}
+```

package/commands/dogfood.md

@@ -0,0 +1,31 @@
+---
+description: "Review failed tool calls in this session, diagnose root causes, and triage into code bug / docs issue / user error"
+---
+
+# Dogfood
+
+Triage session failures for: "$ARGUMENTS"
+
+## Skill Reference
+
+Follow the dogfood skill: `@skills/dogfood/SKILL.md`
+
+## Quick Start
+
+1. **Debug trace first** — Use MCP self-service tools to build a ground-truth picture:
+   - `exarchos_view pipeline` → identify active workflows
+   - `exarchos_workflow describe(topology, playbook)` → get HSM + phase playbooks
+   - `exarchos_event query` + `describe(emissionGuide)` → compare actual vs expected events
+   - `exarchos_orchestrate describe(actions)` + `runbook(phase)` → verify schemas, gates, step ordering
+   - `exarchos_view convergence, telemetry` → per-dimension pass rates, per-tool error rates
+2. Scan this conversation for failed calls to the 5 Exarchos MCP tools (supplementary)
+3. Cross-reference conversation errors with self-service evidence
+4. Check playbook adherence and runbook conformance
+5. Diagnose each failure using `references/root-cause-patterns.md`
+6. Categorize: **code bug**, **documentation issue**, or **user error**
+7. Present the report (include trace-only findings, playbook/runbook adherence)
+8. Offer to file GitHub issues for bugs and doc issues
+
+## Scope
+
+If `$ARGUMENTS` is provided, focus analysis on that workflow or tool. Otherwise, review all Exarchos tool failures in the current session.

package/commands/ideate.md

@@ -52,7 +52,7 @@ After user selects approach:
 
 ## State Management
 
-Initialize workflow state at the start using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"` and the featureId.
+Initialize workflow state at the start using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"`, `featureId`, and `workflowType: "feature"`.
 
 After saving design, update state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
 - Set `artifacts.design` to the design path

package/commands/oneshot.md

@@ -0,0 +1,178 @@
+---
+description: Run a lightweight oneshot workflow — plan + TDD implement + optional PR
+---
+
+# Oneshot
+
+Start a lightweight oneshot workflow for: "$ARGUMENTS"
+
+## When to use
+
+Reach for `/exarchos:oneshot` when the change is:
+
+- Bounded — single file or 2-3 tightly-coupled files
+- Self-contained — no subagent dispatch needed
+- Obvious — no design exploration required
+- Small — direct-commit acceptable, or a single PR review will suffice
+
+Examples: typo fixes, dependency bumps, single-function null checks, CI YAML
+tweaks, config key renames, exploratory spikes.
+
+For anything cross-cutting, multi-file, or needing two-stage review, use
+`/exarchos:ideate` instead.
+
+## Skill Reference
+
+Follow the oneshot workflow skill: `@skills/oneshot-workflow/SKILL.md`
+
+## Iron Law
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+TDD applies to oneshot workflows. There is no exemption for "small" changes —
+the test is what makes the change auditable.
+
+## Workflow position
+
+```
+plan ──► implementing ──┬── [direct-commit] ──► completed
+                        │
+                        └── [opt-in PR]     ──► synthesize ──► completed
+```
+
+Choice state at the end of `implementing` is decided by `synthesisPolicy`
+(set at init) plus any `synthesize.requested` events on the stream.
+
+## Process
+
+### Step 1: Init
+
+Initialize a oneshot workflow using
+`mcp__plugin_exarchos_exarchos__exarchos_workflow` with
+`action: "init"`, `workflowType: "oneshot"`, a `featureId`, and optionally
+`synthesisPolicy: "always" | "never" | "on-request"` (default: `"on-request"`).
+
+If the user has stated a clear preference ("I want a PR for this" → `always`;
+"don't open a PR" → `never`), pass it explicitly. Otherwise rely on the
+default and let the user opt in mid-implementing if they change their mind.
+
+### Step 2: Plan
+
+Produce a one-page plan with four sections:
+
+1. **Goal** — what the user is trying to accomplish (1-2 lines)
+2. **Approach** — implementation strategy (1-2 lines)
+3. **Files** — which files will change (1-5)
+4. **Tests** — which tests will be added (named, not described)
+
+Persist via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with
+`action: "set"`:
+
+- Set `artifacts.plan` to the plan text
+- Set `oneshot.planSummary` to a one-line summary
+- Set `phase` to `"implementing"`
+
+### Step 3: Implementing — in-session TDD loop
+
+For each behavior in the plan:
+
+1. **[RED]** Write a failing test. Run it. Confirm it fails for the right reason.
+2. **[GREEN]** Write minimum code to pass. Run the test. Confirm green.
+3. **[REFACTOR]** Clean up while keeping tests green.
+
+Commit each cycle as a single atomic commit. No subagent dispatch — the main
+agent does the work directly.
+
+### Step 4: Mid-implementing opt-in (optional)
+
+If the user says something like "actually, let's open a PR for this" or "I
+want a review on this", call:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "request_synthesize",
+  featureId: "<id>",
+  reason: "<why the user wants a PR>"
+})
+```
+
+This appends a `synthesize.requested` event. The workflow stays in
+`implementing` — the choice is only acted on at finalize.
+
+### Step 5: Finalize
+
+When all tests pass and typecheck is clean, call:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "finalize_oneshot",
+  featureId: "<id>"
+})
+```
+
+The handler evaluates `synthesisPolicy` + events and transitions to either
+`synthesize` (PR path) or `completed` (direct-commit path). Outcomes:
+
+| Policy | Event present? | Resolved phase |
+|---|---|---|
+| `always` | (any) | `synthesize` |
+| `never` | (any) | `completed` |
+| `on-request` | yes | `synthesize` |
+| `on-request` | no | `completed` |
+
+### Step 6a: Direct-commit path (`completed`)
+
+Push the commits if not already pushed:
+
+```bash
+git push
+```
+
+Workflow is terminal — done.
+
+### Step 6b: Synthesize path
+
+Hand off to the standard synthesis flow: `@skills/synthesis/SKILL.md`. The
+existing `prepare_synthesis` / `validate_pr_body` / `gh pr create` machinery
+applies. After PR merge, the workflow transitions `synthesize → completed`.
+
+You do **not** need to run `/exarchos:delegate` or `/exarchos:review` for an
+opt-in oneshot synthesize — those phases are not in the oneshot playbook.
+
+## When NOT to use oneshot
+
+| Symptom | Use instead |
+|---|---|
+| Cross-cutting refactor | `/exarchos:refactor` or `/exarchos:ideate` |
+| Multi-file feature | `/exarchos:ideate` |
+| Needs design exploration | `/exarchos:ideate` |
+| Needs two-stage review | `/exarchos:ideate` |
+| Coordinates multiple agents | `/exarchos:ideate` + `/exarchos:delegate` |
+| Should land in stages | `/exarchos:ideate` (stacked PRs) |
+
+If you start a oneshot and discover it's bigger than expected: cancel and
+restart with `/exarchos:ideate`. Don't try to grow a oneshot into a feature
+workflow mid-stream.
+
+## Output
+
+Direct-commit path:
+```markdown
+## Oneshot Complete (direct-commit)
+
+Workflow: <featureId>
+Plan: <one-line summary>
+Tests added: N
+Commits: <hash list>
+Path: direct-commit
+```
+
+Synthesize path:
+```markdown
+## Oneshot Complete (synthesize)
+
+Workflow: <featureId>
+PR: <url>
+Tests: X pass | Build: 0 errors
+Path: synthesize → PR review → merge
+```