@lvlup-sw/exarchos 2.4.3 → 2.5.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.5.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,73 +2,54 @@
   <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
 ```
 
 <details>
@@ -80,47 +61,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/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/plan.md

@@ -85,7 +85,7 @@ Save plan to `docs/plans/YYYY-MM-DD-<feature>.md` and capture the path as `$PLAN
 Before planning, check if plan already exists:
 1. Read state file for `.artifacts.plan`
 2. If plan file exists and is valid, skip planning
-3. Auto-chain directly to delegate
+3. Auto-chain directly to plan-review
 
 ## Auto-Chain
 

package/commands/review.md

@@ -21,6 +21,7 @@ Review runs AFTER delegation completes -- reviews the branch stack diff.
 
 - **Stage 1 (spec compliance):** `@skills/spec-review/SKILL.md`
 - **Stage 2 (code quality):** `@skills/quality-review/SKILL.md`
+- **Plugin integration:** `@skills/quality-review/references/axiom-integration.md`
 
 Reviews MUST be dispatched to subagents (not run inline). Use the branch stack diff to reduce context by 80-90%:
 
@@ -35,6 +36,63 @@ Before reviewing, check review status in state:
 2. Only review pending tasks
 3. If all reviews passed, skip to auto-chain
 
+## Quality Check Catalog (Tier 2 — All Platforms)
+
+Before dispatching the quality-review subagent, call `prepare_review` to get the quality check catalog:
+
+```typescript
+exarchos_orchestrate({ action: "prepare_review", featureId: "<id>" })
+```
+
+This returns structured check patterns (grep, structural, heuristic) that the quality-review subagent executes against the codebase. The catalog works on **any MCP platform** — no companion plugins needed.
+
+Pass the catalog to the quality-review subagent along with the diff. The subagent executes checks, collects findings, and feeds them as `pluginFindings` to `check_review_verdict`:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_review_verdict",
+  featureId: "<id>",
+  high: nativeHighCount,
+  medium: nativeMediumCount,
+  low: nativeLowCount,
+  pluginFindings: catalogFindings,  // from check catalog execution
+})
+```
+
+The `pluginFindings` counts are merged with native counts before computing the verdict.
+
+## Companion Plugin Enhancement (Tier 3 — Claude Code / Cursor)
+
+On platforms with skill support, the orchestrator additionally invokes companion plugin skills after the quality-review subagent returns. These provide deeper qualitative analysis beyond the deterministic catalog.
+
+### Detection
+
+Check the `pluginStatus` from `prepare_review` response AND your available skills list:
+- `axiom:audit` — deeper backend quality analysis (7 dimensions)
+- `impeccable:critique` — frontend design quality
+
+### Invocation
+
+```typescript
+// Only if plugin is enabled AND skill is available
+Skill({ skill: "axiom:audit" })    // Pass: diff content, changed file list
+Skill({ skill: "impeccable:critique" })  // Pass: diff content
+```
+
+### Verdict Escalation
+
+Feed companion plugin findings as additional `pluginFindings` to `check_review_verdict`. The merged counts determine the final verdict:
+
+- **No plugin HIGH findings** → verdict unchanged
+- **Plugin HIGH findings found** → escalates APPROVED to NEEDS_FIXES
+
+### Plugin Coverage
+
+Log status in review output:
+- Not installed: `axiom: not installed (install with claude plugin install axiom@lvlup-sw)`
+- Disabled: `axiom: disabled via .exarchos.yml`
+- Active: `axiom: active (N findings)`
+
 ## Output
 
 Track the feature name and plan path as `$FEATURE_NAME` and `$PLAN_PATH`.