Workflow Rehydrate Skill

Overview

Restore full workflow awareness that survives context auto-summarization without starting a new session.

This skill owns the read/restore side of workflow state — reading current state, reconciling it against git reality, and verifying whether a workflow exists at all. For the write side (init, update, transition, capturing a handoff), see

@skills/checkpoint/SKILL.md

Triggers

Activate this skill when:

Restoring context after summarization (
```
rehydrate <featureId>
```
)
The agent has drifted after context compaction (stopped emitting events or using tools proactively)
Returning to a workflow after a break

State Location

Workflow state lives in the MCP event store, not the filesystem. Use

exarchos:exarchos_workflow get

to read state and

exarchos_view pipeline

to discover active workflows. Do not scan

~/.claude/workflow-state/*.state.json

— that path is legacy and may be stale or empty.

Source of Truth — does this workflow exist?

Workflow state lives in two surfaces, and conflating them causes wrong "untracked" conclusions:

The SQLite event store (
```
events
```
+ projected
```
workflow_state
```
+
```
streams
```
) — the authoritative record of whether a workflow exists. This is what
```
rehydrate
```
/
```
get
```
read.
<featureId>.state.json
files (under the state dir) — a secondary "planner's stamp" that carries plan-state facts the event projection cannot derive (review status, declared task list, dimension findings). It may be absent for a tracked workflow (CLI tools, tests, in-flight workflows before the first
```
update
```
) and is not an existence signal.

Canonical existence check: use the rehydrate envelope's _meta.workflowExists
(

true

false

), or equivalently a non-empty

data.workflowState.featureId

. A cold probe of a never-

init

'd featureId returns

success: true

with an empty initial document and

_meta.workflowExists: false

— and is side-effect-free (it emits no

workflow.rehydrated

event). Never infer existence from the presence or absence of a
.state.json
file on disk.

Rehydrate the Workflow

Use

exarchos:exarchos_workflow

with

action: "rehydrate"

and

featureId: "<id>"

— it returns an envelope containing the canonical rehydration document (

workflowState

taskProgress

artifacts

blockers

, phase playbook, next actions) in a single call. No multi-step

get fields=[...]

composition is needed.

If the featureId is unknown or the user hasn't named one, fall back to

exarchos_view pipeline

to list active workflows and ask which to rehydrate, then re-invoke

rehydrate

with the selected

featureId

. The pipeline view is repo-scoped by default — it lists only the caller's repo, so a workflow started in another repo won't appear. Every response reports

unscopedTotal

(the pre-scope count); when

unscopedTotal

exceeds

page.total

, the hidden rows live in other repos (or are legacy rows without recorded identity) — re-query with

scope: "all"

(or an explicit

repoRoot

) to reveal them.

Read State (targeted)

For a targeted read rather than a full rehydration, use

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.

Get Summary

For context restoration after summarization, prefer

action: "rehydrate"

(single-call, includes the phase playbook and next actions). For a minimal read,

action: "get"

with

featureId

outputs a summary suitable for rebuilding orchestrator context.

Output Format

Render the returned document as compact behavioral context (the same shape as post-compaction context) so the agent refreshes its awareness in one pass:

markdown

## Workflow Rehydrated: <featureId>
**Phase:** <phase> | **Type:** <workflowType>

### House Rules (apply every action this turn forward)
**Skill:** <phasePlaybook.skillRef or "(no playbook for this phase)">
**Tools:** <phasePlaybook.tools rendered as bullets>
**Required model-emitted events:** <phasePlaybook.events rendered as bullets — e.g. `task.progressed`, `phase.advanced`>
**Auto-emitted events (runtime fires these):** <phasePlaybook.autoEmittedEvents rendered as bullets>
**Transition:** <phasePlaybook.transitionCriteria> | Guard: <phasePlaybook.guardPrerequisites>
**Validation scripts:** <phasePlaybook.validationScripts joined>

### Event Emission Hints
<_eventHints.missing rendered as bullets, or "(none — phase machinery satisfied)">

### Task Progress
<task table>

### Artifacts
- Design: <path or "not created">
- Plan: <path or "not created">
- PR: <url or "not created">

### Next Action
<suggested action, from the envelope's `next_actions`>

> **Discipline reminder:** every task transition this turn forward MUST land on the workflow event stream via `exarchos_event.append` or `delegate` subagent emission. Direct `Edit` / `Bash` / `git` actions on task branches without corresponding events will desync the workflow tracker (see RCA `docs/rca/2026-05-08-rehydrate-behavioral-gap.md`).

Keep the output minimal — only essential state and behavioral guidance; full details stay in files, not the conversation.

Reconcile State

To verify state matches git reality, run

rehydrate <featureId>

— the rehydration projection folds events newer than the last snapshot and surfaces drift in the returned envelope. For deeper manual verification, run the reconciliation script:

typescript

exarchos_orchestrate({
  action: "reconcile_state",
  stateFile: "<state-file>",
  repoRoot: "<repo-root>"
})

On
passed: true
: State is consistent. On
passed: false
: Discrepancies found — review output and resolve via

exarchos:exarchos_workflow

with

action: "update"

(see

@skills/checkpoint/SKILL.md

Best Practices

Reconcile on resume - Always verify state matches git state before acting
Read state, don't remember - After summarization, read from the event store, not memory
Single-call fetch - One
```
rehydrate
```
call returns the full canonical document; avoid multi-step reads
Existence via
_meta.workflowExists
- Never infer existence from a
```
.state.json
```
file on disk

Troubleshooting

State Desync

If workflow state doesn't match git reality:

Run
```
rehydrate <featureId>
```
— the rehydration projection folds in events newer than the last snapshot
If manual check still needed: compare the rehydration document's
```
workflowState
```
/
```
artifacts
```
with
```
git log
```
and branch state

Update state via

exarchos:exarchos_workflow

with

action: "update"

to match git truth (see

@skills/checkpoint/SKILL.md

)

Resume Finds Stale State

If state references branches or worktrees that no longer exist:

Run
```
rehydrate <featureId>
```
— the rehydration document surfaces stale references
Compare against
```
git branch -a
```
/
```
git worktree list
```
to identify drift
Update via
```
exarchos_workflow update
```
to match git truth

Multiple Active Workflows

If multiple workflow state files exist:

The system uses the most recently updated active (non-completed) workflow

Use

exarchos:exarchos_workflow

with

action: "cancel"

and

dryRun: true

on stale workflows to preview cleanup

Cancel stale workflows before starting new ones

Example Workflow

Resume after context loss: Use

exarchos:exarchos_workflow

with

action: "rehydrate"

and

featureId: "user-authentication"

to get context restoration output.

Check state: Use

exarchos:exarchos_workflow

with

action: "get"

and

featureId: "user-authentication"

Verify existence: Read
```
_meta.workflowExists
```
from the rehydrate envelope — if
```
false
```
, the feature was never started as a workflow, so report that rather than declaring it "untracked" from a filesystem check.

rehydrate

NPX Install

Tags

SKILL.md Content

Workflow Rehydrate Skill

Overview

Triggers

State Location

Source of Truth — does this workflow exist?

Rehydrate the Workflow

Read State (targeted)

Get Summary

Output Format

Reconcile State

Best Practices

Troubleshooting

State Desync

Resume Finds Stale State

Multiple Active Workflows

Example Workflow