You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: reposition messaging around "local-first SDLC workflow harness"
Restructure README, docs landing page, and "Why Exarchos" page around
the approved positioning: local-first SDLC workflow harness providing
structured, durable state. Lead with what developers already do (plan
files, CLAUDE.md, deliberate /clear), not what happens to them.
- README: new hero subtitle, approved opening copy, standalone MCP install
- documentation/index.md: aligned hero text and feature cards
- documentation/learn/index.md: rewritten to match developer behavior
- plugin.json: updated description
- docs/market/copy-templates.md: short-form, Twitter, HN Show templates
- docs/designs/ and docs/plans/: design doc and implementation plan
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: .claude-plugin/plugin.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
{
2
2
"name": "exarchos",
3
-
"description": "Structure for agentic development — durable SDLC workflows with convergence gates, agent teams, and full audit trail.",
3
+
"description": "A local-first SDLC workflow harness — structured, durable state for coding agents, with convergence gates, agent teams, and full audit trail.",
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.
20
-
21
-
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.
22
-
23
-
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.
24
-
25
-
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.
19
+
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.
26
20
27
21
## Your plan.md workflow, with teeth
28
22
29
-
Exarchos replaces markdown files with an event-sourced MCP server. A state machine enforces phase transitions (design, plan, implement, review, ship) with quality gates between each step. Typed agents (implementer, fixer, reviewer) execute in isolated git worktrees, following runbooks that encode step sequences and gate checks. Lifecycle hooks run validation scripts automatically, so the agent can't skip steps even if it wants to.
23
+
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.
24
+
25
+
`/clear` whenever you want. `/rehydrate` when you're back. State persists.
30
26
31
-
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.
27
+
It ships as a Claude Code plugin and a standalone MCP server with a CLI adapter. Install it and run `/ideate`.
32
28
33
29
<divalign="center">
34
30
<ahref="docs/assets/architecture.svg">
35
31
<img src="docs/assets/architecture.svg" alt="Exarchos architecture: workflow pipeline, state machine, agent teams in worktrees, quality gates" width="720" />
That's it. Installs the MCP server, all workflow commands, lifecycle hooks, and validation scripts.
45
+
**Standalone MCP server:**
46
+
```bash
47
+
npx @lvlup-sw/exarchos mcp
48
+
```
50
49
51
-
**Dev companion** (optional, adds Serena, Context7, and Microsoft Learn MCP servers):
50
+
**Dev companion** (optional — adds Serena, Context7, and Microsoft Learn):
52
51
```bash
53
52
npx @lvlup-sw/exarchos-dev
54
53
```
@@ -67,21 +66,19 @@ Requires Node.js >= 20.
67
66
68
67
## What you get
69
68
70
-
Three workflow types (feature, debug, refactor) with enforced phase transitions. You approve twice: the design and the merge. Everything between auto-continues.
69
+
Three workflow types (feature, debug, refactor) with enforced phase transitions. You approve the design and you approve the merge. Everything between auto-continues.
71
70
72
-
**Checkpoint and resume.**`/checkpoint` saves mid-task. `/rehydrate` restores it in ~2-3k tokens. No re-explaining your project from scratch the next day.
71
+
**Checkpoint and resume.**`/checkpoint` saves mid-task. `/rehydrate` restores it in ~2-3k tokens.
73
72
74
-
**Typed agent teams.**Three agent roles (implementer, fixer, reviewer), each with scoped tools, hooks, and worktree isolation. Fixers resume failed tasks with full context instead of starting over.
73
+
**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.
75
74
76
-
**Runbooks.**The MCP server ships machine-readable orchestration sequences. Agents request the steps for a given phase, get back ordered tool calls with schemas and gate semantics. No prose to misinterpret, and any MCP client can use them.
75
+
**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.
77
76
78
-
**Two-stage review.** Spec compliance first (does it match the design?), then code quality (is it well-written?). Verification scripts, not vibes.
77
+
**Two-stage review.** Spec compliance first (does it match the design?), then code quality (is it well-written?). Deterministic convergence gates, not prompts.
79
78
80
-
**Audit trail.** Every transition, gate result, and agent decision goes into an append-only event log. When something breaks, you can trace what happened.
79
+
**Audit trail.** Every transition, gate result, and agent action goes into an append-only event log. When something breaks, trace what happened.
81
80
82
-
**Token-efficient.** Lazy schema registration keeps MCP startup under 500 tokens. Field projection trims state queries by 90%. Code review sends diffs, not full files.
83
-
84
-
Your Claude Code session is the orchestrator. Exarchos manages state; you make decisions at each checkpoint.
81
+
**Token-efficient.** Lazy schema registration keeps MCP startup under 500 tokens. Field projection trims state queries by 90%. Review sends diffs, not full files.
85
82
86
83
### Agent-first architecture
87
84
@@ -91,22 +88,20 @@ Exarchos ships as a single binary (`exarchos`) with an `mcp` subcommand. Claude
|`exarchos_view`| CQRS projections: pipeline status, task boards, stack health |
96
93
97
-
All four tools support lazy schema loading via `describe`. At startup, only slim descriptions and action enums are registered. Full schemas load on demand when the agent calls `describe` for the actions it needs.
98
-
99
-
Agent specifications live in a registry and are served through `exarchos_orchestrate({ action: "agent_spec" })`. Claude Code gets compiled `.md` agent files as a native optimization; other MCP clients get the same specs via the API.
94
+
All four tools support lazy schema loading via `describe`. At startup, only slim descriptions and action enums are registered. Full schemas load on demand.
100
95
101
-
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 you can call `exarchos workflow get --featureId my-feature` from a terminal and get the same result the agent gets. Lifecycle hooks (pre-compact, session-start, guard, task-gate) run as fast-path subcommands that skip heavy initialization.
96
+
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.
102
97
103
-
The design is agent-first: structured input over natural language, strict schema validation over loose parsing. One binary, same behavior whether an agent or a human is driving it.
98
+
Structured input over natural language. Strict schema validation over loose parsing. One binary, same behavior whether an agent or a human is driving it.
Exarchos 2.5.0 is the first public release. We need messaging that communicates the value proposition to developers and power users immediately, drives installs, and differentiates from the existing landscape of agent workflow tools.
10
+
11
+
### Audience
12
+
13
+
Broader developer audience, not limited to Claude Code users. Platform-agnostic positioning with first-class Claude Code support. Later extension to Cursor, Copilot CLI, and other MCP clients.
14
+
15
+
### What developers actually do today
16
+
17
+
Research from Hacker News threads (260+ points) and community tools confirms:
18
+
19
+
-**Plan files per feature.** CLAUDE.md updated multiple times a week. Session summaries written before `/clear` to propagate context to the next window.
20
+
-**Phase-based context propagation.** At phase boundaries, developers have Claude update the plan file with context for a fresh session. Separation of planning and execution is a deliberate workflow.
21
+
-**Deliberate `/clear` over compaction.** Power users run `/clear` at a chosen context length rather than letting compaction happen. Compaction is lossy and unpredictable; `/clear` with a pre-written summary is controlled.
22
+
-**Subagents for context hygiene.** Used defensively to keep exploration out of the main window, not just for parallelism.
23
+
-**At least 7 open-source persistence tools** (Grov, Recall, Mem0, A-MEM, ContextForge, Claude Reflect, and others) exist to solve the memory/persistence problem. This is a validated pain point.
24
+
25
+
The core insight: power users aren't passively losing context. They're actively managing it through manual, unenforceable processes.
26
+
27
+
### Competitive landscape
28
+
29
+
| Feature | Exarchos | Obra Superpowers | Claude Task Master | Manual (plan.md) |
| State persistence across sessions | Event-sourced, survives compaction | Session-based | Task file on disk | None |
32
+
| Phase-gated workflows | State machine with guards | No | No | Manual discipline |
33
+
| Quality verification | Deterministic convergence gates | No | No | Manual review |
34
+
| Agent team coordination | Typed agents in worktrees | Mode switching | No | No |
35
+
| Token efficiency | Lazy schemas, field projection | N/A | Full context load | Full context load |
36
+
| Audit trail | Append-only event log | No | No | Git history only |
37
+
38
+
## Positioning
39
+
40
+
**Category:** Local-first SDLC workflow harness
41
+
42
+
**Core positioning statement:** Exarchos gives coding agents structured, durable state — phase-gated workflows that survive context clears, with deterministic quality verification.
43
+
44
+
**Approach:** Problem-first messaging (Approach C) as the outer shell, mechanism explanation (Approach B: "workflow harness") as the structural explanation. Reserve "governance" framing for enterprise docs.
45
+
46
+
### Tagline
47
+
48
+
**Your agents forget. Exarchos doesn't.**
49
+
50
+
### Secondary line
51
+
52
+
**Your plan.md workflow, with teeth.**
53
+
54
+
## Copy
55
+
56
+
### README / landing page opening
57
+
58
+
> **Your agents forget. Exarchos doesn't.**
59
+
>
60
+
> You already manage this by hand. 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.
61
+
>
62
+
> 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.
63
+
>
64
+
> `/clear` whenever you want. `/rehydrate` when you're back. State persists.
65
+
>
66
+
> It ships as a Claude Code plugin and a standalone MCP server with a CLI adapter. Install it and run `/ideate`.
67
+
68
+
### Key messaging principles
69
+
70
+
1.**Lead with what they already do.** Don't explain context loss as a surprise. Describe the manual work they're doing to prevent it.
71
+
2.**"Local-first SDLC workflow harness"** is the category. Use it consistently.
72
+
3.**"Structured, durable state"** is the mechanism. Not "memory" (confused with RAG/vector stores). Not "persistence" (too generic).
73
+
4.**Deterministic over vibes.** Convergence gates are TypeScript checks, not LLM inference. Same code, same result.
74
+
5.**Two human checkpoints.** Design approval and merge approval. Everything between auto-continues. Don't oversell autonomy; sell controlled autonomy.
75
+
6.**Platform-agnostic core.** Claude Code plugin + standalone MCP server. The MCP server works with any client.
76
+
77
+
### Distribution model
78
+
79
+
Following the Impeccable cross-platform pattern:
80
+
-`npx skills add` with auto-detection for environment
81
+
- Plugin marketplace for Claude Code
82
+
- Standalone MCP server for other clients
83
+
- Thin content layer (skills, commands, hooks, agent specs) per platform; runtime is platform-agnostic
84
+
85
+
## Requirements
86
+
87
+
- DR-1: README restructured around the approved copy
88
+
- DR-2: Marketplace listing updated with positioning
89
+
- DR-3: Landing page (docs site index) aligned with messaging
90
+
- DR-4: Copy templates for social/campaign use
91
+
- DR-5: Cross-platform install instructions reflecting distribution model
> Exarchos: a local-first SDLC workflow harness — structured, durable state for coding agents.
9
+
10
+
**Two-liner:**
11
+
> Your agents forget. Exarchos doesn't. A local-first workflow harness that gives coding agents structured, durable state outside the context window.
12
+
13
+
**Paragraph:**
14
+
> You already manage context by hand — plan files per feature, CLAUDE.md updated between sessions, summaries before /clear. Exarchos replaces the manual process with an event-sourced MCP server. Phase transitions enforced by a state machine. Deterministic convergence gates as TypeScript checks. /clear whenever you want, /rehydrate when you're back.
15
+
16
+
## Twitter/X templates
17
+
18
+
**1. Problem hook:**
19
+
> You keep a plan.md per feature. You update CLAUDE.md between sessions. You write summaries before /clear. You enforce your own phases.
20
+
>
21
+
> That's a workflow harness, done by hand.
22
+
>
23
+
> Exarchos does it for you: durable state, enforced phases, deterministic quality gates.
24
+
25
+
**2. Technical hook:**
26
+
> Exarchos is an event-sourced MCP server. State lives outside the context window. A state machine enforces phase transitions. Convergence gates run as TypeScript checks against your diff.
27
+
>
28
+
> /clear whenever you want. /rehydrate when you're back.
29
+
30
+
**3. Pain point:**
31
+
> The agent skipped your review phase because the context got long enough that it stopped reading your instructions.
32
+
>
33
+
> Exarchos makes that impossible. State machine won't let it through.
34
+
35
+
**4. Agent teams:**
36
+
> Three typed agents: implementer (writes code via TDD), fixer (resumes failures with context), reviewer (read-only, can't edit files).
37
+
>
38
+
> Each in its own worktree. Scoped tools, not honor-system prompts.
39
+
40
+
**5. Comparison:**
41
+
> Plan files: stateless, unenforced, no verification.
**Title:** Show HN: Exarchos — a local-first SDLC workflow harness for coding agents
49
+
50
+
**Body:**
51
+
52
+
If you use Claude Code (or any MCP-compatible agent) for real work, you've probably built your own version of this: plan files per feature, CLAUDE.md updated between sessions, summaries written before /clear so the next session can pick up.
53
+
54
+
Exarchos formalizes that workflow. It's an event-sourced MCP server that gives your agent structured, durable state outside the context window:
55
+
56
+
- Phase transitions enforced by a state machine (design, plan, implement, review, ship)
57
+
- Deterministic convergence gates run as TypeScript checks against your diff and git history
58
+
- Three typed agent roles (implementer, fixer, reviewer) in isolated worktrees
59
+
- Checkpoint/rehydrate across sessions in ~2-3k tokens
60
+
- Append-only event log for audit
61
+
62
+
Ships as a Claude Code plugin and a standalone MCP server. The MCP server works with any client.
0 commit comments