dotdog

dotdog

Feed the dog. Ship with specs. Write .dog specs, map repos into .dag graphs, and expose single-repo or N-repo workspaces to agents.

Install

npm install -g dotdog

Requires Node.js >= 20.

Quick Start

dotdog init my-project      # scaffold a spec workspace
dotdog validate             # score completeness (0-100%)
dotdog analyze              # deep analysis: gaps, suggestions, entity audit

For an existing multi-repo product:

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

Commands

Command	Description
dotdog validate [dir]	Score spec completeness. Checks file existence, entity descriptions, section counts.
dotdog analyze [dir]	Deep analysis. Detects domain, stack, gaps with severity, entity quality audit.
dotdog parse <file>	Parse a .dog file into sections.
dotdog compile [dir]	Compile .dog files into a .dag graph (JSON).
dotdog visualize [dir]	Output Mermaid graph from .dag. --save writes .md for GitHub rendering.
dotdog serve [dir]	Start MCP server over stdio. AI agents query specs and workspace metadata without hallucination.
dotdog workspace init --id <id>	Create .doghouse/workspace.json for one repo or a product workspace.
dotdog workspace add <path>	Add a repository to a workspace with --alias and --role.
dotdog workspace list	List workspace repos and groups.
dotdog workspace validate	Validate workspace aliases, paths, groups, and edges.
dotdog workspace graph	Emit deterministic workspace graph JSON.
dotdog map [dir]	Inspect an existing repo and generate graph-ready .dog facts plus repo.dag.
dotdog staleness [dir]	Detect drift between spec and reality. Compares plan.dog tasks against code.
dotdog generate [dir]	Generate missing spec files from SPEC.dog (data-model, COPY, INDEX).
dotdog simulate <scenario>	Run a simulation scenario. Reads SPEC.dog scenarios, checks pre/postconditions.
dotdog init <project>	Scaffold a new spec workspace project with templates.
dotdog list	List all projects and their .dog file counts.

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 Graph

JSON graph compiled from .dog files. Nodes, edges, properties, and states in a deterministic structure. 85% token savings vs raw .dog files for AI agents.

MCP Server : AI Agent Integration

dotdog serve exposes specs and workspace metadata 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
workspace.list	Structured workspace metadata with repos, groups, and trustedAsInstruction: false

Agent workflow: workspace.list → 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

Links

• GitHub: specdog/dotdog
• npm: dotdog
• Docs: GitHub Pages
• 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 SDD. Write your spec first, or map an existing repo/workspace. Validate it. Compile it. Let AI agents query it. The spec and graph are the source of truth.

spec → validate → compile → serve → AI agent queries

No more specs that rot in a wiki. No more agents guessing from prose. One source. Zero ambiguity.

License

MIT