DOG

<p align="center"> <img src="dog.png" alt="DOG" width="200"> </p>

Documentation Oriented Grammar — A Markdown-native format for system documentation that serves humans and AI agents alike.

Available on: pypi

---

Quick Start

Installation

pip install dog-cli
# or with uv
uv add dog-cli

Basic Usage

# Validate your docs
dog lint docs/

# Format files
dog format docs/

# Generate project index
dog index docs/ --name "My Project"

# Search for concepts
dog search "login" --path docs/

# Get a specific document
dog get "@User" --path docs/

# List all documents
dog list --path docs/

# Find what references a primitive
dog refs "#AuthService" --path docs/

# Generate dependency graph
dog graph --path docs/ | dot -Tpng -o graph.png

# Export all docs as JSON
dog export --path docs/ > context.json

# Serve documentation in browser
dog serve docs/

Agent System Prompt

This is an example system prompt (agent definition) in Claude Code. Use something similar to this in your LLM agent's system prompt to enable DOG-driven development:

---
name: dog-developer
description: >
  PRIMARY DEVELOPMENT AGENT for this codebase. Use for ALL development tasks:
  implementing features, fixing bugs, refactoring, code reviews, and architectural decisions.

  This agent enforces DOG (Documentation-Oriented Grammar)—a documentation-first methodology
  where .dog.md behavioral specifications are the source of truth. Code fulfills documentation,
  not the other way around.
model: opus
---

You are the primary development agent for this codebase, combining expert software engineering with DOG methodology.

## Documentation Structure

```
docs/
├── *.md              # Prose docs
├── index.dog.md      # DOG index (auto-generated)
├── actors/           # @Actor specs
├── behaviors/        # !Behavior specs
├── components/       # #Component specs
└── data/             # &Data specs
```

## DOG Primitives

| Sigil | Type      | Purpose               | Required Sections                      |
| ----- | --------- | --------------------- | -------------------------------------- |
| `@`   | Actor     | Who initiates actions | Description, Notes                     |
| `!`   | Behavior  | What the system does  | Condition, Description, Outcome, Notes |
| `#`   | Component | How it's built        | Description, State, Events, Notes      |
| `&`   | Data      | What's stored         | Description, Fields, Notes             |

## CLI Reference

| Command  | Usage                                       | Purpose                                   |
| -------- | ------------------------------------------- | ----------------------------------------- |
| `get`    | `uv run dog get <name> -p docs -o json`     | Read a primitive with resolved refs       |
| `search` | `uv run dog search <query> -p docs -o json` | Find primitives by fuzz search            |
| `list`   | `uv run dog list [sigil] -p docs -o json`   | List all primitives (filter: `@!#&`)      |
| `refs`   | `uv run dog refs <name> -p docs -o json`    | **Reverse lookup**: what references this? |
| `export` | `uv run dog export -p docs`                 | Bulk export all docs as JSON              |
| `graph`  | `uv run dog graph [root] -p docs`           | DOT output for dependency visualization   |
| `lint`   | `uv run dog lint docs`                      | Validate structure/refs (positional path) |
| `format` | `uv run dog format docs`                    | Normalize whitespace (positional path)    |

**Tips:**
- Use `-o json` for structured output on `get`, `search`, `list`, `refs`
- Use sigil prefix to filter: `#WorkspaceStore`, `!SaveChat`, `@User`, `&Folder`
- `refs` is essential for impact analysis before changes

## Workflow

### Implementation
1. **Understand**: `dog get` + `dog refs` to see dependencies
2. **Design**: Document new behaviors before coding
3. **Implement**: Code fulfills documented behavior
4. **Validate**: `uv run dog lint docs` passes

### Investigation
1. **Explore**: `dog search` + `dog refs` to map the concept
2. **Verify**: Check consistency across all mentions
3. **Fix**: Update docs OR code (whichever is wrong)

### Decision Guide
- **Bug in code** → Fix code to match spec
- **Bug in spec** → Fix spec, then code
- **Missing docs** → Document first, ask if unclear
- **Cross-cutting change** → Use `dog refs` to find all affected docs

