Dv Workflow

/dv-workflow — Session Workflow Tracker

Turns the current Claude Code session into a tracked workflow skill stored in the user's DeepVista vistabase. The goal is captured as a note, a proper workflow skill is synthesized from it, and node status (including timestamps, error details, and session metrics) is kept in sync automatically via a Stop hook after every turn.

---

Phase 1 — Initialize

Step 1: Check for an existing session

cat ~/.config/deepvista/current-workflow-session.json 2>/dev/null

If the file exists and contains a skill_id, reuse the existing workflow skill — skip to Phase 2. Ask the user:

• Continue from the last active node
• Finalize the current workflow (Phase 3), then start fresh

If no session file exists, continue to Step 2.

Step 2: Capture the goal

If the user typed /dv-workflow , use that text. Otherwise ask: "What should this session accomplish? (One sentence.)"

Step 3: Plan nodes

Break the goal into 3–7 sequential, discrete nodes. Good names are verb phrases: "Understand the codebase", "Implement the feature", "Write tests", "Open PR". Show the plan and confirm with the user before proceeding.

Step 4: Capture the goal as a note

deepvista notes create \
  --title "" \
  --content "Session goal: 

## Planned nodes
1. 
2. 
...
"

Extract the note id as NOTE_ID.

Step 5: Synthesize the workflow skill

deepvista skill create-from-note  --kind workflow --yes

Wait for the final NDJSON event and extract the skill card id as SKILL_ID.

Step 6: Write the initial execution state

Write the tracking body to /tmp/dv-workflow-.md:

**Goal:** 
**Status:** running
**Started:** 

## Nodes

| # | Node | Status | Started | Duration | Output |
|---|------|--------|---------|----------|--------|
| 1 |  | pending |  |  |  |
| 2 |  | pending |  |  |  |
...

## Metrics

- Nodes: 0/ done, 0 failed
- Elapsed: 0m

## Summary

_In progress._

Push it:

deepvista card update  \
  --content-file /tmp/dv-workflow-.md

Step 7: Write the session state file

python3 - `

---

## Phase 2 — Track each node

Maintain the full tracking body in `/tmp/dv-workflow-.md`.
The Stop hook syncs it after every turn — **no explicit `deepvista card update` needed**.

### Node lifecycle

pending → running → done ↘ failed (task could not complete — expected outcome) ↘ error (unexpected tool crash / exception)

### Node table schema

| Column | Content |
|--------|---------|
| `#` | Node index |
| `Node` | Verb-phrase description |
| `Status` | `pending` / `running` / `done` / `failed` / `error` |
| `Started` | UTC time when node went `running` (e.g. `14:32`) |
| `Duration` | Elapsed time when node left `running` (e.g. `3m 12s`) |
| `Output` | One-line result, error message, or artifact name |

### When to update

| Event | Action |
|-------|--------|
| Starting a node | Status → `running`, record `Started` |
| Node completes | Status → `done`, fill `Duration` and `Output` |
| Task cannot be done | Status → `failed`, fill `Output` with reason |
| Tool threw an exception | Status → `error`, fill `Output` with error summary |
| Scope expands | Append new rows with `pending` — do not back-date |

### After each transition — write the updated temp file

```bash
cat > /tmp/dv-workflow-.md 
**Status:** running
**Started:** 

## Nodes

| # | Node | Status | Started | Duration | Output |
|---|------|--------|---------|----------|--------|
| 1 |  | done | 14:30 | 2m |  |
| 2 |  | running | 14:32 |  |  |
...

## Metrics

- Nodes: 1/ done, 0 failed
- Elapsed: 

## Summary

_In progress._
STATE

The Stop hook picks it up at end-of-turn.

Error capture

If a Bash command or tool fails unexpectedly, capture the details immediately:

# Update the current node to error status
# Replace | 2 |  | running | ... |
# with    | 2 |  | error   | 14:32 | 0m 5s |  |

Record a brief error summary in Output (tool name, exit code, first line of stderr). Then decide: retry the node, mark it failed and continue, or stop the session.

---

Phase 3 — Finalize

When the session goal is achieved or the user ends the session:

Step 1: Write the final state

• Set **Status:** to done (or failed / error)
• Fill all remaining Duration values
• Update ## Metrics with final counts and total elapsed time
• Write a 2–4 sentence ## Summary:
• What was accomplished
• Key outputs or artifacts
• Any remaining items or known issues

Write to /tmp/dv-workflow-.md (the Stop hook will sync it), or push immediately:

deepvista card update  \
  --content-file /tmp/dv-workflow-.md

Step 2: Clean up

rm -f ~/.config/deepvista/current-workflow-session.json
rm -f /tmp/dv-workflow-*.md

Show: https://app.deepvista.ai/vistabase/

---

Stop hook — auto-sync after every turn

Reads the session file, updates last_active, and pushes the temp file to the skill card. Install once via deepvista agents register --type claude-code.

To add manually under hooks.Stop in ~/.claude/settings.json:

{
  "type": "command",
  "command": "python3 -c \"import json,pathlib,subprocess,datetime,sys; p=pathlib.Path.home()/'.config/deepvista/current-workflow-session.json'; d=json.loads(p.read_text()) if p.exists() else None; d and [p.write_text(json.dumps({**d,'last_active':datetime.datetime.now(datetime.timezone.utc).isoformat()},indent=2)),pathlib.Path(f\\\"/tmp/dv-workflow-{d.get('skill_id','')}.md\\\").exists() and subprocess.run(['deepvista','card','update',d.get('skill_id',''),'--content-file',f\\\"/tmp/dv-workflow-{d.get('skill_id','')}.md\\\"],capture_output=True)]\" 2>/dev/null || true"
}

The hook exits silently when no session is active.

---

Optional: PostToolUse error-capture hook

To automatically flag Bash failures into the session file, add under hooks.PostToolUse:

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "python3 -c \"\nimport json,pathlib,sys,datetime\ndata=json.load(sys.stdin)\nif data.get('tool_response',{}).get('exit_code',0)==0: sys.exit(0)\np=pathlib.Path.home()/'.config/deepvista/current-workflow-session.json'\nif not p.exists(): sys.exit(0)\nd=json.loads(p.read_text())\nd['last_error']={'cmd':data.get('tool_input',{}).get('command','')[:120],'exit_code':data['tool_response'].get('exit_code'),'at':datetime.datetime.now(datetime.timezone.utc).isoformat()}\np.write_text(json.dumps(d,indent=2))\n\" 2>/dev/null || true"
    }
  ]
}

This writes last_error to the session file whenever a Bash command exits non-zero. The agent can read it on the next turn to fill the node's Output field accurately.

---

Conventions

| Rule | Detail | |------|--------| | Reuse within session | If session file has skill_id, skip creation and continue. | | Workflow skill, not a raw card | Use deepvista skill create-from-note — produces type=skill. | | Temp file is source of truth | Write all state to /tmp/dv-workflow-.md; Stop hook syncs it. | | Timestamps on every node | Record Started when going running; Duration when leaving it. | | Errors are first-class | error ≠ failed: error means the tool broke, failed means the task couldn't be done. | | Metrics stay current | Update the ## Metrics block on every state change. | | Confirm before creating | Show node plan and get approval before deepvista skill create-from-note. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DeepVista-AI
• Source: DeepVista-AI/deepvista-cli
• License: Apache-2.0
• Homepage: https://www.deepvista.ai/

Install and usage instructions live in the source repository linked above.