@lvlup-sw/exarchos 2.0.5 → 2.0.6
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 +2 -2
- package/.claude-plugin/plugin.json +1 -8
- package/commands/cleanup.md +3 -3
- package/commands/debug.md +2 -2
- package/commands/ideate.md +3 -3
- package/commands/plan.md +3 -3
- package/commands/refactor.md +1 -1
- package/commands/resume.md +1 -1
- package/commands/synthesize.md +1 -1
- package/dist/node_modules/electron/index.js +1 -0
- package/dist/node_modules/electron/package.json +1 -0
- package/dist/node_modules/playwright-core/index.js +1 -0
- package/dist/node_modules/playwright-core/package.json +1 -0
- package/hooks/hooks.json +1 -1
- package/package.json +3 -2
- package/scripts/build-cli.ts +28 -0
- package/skills/brainstorming/SKILL.md +1 -1
- package/skills/cleanup/SKILL.md +4 -4
- package/skills/debug/references/troubleshooting.md +8 -8
- package/skills/delegation/references/fix-mode.md +1 -1
- package/skills/delegation/references/state-management.md +1 -1
- package/skills/delegation/references/worktree-enforcement.md +1 -1
- package/skills/implementation-planning/SKILL.md +1 -1
- package/skills/refactor/SKILL.md +2 -2
- package/skills/refactor/phases/auto-chain.md +1 -1
- package/skills/shepherd/SKILL.md +8 -8
- package/skills/shepherd/references/assess-checklist.md +1 -1
- package/skills/synthesis/SKILL.md +1 -1
- package/skills/synthesis/references/troubleshooting.md +5 -5
- package/skills/workflow-state/SKILL.md +13 -13
- package/skills/workflow-state/references/mcp-tool-reference.md +7 -7
|
@@ -14,10 +14,10 @@
|
|
|
14
14
|
"source": {
|
|
15
15
|
"source": "npm",
|
|
16
16
|
"package": "@lvlup-sw/exarchos",
|
|
17
|
-
"version": "2.0.
|
|
17
|
+
"version": "2.0.6"
|
|
18
18
|
},
|
|
19
19
|
"description": "SDLC workflows with agent team coordination, quality gates, and Graphite stacked PRs",
|
|
20
|
-
"version": "2.0.
|
|
20
|
+
"version": "2.0.6",
|
|
21
21
|
"author": {
|
|
22
22
|
"name": "Levelup Software"
|
|
23
23
|
},
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "exarchos",
|
|
3
3
|
"description": "SDLC workflows for Claude Code with agent team coordination, quality gates, and Graphite stacked PRs.",
|
|
4
|
-
"version": "2.0.
|
|
4
|
+
"version": "2.0.6",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Levelup Software"
|
|
7
7
|
},
|
|
@@ -31,13 +31,6 @@
|
|
|
31
31
|
"env": {
|
|
32
32
|
"WORKFLOW_STATE_DIR": "~/.claude/workflow-state"
|
|
33
33
|
}
|
|
34
|
-
},
|
|
35
|
-
"graphite": {
|
|
36
|
-
"type": "stdio",
|
|
37
|
-
"command": "gt",
|
|
38
|
-
"args": [
|
|
39
|
-
"mcp"
|
|
40
|
-
]
|
|
41
34
|
}
|
|
42
35
|
}
|
|
43
36
|
}
|
package/commands/cleanup.md
CHANGED
|
@@ -30,12 +30,12 @@ Follow the cleanup skill: `@skills/cleanup/SKILL.md`
|
|
|
30
30
|
|
|
31
31
|
Read workflow state:
|
|
32
32
|
```typescript
|
|
33
|
-
|
|
33
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({ action: "get", featureId: "<feature-id>" })
|
|
34
34
|
```
|
|
35
35
|
|
|
36
36
|
If no `$ARGUMENTS` provided, list active workflows:
|
|
37
37
|
```typescript
|
|
38
|
-
|
|
38
|
+
mcp__plugin_exarchos_exarchos__exarchos_view({ action: "pipeline" })
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
### Step 2: Verify PR Merge Status
|
|
@@ -54,7 +54,7 @@ Collect:
|
|
|
54
54
|
### Step 3: Invoke Cleanup Action
|
|
55
55
|
|
|
56
56
|
```typescript
|
|
57
|
-
|
|
57
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({
|
|
58
58
|
action: "cleanup",
|
|
59
59
|
featureId: "<feature-id>",
|
|
60
60
|
mergeVerified: true,
|
package/commands/debug.md
CHANGED
|
@@ -65,11 +65,11 @@ Switch from hotfix to thorough track during investigation.
|
|
|
65
65
|
|
|
66
66
|
### Step 1: Initialize State
|
|
67
67
|
|
|
68
|
-
Initialize workflow state using `
|
|
68
|
+
Initialize workflow state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"`:
|
|
69
69
|
- Set `featureId` to `debug-<issue-slug>`
|
|
70
70
|
- Set `workflowType` to "debug"
|
|
71
71
|
|
|
72
|
-
Then update the track using `
|
|
72
|
+
Then update the track using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
73
73
|
- Set `track` to "hotfix" or "thorough" based on triage
|
|
74
74
|
|
|
75
75
|
### Step 2: Triage
|
package/commands/ideate.md
CHANGED
|
@@ -52,9 +52,9 @@ After user selects approach:
|
|
|
52
52
|
|
|
53
53
|
## State Management
|
|
54
54
|
|
|
55
|
-
Initialize workflow state at the start using `
|
|
55
|
+
Initialize workflow state at the start using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"` and the featureId.
|
|
56
56
|
|
|
57
|
-
After saving design, update state using `
|
|
57
|
+
After saving design, update state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
58
58
|
- Set `artifacts.design` to the design path
|
|
59
59
|
- Set `phase` to "plan"
|
|
60
60
|
|
|
@@ -66,7 +66,7 @@ Save design to `docs/designs/YYYY-MM-DD-<feature>.md` and capture the path as `$
|
|
|
66
66
|
|
|
67
67
|
After saving the design document, **auto-continue to planning** (no user confirmation here):
|
|
68
68
|
|
|
69
|
-
1. Update state with design path and phase using `
|
|
69
|
+
1. Update state with design path and phase using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
70
70
|
- Set `artifacts.design` to the design document path
|
|
71
71
|
- Set `phase` to "plan"
|
|
72
72
|
|
package/commands/plan.md
CHANGED
|
@@ -71,7 +71,7 @@ Write to `docs/plans/YYYY-MM-DD-<feature>.md`
|
|
|
71
71
|
|
|
72
72
|
## State Management
|
|
73
73
|
|
|
74
|
-
After saving plan, update state with tasks using `
|
|
74
|
+
After saving plan, update state with tasks using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
75
75
|
- Set `artifacts.plan` to the plan path
|
|
76
76
|
- Set `tasks` to an array of task objects (id, title, status, branch)
|
|
77
77
|
- Set `phase` to "plan-review"
|
|
@@ -117,7 +117,7 @@ Plan-review performs delta analysis and **auto-loops** back to `/exarchos:plan`
|
|
|
117
117
|
|
|
118
118
|
If plan-review finds missing coverage:
|
|
119
119
|
|
|
120
|
-
1. Update state with gaps using `
|
|
120
|
+
1. Update state with gaps using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
121
121
|
- Set `planReview.gapsFound` to true
|
|
122
122
|
- Set `planReview.gaps` to an array of gap descriptions
|
|
123
123
|
|
|
@@ -138,7 +138,7 @@ If plan-review finds complete coverage:
|
|
|
138
138
|
|
|
139
139
|
2. **PAUSE for user input**: "Plan covers all design requirements. Approve and continue to delegation? (yes/no)"
|
|
140
140
|
|
|
141
|
-
3. **On approval**, use `
|
|
141
|
+
3. **On approval**, use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
142
142
|
- Set `planReview.approved` to true
|
|
143
143
|
- Set `phase` to "delegate"
|
|
144
144
|
|
package/commands/refactor.md
CHANGED
|
@@ -63,7 +63,7 @@ Switch from polish to overhaul if scope expands.
|
|
|
63
63
|
|
|
64
64
|
### Step 1: Initialize State
|
|
65
65
|
|
|
66
|
-
Initialize workflow state using `
|
|
66
|
+
Initialize workflow state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"`, featureId `refactor-<slug>`, and workflowType `refactor`.
|
|
67
67
|
|
|
68
68
|
### Step 2: Explore
|
|
69
69
|
|
package/commands/resume.md
CHANGED
|
@@ -33,7 +33,7 @@ The SessionStart hook automatically verifies state matches git reality on resume
|
|
|
33
33
|
|
|
34
34
|
### Step 3: Load Context Summary
|
|
35
35
|
|
|
36
|
-
The SessionStart hook provides workflow context automatically. Read the state file using `
|
|
36
|
+
The SessionStart hook provides workflow context automatically. Read the state file using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and the featureId for detailed state.
|
|
37
37
|
|
|
38
38
|
### Step 4: Display Context
|
|
39
39
|
|
package/commands/synthesize.md
CHANGED
|
@@ -90,7 +90,7 @@ After PR is created, this is a **human checkpoint** - user confirmation required
|
|
|
90
90
|
|
|
91
91
|
### Save State
|
|
92
92
|
|
|
93
|
-
Update state using `
|
|
93
|
+
Update state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` and the `featureId`:
|
|
94
94
|
- Set `artifacts.pr` to the PR URL
|
|
95
95
|
- Set `synthesis.prUrl` to the PR URL
|
|
96
96
|
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
module.exports = {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"name":"electron","version":"0.0.0","main":"index.js"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
module.exports = {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"name":"playwright-core","version":"0.0.0","main":"index.js"}
|
package/hooks/hooks.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lvlup-sw/exarchos",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.6",
|
|
4
4
|
"description": "Governed SDLC workflows for Claude Code — agent orchestration, quality gates, and Graphite stacked PRs",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
"files": [
|
|
10
10
|
"dist/exarchos-mcp.js",
|
|
11
11
|
"dist/exarchos-cli.js",
|
|
12
|
+
"dist/node_modules",
|
|
12
13
|
"commands",
|
|
13
14
|
"skills",
|
|
14
15
|
"rules",
|
|
@@ -25,7 +26,7 @@
|
|
|
25
26
|
],
|
|
26
27
|
"scripts": {
|
|
27
28
|
"build": "tsc && bun run build:mcp && bun run build:cli",
|
|
28
|
-
"build:cli": "bun
|
|
29
|
+
"build:cli": "bun run scripts/build-cli.ts",
|
|
29
30
|
"build:mcp": "bun build servers/exarchos-mcp/src/index.ts --outfile dist/exarchos-mcp.js --target node --minify",
|
|
30
31
|
"prepare": "tsc",
|
|
31
32
|
"bench": "cd servers/exarchos-mcp && npx vitest bench",
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Build script for the Exarchos CLI bundle.
|
|
4
|
+
*
|
|
5
|
+
* 1. Bundles with --external for playwright-core and electron (large, unused)
|
|
6
|
+
* 2. Creates stub node_modules so the external imports resolve at runtime
|
|
7
|
+
*
|
|
8
|
+
* playwright-core and electron are transitive Azure SDK deps, never used.
|
|
9
|
+
*/
|
|
10
|
+
import { $ } from 'bun';
|
|
11
|
+
import { mkdirSync, writeFileSync } from 'node:fs';
|
|
12
|
+
import { join } from 'node:path';
|
|
13
|
+
|
|
14
|
+
// Step 1: Bundle with externals
|
|
15
|
+
await $`bun build servers/exarchos-mcp/src/cli.ts --outfile dist/exarchos-cli.js --target node --external playwright-core --external electron`;
|
|
16
|
+
|
|
17
|
+
// Step 2: Create stub node_modules for the externals
|
|
18
|
+
const stubs = ['playwright-core', 'electron'];
|
|
19
|
+
const stubDir = join('dist', 'node_modules');
|
|
20
|
+
|
|
21
|
+
for (const pkg of stubs) {
|
|
22
|
+
const dir = join(stubDir, pkg);
|
|
23
|
+
mkdirSync(dir, { recursive: true });
|
|
24
|
+
writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: pkg, version: '0.0.0', main: 'index.js' }));
|
|
25
|
+
writeFileSync(join(dir, 'index.js'), 'module.exports = {};');
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
console.log(' Stubs created for:', stubs.join(', '));
|
|
@@ -73,7 +73,7 @@ This skill manages workflow state for context persistence.
|
|
|
73
73
|
|
|
74
74
|
### On Start (before Phase 1)
|
|
75
75
|
|
|
76
|
-
Initialize workflow state using `
|
|
76
|
+
Initialize workflow state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"` and the featureId.
|
|
77
77
|
|
|
78
78
|
This creates a state file tracked by the MCP server.
|
|
79
79
|
|
package/skills/cleanup/SKILL.md
CHANGED
|
@@ -34,12 +34,12 @@ Activate this skill when:
|
|
|
34
34
|
|
|
35
35
|
Read workflow state to get current phase and metadata:
|
|
36
36
|
```typescript
|
|
37
|
-
|
|
37
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({ action: "get", featureId: "<id>" })
|
|
38
38
|
```
|
|
39
39
|
|
|
40
40
|
If featureId not provided, use pipeline view to list active workflows:
|
|
41
41
|
```typescript
|
|
42
|
-
|
|
42
|
+
mcp__plugin_exarchos_exarchos__exarchos_view({ action: "pipeline" })
|
|
43
43
|
```
|
|
44
44
|
|
|
45
45
|
### 2. Verify Merge Status
|
|
@@ -65,7 +65,7 @@ For detailed verification guidance, see `references/merge-verification.md`.
|
|
|
65
65
|
|
|
66
66
|
Call the MCP cleanup action with collected data:
|
|
67
67
|
```typescript
|
|
68
|
-
|
|
68
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({
|
|
69
69
|
action: "cleanup",
|
|
70
70
|
featureId: "<id>",
|
|
71
71
|
mergeVerified: true,
|
|
@@ -115,7 +115,7 @@ Output summary:
|
|
|
115
115
|
|
|
116
116
|
Use `dryRun: true` to preview what cleanup would do without modifying state:
|
|
117
117
|
```typescript
|
|
118
|
-
|
|
118
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({
|
|
119
119
|
action: "cleanup",
|
|
120
120
|
featureId: "<id>",
|
|
121
121
|
mergeVerified: true,
|
|
@@ -7,15 +7,15 @@ name: troubleshooting
|
|
|
7
7
|
## MCP Tool Call Failed
|
|
8
8
|
If an Exarchos MCP tool returns an error:
|
|
9
9
|
1. Check the error message -- it usually contains specific guidance
|
|
10
|
-
2. Verify the workflow state exists: call `
|
|
10
|
+
2. Verify the workflow state exists: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and the featureId
|
|
11
11
|
3. If "version mismatch": another process updated state -- retry the operation
|
|
12
|
-
4. If state is corrupted: call `
|
|
12
|
+
4. If state is corrupted: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
|
|
13
13
|
|
|
14
14
|
## State Desync
|
|
15
15
|
If workflow state doesn't match git reality:
|
|
16
16
|
1. The SessionStart hook runs reconciliation automatically on resume
|
|
17
17
|
2. If manual check needed: compare state file with `git log` and branch state
|
|
18
|
-
3. Update state via `
|
|
18
|
+
3. Update state via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to match git truth
|
|
19
19
|
|
|
20
20
|
## Investigation Timeout (Hotfix Track)
|
|
21
21
|
If 15-minute investigation timer expires without root cause:
|
|
@@ -25,7 +25,7 @@ If 15-minute investigation timer expires without root cause:
|
|
|
25
25
|
|
|
26
26
|
## Track Switching
|
|
27
27
|
If hotfix track reveals complexity requiring thorough investigation:
|
|
28
|
-
1. Call `
|
|
28
|
+
1. Call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to update track to "thorough"
|
|
29
29
|
2. Previous investigation findings carry over
|
|
30
30
|
3. RCA phase begins after investigation completes
|
|
31
31
|
|
|
@@ -33,12 +33,12 @@ If hotfix track reveals complexity requiring thorough investigation:
|
|
|
33
33
|
|
|
34
34
|
When Exarchos MCP tools are available, emit events throughout the debug workflow:
|
|
35
35
|
|
|
36
|
-
1. **At workflow start (triage):** `
|
|
37
|
-
2. **On track selection:** `
|
|
38
|
-
3. **On each phase transition:** `
|
|
36
|
+
1. **At workflow start (triage):** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `workflow.started` with workflowType "debug", urgency
|
|
37
|
+
2. **On track selection:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` with selected track (hotfix/thorough)
|
|
38
|
+
3. **On each phase transition:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` from->to
|
|
39
39
|
4. **Thorough track stacking:** Handled by `/exarchos:synthesize` (Graphite stack submission)
|
|
40
40
|
5. **Hotfix track commit:** Single `gt create -m "fix: <description>"` -- no multi-branch stacking needed
|
|
41
|
-
6. **On complete:** `
|
|
41
|
+
6. **On complete:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` to "completed"
|
|
42
42
|
|
|
43
43
|
## Performance Notes
|
|
44
44
|
|
|
@@ -16,7 +16,7 @@ Or auto-invoked after review failures.
|
|
|
16
16
|
|
|
17
17
|
## Fix Mode Process
|
|
18
18
|
|
|
19
|
-
1. **Read failure details** from state using `
|
|
19
|
+
1. **Read failure details** from state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"`:
|
|
20
20
|
- Query `reviews` for review failures
|
|
21
21
|
|
|
22
22
|
2. **Extract fix tasks** from failure reports:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Delegation State Management
|
|
2
2
|
|
|
3
|
-
State update patterns for workflow state during delegation. Use `
|
|
3
|
+
State update patterns for workflow state during delegation. Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` for all mutations.
|
|
4
4
|
|
|
5
5
|
## Read Tasks from State
|
|
6
6
|
|
|
@@ -41,7 +41,7 @@ bash scripts/setup-worktree.sh \
|
|
|
41
41
|
|
|
42
42
|
## Worktree State Tracking
|
|
43
43
|
|
|
44
|
-
Track worktrees in the workflow state file using `
|
|
44
|
+
Track worktrees in the workflow state file using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
|
|
45
45
|
- Set `worktrees.<worktree-id>` to an object containing `branch`, `status`, and either `taskId` (single task) or `tasks` (array of task IDs for multi-task worktrees)
|
|
46
46
|
|
|
47
47
|
## Implementer Prompt Requirements
|
|
@@ -27,7 +27,7 @@ Activate this skill when:
|
|
|
27
27
|
|
|
28
28
|
## Revision Mode (--revise flag)
|
|
29
29
|
|
|
30
|
-
When invoked with `--revise`, plan-review found gaps. Read `.planReview.gaps` from state, re-read the design, add tasks to address each gap, update the plan file, then clear gaps via `
|
|
30
|
+
When invoked with `--revise`, plan-review found gaps. Read `.planReview.gaps` from state, re-read the design, add tasks to address each gap, update the plan file, then clear gaps via `mcp__plugin_exarchos_exarchos__exarchos_workflow` `action: "set"`.
|
|
31
31
|
|
|
32
32
|
### Revision Loop Guard
|
|
33
33
|
|
package/skills/refactor/SKILL.md
CHANGED
|
@@ -151,7 +151,7 @@ Full state schema:
|
|
|
151
151
|
|
|
152
152
|
## Track Switching
|
|
153
153
|
|
|
154
|
-
If scope expands beyond polish limits during explore or brief phase, use `
|
|
154
|
+
If scope expands beyond polish limits during explore or brief phase, use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to set `track` to "overhaul" and update `explore.scopeAssessment.recommendedTrack`.
|
|
155
155
|
|
|
156
156
|
**Scope thresholds:** If >5 files affected OR changes cross module boundaries -> recommend overhaul track.
|
|
157
157
|
|
|
@@ -190,7 +190,7 @@ Output: "Scope expanded beyond polish limits. Switching to overhaul track."
|
|
|
190
190
|
|
|
191
191
|
When Exarchos MCP tools are available, emit events throughout the refactor workflow:
|
|
192
192
|
|
|
193
|
-
1. **At workflow start (explore):** `
|
|
193
|
+
1. **At workflow start (explore):** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` → `workflow.started` with workflowType "refactor"
|
|
194
194
|
2. **On track selection:** Auto-emitted by `exarchos_workflow` `set` when `phase` is provided — emits `workflow.transition` with selected track (polish/overhaul)
|
|
195
195
|
3. **On each phase transition:** Auto-emitted by `exarchos_workflow` `set` when `phase` is provided — emits `workflow.transition` with from/to/trigger/featureId
|
|
196
196
|
4. **Overhaul track stacking:** Handled by `/delegate` (subagents use `gt create` per implementer prompt)
|
|
@@ -165,7 +165,7 @@ polish:implement → [scope expands] → overhaul:plan
|
|
|
165
165
|
Auto-chain handles this via MCP tools:
|
|
166
166
|
|
|
167
167
|
```text
|
|
168
|
-
# When scope expands during implement, use
|
|
168
|
+
# When scope expands during implement, use mcp__plugin_exarchos_exarchos__exarchos_workflow with action: "set":
|
|
169
169
|
# 1. First call: Set updates
|
|
170
170
|
updates: { "implement.switchReason": "<reason>", "implement.switchedAt": "<ISO8601>" }
|
|
171
171
|
|
package/skills/shepherd/SKILL.md
CHANGED
|
@@ -44,7 +44,7 @@ Gather the current state of all PRs in the stack. See `references/assess-checkli
|
|
|
44
44
|
|
|
45
45
|
**Read PR URLs from workflow state:**
|
|
46
46
|
```
|
|
47
|
-
|
|
47
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({ action: "get", featureId: "<id>", fields: ["synthesis", "artifacts"] })
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
**For each PR, check four dimensions:**
|
|
@@ -203,7 +203,7 @@ Track shepherd progress in the workflow state under the `shepherd` field.
|
|
|
203
203
|
### Initialize Shepherd
|
|
204
204
|
|
|
205
205
|
```
|
|
206
|
-
|
|
206
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({
|
|
207
207
|
action: "set",
|
|
208
208
|
featureId: "<id>",
|
|
209
209
|
updates: {
|
|
@@ -222,7 +222,7 @@ mcp__exarchos__exarchos_workflow({
|
|
|
222
222
|
|
|
223
223
|
After each assess cycle:
|
|
224
224
|
```
|
|
225
|
-
|
|
225
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({
|
|
226
226
|
action: "set",
|
|
227
227
|
featureId: "<id>",
|
|
228
228
|
updates: {
|
|
@@ -253,7 +253,7 @@ mcp__exarchos__exarchos_workflow({
|
|
|
253
253
|
### Record Approval Request
|
|
254
254
|
|
|
255
255
|
```
|
|
256
|
-
|
|
256
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({
|
|
257
257
|
action: "set",
|
|
258
258
|
featureId: "<id>",
|
|
259
259
|
updates: {
|
|
@@ -293,10 +293,10 @@ mcp__exarchos__exarchos_workflow({
|
|
|
293
293
|
|
|
294
294
|
When Exarchos MCP tools are available:
|
|
295
295
|
|
|
296
|
-
1. **On shepherd start:** `
|
|
297
|
-
2. **On each iteration:** `
|
|
298
|
-
3. **On approval request:** `
|
|
299
|
-
4. **On completion:** `
|
|
296
|
+
1. **On shepherd start:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` — event type `shepherd.started` with PR URLs and iteration count
|
|
297
|
+
2. **On each iteration:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` — event type `shepherd.iteration` with assessment results and actions taken
|
|
298
|
+
3. **On approval request:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` — event type `shepherd.approval_requested` with approver list
|
|
299
|
+
4. **On completion:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` — event type `shepherd.completed` with total iterations and final status
|
|
300
300
|
|
|
301
301
|
## Troubleshooting
|
|
302
302
|
|
|
@@ -6,7 +6,7 @@ Detailed steps for gathering PR status during each shepherd iteration.
|
|
|
6
6
|
|
|
7
7
|
Read PR URLs from workflow state:
|
|
8
8
|
```
|
|
9
|
-
|
|
9
|
+
mcp__plugin_exarchos_exarchos__exarchos_workflow({ action: "get", featureId: "<id>", fields: ["synthesis", "artifacts"] })
|
|
10
10
|
```
|
|
11
11
|
|
|
12
12
|
Extract PR numbers from URLs (e.g., `https://github.com/owner/repo/pull/123` → `123`).
|
|
@@ -65,7 +65,7 @@ See `references/troubleshooting.md` for test failures, PR check failures, and me
|
|
|
65
65
|
|
|
66
66
|
## State Management
|
|
67
67
|
|
|
68
|
-
Call `
|
|
68
|
+
Call `mcp__plugin_exarchos_exarchos__exarchos_workflow` for all state operations. Full parameter reference: `@skills/workflow-state/SKILL.md` § Update State.
|
|
69
69
|
|
|
70
70
|
### Read Task State
|
|
71
71
|
|
|
@@ -77,15 +77,15 @@ If the user receives PR review comments:
|
|
|
77
77
|
## MCP Tool Call Failed
|
|
78
78
|
If an Exarchos MCP tool returns an error:
|
|
79
79
|
1. Check the error message -- it usually contains specific guidance
|
|
80
|
-
2. Verify the workflow state exists: call `
|
|
80
|
+
2. Verify the workflow state exists: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and the featureId
|
|
81
81
|
3. If "version mismatch": another process updated state -- retry the operation
|
|
82
|
-
4. If state is corrupted: call `
|
|
82
|
+
4. If state is corrupted: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
|
|
83
83
|
|
|
84
84
|
## State Desync
|
|
85
85
|
If workflow state doesn't match git reality:
|
|
86
86
|
1. The SessionStart hook runs reconciliation automatically on resume
|
|
87
87
|
2. If manual check needed: compare state file with `git log` and branch state
|
|
88
|
-
3. Update state via `
|
|
88
|
+
3. Update state via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to match git truth
|
|
89
89
|
|
|
90
90
|
## PR Creation Failed
|
|
91
91
|
If `gt submit` fails:
|
|
@@ -104,9 +104,9 @@ If `gt restack` encounters conflicts:
|
|
|
104
104
|
|
|
105
105
|
When Exarchos MCP tools are available:
|
|
106
106
|
|
|
107
|
-
1. **After stack submission:** Call `
|
|
107
|
+
1. **After stack submission:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `stack.enqueued` including PR numbers from `gt log --short`
|
|
108
108
|
2. **Monitor merge status:** Use `mcp__graphite__run_gt_cmd` with `["log", "--short"]` to check stack/PR status
|
|
109
|
-
3. **On successful merge:** Call `
|
|
109
|
+
3. **On successful merge:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `phase.transitioned` to mark workflow complete
|
|
110
110
|
|
|
111
111
|
## Performance Notes
|
|
112
112
|
|
|
@@ -48,7 +48,7 @@ For full MCP tool signatures, error handling, and anti-patterns, see `references
|
|
|
48
48
|
|
|
49
49
|
### Initialize State
|
|
50
50
|
|
|
51
|
-
At the start of `/exarchos:ideate`, use `
|
|
51
|
+
At the start of `/exarchos:ideate`, use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"` with:
|
|
52
52
|
- `featureId`: the workflow identifier (e.g., `"user-authentication"`)
|
|
53
53
|
- `workflowType`: one of `"feature"`, `"debug"`, `"refactor"`
|
|
54
54
|
|
|
@@ -56,7 +56,7 @@ This creates a new state file with phase "ideate".
|
|
|
56
56
|
|
|
57
57
|
### Read State
|
|
58
58
|
|
|
59
|
-
Use `
|
|
59
|
+
Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and `featureId`:
|
|
60
60
|
|
|
61
61
|
- **Full state**: Call with just `featureId`
|
|
62
62
|
- **Specific field**: Add `query` for dot-path lookup (e.g., `query: "phase"`, `query: "tasks"`)
|
|
@@ -66,7 +66,7 @@ Field projection via `fields` returns only the requested top-level keys, reducin
|
|
|
66
66
|
|
|
67
67
|
### Update State
|
|
68
68
|
|
|
69
|
-
Use `
|
|
69
|
+
Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` with `featureId` and either `updates`, `phase`, or both:
|
|
70
70
|
|
|
71
71
|
- **Update phase**: `phase: "delegate"`
|
|
72
72
|
- **Set artifact path**: `updates: { "artifacts.design": "docs/designs/2026-01-05-feature.md" }`
|
|
@@ -78,7 +78,7 @@ Worktree status values: `'active' | 'merged' | 'removed'`
|
|
|
78
78
|
|
|
79
79
|
### Get Summary
|
|
80
80
|
|
|
81
|
-
For context restoration after summarization, use `
|
|
81
|
+
For context restoration after summarization, use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and `featureId`. This outputs a minimal summary suitable for rebuilding orchestrator context.
|
|
82
82
|
|
|
83
83
|
### Reconcile State
|
|
84
84
|
|
|
@@ -168,19 +168,19 @@ Key sections:
|
|
|
168
168
|
### MCP Tool Call Failed
|
|
169
169
|
If an Exarchos MCP tool returns an error:
|
|
170
170
|
1. Check the error message — it usually contains specific guidance
|
|
171
|
-
2. Verify the workflow state exists: call `
|
|
171
|
+
2. Verify the workflow state exists: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and the featureId
|
|
172
172
|
3. If "version mismatch": another process updated state — retry the operation
|
|
173
|
-
4. If state is corrupted: call `
|
|
173
|
+
4. If state is corrupted: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
|
|
174
174
|
|
|
175
175
|
### State Desync
|
|
176
176
|
If workflow state doesn't match git reality:
|
|
177
177
|
1. The SessionStart hook runs reconciliation automatically on resume
|
|
178
178
|
2. If manual check needed: compare state file with `git log` and branch state
|
|
179
|
-
3. Update state via `
|
|
179
|
+
3. Update state via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to match git truth
|
|
180
180
|
|
|
181
181
|
### Checkpoint File Missing
|
|
182
182
|
If the PreCompact hook can't find state to checkpoint:
|
|
183
|
-
1. Verify a workflow is active: call `
|
|
183
|
+
1. Verify a workflow is active: call `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` and the featureId
|
|
184
184
|
2. If no active workflow: the hook will silently skip (expected behavior)
|
|
185
185
|
3. If workflow exists but checkpoint fails: check disk space and permissions
|
|
186
186
|
|
|
@@ -193,18 +193,18 @@ If state references branches or worktrees that no longer exist:
|
|
|
193
193
|
### Multiple Active Workflows
|
|
194
194
|
If multiple workflow state files exist:
|
|
195
195
|
1. The system uses the most recently updated active (non-completed) workflow
|
|
196
|
-
2. Use `
|
|
196
|
+
2. Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true` on stale workflows to preview cleanup
|
|
197
197
|
3. Cancel stale workflows before starting new ones
|
|
198
198
|
|
|
199
199
|
## Example Workflow
|
|
200
200
|
|
|
201
|
-
1. **Start new workflow**: Use `
|
|
201
|
+
1. **Start new workflow**: Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"` with `featureId: "user-authentication"`, `workflowType: "feature"`
|
|
202
202
|
|
|
203
|
-
2. **After design phase**: Use `
|
|
203
|
+
2. **After design phase**: Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` with:
|
|
204
204
|
- `featureId: "user-authentication"`
|
|
205
205
|
- `phase: "plan"`
|
|
206
206
|
- `updates: { "artifacts.design": "docs/designs/2026-01-05-user-auth.md" }`
|
|
207
207
|
|
|
208
|
-
3. **Check state**: Use `
|
|
208
|
+
3. **Check state**: Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` with `featureId: "user-authentication"`
|
|
209
209
|
|
|
210
|
-
4. **Resume after context loss**: Use `
|
|
210
|
+
4. **Resume after context loss**: Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "get"` with `featureId: "user-authentication"` to get context restoration output
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Detailed tool usage, methods, and anti-patterns for all installed MCP servers.
|
|
4
4
|
|
|
5
|
-
## Exarchos (`
|
|
5
|
+
## Exarchos (`mcp__plugin_exarchos_exarchos__*`)
|
|
6
6
|
|
|
7
7
|
Unified MCP server for workflow orchestration, event sourcing, CQRS views, and task coordination. **Always use for workflow tracking.** Exposes 5 composite tools with action discriminators. Note: inter-agent messaging uses Claude Code's native Agent Teams, not Exarchos.
|
|
8
8
|
|
|
@@ -10,11 +10,11 @@ Unified MCP server for workflow orchestration, event sourcing, CQRS views, and t
|
|
|
10
10
|
|
|
11
11
|
| Tool | Actions | When to Use |
|
|
12
12
|
|------|---------|-------------|
|
|
13
|
-
| `
|
|
14
|
-
| `
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
13
|
+
| `mcp__plugin_exarchos_exarchos__exarchos_workflow` | `init`, `get`, `set`, `cancel`, `cleanup` | Workflow CRUD: starting workflows, reading/updating state, cancelling abandoned workflows, resolving merged workflows |
|
|
14
|
+
| `mcp__plugin_exarchos_exarchos__exarchos_event` | `append`, `query` | Event sourcing: recording workflow events, reading event history |
|
|
15
|
+
| `mcp__plugin_exarchos_exarchos__exarchos_orchestrate` | `task_claim`, `task_complete`, `task_fail` | Task coordination and lifecycle |
|
|
16
|
+
| `mcp__plugin_exarchos_exarchos__exarchos_view` | `pipeline`, `tasks`, `workflow_status`, `stack_status`, `stack_place` | CQRS materialized views for read-optimized queries |
|
|
17
|
+
| `mcp__plugin_exarchos_exarchos__exarchos_sync` | `now` | Force sync of materialized views |
|
|
18
18
|
|
|
19
19
|
### Workflow Tool Actions
|
|
20
20
|
|
|
@@ -104,7 +104,7 @@ A compound state's fix cycle limit was reached. Escalate to user or cancel the w
|
|
|
104
104
|
| Don't | Do Instead |
|
|
105
105
|
|-------|------------|
|
|
106
106
|
| Use `gh pr create` or `create_pull_request` | Use Graphite `gt submit --no-interactive --publish --merge-when-ready` for ALL PR creation |
|
|
107
|
-
| Manually edit workflow state JSON | Use `
|
|
107
|
+
| Manually edit workflow state JSON | Use `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` |
|
|
108
108
|
| Use `git commit` or `git push` | Use `gt create` + `gt submit --no-interactive --publish --merge-when-ready` |
|
|
109
109
|
| Skip state reconciliation on resume | The SessionStart hook handles reconciliation automatically |
|
|
110
110
|
|