Metadata-Version: 2.4
Name: dog-cli
Version: 2026.5.1
Summary: Documentation Oriented Grammar (DOG) CLI Tool
Author-email: Qian Zhang <contact@qzsh.email>
License: MIT License
        
        Copyright (c) 2025 Qian Zhang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,cli,documentation,dog,llm,markdown,nlp,tool
Classifier: Development Status :: 4 - Beta
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.13
Requires-Dist: fastapi>=0.115
Requires-Dist: marko>=2.2.1
Requires-Dist: pydantic>=2.12
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: typer>=0.20.0
Requires-Dist: uvicorn>=0.34
Requires-Dist: watchfiles>=1.0
Description-Content-Type: text/markdown

# DOG

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

**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](https://pypi.org/project/dog-cli/) and as prebuilt binaries on [Releases](https://github.com/AirswitchAsa/dog/releases/latest).

---

## Install

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

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

**CLI** — prebuilt binary for macOS / Linux:

```bash
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](docs/guides/install.md) 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:

```markdown
# 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:

```bash
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](docs/guides/getting-started.md) for the primitive types, sigils, and required sections, or the [CLI reference](docs/guides/cli.md) for all commands.

---

## The workflow

```text
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](docs/guides/agent-workflow.md) 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.

| You already have                | DOG's role                                                              |
| ------------------------------- | ----------------------------------------------------------------------- |
| Gherkin / BDD scenarios         | Describes the durable concept graph around those behavior examples.    |
| OpenAPI / AsyncAPI contracts    | Connects API and event contracts to actors, behaviors, and data.       |
| C4 diagrams                     | Provides a queryable, lintable concept map instead of static visuals.  |
| ADRs                            | ADRs explain *why*. DOG describes what the system currently *means*.   |
| Spec Kit / Kiro feature specs   | Concept diffs that survive implementation, instead of disposable plans. |

See [comparisons](docs/guides/comparisons.md) for the full picture.

---

## Does it actually work?

A controlled eval against the [`crates/warp_cli`](https://github.com/warpdotdev/warp/tree/main/crates/warp_cli) subsystem of [warpdotdev/warp](https://github.com/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.

| | A (baseline) | B (with DOG) |
|---|---|---|
| Concept recall (mean) | 0.957 | **0.991** |
| File recall (mean) | 0.733 | **0.967** |
| Hallucination rate | 0/15 | 0/15 |
| Tool calls per task (mean) | 19.7 | **12.7** |

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](https://github.com/AirswitchAsa/dog-eval-warp).

---

## Docs

- [Getting started](docs/guides/getting-started.md) — primitives, sigils, your first `.dog.md`
- [Install guide](docs/guides/install.md) — binaries, PyPI, building from source
- [CLI reference](docs/guides/cli.md) — every command and flag
- [Agent workflow](docs/guides/agent-workflow.md) — concept-diff workflow, skill install, system-prompt fallback
- [Comparisons](docs/guides/comparisons.md) — DOG vs Gherkin, OpenAPI, C4, ADRs, Spec Kit, Kiro
- [Evaluation](https://github.com/AirswitchAsa/dog-eval-warp) — controlled eval on a real Rust codebase
- [Philosophy](docs/guides/philosophy.md) — design principles
- [Example docset](docs/) — DOG dogfooding itself

---

## License

MIT
