Donegraph

DoneGraph · AI Accountability Infrastructure

🏆 UCWS Singapore Hackathon 2026 — Skill Track
→ Judge Evaluation Sheet | → Architecture Overview

The git log for human-AI collaboration.

git log records what the code did. DoneGraph records what the human and AI decided, why, with what proof, and what is still open. It is the accountability layer that makes AI-assisted work auditable, resumable, and trustworthy.

Works as a local plugin for Codex, Claude Code, Cursor, VS Code Copilot, and shell-based AI workflows.

English | 简体中文

Live product: https://donegraph.space
Upload space: https://donegraph.space/share
Agent skill: https://donegraph.space/skill.md

---

The Problem

You have been building with an AI agent for three hours. It edited files, ran tests, changed direction twice, and left a long chat behind. Three questions remain unanswered:

1. What is actually done? — Activity is not progress. Chat history is not proof.
2. Can someone else trust it? — A teammate, a reviewer, the next AI session — none of them can reconstruct the decision chain from a raw chat log.
3. Where does the next session start? — Context windows expire. Memory resets. The next agent starts cold.

DoneGraph exists because in the AI era, "done" is too cheap to say and too hard to verify.

The Solution

DoneGraph turns goals, actions, decisions, artifacts, evidence, blockers, and next steps into a structured accountability graph — a clean work record with a 6-dimension Accountability Score that measures how trustworthy the work trail is. It generates a replay dashboard, proof summary, recap letter, Agent Radio debrief, and safe snapshot.

Every claim of "done" must be backed by evidence. Activity is not progress. Progress is earned.

---

Features

Capture The Current Context

Run /donegraph-capture when you join an existing task. DoneGraph reads local context such as changed files, file names, package.json scripts, and an optional goal, then turns that into starting collaboration events.

Track Human-AI Progress

Record meaningful checkpoints as the task moves forward: implementation work, design decisions, generated artifacts, verification results, blockers, and completion milestones.

Show Evidence, Not Just Activity

Progress is tied to proof. A passing command, manual check, failing test, unknown verification state, or blocker becomes part of the graph instead of disappearing into chat history.

Generate A Local Dashboard

Open .donegraph/dashboard.html to see what was completed, which evidence supports it, how the records connect, and where the next session should pick up.

Publish A Safe Snapshot

Generate .donegraph/safe-snapshot.json when you want to share one AI run without exposing the raw chat, file contents, local paths, or secret-looking values. The hosted share page can import snapshots in the browser, while the cloud API stores safe snapshots through Vercel Blob or Supabase.

Auto Upload From Agents

Open https://donegraph.space/share, create an upload space, and copy the generated Agent instruction. The agent can then publish future safe snapshots with DONEGRAPH_UPLOAD_TOKEN at stable stopping points.

Resume Large Tasks Cleanly

DoneGraph writes achievement-log.md and next-steps.md so the next AI session can continue from the real task state instead of asking you to reconstruct the story.

Stay Clean-Room

DoneGraph does not import external code graphs, third-party graph schemas, or .understand-anything artifacts. Its graph models one thing only: collaboration progress between a person and AI.

---

Five Axioms of AI Accountability

DoneGraph is built on five design axioms. These are not aspirational — they are structural constraints enforced by the code.

#	Axiom	Principle	Enforcement
1	Earned Progress	"Done" without evidence is not done. Activity is not progress.	Accountability Score hard gate: completion without pass evidence = UNACCOUNTED
2	Transparent Handoff	Every session ends with a clear state for the next human or AI.	next-steps.md and achievement-log.md are always generated
3	Privacy by Default	Raw sessions never leave the machine. Sharing requires explicit redaction.	Three privacy tiers: local_only, redacted_share, full_disclosure
4	Clean-Room Fidelity	The graph models collaboration facts, not code structure.	7 node types (goal, task, decision, artifact, evidence, blocker, next_step), no external schema dependencies
5	Immutable Trail	Events are append-only. The session log is a ledger, not a draft.	session.jsonl is append-only; no event is ever modified or deleted

---

6-Dimension Accountability Rubric

Every DoneGraph session is scored on six dimensions. The composite score determines the verdict.

#	Dimension	Weight	Hard Gate
1	Evidence Coverage	25	—
2	Completion Integrity	25	Completion without pass evidence → UNACCOUNTED
3	Decision Traceability	15	—
4	Handoff Quality	15	—
5	Privacy Safety	10	—
6	Graph Coherence	10	—

