Decisions as Code

A text-based knowledge graph for architecture decisions, policies, opportunities, incidents, specs and processes. Plain Markdown in your repo, validated against a schema, reviewed in pull requests.

Get Started View Live Demo

$ dg init
$ dg new opportunity "Sell llama milk online"
OPP-001 -> docs/opportunities/opp-001-sell-llama-milk-online.md

$ dg new adr "Use PostgreSQL" enables OPP-001
ADR-001 -> docs/architecture/adr-001-use-postgresql.md

$ dg serve --open

Decision Graph web UI showing an interactive graph of linked ADRs, opportunities, policies and incidents — Explore your decision graph with `dg serve`

Why Decision Graph?

Plain Text & Git-Native

Markdown files with YAML frontmatter. Review decisions in PRs, track history with git blame, merge conflicts are just text.

6 Record Types, One Schema

Architecture Decision Record, Policy Document, Opportunity, Incident Report, Behavioral Specification / User Story and Process Document. A KDL schema defines required fields, sections and status transitions; dg validate enforces it. Eject and add your own types.

Linked Knowledge Graph

Connect records with typed relations: supersedes, enables, triggers, depends_on, implements, conflicts_with and related. Backlinks come for free; dg lint catches dangling refs, cycles and orphans.

Built-in Web UI

dg serve launches a local site with search, an interactive graph, kanban, roadmap and team pages. dg export --site builds the same site as static files.

Built for AI Agents

dg init sets up skills and instructions for Claude Code, Gemini CLI and OpenCode. Agents write docs with dg new / dg set and get instant schema feedback from dg validate.

Users & Teams

Define people, teams and orgs in .dg/org.kdl. Authors, owners and action-item assignees are validated, and departed users are tracked.

Live Demos

Explore decision archives built with Decision Graph

Silicon Valley

Pied Piper

The compression company's strategic decisions, from the middle-out algorithm architecture to the PiperNet decentralized internet.

15 records
12 people
8 teams

Historical

Microsoft

Historical decisions from Microsoft's founding through the Satya Nadella era. Based on the excellent Acquired podcast episodes.

33 records
13 people
10 teams
1975–2014

Record Types

6 built-in types, straight from the default schema.

ADR-001 docs/architecture/

Architecture Decision Record

Sections: Context · Decision · Consequences

Status: proposed · accepted · rejected · deprecated · superseded

POL-001 docs/policies/

Policy Document

Sections: Purpose · Policy · Scope

Status: proposed · active · deprecated · superseded

OPP-001 docs/opportunities/

Opportunity

Sections: Description

Status: identified · validating · pursuing · completed · deprecated · declined

INC-001 docs/incidents/

Incident Report

Sections: Summary · Timeline · Root Cause

Status: open · mitigated · resolved

SPEC-001 docs/specs/

Behavioral Specification / User Story

Sections: Story · Scenarios

Status: draft · proposed · approved · implemented · deprecated

PROC-001 docs/processes/

Process Document

Sections: Overview · Inputs and Prerequisites · Outputs · Process Flow · Steps

Status: draft · proposed · active · deprecated · superseded

Plus 3 README types (readme, service-readme, app-readme): dg checks that project, service and app READMEs document architecture, risks and local development.

Installation

macOS and Linux:

$ brew install decisiongraph/tap/dg

Or grab a prebuilt binary from GitHub Releases.

The repo is a Nix flake exposing a dg package:

# run without installing
$ nix run github:decisiongraph/dg -- --version

# install to your profile
$ nix profile install github:decisiongraph/dg

Prebuilt binaries for x86_64-linux, aarch64-linux and aarch64-darwin are in the decisiongraph cachix: cachix use decisiongraph.

Use the prebuilt release binaries (no compiling). In devenv.yaml:

inputs:
  dg:
    url: github:decisiongraph/dg
    flake: false

and in devenv.nix:

{ pkgs, inputs, ... }: {
  packages = [ (pkgs.callPackage "${inputs.dg}/nix/dg-bin.nix" { }) ];
}

devenv update dg moves to the latest release.

Build from source (needs Rust and bun for the embedded web UI):

$ cargo install --locked --git https://github.com/decisiongraph/dg dg-cli

Or from a checkout:

$ git clone https://github.com/decisiongraph/dg && cd dg
$ cargo install --path crates/dg-cli

Quick Start

# Scaffold .dg/, git hooks and AI agent config
$ dg init

# Create linked records
$ dg new opportunity "Sell llama milk online"
$ dg new adr "Use Rails with PostgreSQL" enables OPP-001
$ dg new spec "Llama milk checkout flow" implements OPP-001

# Validate against the schema + graph health
$ dg lint

# Find things
$ dg list --type adr
$ dg search "postgres"
$ dg refs OPP-001 --backlinks

# Browse locally, or export a static site
$ dg serve --open
$ dg export --site -o ./site

Start capturing decisions today

Your future self will thank you when you can trace why that architecture decision was made.

View on GitHub Install Now