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

For a GitHub Spec Kit project:

dotdog speckit import .                # import specs/<feature> artifacts
dotdog compile .doghouse/speckit      # compile the imported local graphs
dotdog serve .doghouse/speckit        # expose them over local MCP

Imports are local and portable. dotdog makes no network requests, quotes imported Markdown so it cannot create unintended graph syntax, tracks generated artifact hashes, and preserves files you edit; use --force only when you intentionally want to replace them.

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 design [dir] | Audit compiled data models for identifiers, relationships, lifecycle, ownership, access, and sensitive data. | | 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 path <from> <to> | Find a bounded shortest path in a repo-world DAG. | | dotdog map [dir] | Inspect an existing repo and generate graph-ready .dog facts plus repo.dag. | | dotdog speckit import [dir] | Import local GitHub Spec Kit artifacts into queryable dotdog projects. | | 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 | | infraVerify | Read-only checks for declared infrastructure resources | | path | Bounded shortest connecting subgraph between two entities |

Agent workflow: workspace.list → listProjects → getEntity → traverse graph.

dotdog serve is a local stdio server: it opens no TCP port and writes no query logs. Generated .doghouse graphs and facts are ignored by default. Workspace responses contain repository-relative path values; cwd remains a relative compatibility alias. Secure any external MCP gateway separately 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

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