Skip to content

DeepVista-AI/deepvista-cli / skills/dv-workflow

dv-workflow

Verified

Create and track a DeepVista workflow skill for the current Claude Code session. On first invocation, captures the session goal as a note and synthesizes a workflow skill via deepvista skill create-from-note. Subsequent invocations in the same session reuse the existing skill. A Stop hook auto-syncs node status, timestamps, error details, and session metrics to the skill card after every turn.

/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 <goal>, 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

[!NOTE] This one stays type=note on purpose (DV-1911). The user confirmed the plan in step 3, so it is human-initiated, and skill create-from-note emits a cardType="note" chip for its source card — see _build_create_from_note_instruction in deepvista_cli/commands/skill.py. Machine-generated workflow output uses card create --type artifact instead.

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

## Planned nodes
1. <node 1>
2. <node 2>
...
"

Extract the note id as NOTE_ID.

Step 5: Synthesize the workflow skill

deepvista skill create-from-note <NOTE_ID> --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-<SKILL_ID>.md:

**Goal:** <goal>
**Status:** running
**Started:** <UTC ISO timestamp>

## Nodes

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

## Metrics

- Nodes: 0/<total> done, 0 failed
- Elapsed: 0m

## Summary

_In progress._

Push it:

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

Step 7: Write the session state file

python3 - << 'PY'
import json, pathlib, datetime
p = pathlib.Path.home() / ".config/deepvista/current-workflow-session.json"
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text(json.dumps({
  "skill_id": "SKILL_ID",
  "note_id": "NOTE_ID",
  "goal": "GOAL",
  "started_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
  "current_node": 1,
  "error": None,
}, indent=2))
PY

Step 8: Ensure Stop hook is installed

Check ~/.claude/settings.json for a Stop hook containing current-workflow-session. If absent, install via:

deepvista agents sync --type claude-code

Or add manually — see the Stop hook section below.

Show: https://app.deepvista.ai/vistabase/<SKILL_ID>


Phase 2 — Track each node

Maintain the full tracking body in /tmp/dv-workflow-<SKILL_ID>.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

ColumnContent
#Node index
NodeVerb-phrase description
Statuspending / running / done / failed / error
StartedUTC time when node went running (e.g. 14:32)
DurationElapsed time when node left running (e.g. 3m 12s)
OutputOne-line result, error message, or artifact name

When to update

EventAction
Starting a nodeStatus → running, record Started
Node completesStatus → done, fill Duration and Output
Task cannot be doneStatus → failed, fill Output with reason
Tool threw an exceptionStatus → error, fill Output with error summary
Scope expandsAppend new rows with pending — do not back-date

After each transition — write the updated temp file

cat > /tmp/dv-workflow-<SKILL_ID>.md << 'STATE'
**Goal:** <goal>
**Status:** running
**Started:** <ISO>

## Nodes

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

## Metrics

- Nodes: 1/<total> done, 0 failed
- Elapsed: <Xm>

## 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 | <node name> | running | ... |
# with    | 2 | <node name> | error   | 14:32 | 0m 5s | <error summary> |

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-<SKILL_ID>.md (the Stop hook will sync it), or push immediately:

deepvista card update <SKILL_ID> \
  --content-file /tmp/dv-workflow-<SKILL_ID>.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/<SKILL_ID>


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 sync --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

RuleDetail
Reuse within sessionIf session file has skill_id, skip creation and continue.
Workflow skill, not a raw cardUse deepvista skill create-from-note — produces type=skill.
Temp file is source of truthWrite all state to /tmp/dv-workflow-<SKILL_ID>.md; Stop hook syncs it.
Timestamps on every nodeRecord Started when going running; Duration when leaving it.
Errors are first-classerror ≠ failed: error means the tool broke, failed means the task couldn't be done.
Metrics stay currentUpdate the ## Metrics block on every state change.
Confirm before creatingShow node plan and get approval before deepvista skill create-from-note.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall