dotdog

Feed the dog. Ship with specs. Write .dog specs. Dog checks them. AI agents fetch them.

Install

npm install -g dotdog

Requires Node.js >= 20.

Quick Start

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

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 without hallucination. | | 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 genome project with templates. | | dotdog list | List all projects and their .dog file counts. |

File Formats

.dog : Human-Written Spec Genome

Markdown prose + YAML structured blocks. Free and open source. Define entities, relationships, events, predictions, 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 to any MCP-compatible AI agent over stdio. Six tools:

| 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

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. Validate it. Compile it. Let AI agents query it. The spec is 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