@lvlup-sw/exarchos 2.0.1

package/skills/workflow-state/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: workflow-state
+description: "Checkpoint and resume workflow state for context persistence across sessions. Use when the user says 'save progress', 'checkpoint', 'I need to stop', or runs /checkpoint or /resume. Saves current workflow phase, task progress, and artifacts for later resumption. Do NOT use for workflow initialization (handled by ideate/debug/refactor commands)."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: utility
+  phase-affinity:
+    - ideate
+    - plan
+    - delegate
+    - review
+    - synthesize
+---
+
+# Workflow State Management Skill
+
+## Overview
+
+Manage persistent workflow state that survives context auto-summarization.
+
+State files store: task details, worktree locations, PR URLs, and review status.
+
+## Triggers
+
+Activate this skill when:
+- Starting a new workflow (`/exarchos:ideate`)
+- Transitioning between workflow phases
+- Restoring context after summarization (`/exarchos:resume`)
+- Saving progress for later continuation (`/exarchos:checkpoint`)
+
+## Phase Transitions
+
+Valid transitions, guards, and prerequisites for all workflow types are documented in `references/phase-transitions.md`. **CRITICAL:** When a transition has a guard, send the prerequisite `updates` and `phase` in a single `set` call — updates apply before guards evaluate.
+
+## State File Location
+
+```
+~/.claude/workflow-state/<feature-id>.state.json
+```
+
+State files are gitignored - they persist locally but are not committed.
+
+## State Operations
+
+For full MCP tool signatures, error handling, and anti-patterns, see `references/mcp-tool-reference.md`.
+
+### Initialize State
+
+At the start of `/exarchos:ideate`, use `mcp__exarchos__exarchos_workflow` with `action: "init"` with:
+- `featureId`: the workflow identifier (e.g., `"user-authentication"`)
+- `workflowType`: one of `"feature"`, `"debug"`, `"refactor"`
+
+This creates a new state file with phase "ideate".
+
+### Read State
+
+Use `mcp__exarchos__exarchos_workflow` with `action: "get"` and `featureId`:
+
+- **Full state**: Call with just `featureId`
+- **Specific field**: Add `query` for dot-path lookup (e.g., `query: "phase"`, `query: "tasks"`)
+- **Multiple fields**: Add `fields` array for projection (e.g., `fields: ["phase", "featureId", "tasks"]`)
+
+Field projection via `fields` returns only the requested top-level keys, reducing token cost.
+
+### Update State
+
+Use `mcp__exarchos__exarchos_workflow` with `action: "set"` with `featureId` and either `updates`, `phase`, or both:
+
+- **Update phase**: `phase: "delegate"`
+- **Set artifact path**: `updates: { "artifacts.design": "docs/designs/2026-01-05-feature.md" }`
+- **Mark task complete**: `updates: { "tasks[id=001].status": "complete", "tasks[id=001].completedAt": "<timestamp>" }`
+- **Add worktree**: `updates: { "worktrees.wt-001": { "branch": "feature/001-types", "taskId": "001", "status": "active" } }`
+- **Phase + updates together**: `phase: "delegate"`, `updates: { "artifacts.plan": "docs/plans/plan.md" }`
+
+Worktree status values: `'active' | 'merged' | 'removed'`
+
+### Get Summary
+
+For context restoration after summarization, use `mcp__exarchos__exarchos_workflow` with `action: "get"` and `featureId`. This outputs a minimal summary suitable for rebuilding orchestrator context.
+
+### Reconcile State
+
+To verify state matches git reality, the SessionStart hook automatically reconciles on resume. For manual verification, run the reconciliation script:
+
+```bash
+scripts/reconcile-state.sh --state-file <state-file> --repo-root <repo-root>
+```
+
+**On exit 0:** State is consistent.
+**On exit 1:** Discrepancies found — review output and resolve.
+
+## Integration Points
+
+### When to Update State
+
+| Event | State Update |
+|-------|--------------|
+| `/exarchos:ideate` starts | Create state file |
+| Design saved | Set `artifacts.design`, phase = "plan" |
+| Plan saved | Set `artifacts.plan`, populate tasks, phase = "plan-review" |
+| Plan-review gaps found | Set `planReview.gaps`, auto-loop to plan |
+| Plan-review approved | Set `planReview.approved = true`, phase = "delegate" |
+| Task dispatched | Set task `status = "in_progress"`, `startedAt` |
+| Task complete | Set task `status = "complete"`, `completedAt` |
+| Worktree created | Add to `worktrees` object |
+| Review complete | Update `reviews` object |
+| PR created | Set `artifacts.pr`, `synthesis.prUrl` |
+| PR feedback | Append to `synthesis.prFeedback` |
+
+### Automatic State Updates
+
+Skills should update state at key moments:
+
+**brainstorming/SKILL.md:**
+```markdown
+After saving design:
+1. Update state: `.artifacts.design = "<path>"`
+2. Update state: `.phase = "plan"`
+```
+
+**implementation-planning/SKILL.md:**
+```markdown
+After saving plan:
+1. Update state: `.artifacts.plan = "<path>"`
+2. Populate `.tasks` from plan
+3. Update state: `.phase = "delegate"`
+```
+
+**delegation/SKILL.md:**
+```markdown
+On task dispatch:
+- Update task status to "in_progress"
+- Add worktree to state if created
+
+On task complete:
+- Update task status to "complete"
+- Check if all tasks done, suggest checkpoint
+```
+
+## State Schema
+
+See `docs/schemas/workflow-state.schema.json` for full schema.
+
+Key sections:
+- `version`: Schema version (currently "1.1")
+- `featureId`: Unique workflow identifier
+- `workflowType`: Required. One of "feature", "debug", or "refactor"
+- `phase`: Current workflow phase
+- `artifacts`: Paths to design, plan, PR
+- `tasks`: Task list with status
+- `worktrees`: Active git worktrees
+- `planReview`: Plan-review delta analysis results (`gaps`, `approved`)
+- `reviews`: Review results
+- `synthesis`: Merge/PR state
+
+## Best Practices
+
+1. **Update often** - State should reflect reality at all times
+2. **Use MCP tools** - Prefer workflow-state MCP tools over manual JSON editing
+3. **Reconcile on resume** - Always verify state matches git state
+4. **Checkpoint at boundaries** - Save state before likely context exhaustion
+5. **Read state, don't remember** - After summarization, read from state file
+
+## Troubleshooting
+
+### MCP Tool Call Failed
+If an Exarchos MCP tool returns an error:
+1. Check the error message — it usually contains specific guidance
+2. Verify the workflow state exists: call `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId
+3. If "version mismatch": another process updated state — retry the operation
+4. If state is corrupted: call `mcp__exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
+
+### State Desync
+If workflow state doesn't match git reality:
+1. The SessionStart hook runs reconciliation automatically on resume
+2. If manual check needed: compare state file with `git log` and branch state
+3. Update state via `mcp__exarchos__exarchos_workflow` with `action: "set"` to match git truth
+
+### Checkpoint File Missing
+If the PreCompact hook can't find state to checkpoint:
+1. Verify a workflow is active: call `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId
+2. If no active workflow: the hook will silently skip (expected behavior)
+3. If workflow exists but checkpoint fails: check disk space and permissions
+
+### Resume Finds Stale State
+If state references branches or worktrees that no longer exist:
+1. The SessionStart hook handles reconciliation automatically
+2. It updates state to reflect current git reality
+3. Missing branches are flagged in the session-start output
+
+### Multiple Active Workflows
+If multiple workflow state files exist:
+1. The system uses the most recently updated active (non-completed) workflow
+2. Use `mcp__exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true` on stale workflows to preview cleanup
+3. Cancel stale workflows before starting new ones
+
+## Example Workflow
+
+1. **Start new workflow**: Use `mcp__exarchos__exarchos_workflow` with `action: "init"` with `featureId: "user-authentication"`, `workflowType: "feature"`
+
+2. **After design phase**: Use `mcp__exarchos__exarchos_workflow` with `action: "set"` with:
+   - `featureId: "user-authentication"`
+   - `phase: "plan"`
+   - `updates: { "artifacts.design": "docs/designs/2026-01-05-user-auth.md" }`
+
+3. **Check state**: Use `mcp__exarchos__exarchos_workflow` with `action: "get"` with `featureId: "user-authentication"`
+
+4. **Resume after context loss**: Use `mcp__exarchos__exarchos_workflow` with `action: "get"` with `featureId: "user-authentication"` to get context restoration output

package/skills/workflow-state/references/mcp-tool-reference.md

@@ -0,0 +1,111 @@
+# MCP Tool Reference
+
+Detailed tool usage, methods, and anti-patterns for all installed MCP servers.
+
+## Exarchos (`mcp__exarchos__*`)
+
+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.
+
+### Composite Tools
+
+| Tool | Actions | When to Use |
+|------|---------|-------------|
+| `mcp__exarchos__exarchos_workflow` | `init`, `get`, `set`, `cancel`, `cleanup` | Workflow CRUD: starting workflows, reading/updating state, cancelling abandoned workflows, resolving merged workflows |
+| `mcp__exarchos__exarchos_event` | `append`, `query` | Event sourcing: recording workflow events, reading event history |
+| `mcp__exarchos__exarchos_orchestrate` | `task_claim`, `task_complete`, `task_fail` | Task coordination and lifecycle |
+| `mcp__exarchos__exarchos_view` | `pipeline`, `tasks`, `workflow_status`, `stack_status`, `stack_place` | CQRS materialized views for read-optimized queries |
+| `mcp__exarchos__exarchos_sync` | `now` | Force sync of materialized views |
+
+### Workflow Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `init` | Starting any `/exarchos:ideate`, `/exarchos:debug`, or `/exarchos:refactor` workflow |
+| `get` | Restoring context, checking phase, reading task details. Use `query` for dot-path lookup (e.g., `query: "phase"`), or `fields` array for projection (e.g., `fields: ["phase", "tasks"]`) to reduce token cost |
+| `set` | Updating phase (`phase: "delegate"`), recording artifacts, marking tasks complete. Use `updates` for field changes and `phase` for transitions |
+| `cancel` | Cleaning up abandoned workflows. Supports `dryRun: true` to preview cleanup actions |
+| `cleanup` | Resolve a merged workflow to completed. Verifies merge, backfills synthesis metadata, force-resolves reviews, transitions to completed. Requires `mergeVerified: true` — pass after verifying PRs are merged via GitHub API |
+
+**Hooks (automatic, no tool call needed):**
+- **SessionStart hook** — Discovers active workflows, restores context, determines next action, and verifies state on resume (replaces former `workflow_list`, `workflow_summary`, `workflow_next_action`, `workflow_reconcile` tools)
+- **PreCompact hook** — Saves checkpoints before context exhaustion (replaces former `workflow_checkpoint` tool)
+- Valid phase transitions are documented in `references/phase-transitions.md` (replaces former `workflow_transitions` tool). `INVALID_TRANSITION` errors include valid targets with guard descriptions.
+
+### Event Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `append` | Recording workflow events (task.assigned, gate.executed, etc.). Use `expectedSequence` for optimistic concurrency |
+| `query` | Reading event history. Use `filter` for type/time filtering, `limit`/`offset` for pagination |
+
+### Orchestrate Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `task_claim` | Claim a task for execution. Returns `ALREADY_CLAIMED` if previously claimed — handle gracefully |
+| `task_complete` | Mark a task complete with optional `result` (artifacts, duration) |
+| `task_fail` | Mark a task failed with `error` message and optional `diagnostics` |
+
+### View Tool Actions
+
+| Action | When to Use |
+|--------|-------------|
+| `pipeline` | Aggregated view of all workflows with stack positions. Use `limit`/`offset` for pagination |
+| `tasks` | Task detail view with filtering and projection. Use `workflowId` to scope, `filter` for property matching, `fields` for projection (e.g., `fields: ["taskId", "status", "title"]`), `limit`/`offset` for pagination |
+| `workflow_status` | Workflow phase, task counts, and metadata. Use `workflowId` to scope |
+| `stack_status` | Get current stack positions from events. Use `streamId` to scope |
+| `stack_place` | Record a stack position with `position`, `taskId`, `branch`, optional `prUrl` |
+
+## GitHub (`mcp__plugin_github_github__*`)
+> Available with exarchos-dev-tools companion. Fallback: use `gh` CLI.
+
+## Serena (`mcp__plugin_serena_serena__*`)
+> Available with exarchos-dev-tools companion. Fallback: use Grep/Read/Glob.
+
+## Context7 (`mcp__plugin_context7_context7__*`)
+> Available with exarchos-dev-tools companion. Fallback: use WebSearch.
+
+## Graphite (`mcp__graphite__*`)
+
+Stacked PR management and merge queue. **Use for all PR stacking and submission.**
+
+| Tool | When to Use |
+|------|-------------|
+| `run_gt_cmd` | Execute any `gt` command: `create`, `submit`, `modify`, `restack`, `sync`, `checkout` |
+| `learn_gt` | Learn Graphite stacking workflow and available commands |
+
+### Key commands via `run_gt_cmd`
+
+| Instead of | Use |
+|------------|-----|
+| `git commit` + `git push` | `gt create -m "message"` then `gt submit --no-interactive --publish --merge-when-ready` |
+| `gh pr create` | `gt submit --no-interactive --publish --merge-when-ready` (creates stacked PRs automatically) |
+| Manual rebasing | `gt restack` (rebases all PRs in the stack) |
+| `git checkout <branch>` | `gt checkout` (interactive branch selection) |
+
+**Proactive use:** When the workflow involves stacked PRs or progressive merging (e.g., `/exarchos:delegate` with multiple tasks), use `mcp__graphite__run_gt_cmd` for stack management rather than raw git commands or `gh pr create`.
+
+## Microsoft Learn (`mcp__microsoft-learn__*`)
+> Available with exarchos-dev-tools companion. Fallback: use WebSearch.
+
+## Workflow Transition Errors
+
+### INVALID_TRANSITION
+No path exists from current phase to target. Check `validTargets` in the error — it lists reachable phases with guard descriptions. You may need to step through intermediate phases.
+
+### GUARD_FAILED
+The transition exists but the guard condition is unmet. Send prerequisite `updates` and `phase` in a **single** `set` call — updates apply before guards evaluate. See `references/phase-transitions.md` for guard prerequisites.
+
+### CIRCUIT_OPEN
+A compound state's fix cycle limit was reached. Escalate to user or cancel the workflow.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Use `gh pr create` or `create_pull_request` | Use Graphite `gt submit --no-interactive --publish --merge-when-ready` for ALL PR creation |
+| Manually edit workflow state JSON | Use `mcp__exarchos__exarchos_workflow` with `action: "set"` |
+| Use `git commit` or `git push` | Use `gt create` + `gt submit --no-interactive --publish --merge-when-ready` |
+| Skip state reconciliation on resume | The SessionStart hook handles reconciliation automatically |
+
+> See companion reference for additional tool anti-patterns (Serena, GitHub MCP, Context7).

package/skills/workflow-state/references/phase-transitions.md

@@ -0,0 +1,141 @@
+# Phase Transitions Reference
+
+All valid HSM phase transitions for each workflow type. Every transition listed here is the **only** way to move between phases — the HSM rejects unlisted transitions with `INVALID_TRANSITION`.
+
+## Combined Updates + Phase Pattern
+
+**CRITICAL:** When a transition has a guard that requires prerequisite state, send `updates` and `phase` in a single `set` call. Updates are applied BEFORE guards evaluate:
+
+```
+action: "set"
+featureId: "my-feature"
+phase: "delegate"
+updates: { "planReview.approved": true }
+```
+
+This satisfies the `planReviewComplete` guard in one call. Two separate calls (set data, then transition) also work but waste a tool call.
+
+## Universal Transitions
+
+Available from **any non-final** phase in all workflow types:
+
+| To | Guard | How to Trigger |
+|----|-------|----------------|
+| `cancelled` | None | `exarchos_workflow cancel` (not `set`) — runs saga compensation |
+| `completed` | `merge-verified` | `exarchos_workflow cleanup` with `mergeVerified: true` — for post-merge resolution |
+
+## Feature Workflow
+
+```
+ideate → plan → plan-review → delegate ⇄ review → synthesize → completed
+                     ↓
+                    plan (gaps found)
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `ideate` | `plan` | `design-artifact-exists` | Set `artifacts.design` |
+| `plan` | `plan-review` | `plan-artifact-exists` | Set `artifacts.plan` |
+| `plan-review` | `delegate` | `plan-review-complete` | Set `planReview.approved = true` |
+| `plan-review` | `plan` | `plan-review-gaps-found` | Set `planReview.gapsFound = true` |
+| `delegate` | `review` | `all-tasks-complete` | All `tasks[].status = "complete"` |
+| `review` | `synthesize` | `all-reviews-passed` | All `reviews.{name}.status` in `["pass", "passed", "approved"]` |
+| `review` | `delegate` | `any-review-failed` | Any `reviews.{name}.status` in `["fail", "failed", "needs_fixes"]` (fix cycle) |
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+| `blocked` | `delegate` | `human-unblocked` | Set `unblocked = true` |
+
+**Compound state:** `implementation` contains `delegate` and `review`. Max 3 fix cycles before circuit breaker opens.
+
+## Debug Workflow
+
+```
+triage → investigate → [hotfix-track | thorough-track] → synthesize → completed
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `triage` | `investigate` | `triage-complete` | Set `triage.symptom` |
+| `investigate` | `rca` | `thorough-track-selected` | Set `track = "thorough"` |
+| `investigate` | `hotfix-implement` | `hotfix-track-selected` | Set `track = "hotfix"` |
+
+### Thorough Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `rca` | `design` | `rca-document-complete` | Set `artifacts.rca` |
+| `design` | `debug-implement` | `fix-design-complete` | Set `artifacts.fixDesign` |
+| `debug-implement` | `debug-validate` | `implementation-complete` | Always passes |
+| `debug-validate` | `debug-review` | `validation-passed` | Set `validation.testsPass = true` |
+| `debug-review` | `synthesize` | `review-passed` | All `reviews.{name}.status` passing |
+
+**Compound state:** `thorough-track` contains `rca` through `debug-review`. Max 2 fix cycles.
+
+### Hotfix Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `hotfix-implement` | `hotfix-validate` | `implementation-complete` | Always passes |
+| `hotfix-validate` | `completed` | `validation-passed` | Set `validation.testsPass = true` |
+
+### Shared
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+
+## Refactor Workflow
+
+```
+explore → brief → [polish-track | overhaul-track] → completed
+```
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `explore` | `brief` | `scope-assessment-complete` | Set `explore.scopeAssessment` |
+| `brief` | `polish-implement` | `polish-track-selected` | Set `track = "polish"` |
+| `brief` | `overhaul-plan` | `overhaul-track-selected` | Set `track = "overhaul"` |
+
+### Polish Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `polish-implement` | `polish-validate` | `implementation-complete` | Always passes |
+| `polish-validate` | `polish-update-docs` | `goals-verified` | Set `validation.testsPass = true` |
+| `polish-update-docs` | `completed` | `docs-updated` | Set `validation.docsUpdated = true` |
+
+### Overhaul Track
+
+| From | To | Guard | Prerequisite |
+|------|----|-------|-------------|
+| `overhaul-plan` | `overhaul-delegate` | `plan-artifact-exists` | Set `artifacts.plan` |
+| `overhaul-delegate` | `overhaul-review` | `all-tasks-complete` | All `tasks[].status = "complete"` |
+| `overhaul-review` | `overhaul-update-docs` | `all-reviews-passed` | All `reviews.{name}.status` passing |
+| `overhaul-review` | `overhaul-delegate` | `any-review-failed` | Any `reviews.{name}.status` failing (fix cycle) |
+| `overhaul-update-docs` | `synthesize` | `docs-updated` | Set `validation.docsUpdated = true` |
+| `synthesize` | `completed` | `pr-url-exists` | Set `synthesis.prUrl` or `artifacts.pr` |
+
+**Compound state:** `overhaul-track` contains `overhaul-plan` through `overhaul-review`. Max 3 fix cycles.
+
+## Troubleshooting
+
+### INVALID_TRANSITION Error
+
+The HSM rejected the transition because no path exists from the current phase to the target.
+
+1. Check `validTargets` in the error response — it lists all reachable phases with their guards
+2. You may need to step through intermediate phases (no phase skipping)
+
+### GUARD_FAILED Error
+
+The transition exists but the guard condition is not met.
+
+1. Check `guardDescription` in the error response for what's required
+2. Set the prerequisite state via `updates` in the same `set` call as the `phase`
+3. Refer to the "Prerequisite" column in the tables above
+
+### CIRCUIT_OPEN Error
+
+A compound state's fix cycle limit has been reached (e.g., review → delegate looped too many times).
+
+1. The workflow is stuck — escalate to the user
+2. Consider cancelling and restarting with a different approach