Three verdicts: ACCOUNTABLE (≥80) · PARTIAL (50–80) · UNACCOUNTED (<50 or hard gate failure).

---

Quick Start

1. Install The Plugin

From a local checkout:

./install.sh codex

After installation, restart your CLI or IDE. The installer links the DoneGraph skills for the selected platform and creates a universal local plugin entry:

~/.donegraph-plugin

From GitHub:

curl -fsSL https://raw.githubusercontent.com/serein431/DoneGraph/main/install.sh | bash -s codex

Native plugin package shape:

.agents/plugins/marketplace.json
plugins/donegraph/.codex-plugin/plugin.json
plugins/donegraph/skills/
plugins/donegraph/scripts/donegraph

The marketplace entry points at ./plugins/donegraph, which is the validated plugin root. Skills call the plugin-owned wrapper by relative path, so the package can run as a self-contained plugin.

2. Start A Session

/donegraph-start Ship a hackathon demo that shows AI progress clearly

If you are joining an existing task, capture local context first:

/donegraph-capture --goal "Ship a standalone clean-room DoneGraph demo"

3. Record Progress

/donegraph-checkpoint Implemented the command-first DoneGraph CLI --command "npm test"
/donegraph-proof Tests passed --pass --command "npm test"
/donegraph-done The demo can show completed work, evidence, and the next handoff

4. Open The Dashboard

/donegraph-dashboard

DoneGraph writes:

.donegraph/session.jsonl
.donegraph/task-graph.json
.donegraph/achievement-log.md
.donegraph/next-steps.md
.donegraph/dashboard.html
.donegraph/safe-snapshot.json
.donegraph/safe-snapshot.md

The dashboard includes a real-run replay, a guided walkthrough, a copyable plain-language summary, and a daily recap letter written by the AI for the user.

For the hosted product experience, open https://donegraph.space. For local review, open landing.html after npm run demo; it gives the product landing page first, with the real dashboard embedded inside the page.

---

Commands

Plugin commands:

/donegraph-start <goal>
/donegraph-capture [--goal <goal>] [--platform codex|claude|cursor|generic]
/donegraph-checkpoint <what changed> [--command <cmd>] [--path <file>]
/donegraph-proof <proof text> --pass|--fail|--blocked|--unknown [--command <cmd>]
/donegraph-done <completion summary>
/donegraph-dashboard [--no-open]
/donegraph-summary
/donegraph snapshot
/donegraph publish --target https://donegraph.space

Terminal fallback:

donegraph start "Ship the hackathon demo" --platform codex
donegraph capture --goal "Ship the hackathon demo" --platform codex
donegraph checkpoint "Implemented CLI" --command "npm test"
donegraph proof "Tests passed" --pass --command "npm test"
donegraph done "Demo ready"
donegraph dashboard
donegraph snapshot
donegraph publish --target https://donegraph.space

Development fallback inside this repo:

npm run cli -- start "Build DoneGraph" --platform generic
npm run cli -- capture --goal "Build DoneGraph" --platform generic
npm run cli -- checkpoint "Added installer and plugin skills"
npm run cli -- proof "Typecheck passed" --pass --command "npm run typecheck"
npm run cli -- dashboard --no-open

---

Multi-Platform Installation

Claude Code

/plugin marketplace add serein431/DoneGraph
/plugin install donegraph

Codex / Cursor / VS Code / Gemini / OpenCode / Generic Agents

macOS / Linux:

./install.sh
./install.sh codex
./install.sh claude
./install.sh cursor
./install.sh --update
./install.sh --uninstall codex

Supported local installer targets:

codex, claude, cursor, vscode, gemini, opencode, generic

Cursor and VS Code can also discover metadata from:

.cursor-plugin/plugin.json
.copilot-plugin/plugin.json

---

Share The Graph With Your Team

The graph is just local artifacts. Commit or attach the files when they are useful for reviews, handoffs, demos, and async collaboration.

Good candidates:

landing.html
.donegraph/task-graph.json
.donegraph/achievement-log.md
.donegraph/next-steps.md
.donegraph/dashboard.html
.donegraph/safe-snapshot.json

Keep session.jsonl private if the raw event stream contains sensitive task notes.

