@lvlup-sw/exarchos 2.0.3 → 2.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +3 -3
- package/.claude-plugin/plugin.json +5 -5
- package/README.md +78 -149
- package/dist/exarchos-mcp.js +5 -6
- package/package.json +2 -2
|
@@ -5,18 +5,18 @@
|
|
|
5
5
|
"email": "oss@levelupsoftware.com"
|
|
6
6
|
},
|
|
7
7
|
"metadata": {
|
|
8
|
-
"description": "
|
|
8
|
+
"description": "SDLC workflow plugins for Claude Code",
|
|
9
9
|
"version": "1.0.0"
|
|
10
10
|
},
|
|
11
11
|
"plugins": [
|
|
12
12
|
{
|
|
13
13
|
"name": "exarchos",
|
|
14
14
|
"source": { "source": "npm", "package": "@lvlup-sw/exarchos", "version": "2.0.3" },
|
|
15
|
-
"description": "
|
|
15
|
+
"description": "SDLC workflows with agent team coordination, quality gates, and Graphite stacked PRs",
|
|
16
16
|
"version": "2.0.3",
|
|
17
17
|
"author": { "name": "Levelup Software" },
|
|
18
18
|
"category": "productivity",
|
|
19
|
-
"tags": ["workflow", "sdlc", "
|
|
19
|
+
"tags": ["workflow", "sdlc", "graphite", "stacked-prs", "tdd"]
|
|
20
20
|
}
|
|
21
21
|
]
|
|
22
22
|
}
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "exarchos",
|
|
3
|
-
"description": "
|
|
3
|
+
"description": "SDLC workflows for Claude Code with agent team coordination, quality gates, and Graphite stacked PRs.",
|
|
4
4
|
"version": "2.0.3",
|
|
5
5
|
"author": { "name": "Levelup Software" },
|
|
6
6
|
"homepage": "https://github.com/lvlup-sw/exarchos",
|
|
7
7
|
"repository": "https://github.com/lvlup-sw/exarchos",
|
|
8
8
|
"license": "Apache-2.0",
|
|
9
9
|
"keywords": [
|
|
10
|
-
"workflow", "sdlc", "
|
|
11
|
-
"event-sourcing", "tdd", "code-review", "teams"
|
|
10
|
+
"workflow", "sdlc", "graphite", "stacked-prs",
|
|
11
|
+
"event-sourcing", "tdd", "code-review", "agent-teams"
|
|
12
12
|
],
|
|
13
13
|
"commands": "./commands/",
|
|
14
14
|
"skills": "./skills/",
|
|
@@ -16,8 +16,8 @@
|
|
|
16
16
|
"mcpServers": {
|
|
17
17
|
"exarchos": {
|
|
18
18
|
"type": "stdio",
|
|
19
|
-
"command": "
|
|
20
|
-
"args": ["
|
|
19
|
+
"command": "node",
|
|
20
|
+
"args": ["${CLAUDE_PLUGIN_ROOT}/dist/exarchos-mcp.js"],
|
|
21
21
|
"env": {
|
|
22
22
|
"WORKFLOW_STATE_DIR": "~/.claude/workflow-state"
|
|
23
23
|
}
|
package/README.md
CHANGED
|
@@ -3,139 +3,69 @@
|
|
|
3
3
|
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
|
|
6
|
-
**
|
|
7
|
-
|
|
6
|
+
**SDLC workflows for Claude Code**<br>
|
|
7
|
+
Agent teams · Quality gates · Graphite stacked PRs · Event-sourced state
|
|
8
8
|
</div>
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
##
|
|
13
|
-
|
|
14
|
-
### From Claude Code Marketplace (Recommended)
|
|
12
|
+
## Why Exarchos?
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
claude plugin install exarchos@lvlup-sw
|
|
18
|
-
```
|
|
14
|
+
Claude Code doesn't have workflow structure out of the box. Agents lose context mid-task, skip tests, produce monolithic PRs, and leave you reconstructing what happened after the fact.
|
|
19
15
|
|
|
20
|
-
|
|
16
|
+
Exarchos adds SDLC process to Claude Code. Three workflows (feature, debug, refactor) move through defined phases with human checkpoints at design and merge. Between those checkpoints, agent teams work in parallel git worktrees while the orchestrator manages state, enforces review gates, and logs every transition.
|
|
21
17
|
|
|
22
|
-
|
|
23
|
-
git
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
18
|
+
- **Three SDLC workflows.** Feature, debug, and refactor tracks with defined phases. You approve at design and merge; everything else auto-continues.
|
|
19
|
+
- **Parallel agent teams.** Delegate implementation to teammates working in isolated git worktrees with independent context.
|
|
20
|
+
- **Two-stage code review.** Spec compliance first, then code quality. TDD enforcement and deterministic validation scripts gate every merge.
|
|
21
|
+
- **Graphite stacked PRs.** Work ships as incremental stacked PRs through merge queue. No monolithic diffs, no manual branch management.
|
|
22
|
+
- **Append-only event log.** Every workflow transition, task completion, and agent interaction is recorded. Trace what happened, when, and why.
|
|
23
|
+
- **Low context overhead.** Composite MCP tools and on-demand content loading keep token usage minimal.
|
|
24
|
+
- **Persistent state.** Workflows survive context compaction and session restarts. Pick up where you left off across sessions and machines.
|
|
28
25
|
|
|
29
|
-
|
|
26
|
+
## Installation
|
|
30
27
|
|
|
31
|
-
|
|
28
|
+
### From Marketplace (Recommended)
|
|
32
29
|
|
|
33
30
|
```bash
|
|
34
|
-
|
|
31
|
+
# Add the lvlup-sw marketplace
|
|
32
|
+
/plugin marketplace add lvlup-sw/exarchos
|
|
33
|
+
|
|
34
|
+
# Install the core plugin
|
|
35
|
+
/plugin install exarchos@lvlup-sw
|
|
35
36
|
```
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
This installs the Exarchos MCP server, Graphite MCP integration, all workflow commands and skills, lifecycle hooks, and validation scripts.
|
|
38
39
|
|
|
39
|
-
|
|
40
|
-
npx -y github:lvlup-sw/exarchos
|
|
41
|
-
```
|
|
40
|
+
**Dev companion** (optional): adds GitHub, Serena, Context7, and Microsoft Learn MCP servers. `npx @lvlup-sw/exarchos-dev`
|
|
42
41
|
|
|
43
|
-
|
|
42
|
+
### For Development
|
|
44
43
|
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
? Proceed with install? Yes
|
|
44
|
+
```bash
|
|
45
|
+
git clone https://github.com/lvlup-sw/exarchos.git
|
|
46
|
+
cd exarchos
|
|
47
|
+
npm install && npm run build
|
|
48
|
+
claude --plugin-dir .
|
|
51
49
|
```
|
|
52
50
|
|
|
53
51
|
### Prerequisites
|
|
54
52
|
|
|
55
53
|
- **Node.js** >= 20
|
|
56
|
-
- **Graphite CLI** (`gt`) — required for stacked PR workflows
|
|
54
|
+
- **Graphite CLI** (`gt`) — required for stacked PR workflows ([install](https://graphite.dev/docs/install))
|
|
55
|
+
|
|
56
|
+
> Migrating from the legacy `npx` installer? See the [migration guide](docs/migration-from-legacy-installer.md).
|
|
57
57
|
|
|
58
58
|
## Workflows
|
|
59
59
|
|
|
60
|
+
> **Note:** Commands are shown in short form (`/ideate`) throughout this README. When installed as a plugin, commands are namespaced as `/exarchos:ideate`, `/exarchos:plan`, etc.
|
|
61
|
+
|
|
60
62
|
| Task | Command |
|
|
61
63
|
|------|---------|
|
|
62
|
-
| New feature
|
|
63
|
-
| Bug fix | `/
|
|
64
|
-
| Code improvement | `/
|
|
65
|
-
|
|
66
|
-
## Build & Test
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
npm run build # tsc + bun → dist/
|
|
70
|
-
npm run test:run # vitest single run
|
|
71
|
-
npm run typecheck # tsc --noEmit
|
|
72
|
-
npm run validate # Validate plugin structure
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
## Why Exarchos?
|
|
76
|
-
|
|
77
|
-
Claude Code is powerful, but complex features expose three gaps: sessions lose state during context compaction, subagents can't collaborate or challenge each other, and there's no structured way to verify what agents produce. Exarchos fills these gaps.
|
|
78
|
-
|
|
79
|
-
- **Verifiable outcomes** — Layered quality gates enforce spec compliance, code quality, and TDD at every stage. Work that doesn't pass doesn't merge.
|
|
80
|
-
- **Multi-agent orchestration** — Agent teams work in parallel git worktrees with independent context. The orchestrator steers; teammates execute, review, and coordinate.
|
|
81
|
-
- **Graphite stacked PRs** — Completed tasks are progressively stacked as PRs via Graphite, with merge queue integration. No monolithic PRs.
|
|
82
|
-
- **Full auditability** — Every workflow transition, task completion, and agent interaction is recorded in an append-only event store. Saga compensation ensures safe cancellation and recovery. CQRS materialized views provide real-time observability.
|
|
83
|
-
- **Context resilience** — HSM-driven workflow state survives context compaction. Sessions auto-resume exactly where they left off.
|
|
84
|
-
- **Token efficient** — 5 composite MCP tools using action discriminators replace what would otherwise be 26+ individual tool definitions. Fewer tool schemas in context means lower per-call token overhead. Structured Markdown content layers (commands, skills, rules) load on demand — only what's relevant enters the context window.
|
|
85
|
-
|
|
86
|
-
## Architecture
|
|
87
|
-
|
|
88
|
-
Exarchos is a unified MCP server combining workflow state management, event sourcing, CQRS views, and team coordination.
|
|
89
|
-
|
|
90
|
-
```
|
|
91
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
92
|
-
│ Claude Code Lead │
|
|
93
|
-
│ Orchestrator — /ideate, /plan, /delegate, etc. │
|
|
94
|
-
└────────────────────────────┬────────────────────────────────┘
|
|
95
|
-
│
|
|
96
|
-
┌────────┴────────┐
|
|
97
|
-
│ Exarchos MCP │
|
|
98
|
-
│ │
|
|
99
|
-
│ Event Store │ Append-only JSONL
|
|
100
|
-
│ CQRS Views │ Materialized read models
|
|
101
|
-
│ Team Coord │ Spawn/message/shutdown
|
|
102
|
-
│ Workflow HSM │ State machine transitions
|
|
103
|
-
└────────┬────────┘
|
|
104
|
-
│
|
|
105
|
-
┌──────────────┼──────────────┐
|
|
106
|
-
│ │ │
|
|
107
|
-
Teammate 1 Teammate 2 Teammate N
|
|
108
|
-
(worktree) (worktree) (worktree)
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
### MCP Tools (5 Composite)
|
|
64
|
+
| New feature or design | `/ideate` |
|
|
65
|
+
| Bug fix | `/debug` |
|
|
66
|
+
| Code improvement | `/refactor` |
|
|
112
67
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
| Tool | Actions | Purpose |
|
|
116
|
-
|------|---------|---------|
|
|
117
|
-
| **`exarchos_workflow`** | `init`, `get`, `set`, `cancel`, `cleanup` | HSM state transitions, phase tracking, lifecycle management |
|
|
118
|
-
| **`exarchos_event`** | `append`, `query` | Append-only event log, temporal queries |
|
|
119
|
-
| **`exarchos_orchestrate`** | `task_claim`, `task_complete`, `task_fail` | Task lifecycle for delegated work |
|
|
120
|
-
| **`exarchos_view`** | `pipeline`, `tasks`, `workflow_status`, `stack_status`, `stack_place`, `telemetry`, `team_performance`, `delegation_timeline` | CQRS materialized read models |
|
|
121
|
-
| **`exarchos_sync`** | `now` | Remote state synchronization |
|
|
122
|
-
|
|
123
|
-
### Companion MCP Servers & Plugins
|
|
124
|
-
|
|
125
|
-
Configured during install via the interactive wizard:
|
|
126
|
-
|
|
127
|
-
| Server/Plugin | Type | Purpose |
|
|
128
|
-
|---------------|------|---------|
|
|
129
|
-
| **Exarchos** | MCP (bundled) | Workflow orchestration, event sourcing, team coordination |
|
|
130
|
-
| **Graphite** | MCP (external) | Stacked PR management and merge queue |
|
|
131
|
-
| **Microsoft Learn** | MCP (remote) | Official Azure/.NET documentation |
|
|
132
|
-
| **GitHub** | Claude plugin | PRs, issues, code search |
|
|
133
|
-
| **Serena** | Claude plugin | Semantic code analysis |
|
|
134
|
-
| **Context7** | Claude plugin | Up-to-date library documentation |
|
|
135
|
-
|
|
136
|
-
## Workflow Details
|
|
137
|
-
|
|
138
|
-
Three HSM-driven SDLC workflows with automatic state checkpointing. All workflows auto-resume on session start. Human checkpoints only at plan approval and merge confirmation.
|
|
68
|
+
Supporting commands (`/plan`, `/delegate`, `/review`, `/synthesize`, `/checkpoint`, `/resume`, `/cleanup`) are phase commands invoked within workflows.
|
|
139
69
|
|
|
140
70
|
### Feature Workflow
|
|
141
71
|
|
|
@@ -158,12 +88,12 @@ Three HSM-driven SDLC workflows with automatic state checkpointing. All workflow
|
|
|
158
88
|
|
|
159
89
|
| Phase | Command | Purpose |
|
|
160
90
|
|-------|---------|---------|
|
|
161
|
-
| Design | `/ideate` | Collaborative design exploration with trade-offs |
|
|
162
|
-
| Plan | `/plan` | TDD task decomposition + stack ordering |
|
|
91
|
+
| Design | `/exarchos:ideate` | Collaborative design exploration with trade-offs |
|
|
92
|
+
| Plan | `/exarchos:plan` | TDD task decomposition + stack ordering |
|
|
163
93
|
| Plan review | — | Human approval checkpoint |
|
|
164
|
-
| Delegate | `/delegate` | Spawn agent teams in worktrees
|
|
165
|
-
| Review | `/review` | Two-stage: spec compliance → code quality |
|
|
166
|
-
| Synthesize | `/synthesize` | Enqueue Graphite stack in merge queue |
|
|
94
|
+
| Delegate | `/exarchos:delegate` | Spawn agent teams in worktrees |
|
|
95
|
+
| Review | `/exarchos:review` | Two-stage: spec compliance → code quality |
|
|
96
|
+
| Synthesize | `/exarchos:synthesize` | Enqueue Graphite stack in merge queue |
|
|
167
97
|
|
|
168
98
|
### Debug Workflow
|
|
169
99
|
|
|
@@ -205,52 +135,51 @@ Three HSM-driven SDLC workflows with automatic state checkpointing. All workflow
|
|
|
205
135
|
| **Polish** | implement → validate → update docs → completed | Small changes, ≤5 files, direct edits |
|
|
206
136
|
| **Overhaul** | plan → delegate → review → update docs → synthesize | Large restructuring, delegation required |
|
|
207
137
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
Every task follows Red-Green-Refactor:
|
|
211
|
-
1. **RED**: Write failing test first
|
|
212
|
-
2. **GREEN**: Minimum code to pass
|
|
213
|
-
3. **REFACTOR**: Clean up, tests stay green
|
|
214
|
-
|
|
215
|
-
## What's Installed
|
|
216
|
-
|
|
217
|
-
The installer copies (standard mode) or symlinks (dev mode) into `~/.claude/`:
|
|
218
|
-
|
|
219
|
-
| Type | Count | Examples |
|
|
220
|
-
|------|-------|----------|
|
|
221
|
-
| Commands | 12 | `/ideate`, `/plan`, `/delegate`, `/review`, `/synthesize`, `/debug`, `/refactor` |
|
|
222
|
-
| Skills | 14 | brainstorming, delegation, debug, refactor, spec-review, quality-review |
|
|
223
|
-
| Rule sets | 3 | TypeScript, C#/.NET, Workflow & Orchestration |
|
|
224
|
-
| MCP servers | 1–3 | Exarchos (required), Graphite (required), Microsoft Learn (optional) |
|
|
225
|
-
| Plugins | 0–3 | GitHub, Serena, Context7 |
|
|
226
|
-
|
|
227
|
-
### Installation Modes
|
|
138
|
+
## How It Works
|
|
228
139
|
|
|
229
|
-
|
|
230
|
-
|------|-------------|----------|
|
|
231
|
-
| **Standard** | Copies files to `~/.claude/` with content hash tracking | End users |
|
|
232
|
-
| **Dev** | Symlinks to repo for live editing | Exarchos contributors |
|
|
140
|
+
Your Claude Code session acts as the orchestrator. Exarchos manages workflow state; you make decisions at each checkpoint. Agent teammates execute tasks in isolated git worktrees, each with independent context, working in parallel.
|
|
233
141
|
|
|
234
|
-
|
|
142
|
+
```
|
|
143
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
144
|
+
│ Claude Code Lead │
|
|
145
|
+
│ Orchestrator — /ideate, /plan, /delegate │
|
|
146
|
+
└────────────────────────────┬────────────────────────────────┘
|
|
147
|
+
│
|
|
148
|
+
┌────────┴────────┐
|
|
149
|
+
│ Exarchos MCP │
|
|
150
|
+
│ │
|
|
151
|
+
│ Workflow State │ Persistent across sessions
|
|
152
|
+
│ Event Log │ Full audit trail
|
|
153
|
+
│ Team Coord │ Spawn/message/shutdown
|
|
154
|
+
│ Quality Gates │ Automated verification
|
|
155
|
+
└────────┬────────┘
|
|
156
|
+
│
|
|
157
|
+
┌──────────────┼──────────────┐
|
|
158
|
+
│ │ │
|
|
159
|
+
Teammate 1 Teammate 2 Teammate N
|
|
160
|
+
(worktree) (worktree) (worktree)
|
|
161
|
+
```
|
|
235
162
|
|
|
236
|
-
|
|
163
|
+
### Integrations
|
|
237
164
|
|
|
238
|
-
|
|
165
|
+
| Component | Source | Purpose |
|
|
166
|
+
|-----------|--------|---------|
|
|
167
|
+
| **Exarchos** | Core plugin | Workflow orchestration, event logging, team coordination |
|
|
168
|
+
| **Graphite** | Core plugin | Stacked PR management and merge queue |
|
|
169
|
+
| **GitHub** | [Dev companion](companion/) | PRs, issues, code search |
|
|
170
|
+
| **Serena** | [Dev companion](companion/) | Semantic code analysis |
|
|
171
|
+
| **Context7** | [Dev companion](companion/) | Up-to-date library documentation |
|
|
172
|
+
| **Microsoft Learn** | [Dev companion](companion/) | Official Azure/.NET documentation |
|
|
239
173
|
|
|
240
|
-
|
|
241
|
-
2. **Global**: `~/.claude/` (installed by Exarchos)
|
|
174
|
+
For technical details on the MCP server architecture, event sourcing model, and tool API, see the [architecture documentation](docs/).
|
|
242
175
|
|
|
243
|
-
|
|
176
|
+
## Build & Test
|
|
244
177
|
|
|
245
178
|
```bash
|
|
246
|
-
#
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
paths: '**/*.ts'
|
|
251
|
-
---
|
|
252
|
-
# My project rule
|
|
253
|
-
EOF
|
|
179
|
+
npm run build # tsc + bun → dist/
|
|
180
|
+
npm run test:run # vitest single run
|
|
181
|
+
npm run typecheck # tsc --noEmit
|
|
182
|
+
npm run validate # Validate plugin structure
|
|
254
183
|
```
|
|
255
184
|
|
|
256
185
|
## License
|