dotdog

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

What dotdog does

dotdog is a spec-driven design toolchain for single repos, monorepos, and polyrepo workspaces.

It supports three starting points:

1. Empty project — create a spec foundation before implementation.

2. Existing project — map the current repo into structured graph facts.

3. Workspace product — describe a product made from N repositories with .doghouse/workspace.json.

The core flow:

plan -> spec workspace -> validation -> repo/workspace graph -> agent execution

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

Related MCP server: io.github.pmgarg/cgraphy

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

For an existing product or organization workspace:

dotdog workspace init --id example-workspace
dotdog workspace add ../example-service --alias example-service --role api
dotdog workspace add ../example-interface --alias example-interface --role web
dotdog workspace validate
dotdog workspace graph --json

For a project created with GitHub Spec Kit:

dotdog speckit import .
dotdog compile .doghouse/speckit
dotdog serve .doghouse/speckit

The importer reads local specs/<feature> artifacts, writes generated graphs under .doghouse/speckit, and preserves edited outputs unless --force is explicit. Imported Markdown is quoted inside generated .dog files so source content cannot create unintended graph syntax.

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

Workspaces for N repos

A Dotdog workspace is a product boundary. It can contain one repo, a monorepo, or N separate repositories.

Workspace metadata lives in:

.doghouse/workspace.json

Example:

{
  "version": 1,
  "workspace": { "id": "example-workspace", "name": "example-workspace" },
  "repos": [
    { "alias": "example-service", "role": "api", "path": "../example-service" },
    { "alias": "example-interface", "role": "web", "path": "../example-interface" }
  ],
  "groups": [],
  "edges": []
}

The workspace graph emits repo-qualified facts so humans and agents can distinguish where a fact came from:

example-service:src/routes/core-flow.ts
example-interface:src/features/core-flow/index.ts

No manifest is required for single-repo projects; Dotdog treats the current repo as a one-repo workspace by default.

Only .doghouse/workspace.json is intended for version control. Generated workspace graphs and observed facts are ignored by default because they may contain repository metadata. Workspace CLI and MCP responses use repository-relative paths; the legacy cwd key is a relative alias for path.

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.

For greenfield work, run dotdog design after dotdog compile. It audits the compiled data model for stable identifiers, relationships, lifecycle, ownership, access patterns, and sensitive-data handling, then gives concrete next steps without inventing domain facts.

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

Planned:

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
CoreFlowPage renders StatusPanel
CoreFlowPage calls POST /api/core-flow
POST /api/core-flow writes records
POST /api/core-flow depends_on SERVICE_TOKEN
records implemented_by prisma/schema.prisma

MCP Server : AI Agent Integration

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

Agent workflow:

workspace.list -> listProjects -> getEntity -> traverse graph

dotdog serve is a local stdio server. It does not open a TCP port or write query logs. If you place it behind a gateway, secure the gateway with authentication and least-privilege access.

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