For automatic cloud upload, create an upload space at https://donegraph.space/share, copy the generated Agent instruction, then let the agent publish at stable stopping points:

DONEGRAPH_UPLOAD_TOKEN=<token> donegraph publish --target https://donegraph.space

If cloud upload is not configured yet, donegraph publish still writes .donegraph/safe-snapshot.json locally so the user can import it on /share.

The Vercel deployment can use Vercel Blob directly:

BLOB_READ_WRITE_TOKEN
DONEGRAPH_PUBLIC_URL=https://donegraph.space

Supabase is still supported as an alternative database-backed storage path:

SUPABASE_URL
SUPABASE_SERVICE_ROLE_KEY
DONEGRAPH_SNAPSHOT_TABLE=donegraph_snapshots
DONEGRAPH_SPACE_TABLE=donegraph_upload_spaces

Minimal Supabase tables, if you choose Supabase:

create extension if not exists pgcrypto;

create table donegraph_upload_spaces (
  id uuid primary key default gen_random_uuid(),
  created_at timestamptz not null default now(),
  name text not null,
  email text,
  upload_token_hash text not null unique
);

create table donegraph_snapshots (
  id uuid primary key default gen_random_uuid(),
  created_at timestamptz not null default now(),
  space_id uuid references donegraph_upload_spaces(id) on delete set null,
  generated_at timestamptz,
  goal text,
  privacy_mode text,
  summary jsonb,
  snapshot jsonb not null
);

---

Under The Hood

Clean-Room Collaboration Schema

DoneGraph is not a code dependency graph. Its nodes are collaboration facts:

goal, task, decision, artifact, evidence, blocker, achievement, next_step

Its edges describe how work moves:

belongs_to_goal, continues_as, produced, verified_by,
blocked_by, decided_by, needs_followup, supersedes

The capture command only reads local context such as git status, file names, package.json scripts, and the optional user goal. It does not consume .understand-anything, external graph files, or third-party schemas.

Local Artifact Pipeline

AI platform command
        |
        v
DoneGraph plugin skill
        |
        v
donegraph CLI
        |
        v
.donegraph/session.jsonl
        |
        v
task-graph.json + achievement-log.md + next-steps.md + dashboard.html
        |
        v
safe-snapshot.json for one-run sharing

Adapters stay thin. The graph logic lives in packages/core; the CLI and storage layer live in apps/cli; each platform wrapper only maps a user command to the same CLI.

---

3 Minute Hackathon Demo

For the shortest live operator script, see DEMO.md. For the judging path, pitch script, MVP boundary, and fallback plan, see HACKATHON.md.

npm install
npm run build

npm run cli -- start "Ship a hackathon demo that shows AI progress clearly" --platform codex
npm run cli -- capture --goal "Ship a standalone clean-room DoneGraph demo" --platform codex
npm run cli -- checkpoint "Implemented the command-first DoneGraph CLI" --command "npm test"
npm run cli -- checkpoint "Generated a static dashboard" --path ".donegraph/dashboard.html"
npm test
npm run cli -- proof "Tests passed" --pass --command "npm test"
npm run typecheck
npm run cli -- proof "Typecheck passed" --pass --command "npm run typecheck"
npm run build
npm run cli -- proof "Build passed" --pass --command "npm run build"
npm run cli -- checkpoint "The dashboard can replay the real work run" --path ".donegraph/dashboard.html"
npm run cli -- checkpoint "The dashboard can write a daily recap letter from the work record" --path ".donegraph/dashboard.html"
npm run cli -- done "The demo can now show completed work, evidence, and the next handoff"
npm run cli -- dashboard
open landing.html

Use --no-open if you only want to generate the HTML.

---

Repository Shape

apps/cli                  DoneGraph CLI and local artifact storage
packages/core             Pure graph, summary, Markdown, and dashboard rendering
plugins/donegraph         Codex plugin root, skills, and wrapper script
platforms/*               Thin integration notes for other AI environments
install.sh                Multi-platform local installer
scripts/demo-donegraph.sh 3-minute product demo path
landing.html              Product landing page that embeds the generated dashboard

Verify

npm test
npm run typecheck
npm run build

Optional Codex plugin package validation, when the local Codex system skill is available:

python3 "$HOME/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py" plugins/donegraph

---

Stop losing the thread. Start seeing what you and AI actually finished.