DDx — Document-Driven Development eXperience

Documents drive the agents. DDx drives the documents.

Full Documentation →

What You Just Saw

DDx + HELIX takes a project from zero to working software:

1. ddx init — create a document library
2. ddx install helix — install the HELIX workflow plugin
3. Agent frames the project — creates PRD, feature specs, and tracker beads
4. Agent builds it — TDD, one commit per bead, all tests passing
5. Agent evolves it — adds a feature, updates specs, extends code
6. ddx bead list — every step tracked, every bead closed

Quick Start

# Install DDx
curl -fsSL https://raw.githubusercontent.com/DocumentDrivenDX/ddx/main/install.sh | bash

# Initialize your project
cd your-project
ddx init

# Install HELIX workflow plugin
ddx install helix

# Explore
ddx doctor
ddx persona list
ddx bead list

Development

Local Install

The canonical local binary is ${HOME}/.local/bin/ddx. Use the installer for all local deployments:

make build
./install.sh --from-build

make install runs the same installer path after building. Avoid copying DDx to other PATH directories by hand; add an installer mode when a different deployment source is needed. Use ./install.sh --from-build --no-shell --prefix "$TMPDIR/ddx-install-test" for throwaway installer checks.

Build and Test CLI

cd cli
make dev      # Start Go development server
make test     # Run all tests

Frontend Development (SvelteKit)

The web UI is built with SvelteKit and Bun:

# Install dependencies and start dev server
cd cli/internal/server/frontend && bun install && bun run dev

# Generate GraphQL types from schema
bun run houdini:generate

# Run unit tests
bun run test

# Run e2e tests with Playwright
bun run test:e2e

Build Something

# Frame: create specs and work items
ddx run --harness claude --prompt frame-prompt.md

# Build: agent implements per specs, TDD, closes beads
ddx try ddx-abc12345

# Evolve: add a feature
ddx work

# Inspect
ddx bead list          # all beads tracked
ddx log                 # history
ddx doc history PRD-001  # spec evolution
ddx metric list        # metric artifacts
ddx metric show MET-001  # metric definition + recent history

ddx metric inspection commands are read-only projections over the exec substrate. ddx metric run <MET-id> is the convenience wrapper for ddx exec run <definition-id> that resolves the latest active definition bound to the metric artifact.

Key Commands

Command	What it does
ddx init	Initialize document library
ddx install <name>	Install a workflow plugin
ddx doctor	Validate installation health
Prose quality support	Guidance for ddx doc prose --changed and prose config
ddx bead create/list/ready	Track work items
ddx metric list/show/validate/run/history/compare/trend	Inspect metric artifacts and run history
ddx run	Invoke an AI agent once
ddx try	Execute a specific bead
ddx work	Drain the bead queue
ddx log	View history
ddx persona bind	Assign personas to roles

Ecosystem

Workflow tools (HELIX, etc.)  →  opinionated practices
DDx (this project)            →  document infrastructure
AI agents (Claude, etc.)      →  consume docs, produce code

License

MIT. See LICENSE.