## Quality Gate

Before completing any task:
- [ ] `uv run dog lint docs` passes
- [ ] Code matches documented Behaviors
- [ ] Terminology consistent (use `dog refs` to verify)

## Key Concepts

- **Ephemeral = Unsaved**: `folderId: null` means client-only (Zustand)
- **Folder context**: `internal_summary` improves search relevance
- **LRU eviction**: Unsaved searches capped at 50

You advocate for documentation-first development. If specs are unclear, clarify or document before implementing.

---

Example

See the docs/ folder for a complete example of DOG documentation for this project.

---

What is DOG?

.dog.md is a Markdown-native specification format. Each file defines exactly one primitive type — Project, Actor, Behavior, Component, or Data — using light structural conventions.

DOG serves as:

• Human-readable system documentation
• A structured knowledge base for LLM agents
• A behavioral reference for AI-assisted testing

Primitive Types

| Type | Purpose | Example | | ------------- | -------------------------------------- | -------------------------- | | Project | Root index of a documentation set | # Project: MyApp | | Actor | User or service that initiates actions | # Actor: User | | Behavior | System response or state transition | # Behavior: Login Flow | | Component | Subsystem or UI element | # Component: AuthService | | Data | Domain entity with fields | # Data: Credentials |

Cross-References

Use sigils inside backticks to reference other concepts:

| Syntax | Meaning | | -------------------- | ------------------- | | `@User` | Actor reference | | `!Login` | Behavior reference | | `#AuthService` | Component reference | | `&Credentials` | Data reference |

---

CLI Commands

dog lint <path>

Validate .dog.md files for structure and reference errors.

dog lint docs/
dog lint my-behavior.dog.md

dog format <path>

Format .dog.md files (normalize whitespace).

dog format docs/
dog format --check docs/  # Check without modifying

dog index <path> --name <name>

Generate or update a Project index file (index.dog.md).

dog index docs/ --name "My Project"

dog search <query>

Search documents using fuzzy matching. Returns top-k results sorted by relevance.

dog search "login"
dog search "#auth"              # Filter by Component type
dog search "user" --limit 5 --output json

| Option | Description | | ---------------- | ---------------------------------- | | --path, -p | Directory to search (default: .) | | --limit, -l | Max results (default: 10) | | --output, -o | text or json |

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog get <name>

Get a document by name with resolved references.

dog get "Login Flow"
dog get "@User"                 # Get Actor named User
dog get "#AuthService" --output json

| Option | Description | | ---------------- | ---------------------------------- | | --path, -p | Directory to search (default: .) | | --output, -o | text or json |

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog list

List all documents.

dog list
dog list !                      # List only Behaviors
dog list --output json

| Option | Description | | ---------------- | ---------------------------------- | | --path, -p | Directory to search (default: .) | | --output, -o | text or json |

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog patch <name>

Update specific sections of a DOG document programmatically.

dog patch "@User" --data '{"sections": {"Description": "Updated description"}}'
dog patch "Login" --data '{"sections": {"Outcome": "New outcome"}}'

| Option | Description | | -------------- | ---------------------------------- | | --path, -p | Directory to search (default: .) | | --data, -d | JSON patch data |

dog refs <name>

Find all documents that reference a given primitive (reverse lookup).

dog refs "#AuthService"         # What references AuthService?
dog refs "@User" --output json  # JSON output

| Option | Description | | ---------------- | ---------------------------------- | | --path, -p | Directory to search (default: .) | | --output, -o | text or json |

Use sigil prefixes to filter by type: @ (Actor), ! (Behavior), # (Component), & (Data).

dog graph [root]

Generate a DOT format dependency graph for visualization.

dog graph                              # Full graph
dog graph "!Login"                     # Subgraph from Login behavior
dog graph -p docs/ | dot -Tpng -o graph.png  # Render with graphviz

| Option | Description | | -------------- | ---------------------------------- | | --path, -p | Directory