Purpose
dotdog is a spec-driven design toolchain for single-repository, monorepo, and polyrepo workspaces. Its goal is to turn plans, repositories, or multi-repository products into structured .dog specs, compile them into .dag graphs, and let AI agents query the real project structure instead of guessing.
Main Capabilities
Three Starting Points
- Empty project: create a spec foundation before implementation.
- Existing project: map the current repository into structured graph facts.
- Workspace product: describe a product composed of N repositories with .doghouse/workspace.json.
.dog and .dag
.dog files are human-readable source specs, using Markdown prose plus YAML structured blocks. .dag files are compiled implementation graphs for agents and tools to use.
What dotdog init Creates
dotdog init <project> creates a project spec workspace under specs/<project>/. The planned full scaffold includes:
- SPEC.dog — product intent, behavior, flows, and user stories.
- data-model.dog — entities, states, schema, and relationships.
- plan.dog — implementation phases and tasks.
- constitution.dog — constraints, rules, and boundaries.
- INDEX.dog — a navigation map for humans and agents.
- COPY.dog — user-facing text and interface language.
Workspace (N Repositories)
A Dotdog workspace is a product boundary and can contain one repository, one monorepo, or N independent repositories. Workspace metadata lives in .doghouse/workspace.json. The workspace graph generates repository-qualified facts, letting humans and agents distinguish sources of truth. Single-repository projects do not need a manifest; by default, Dotdog treats the current repository as a single-repository workspace. Only .doghouse/workspace.json is suitable for version control; the generated workspace graph and observation facts are ignored by default because they may contain repository metadata.
Existing Repository Mapping
dotdog is not only for scaffolding empty projects; it can also map existing repositories. The target graphThe spec connects product intent to real implementation. 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 specifications. Target edge types include imports, calls, renders, reads, writes, depends_on, implements, configured_by, deployed_by, tested_by, documented_by, and owned_by.
For brand-new projects, you can run dotdog design after dotdog compile. It audits the compiled data model, checking stable identifiers, relationships, lifecycle, ownership, access patterns, and sensitive data handling, then gives concrete next steps without inventing domain facts.
MCP Server
dotdog serve exposes the spec to any MCP-compatible AI agent via stdio. It is a local stdio server, does not open a TCP port, and does not write query logs. If placed behind a gateway, configure authentication and least-privilege access for the gateway.
Self-Validation
dotdog validates its own spec, and this validation runs on every PR.
VS Code Extension
Provides syntax highlighting for .dog files. See the official repository instructions for installation.
Usage
Requires Node.js >= 20 or Bun >= 1.3.
Initialize a project:
dotdog init <project>
Compile the graph:
dotdog compile
Design audit (brand-new projects):
dotdog design
Start the MCP server:
dotdog serve
For projects created with GitHub Spec Kit, the importer reads local specs/<feature> artifacts, writes the generated graph under .doghouse/speckit, and preserves edited output unless --force is explicitly used. Imported Markdown is quoted in the generated .dog files so that the source content does not produce unintended graph syntax.
Format Specifications
- .dog format specification: language definition, EBNF grammar, validation rules.
- .dag format specification: graph definition, MCP API, token efficiency.
When to Use
Spec-driven development and spec-driven design: write or map the spec first, validate, compile, then let the agent query the implementation graph. Suitable for teams and projects that want to avoid specs rotting in a wiki and avoid agents guessing from prose.
Related Projects
- dotdefi — spec-first DeFi development. Write .dog specs, generate Solidity stubs.
- collar — DAG-first agent harness.
- dogbench — token savings benchmark for Collar and dotdog.
- dogfood-paybot — dogfooding: using dotdog on a real payment bot project.
- homebrew-dotdog — Homebrew tap for brew install dotdog.
Limitations
- Requires Node.js >= 20 or Bun >= 1.3.
- dotdog serve is a local stdio server and does not open a TCP port; if placed behind a gateway, you must configure authentication and least privilege yourself.
- Only .doghouse/workspace.json is suitable for version control; generated workspace graphs and observed facts are ignored by default.
- The official materials do not provide specific pricing, platform support scope, or performance data.
