DOG

Documentation Oriented Grammar — a typed, lintable concept graph of your project, written in plain Markdown.

DOG turns agent planning into persistent project knowledge. Instead of asking coding agents to repeatedly read the repo, write a disposable spec, write a disposable plan, and then implement, DOG keeps a small concept graph of actors, behaviors, components, and data that agents can query, diff, and lint.

The DOG docs diff is the plan.

Available on PyPI and as prebuilt binaries on Releases.

Install

Agent skill — recommended. Teaches Claude Code, Cursor, Codex, and similar agents to use DOG automatically:

npx skills add https://github.com/AirswitchAsa/dog/tree/main/skills/dog

CLI — prebuilt binary for macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/AirswitchAsa/dog/main/scripts/install.sh | sh

Or pip install dog-cli / uv add dog-cli. See the install guide for Windows, Intel macOS, and building from source.

A tiny example

A .dog.md file defines exactly one primitive — Actor, Behavior, Component, or Data — with a few required sections and typed cross-references:

# Behavior: Login

## Condition

A `@User` submits valid `&Credentials` to `#AuthService`.

## Description

Authenticates the user and starts a session.

## Outcome

A `&Session` is created and returned to the user.

## Notes

- Failed attempts are rate-limited.

Now an agent can navigate the project as a graph:

dog get "!Login" --depth 1   # read the spec with referenced primitives inlined
dog refs "#AuthService"      # impact analysis: what depends on AuthService?
dog lint docs                # validate structure and references

See the getting-started guide for the primitive types, sigils, and required sections, or the CLI reference for all commands.

The workflow

brainstorm change
  → update DOG concept docs
  → review the DOG docs diff
  → implement against that diff

The output of understanding is a durable map of the system, not a plan that gets thrown away after one task. See the agent workflow guide for how this works inside Claude Code, Cursor, and other agents.

How DOG relates to other specs

DOG does not replace your existing specs. It connects them.

See comparisons for the full picture.

Does it actually work?

A controlled eval against the crates/warp_cli subsystem of warpdotdev/warp: same agent (claude-sonnet-4-6), 5 information-retrieval tasks, 3 trials per condition. Condition A gets warp source only; condition B adds an authored DOG docset and the dog skill.

B matches or beats A on concept recall on every task, doubles file recall on the two tasks where A struggled to cite the right file, and uses ~35% fewer tool calls on average. Zero hallucinations in either condition.

The DOG docs were authored in a separate Claude Code session with no shared context with the eval runner, and ground truth was sourced from the Rust code rather than from the docs — so B doesn't get credit for echoing its own docs back.

Full methodology, per-task analysis, raw transcripts, and limitations: AirswitchAsa/dog-eval-warp.

Docs

• Getting started — primitives, sigils, your first .dog.md
• Install guide — binaries, PyPI, building from source
• CLI reference — every command and flag
• Agent workflow — concept-diff workflow, skill install, system-prompt fallback
• Comparisons — DOG vs Gherkin, OpenAPI, C4, ADRs, Spec Kit, Kiro
• Evaluation — controlled eval on a real Rust codebase
• Philosophy — design principles
• Example docset — DOG dogfooding itself

License

MIT