dev-workgraph

Turn a Git repository into a career story you can defend — for a performance review, a CV, or interview prep.

You point the CLI at a repo where you actually worked. It reads your commits and patches, asks what Git cannot know, you confirm the missing context, and it writes RECONSTRUCTION.<project>.md: what you did, where in the system, and what impact means for your role (Principal, Staff, Senior, Junior) — with role narrative bullets and CV bullets grounded in evidence, not a blank ChatGPT prompt.

Why this exists

The problem. Sooner or later you must explain your work — at a half-yearly or annual review, on a resume, to a recruiter, to an ATS, or for a project you shipped years ago. You were busy — but memory fades. Git remembers diffs; it does not remember why, whether it shipped, who owned the design, or how it maps to impact. Generic AI can polish prose, but it invents or drifts because it never saw your repo or your answers.

What dev-workgraph does instead. It reconstructs work from your Git history plus your confirmations:

| You need to… | What you get | |--------------|--------------| | Performance review | First-person Your IMPACT, four role-framed bullets, technologies — tied to commits and signals from the period | | CV / resume | Four impersonal CV bullets with real stack and architecture keywords from the codebase | | Interview prep | A readable narrative of what you built and Possible questions with your own answers — ownership, production, design vs implementation |

This is not a commit counter, activity heatmap, or auto-scored achievement tool. It does not claim customer impact or production usage unless you stated that in an answer.

How it works (short).

1. Evidence — your commits → patches, areas, work sessions, technical/architecture signals.
2. Ask — up to four role-aware questions per round (what Git cannot infer).
3. Confirm — you answer; answers are stored on the finish archive, separate from the prepared narrative.
4. Deliver — RECONSTRUCTION.<project>.md (+ optional .v2.md after deepen when you recall more team context, pivots, or review framing).

See real outputs on GitHub: Forge Secure Notes for Jira (Principal) and keycloak-radius-plugin (Staff, open-source IAM).

Evidence pipeline, not a resume generator

The goal is not “generate a resume from Git.” dev-workgraph builds an evidence-based career reconstruction pipeline:

• Deterministic layer (commits, patches, file paths, timestamps) stays separate from model-generated summaries and narratives — so evidence is stable when models or prompts change.
• Raw Git activity is converted into structured signals (technical, architecture, security) and ranked context (high / medium / low); maintenance noise (dependency bumps, releases) is deprioritized so design work is not drowned out.
• A feedback loop closes the gap Git cannot fill: the tool finds missing intent in the evidence, asks targeted questions, and stores your answers as a separate context layer that reframes activity into role-based impact.
• Final claims are grounded in verified inputs — repository data, commits, generated evidence, and human corrections — making the output easier to defend in a review or interview than a generic AI narrative.

Under the hood, the pipeline builds a work graph from Git history and your answers: commits, sessions, reports, questions, and Q&A linked by provenance. The RECONSTRUCTION is a fold over that graph — every claim traceable to evidence or a confirmed answer. That graph is also the foundation for safe retrieval (RAG) over your own work later: retrieval first, generation on a corpus you can defend.

Install

# run on demand, no install
npx dev-workgraph run .

# or install globally for a persistent `dev-workgraph` command
npm install -g dev-workgraph

This provides the dev-workgraph command. You also need a local LLM server — Ollama or LM Studio (see Quick start).

Quick start

Prerequisites: Node.js 20+, Git, and a local LLM backend — Ollama or LM Studio. check and run discover both automatically when their servers are running.

Option A: Ollama

brew install ollama
ollama pull qwen2.5-coder:14b
ollama pull gpt-oss:latest
ollama pull gemma4:31b
ollama serve

Option B: LM Studio

