dotdog

Spec-driven design for agent-ready projects. Turn plans or existing repos into structured .dog specs, validate them, compile them into .dag graphs, and let agents query real project structure instead of guessing.

What dotdog does

dotdog is a spec-driven design toolchain.

It supports two starting points:

1. Empty project — create a spec foundation before implementation.
2. Existing project — map the current repo into a structured spec workspace.

The core flow:

plan -> spec workspace -> validation -> implementation graph -> agent execution

.dog files are the human-readable source specs. .dag files are compiled implementation graphs for agents and tools.

Install

npm install -g dotdog    # npm
brew install dotdog       # Homebrew
bun add -g dotdog         # bun

Requires Node.js >= 20 or Bun >= 1.3.

Quick Start

dotdog init my-project     # create a spec workspace
dotdog validate            # check spec completeness
dotdog compile             # build the .dag implementation graph
dotdog serve               # expose the graph to MCP-compatible agents

What init creates

dotdog init <project> creates a project spec workspace under specs/<project>/.

specs/<project>/
  INDEX.dog
  SPEC.dog
  constitution.dog
  data-model.dog
  plan.dog
  COPY.dog

Planned full scaffold:

specs/<project>/
  INDEX.dog
  SPEC.dog
  constitution.dog
  data-model.dog
  plan.dog
  COPY.dog
  tasks.dog
  tasks/
    AGENTS.dog

Edit order:

1. SPEC.dog — product intent, behavior, flows, and user stories.
2. data-model.dog — entities, states, schemas, and relationships.
3. plan.dog — implementation phases and tasks.
4. constitution.dog — constraints, rules, and boundaries.
5. INDEX.dog — navigation map for humans and agents.
6. COPY.dog — user-facing text and interface language.

Then run:

dotdog validate
dotdog compile

Repo mapping direction

dotdog should not only scaffold empty projects. It should also map existing repos.

The intended graph connects product intent to real implementation:

frontend component -> API route -> backend handler -> schema -> database table -> env var -> infra resource -> task/spec reason

Target node types include files, directories, packages, frontend components, routes, pages, API endpoints, backend handlers, services, schemas, database tables, migrations, environment variables, cloud resources, CI workflows, tests, tasks, and specs.

Target edge types include imports, calls, renders, reads, writes, depends_on, implements, configured_by, deployed_by, tested_by, documented_by, and owned_by.

See Spec-Driven Repo Mapping for the formal plan.

Commands

Command	Description
dotdog init <project>	Create a spec workspace for a new project.
dotdog validate [dir]	Score spec completeness. Checks file existence, entity descriptions, section counts.
dotdog compile [dir]	Compile .dog files into a .dag graph for agents and tools.
dotdog analyze [dir]	Deep analysis. Detects domain, stack, gaps with severity, entity quality audit.
dotdog badge [dir]	Generate a shields.io SVG badge showing token savings.
dotdog staleness [dir]	Detect drift between spec and reality. Compares plan.dog tasks against code.
dotdog tokens [dir]	Count tokens in .dog files and compare to compiled .dag savings.
dotdog index [dir]	Build search index for semantic queries across compiled specs.
dotdog search <query>	Semantic search across compiled specs using the search index.
dotdog serve [dir]	Start MCP server over stdio. AI agents query specs without hallucination.
dotdog simulate <scenario>	Walk through a scenario. Reads SPEC.dog scenarios, checks pre/postconditions.
dotdog predictions [dir]	List all predictions with status (pending, correct, wrong, partial).
dotdog resolve <name>	Mark a prediction as correct, wrong, or partial with evidence.
dotdog doctor	Baseline health check. Validates specs, detects stale .dag.
dotdog visualize [dir]	Output Mermaid graph from .dag. --save writes .md for GitHub rendering.
dotdog generate [dir]	Generate missing spec files from SPEC.dog (data-model, COPY, INDEX).
dotdog parse <file>	Parse a .dog file into sections (entities, relationships, copy).
dotdog kit	List, init, or manage spec kits (starter templates).
dotdog list	List all projects and their .dog file counts.
dotdog woof	Prints "woof" because every good CLI deserves an easter egg.
dotdog live [entity]	Test live endpoints + cloud infrastructure against .dog contracts. Hits URLs, diffs responses, backup failover. Verify S3 buckets, Vercel projects, Supabase tables, and more.

Planned:

Command	Description
dotdog init <project> --map	Create a spec workspace and seed it from the current repo.
dotdog map [dir]	Inspect an existing repo and generate graph-ready .dog facts.

File Formats

.dog : Human-Written Source Spec

Markdown prose + YAML structured blocks. Free and open source. Define entities, relationships, events, predictions, implementation facts, and copy in a single format that both humans and parsers understand.

### Entity: User

A person who uses the app.

```yaml
entity: User
type: entity
properties:
  id:
    type: string
    required: true
  email:
    type: string
    required: true
states: [active, suspended]
lifecycle: active -> suspended

### `.dag` : Machine-Compiled Implementation Graph

JSON graph compiled from `.dog` files. Nodes, edges, properties, and states in a deterministic structure. Designed for AI agents to query exact project structure with lower token cost than raw prose.

Example graph facts:

```text
CheckoutPage renders CartSummary
CheckoutPage calls POST /api/checkout
POST /api/checkout writes orders
POST /api/checkout depends_on STRIPE_SECRET_KEY
orders implemented_by prisma/schema.prisma

MCP Server : AI Agent Integration

dotdog serve exposes specs to any MCP-compatible AI agent over stdio.

Tool	Description
getEntity	Exact entity with properties, states, lifecycle, and connected edges
traverse	BFS subgraph from any starting node to any depth
search	Find entities by name or type
schema	Property definitions only : zero prose, agent-optimized
summary	Node count, edge count, file count, compile time
listProjects	Array of project names

Agent workflow:

listProjects -> getEntity -> traverse graph

Dogfood

dotdog validates its own specs. Every PR:

dotdog validate -> find gaps -> fix spec -> PR -> merge -> tag -> CI publish

Eat your own dogfood. The tool is the project.

VS Code Extension

Syntax highlighting for .dog files. Install:

cp -r extensions/vscode ~/.vscode/extensions/dotdog

Format Specifications

• .dog format spec : language definition, EBNF grammar, validation rules
• .dag format spec : graph definition, MCP API, token efficiency

Related Projects

• dotdefi — Spec-first DeFi development. Write .dog specs, generate Solidity stubs.
• collar — DAG-first agent harness.
• dogbench — Token-savings benchmarks for Collar and dotdog.
• dogfood-paybot — Dogfood test: dotdog on a real payment bot project.
• homebrew-dotdog — Homebrew tap for brew install dotdog.

Links

• GitHub: specdog/dotdog
• npm: dotdog
• Docs: Tutorial · FAQ · Integrations · Use Cases
• llms.txt: llms.txt : structured for AI agent discovery
• AGENTS.md: AGENTS.md : instructions for AI coding agents

Spec-Driven Development

dotdog is built for spec-driven development and spec-driven design. Write or map the spec first. Validate it. Compile it. Let agents query the implementation graph.

plan -> spec -> validate -> compile -> serve -> agent queries

No more specs that rot in a wiki. No more agents guessing from prose. One source. Queryable graph.

License

MIT