dsh-workstate

Readme

# dsh-workstate

**A structured work-state protocol for handing off AI coding tasks between agents.**

`dsh-workstate` is a local-first plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). It captures what an agent is doing now: task state, progress, decisions, failures, verification, changed paths, next actions, and a Git integrity fingerprint. It is not a conversation dump.

[中文文档](./README.zh.md)

## Why

Normal handoffs preserve prose. Workstate preserves a machine-readable state packet and checks that the workspace still matches before another agent resumes it.

- `checkpoint`: pause and preserve current work.
- `transfer`: create a shareable export for another agent or developer.
- `resume`: validate and inject an existing packet; never changes Git state.
- `diff`: compare two checkpoints by stable work-item IDs.

## Install

Requires Node.js 22.19+ and DeepSeek Harness `0.1.0-rc.6`.

```bash
dsh plugin --profile web add dsh-workstate
```

Add this insert to `~/.dsh/profiles/web/cordis.patch.yml`, preserving existing rows:

```yaml
- insert:
    - id: workstate
      name: dsh-workstate
```

Restart DSH. For a temporary source checkout, point an equivalent patch at the locally installed package.

## Commands

```text
/workstate checkpoint [note]
/workstate transfer [target]
/workstate list
/workstate inspect [id]
/workstate diff <from> <to>
/workstate validate [id]
/workstate resume [id]
/workstate resume [id] --allow-diverged
```

The model also receives `workstate_capture`, `workstate_list`, `workstate_read`, `workstate_diff`, `workstate_validate`, and `workstate_resume` tools.

## Storage and safety

Packets use `dsh.workstate/v1alpha1` and live under `.dsh/workstate/`. Checkpoint history is local and gitignored. Only `transfer` exports are intentionally trackable. Packets contain paths and hashes, never file contents or diffs. Known credential patterns are rejected before persistence.

Resume validation compares Git branch, commit, dirty state and a content fingerprint. Divergence fails closed. The plugin never checks out, resets, stashes, stages, commits, or pushes.

## Development

```bash
npm install
npm run check
```

## License

MIT