1. Install LM Studio and load models in the app.
2. Start the local server (default http://127.0.0.1:1234).
3. Run dev-workgraph check — loaded models appear in the picker alongside Ollama.

You can mix providers: e.g. commit slots on Ollama, narrative on LM Studio. Each of the three model slots (commit, report, narrative) stores provider, baseUrl, and model in ~/.workgraph/config.json.

Run the pipeline

cd /path/to/your/repo
npx dev-workgraph run .

The pipeline ends with final: you answer up to four questions interactively. The markdown deliverable is written to your current working directory. Everything before that can run unattended and be resumed.

Example outputs

Real RECONSTRUCTION.*.md files from dogfooding on production repos (local Ollama / LM Studio, interactive final + deepen):

| Project | Role | Output | |---------|------|--------| | Forge Secure Notes for Jira | Principal Developer | RECONSTRUCTION.Forge-Secure-Notes-for-Jira.v2.md — zero-trust Jira Forge app, encryption, ~300 commits | | keycloak-radius-plugin | Staff Developer | RECONSTRUCTION.keycloak-radius-plugin.v2.md — open-source Keycloak RADIUS plugin, IAM / platform migrations |

More examples: examples/ on GitHub.

Review periods

Doing a periodic review (“what did I do in 2024?”)? Scope the whole pipeline to a date window with --period:

npx dev-workgraph init:period ./repo --period 2024 --from 2024-01-01 --to 2025-01-01
npx dev-workgraph run:period  ./repo --period 2024

The deliverable is RECONSTRUCTION.<project>.2024.md — a period review does not overwrite your all-time reconstruction. Every pipeline command accepts --period <id>.

How it runs

Local only — Ollama and/or LM Studio on your machine (or another host reachable via --ollama-url / --lmstudio-url). No cloud API; analysis stays under ~/.workgraph/ unless you export a bundle yourself.

Resumable — stop anytime before final; re-run npx dev-workgraph run . and completed commits, groups, and report folds are skipped. Interactive Q&A starts only after prepare.

Dogfooded on MacBook Pro M4 Pro (48 GB). One real repo (~300 commits): unattended stages took ~6 hours before the first questions (final). Time depends on models, patch size, and cache from prior runs.

Recommended models (Ollama)

These are the models used for the example outputs below. With LM Studio, pick equivalent models in the interactive picker — names depend on what you have loaded.

| Slot | Model | Used for | |------|--------|----------| | commitModel | qwen2.5-coder:14b | summarize, commit-group | | reportModel | gpt-oss:latest | report | | narrativeModel | gemma4:31b | init, prepare, final, deepen |

run saves the three slots in ~/.workgraph/config.json.

Pipeline

| Stage | Command | LLM | What it does | |-------|---------|-----|--------------| | Preflight | check | — | LLM backend reachable (Ollama and/or LM Studio), models installed | | Authors | authors | — | Select your commit emails | | Context | init | narrative | Role, project story, README → project.json | | Evidence | evidence | — | Patches + deterministic JSON per commit | | Commit layer | summarize | commit | Per-commit summary, signals, questions | | Sessions | commit-group | commit | Pluggable partition (default: day-gap); session history | | Cumulative | report | report | Fold groups → growing narrative report | | Distill | prepare | narrative | One history + up to 4 questions for final | | Deliver | final | narrative | You answer → RECONSTRUCTION.<project>.md | | Extend | deepen | narrative | Recalled context + 4 new Q&A → .v2.md, … |

run executes everything through final. deepen is not part of run — run it separately when you remember more context.

Commands

dev-workgraph check
dev-workgraph init         ./repo
dev-workgraph authors      ./repo
dev-workgraph evidence     ./repo
dev-workgraph summarize    ./repo
dev-workgraph commit-group ./repo
dev-workgraph report       ./repo
dev-workgraph prepare      ./repo
dev-workgraph final        ./repo
dev-workgraph deepen       ./repo
dev-workgraph run          ./repo
dev-workgraph export       ./repo
dev-workgraph import       <bundle.tar.gz>
dev-workgraph init:period  ./repo --period 2024 --from 2024-01-01 --to 2025-01-01
dev-workgraph run:period   ./repo --period 2024

Common flags:

• --period <id> — scope to a review window (periods/<id>/ data subtree)
• --strategy <id> — commit-group partition strategy (default: first registered, usually day-gap)
• --days <n> / --max-commits <n> — day-gap strategy only (skip interactive prompts)
• --model <name> — force model for this command (must be unique across reachable backends)
• --ollama-url <url> — Ollama server URL (default http://127.0.0.1:11434)
• --lmstudio-url <url> — LM Studio server URL (default http://127.0.0.1:1234)
• final --answers-file <path> — non-interactive answers (JSON)
• final --output <path> — override markdown path
• deepen --context-file <path> — non-interactive recalled context

On-disk data

All analysis is namespaced per repository under ~/.workgraph/data/repos/<repo-id>/:

project.json
commits/<ts>/<hash>.{patch,json}     # evidence (deterministic)
summaries/<ts>/<hash>.json           # commit model layer
groups/<timestampEnd>.json
reports/<reportId>.json
prepared/<reportId>.json             # questions only — no answers
finish/
  <id>.json                          # finish archive
  <id>.question.json                 # v1 questions
  <id>.v2.json / .question.v2.json   # deepen / extension
  <id>.md

<repo-id> is <basename>-<hash8> from the absolute repo path. Config (authors, role, models, commitGroupStrategy, day-gap thresholds) lives in ~/.workgraph/config.json.

Q&A storage

Human answers live on the finish chain, not in prepared/:

• Question text — finish/<id>.question.json (or .question.vN.json); each question has a Unix-ms id
• Answers — finish/<id>.json → { questionId, answer }[] (cumulative)
• Rounds — sourceQuestions: { "<finishId>": ["v1", "v2", …] } on the finish record

Portability

dev-workgraph export ./repo
dev-workgraph import ./bundle.workgraph.tar.gz --repo /new/path

Bundles data directory + config entry. No LLM calls.

Extensibility

| Plugin | Registration | Docs | |--------|--------------|------| | LLM backends | LLM_PROVIDER_KINDS in src/lib/llm/providers.ts | ARCHITECTURE.md — Extending LLM providers | | Commit-group strategies | COMMIT_GROUP_STRATEGIES in src/lib/commit-group/registry.ts | ARCHITECTURE.md — Extending commit-group strategies |

Only partition is customizable for commit-group; the runner always produces the same GroupRecord for report. Default strategy: day-gap (--days, --max-commits). With multiple strategies registered, run prompts for --strategy (saved as commitGroupStrategy).

Core principle

Git patches     = evidence (trustworthy)
Model summaries = interpretation (may be wrong; must cite reasons)
Questions       = what Git cannot know
Your answers    = confirmed context (not proof unless you stated it)
RECONSTRUCTION  = personal artifact for review / interview prep — not auto-scored

Development

From a git checkout of this package:

npm install
npm run build
npm test
npm run verify
npm link   # optional: global dev-workgraph command

License

Apache-2.0