From f01cb93aaf6c07df7ddb88b7b1b6edfa92f825df Mon Sep 17 00:00:00 2001 From: logohere <69400476+logohere@users.noreply.github.com> Date: Sun, 1 Nov 2026 05:22:33 -0500 Subject: [PATCH 1/2] docs: unify site design and add product research and practical guides --- README.md | 4 + _layouts/default.html | 34 ++++ about.html | 55 ++----- about/index.html | 28 +++- agents.html | 73 ++------- assets/dog.svg | 11 ++ assets/site.css | 144 +++++++++++++++++ assets/site.js | 35 ++++ blog.html | 71 +++----- blog/agent-first-documentation/index.html | 40 ++--- blog/collar-graph-backed-agents/index.html | 53 ++++++ blog/dogbench-measurement/index.html | 49 ++++++ blog/dotdog-1-research/index.html | 59 +++++++ blog/dotdog-workspace-bridge/index.html | 51 ++---- blog/google-ard-dotdog/index.html | 60 +++---- blog/index.html | 28 +++- blog/karpathy-wiki-brain/index.html | 60 +++---- blog/leash-control-boundaries/index.html | 53 ++++++ collar.html | 76 +++------ dogbench.html | 42 +++-- dogbench/index.html | 42 +++-- dogfood.html | 180 +++------------------ dotdog.html | 35 ++-- dotdog/index.html | 60 ++----- github.html | 28 ++-- github/index.html | 28 ++-- guides/rea-graphs/index.html | 65 ++++++++ guides/type-driven-development/index.html | 91 +++++++++++ handbook.html | 76 ++------- homebrew.html | 65 ++------ index.html | 108 +------------ leash.html | 52 ++---- llms.txt | 31 +++- scripts/check-site.py | 5 +- site-map.json | 53 +++--- sitemap.xml | 57 +++---- 36 files changed, 1073 insertions(+), 929 deletions(-) create mode 100644 _layouts/default.html create mode 100644 assets/dog.svg create mode 100644 assets/site.css create mode 100644 assets/site.js create mode 100644 blog/collar-graph-backed-agents/index.html create mode 100644 blog/dogbench-measurement/index.html create mode 100644 blog/dotdog-1-research/index.html create mode 100644 blog/leash-control-boundaries/index.html create mode 100644 guides/rea-graphs/index.html create mode 100644 guides/type-driven-development/index.html diff --git a/README.md b/README.md index 5d6ecbb..8d170c0 100644 --- a/README.md +++ b/README.md @@ -9,3 +9,7 @@ Run from your repository with npm: `npx dotdog@1.0.0 refresh --json`, or Bun: `bunx --bun dotdog@1.0.0 refresh --json`. Node.js 22.12+ or Bun 1.3+; the optional type adapter additionally requires Node and a trusted project-installed TypeScript 7.0.2 compiler. **[dogbench](https://specdog.github.io/dogbench)** — token-savings benchmark for Collar and dotdog. [GitHub](https://github.com/specdog/dogbench) + +## Author + +A specdog project by **[Justin DiClemente](https://github.com/logohere)**. [Short bio](https://specdog.github.io/about#justin-diclemente). diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 0000000..ebcf74c --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,34 @@ + + + + + +{{ page.title | default: site.title | default: 'specdog' | escape }} | specdog + + + + + + + +
+ +
+
+{{ content }} +
+ + + diff --git a/about.html b/about.html index 84fe084..f52bdd5 100644 --- a/about.html +++ b/about.html @@ -5,56 +5,27 @@ About specdog - - + + + +
-
+
+

About specdog

specdog is a toolkit for making software specs easier for both humans and AI agents to read. The goal is simple: keep intent, implementation rules, and agent instructions in structured files that can be validated and queried.

The project focuses on spec-driven development, agent discovery, and small runtime surfaces that reduce guesswork when an agent enters a codebase.

@@ -67,11 +38,19 @@

What we build

leash

A robotics-oriented harness for simulation-first agent control and capability gating.

+

About Justin DiClemente

+

Justin DiClemente builds open-source tools for software development and agent workflows. His specdog projects explore structured specifications, graph-based code context, type-driven design, and Rust-based robotics tooling.

+

He is the creator of specdog, including Dotdog, Collar, Leash and Dogbench. Find Justin on GitHub.

Why it exists

AI agents work better when they can find exact names, relationships, states, and constraints without scanning long prose. specdog tools make that structure explicit while still keeping the source material readable.

Where to start

Start with the guide for the workflow, for agents for runtime instructions, or the blog for background writing.

+ + diff --git a/about/index.html b/about/index.html index 882fd57..1515dc3 100644 --- a/about/index.html +++ b/about/index.html @@ -5,8 +5,32 @@ About specdog - + + + - + + +
+ +
+
+ +
+ + + diff --git a/agents.html b/agents.html index 423fcef..a333f8c 100644 --- a/agents.html +++ b/agents.html @@ -5,71 +5,27 @@ For AI Agents | specdog - - + + + +
- +
+

For AI Agents

If you are an AI coding agent reading this page: follow these rules and you will not hallucinate on dotdog projects.

@@ -132,6 +88,7 @@

Type-driven design

Use the type-driven design workflow when implementing modeled entities and lifecycles. Define domain types, state-specific data, and operation signatures before function bodies. Use explicit failure types and exhaustive handling where the language supports them.

Parse external data into checked domain values; do not treat a type assertion as validation. Run the project's type checker, compile-failure checks for forbidden usage, and runtime tests. Spec completeness and graph compilation do not prove application type safety or runtime correctness.

+
Type-driven development guideREA/Ghidra guide

Commands reference

@@ -160,12 +117,12 @@

How to detect agent-ready projects

  • Optional removable hooks, with independent pinned CLI checks in CI
  • Application-specific compiler, runtime and integration tests
    • - - + + diff --git a/assets/dog.svg b/assets/dog.svg new file mode 100644 index 0000000..52ff391 --- /dev/null +++ b/assets/dog.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/assets/site.css b/assets/site.css new file mode 100644 index 0000000..c285f9f --- /dev/null +++ b/assets/site.css @@ -0,0 +1,144 @@ +:root { color-scheme: light; --ink: #1a1a2e; --muted: #5b6170; --amber: #f59e0b; --line: #e8e5dd; } + * { box-sizing: border-box; } + html { scroll-behavior: smooth; } + body { margin: 0; background: #fffdf8; color: var(--ink); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.6; } + a { color: #925006; text-underline-offset: 4px; } + a:hover { color: #6f3c00; } + button { font: inherit; cursor: pointer; } + a:focus-visible, button:focus-visible { outline: 3px solid #b45309; outline-offset: 5px; } + .skip-link { position: absolute; top: -80px; left: 20px; padding: 10px 16px; background: white; z-index: 2; } + .skip-link:focus { top: 12px; } + .site-header, main, footer { width: min(1080px, calc(100% - 64px)); margin: auto; } + .site-header { border-bottom: 1px solid var(--line); } + nav { display: flex; align-items: center; gap: 23px; padding: 23px 0; flex-wrap: wrap; } + nav a { text-decoration: none; color: var(--muted); font-size: 14px; font-weight: 500; } + nav .brand { margin-right: auto; font-size: 23px; font-weight: 750; letter-spacing: -.8px; color: var(--ink); } + .hero { display: grid; grid-template-columns: 1.4fr 1fr; gap: 72px; align-items: center; padding: 76px 0 60px; } + .release-link { display: inline-flex; gap: 12px; align-items: center; font-size: 13px; font-weight: 600; text-decoration: none; } + .release-link span { padding: 3px 10px; background: #fef0cd; border: 1px solid #eddaaa; border-radius: 99px; white-space: nowrap; } + h1 { font-size: clamp(44px, 5.7vw, 68px); line-height: 1.06; letter-spacing: -3px; margin: 23px 0; font-weight: 750; } + h1 span { color: #a65a00; } + .hero-copy > p { font-size: 18px; line-height: 1.65; color: var(--muted); max-width: 550px; margin: 0 0 27px; } + .btns { display: flex; gap: 12px; flex-wrap: wrap; } + .btn { display: inline-block; padding: 11px 20px; border-radius: 7px; font-size: 14px; font-weight: 650; text-decoration: none; border: 1px solid var(--line); background: #fff; color: var(--ink); } + .btn.primary { background: var(--amber); border-color: var(--amber); } + .btn:hover { background: #fef0cd; color: var(--ink); } + .btn.primary:hover { background: #e99400; } + .hero-copy .byline { margin: 17px 0 0; font-size: 12px; color: var(--muted); } + .dog-panel { text-align: center; padding: 27px 20px 22px; background: #fff8e9; border: 1px solid #eedfbd; border-radius: 16px; } + .eyebrow { font-size: 11px; letter-spacing: 1.8px; font-weight: 700; text-transform: uppercase; color: #78623c; margin: 0; } + .dog-widget { display: block; width: 166px; height: 166px; margin: 17px auto 0; border: 0; background: transparent; border-radius: 50%; } + #dog-svg { width: 150px; height: 150px; transition: transform .15s; } + #dog-status { min-height: 26px; font-size: 13px; color: #78623c; margin: 7px 0 17px; } + .actions { display: flex; justify-content: center; gap: 8px; flex-wrap: wrap; } + .actions button { background: #fffdf8; border: 1px solid #e7d7b4; color: #6f511f; padding: 5px 12px; border-radius: 99px; font-size: 12px; } + .actions button:hover { background: #fef0cd; } + .install { display: grid; grid-template-columns: 1fr 1.5fr; gap: 48px; align-items: start; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); padding: 32px 0; } + h2 { font-size: 27px; line-height: 1.25; letter-spacing: -.7px; margin: 0 0 10px; } + .section-copy { margin: 0; color: var(--muted); font-size: 14px; } + .terminal { background: #1e293b; color: #e2e8f0; border: 1px solid #334155; border-radius: 10px; overflow: hidden; } + .terminal-bar { display: flex; align-items: center; justify-content: space-between; padding: 8px 12px; border-bottom: 1px solid #334155; } + [role="tablist"] { display: flex; gap: 4px; } + [role="tab"] { border: 0; border-radius: 5px; padding: 4px 12px; color: #b6c3d5; background: transparent; font-size: 12px; } + [role="tab"][aria-selected="true"] { color: #fff; background: #3b485c; } + .copy-btn { border: 1px solid #526178; border-radius: 5px; padding: 3px 10px; color: #e2e8f0; background: transparent; font-size: 12px; } + .copy-btn:hover { background: #3b485c; } + .terminal pre { margin: 0; padding: 21px 20px; white-space: pre-wrap; overflow-wrap: anywhere; font-size: 13px; color: #93c5fd; } + .requirements { color: var(--muted); font-size: 12px; margin: 12px 0 0; } + .copy-status { font-size: 12px; color: #fcd38a; padding: 0 20px; } + .copy-status:empty { display: none; } + .features { padding: 56px 0; } + .section-heading { margin-bottom: 24px; } + .feature-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 28px; } + .feature { border-top: 2px solid #e5c785; padding-top: 18px; } + .feature .eyebrow { color: #925006; } + h3 { font-size: 19px; letter-spacing: -.35px; margin: 9px 0; } + .feature p:not(.eyebrow) { font-size: 14px; color: var(--muted); margin: 0 0 13px; } + .feature a { font-size: 13px; font-weight: 600; } + .resource-strip { display: flex; justify-content: space-between; align-items: center; gap: 25px; padding: 24px; background: #f6f4ee; border: 1px solid var(--line); border-radius: 10px; } + .resource-strip h2 { font-size: 20px; margin-bottom: 6px; } + .resource-links { display: flex; gap: 20px; flex-wrap: wrap; font-size: 13px; font-weight: 600; } + .family { padding: 48px 0; } + .family-heading { font-size: 12px; color: var(--muted); margin: 0 0 15px; } + .product-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 26px; } + .product-card a { font-size: 16px; font-weight: 700; text-decoration: none; } + .product-card p { margin: 5px 0 0; font-size: 13px; color: var(--muted); } + footer { display: flex; justify-content: space-between; gap: 18px; flex-wrap: wrap; padding: 22px 0 30px; border-top: 1px solid var(--line); font-size: 12px; color: var(--muted); } + footer p { margin: 0; } + footer a { color: var(--muted); } + @media (max-width: 800px) { + nav { gap: 15px; } + nav .brand { flex-basis: 100%; margin: 0; } + .hero { gap: 30px; padding: 44px 0; } + h1 { font-size: 48px; letter-spacing: -2px; } + .hero-copy > p { font-size: 16px; } + .install { grid-template-columns: 1fr; gap: 20px; } + .feature-grid { gap: 20px; } + .resource-strip { align-items: flex-start; flex-direction: column; } + } + @media (max-width: 560px) { + .site-header, main, footer { width: calc(100% - 40px); } + nav { gap: 10px 18px; padding: 18px 0; } + nav a { font-size: 12px; } + .hero { grid-template-columns: 1fr; gap: 28px; padding: 34px 0; } + h1 { font-size: 48px; } + .dog-panel { padding: 18px; } + .dog-widget { margin-top: 5px; height: 140px; } + #dog-svg { height: 130px; } + .feature-grid, .product-grid { grid-template-columns: 1fr; gap: 25px; } + .features { padding: 36px 0; } + .family { padding: 34px 0; } + .release-link { gap: 8px; font-size: 12px; } + } + @media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } #dog-svg { transition: none; } } + + nav a.active:not(.brand) { color: #925006; } + .page { max-width: 820px; padding: 52px 0 64px; } + .page h1 { font-size: clamp(34px, 5vw, 48px); line-height: 1.14; letter-spacing: -1.8px; margin: 0 0 20px; } + .page h2 { margin: 36px 0 14px; font-size: 25px; padding-top: 8px; } + .page h3 { margin: 26px 0 10px; } + .page p, .page li { color: var(--muted); } + .page p { margin: 0 0 18px; } + .page ul, .page ol { padding-left: 24px; } + .page li { margin: 8px 0; } + .page .eyebrow { color: #925006; margin-bottom: 14px; } + .page .lead, .page .dek, .page .intro, .page .tagline, .page .sub { font-size: 18px; line-height: 1.7; } + .page .meta, .page .muted { font-size: 13px; } + .page code { background: #f3efe5; padding: 2px 5px; border-radius: 4px; color: #6f511f; font-size: .88em; overflow-wrap: anywhere; } + .page pre { position: relative; background: #1e293b; color: #e2e8f0; padding: 22px 60px 22px 22px; margin: 20px 0; border-radius: 10px; overflow-x: auto; font-size: 13px; line-height: 1.7; } + .page pre code { color: #e2e8f0; background: none; padding: 0; font-size: inherit; overflow-wrap: normal; } + .page .code-wrap { position: relative; padding-top: 38px; margin: 20px 0; background: #1e293b; border-radius: 10px; } + .page .code-wrap pre { margin: 0; padding: 12px 22px 22px; border-radius: 0 0 10px 10px; } + .page .copy-btn { position: absolute; top: 10px; right: 10px; } + .page .copy-btn svg { width: 16px; height: 16px; } + .page .copy-status { color: #78623c; padding: 0; margin-top: 8px; } + .page table { width: 100%; border-collapse: collapse; margin: 22px 0; table-layout: fixed; } + .page th, .page td { text-align: left; padding: 12px; border-bottom: 1px solid var(--line); font-size: 14px; vertical-align: top; overflow-wrap: anywhere; } + .page th { color: var(--ink); background: #f6f4ee; font-weight: 650; } + .page td { color: var(--muted); } + .page blockquote, .page .callout, .page .explain { background: #fff8e9; border: 1px solid #eedfbd; border-left: 3px solid var(--amber); border-radius: 8px; padding: 18px 22px; margin: 24px 0; } + .page blockquote p:last-child, .page .callout p:last-child { margin-bottom: 0; } + .page .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(230px, 100%), 1fr)); gap: 18px; margin: 24px 0; } + .page .card, .page .post { border: 1px solid var(--line); background: #fffdf8; padding: 22px; border-radius: 10px; } + .page .card strong, .page .card > a { font-weight: 650; } + .page .card p { font-size: 14px; margin: 10px 0 0; } + .page .post { margin: 18px 0; } + .page .post h2 { padding: 0; margin: 8px 0 12px; } + .page .post > a { font-size: 20px; font-weight: 650; } + .page .post .meta { margin: 8px 0; } + .page .badge-row, .page .links, .page .actions, .page .demo-actions { display: flex; gap: 12px; align-items: center; flex-wrap: wrap; margin: 20px 0; } + .page .hero-art { display: block; width: 110px; height: 110px; margin: 0 0 24px; } + .page img { max-width: 100%; } + .page .button { display: inline-block; padding: 10px 18px; border: 1px solid var(--line); border-radius: 7px; color: var(--ink); background: #fff; font-weight: 650; font-size: 14px; text-decoration: none; } + .page .button.primary { background: var(--amber); border-color: var(--amber); } + .page .back { margin-top: 40px; } + .page hr { border: 0; border-top: 1px solid var(--line); margin: 32px 0; } + .page .reading-links { display: flex; flex-wrap: wrap; gap: 12px 24px; margin: 20px 0; } + @media (max-width: 560px) { + .page { padding-top: 34px; } + .page h1 { letter-spacing: -1px; } + .page th, .page td { padding: 8px 6px; font-size: 12px; } + .page .card, .page .post { padding: 18px; } + } + +nav .brand { display: inline-flex; align-items: center; gap: 8px; } diff --git a/assets/site.js b/assets/site.js new file mode 100644 index 0000000..0a57b74 --- /dev/null +++ b/assets/site.js @@ -0,0 +1,35 @@ +(() => { + async function copyBlock(button) { + const pre = button.closest('.code-wrap')?.querySelector('pre'); + if (!pre) return; + try { + await navigator.clipboard.writeText(pre.textContent); + button.textContent = 'Copied'; + button.setAttribute('aria-label', 'Code copied'); + } catch { + button.textContent = 'Select code'; + button.setAttribute('aria-label', 'Clipboard unavailable; select the code to copy'); + } + setTimeout(() => { button.textContent = 'Copy'; button.setAttribute('aria-label', 'Copy code'); }, 2000); + } + window.copyBlock = copyBlock; + document.querySelectorAll('.page pre').forEach(pre => { + let wrap = pre.parentElement; + if (!wrap.classList.contains('code-wrap')) { + wrap = document.createElement('div'); + wrap.className = 'code-wrap'; + pre.before(wrap); + wrap.append(pre); + } + let button = wrap.querySelector('.copy-btn'); + if (!button) { + button = document.createElement('button'); + button.className = 'copy-btn'; + button.type = 'button'; + button.addEventListener('click', () => copyBlock(button)); + wrap.append(button); + } + button.textContent = 'Copy'; + button.setAttribute('aria-label', 'Copy code'); + }); +})(); diff --git a/blog.html b/blog.html index 4b3c267..89f61a8 100644 --- a/blog.html +++ b/blog.html @@ -3,62 +3,43 @@ -Blog | specdog - - - +From the pack | specdog + + + + + + +
    -
    -

    Blog

    -

    Notes on spec-driven development, agent-readable documentation, and the tooling around dotdog, collar, leash, and dogbench.

    -
    Dotdog Workspaces: One Graph for N Repos
    workspace manifests, repo graphs, and agent context
    -
    Agent-First Documentation — The New Standard
    specs, documentation, and agent workflows
    -
    Google's Agentic Resource Discovery Is the Missing Layer of the Agent Internet
    agent discovery, structured resources, and MCP
    -
    Karpathy's LLM OS Needs a Brain. Here's What That Looks Like.
    LLM operating systems, entity graphs, and memory
    +
    +
    +

    Notes / Research and products

    +

    From the pack

    + +

    Notes from the pack: practical workflows, product architecture, and research with its limits left intact.

    + + + + + +
    + diff --git a/blog/agent-first-documentation/index.html b/blog/agent-first-documentation/index.html index 1a19a50..66d98f5 100644 --- a/blog/agent-first-documentation/index.html +++ b/blog/agent-first-documentation/index.html @@ -6,43 +6,27 @@ Agent-First Documentation — The New Standard | specdog - + - + + + +
    +
    +
    spec-driven documentation

    Agent-First Documentation — The New Standard

    @@ -52,5 +36,11 @@

    Agent-First Documentation — The New Standard

    For agents: start with /agents, then use /handbook, /sitemap.xml, and /llms.txt to discover the project surface.

    ← Back to blog

    +
    + + diff --git a/blog/collar-graph-backed-agents/index.html b/blog/collar-graph-backed-agents/index.html new file mode 100644 index 0000000..8456650 --- /dev/null +++ b/blog/collar-graph-backed-agents/index.html @@ -0,0 +1,53 @@ + + + + + +Collar: graph-backed context is not the whole agent | specdog + + + + + + + + + +
    + +
    +
    +

    From the pack / Product notes

    +

    Collar: graph-backed context is not the whole agent

    +

    · By Justin DiClemente

    +

    Dotdog prepares queryable project context. Collar is a separate agent harness that consumes graph-backed guidance while coordinating model and tool interactions.

    +

    The problem is context assembly

    +

    A coding agent needs more than a long system prompt. It needs the right project rules, current artifacts and tool results for the task at hand. Collar organizes behavioral guidance around .dag representations rather than treating every document as undifferentiated prose.

    +

    The current project README describes graph-backed system/skill loading, model routing and persistent session state. These are the project's documented capabilities; this article is not an independent reproduction of its model-provider behavior.

    +

    How it differs from Dotdog

    +
    CommandWhen to use
    DotdogCollar
    Compile/import/query specs and code evidence.Run the agent conversation and tool workflow.
    CLI plus local stdio MCP.Interactive/headless harness with configured model providers.
    No model account needed for local graph operations.Provider setup and authorization depend on the chosen backend.
    +

    Use Dotdog with your existing agent host when graph context is all you need. Evaluate Collar when you specifically want its harness behavior. Neither requires turning the other into a hosted platform.

    +

    Read the graph, verify the action

    +

    A compact representation can reduce an input payload on a particular task, but that does not establish better answers or lower total cost. Model choice, retries, tool calls and output length all affect a run. We are not carrying old compression figures or router timings onto the website without a reproducible, scoped comparison.

    +

    Graph text is also data, not blanket execution authority. Follow repository instructions, inspect evidence freshness and keep independent application tests in the loop.

    +

    Start with the actual project

    +

    Review Collar's installation instructions, supported providers and security guidance before connecting accounts or tools. Keep credentials out of graph exports and published benchmark logs.

    +

    Credits

    +

    Collar is a specdog project by Justin DiClemente. It is forked from NousResearch/hermes-agent; the upstream work and license attribution remain part of the project.

    +
    Collar overviewDotdog agent setupSource and issues
    +
    + + + diff --git a/blog/dogbench-measurement/index.html b/blog/dogbench-measurement/index.html new file mode 100644 index 0000000..fdcfd14 --- /dev/null +++ b/blog/dogbench-measurement/index.html @@ -0,0 +1,49 @@ + + + + + +Dogbench: measure runs, not promises | specdog + + + + + + + + + +
    + +
    +
    +

    From the pack / Product notes

    +

    Dogbench: measure runs, not promises

    +

    · By Justin DiClemente

    +

    A smaller prompt is an observation. A cheaper or better development workflow is a separate claim. Dogbench exists to explore those measurements.

    +

    Compare complete runs

    +

    The Dogbench repository describes a local harness for collecting usage from available agent clients and comparing tasks. Treat it as experimental tooling, not a public leaderboard or proof that one harness always wins.

    +

    For a useful comparison, pin the task and input revision, model/provider, runtime, permissions and cache state. Include retries, tool traffic and output tokens rather than reporting only the initial context. Mark unavailable usage as unavailable; do not turn it into a zero.

    +

    Correctness comes before a savings percentage

    +

    A fast result that omits the relevant relationship or fails the task is not an improvement. Check the returned facts or task outcome, repeat runs and retain the variance. Do not mix tokenizer counts, byte-based estimates and provider billing units.

    +

    The Dotdog release comparison follows a narrower method: same-source builds, stated warm-cache conditions, repeated workflow timings and unchanged-result checks. It does not establish coding-agent productivity or general cloud cost savings.

    +

    No synthetic scoreboards

    +

    We are not publishing sample dollar amounts as live customer results. Dogbench's older README examples are illustrative and are not used as evidence for website claims. Its full current comparison/provider surface has not been independently reproduced by this website update.

    +

    Before sharing a run, review outputs for prompts, local paths, account identifiers and credentials. Prefer a sanitized report with the exact scope over raw session logs.

    +
    Dogbench overviewSourceResearch and evidence boundaries
    +
    + + + diff --git a/blog/dotdog-1-research/index.html b/blog/dotdog-1-research/index.html new file mode 100644 index 0000000..bd344dd --- /dev/null +++ b/blog/dotdog-1-research/index.html @@ -0,0 +1,59 @@ + + + + + +Specs, types, and graphs: the Dotdog 1.0 research | specdog + + + + + + + + + +
    + +
    +
    +

    From the pack / Product notes

    +

    Specs, types, and graphs: the Dotdog 1.0 research

    +

    · By Justin DiClemente

    +

    Specs, types, and graphs solve different problems. The useful part is connecting them without turning partial evidence into a promise.

    +

    Start with three separate questions

    +
    QuestionArtifactLimit
    What should the system do?Authored specificationA clear rule may still be wrong or unimplemented.
    Which states and interfaces can code represent?Types and compiler diagnosticsOnly encoded constraints are checked; untrusted runtime input still needs parsing.
    How do artifacts and observations connect?Graphs with source/evidence identitiesMissing or truncated relationships do not prove independence.
    +

    Dotdog 1.0 keeps those roles distinct. Specs hold intent, repository extraction records a bounded view of code, and imported type/native graphs retain the evidence behind their relationships. We did not add another database or make a compiler mandatory for ordinary graph use.

    +

    New research: intent helps, but maintenance still costs

    +

    Agarwal and colleagues' October revision of Spec-Driven Development as Prescribed and as Practiced studies public artifacts, practitioner discussions and interviews. Participants reported more reliable agent behavior alongside added planning/review work; the authors also identify specification decay and differences between individual and team adoption. This is an empirical preprint, not a controlled validation of Dotdog.

    +

    Our design implication is to preserve intent and source evidence separately, make freshness inspectable, and keep checks reproducible. A completeness score is not a substitute for runtime tests or ongoing review.

    +

    New compiler APIs do not mean automatic compatibility

    +

    Microsoft's October 20 TypeScript 7.1 beta announcement introduces separate synchronous/asynchronous compiler entry points and snapshot-based updates. Its examples also make resource disposal explicit. This is relevant future adapter work, not a reason to silently replace the interface a released tool actually tested.

    +

    Dotdog 1.0 supports a trusted project-installed TypeScript 7.0.2 compiler through its version-specific unstable/sync API. It retains original project settings and diagnostics in a bounded Node worker. Other compiler versions and unsupported project configurations fail explicitly. The beta was researched separately; it is not a required dependency or a claimed supported version.

    +

    Specs remain useful outside one tool

    +

    GitHub Spec Kit's extension model allows additional commands and integrations while keeping their behavior and governance explicit. Dotdog reuses that boundary with an optional community extension for local import, inspection and stdio MCP access. It does not replace Spec Kit's workflow or require a new hosted service.

    +

    What we actually checked

    +

    The 1.0 release record links the approved source, retained npm archive, checksums and publisher. The final implementation suite passed 133 tests and 2,124 assertions. Fresh npm/Bun registry consumers exercised spec refresh, context/impact, real compiler invalid/repair behavior, evidence-tamper rejection, REA import/path and real stdio MCP.

    +

    The separate research findings preserve earlier prototype failures and historical compiler/corpus checkpoints. A broken legacy extractor was not relabeled a production success. The published adapter uses the separately tested compiler interface.

    +

    What we have not established

    +

    These checks do not measure coding-agent productivity, whole-program semantic closure or general cost savings. Authenticated model-driven Claude invocation/edit-refresh remains unverified. Type success does not prove business requirements; saved native references do not prove runtime equivalence.

    +

    That is why the old dogfood dashboard is no longer a live-status claim. Versioned inputs, exact checks and retained failure boundaries are more useful than unqualified green numbers.

    +

    Try the workflows

    +
    Type-driven development guideREA/Ghidra graph guideUpgrade to 1.0
    +

    Further reading: technical thesis, historical thesis PDF, and measured performance scope.

    +
    + + + diff --git a/blog/dotdog-workspace-bridge/index.html b/blog/dotdog-workspace-bridge/index.html index a5ee19b..6093f9b 100644 --- a/blog/dotdog-workspace-bridge/index.html +++ b/blog/dotdog-workspace-bridge/index.html @@ -6,52 +6,27 @@ Dotdog Workspaces: One Graph for N Repos | specdog - + - + + + + +
    +
    +
    dotdog update

    Dotdog Workspaces: One Graph for N Repos

    @@ -115,5 +90,11 @@

    What comes next

    ← Back to blog

    +
    + + diff --git a/blog/google-ard-dotdog/index.html b/blog/google-ard-dotdog/index.html index 4a435f2..8192db0 100644 --- a/blog/google-ard-dotdog/index.html +++ b/blog/google-ard-dotdog/index.html @@ -3,54 +3,38 @@ -Agentic Resource Discovery and dotdog | specdog - - - - - + + +
    -
    -
    agent discovery
    -

    Agentic Resource Discovery and dotdog

    -

    Why agent discovery needs clean indexes, machine-readable metadata, and stable resource maps.

    -

    specdog blog

    -

    Agents need to find the right resource before they can reason about it. A human can tolerate a messy site by guessing, searching, or clicking around. An agent works better when the site declares its important pages directly.

    That is the practical value of agentic resource discovery: give models and tools a stable map of what exists, what each page means, and where the canonical source lives.

    What discovery requires

    Discovery starts with crawlable pages and stable URLs. It improves with canonical links, page descriptions, sitemap coverage, and a concise llms.txt that names the project surfaces in plain language.

    The goal is not keyword stuffing. The goal is consistency. If dotdog is the spec compiler, collar is the DAG-first harness, leash is the robotics harness, and dogbench is the benchmark surface, every public index should say that in the same way.

    Where dotdog fits

    dotdog gives projects a structured source of truth. The website then exposes that source of truth to humans, search engines, and generative engines. This makes the site easier to cite, easier to crawl, and easier for an agent to use as a starting point.

    -
    For agents: start with /agents, then use /handbook, /sitemap.xml, and /llms.txt to discover the project surface.
    -

    ← Back to blog

    -
    +
    +
    +

    Field guide / Practical workflows

    +

    Archived article

    + +

    This older opinion piece is no longer part of the current product guidance.

    Read the current product notes or source-backed research.

    +
    + diff --git a/blog/index.html b/blog/index.html index 79161bb..b775c5c 100644 --- a/blog/index.html +++ b/blog/index.html @@ -5,8 +5,32 @@ Blog | specdog - + + + - + + +
    + +
    +
    + +
    + + + diff --git a/blog/karpathy-wiki-brain/index.html b/blog/karpathy-wiki-brain/index.html index 38be4b0..8192db0 100644 --- a/blog/karpathy-wiki-brain/index.html +++ b/blog/karpathy-wiki-brain/index.html @@ -3,54 +3,38 @@ -Project Memory for LLM Systems | specdog - - - - - + + +
    -
    -
    LLM systems
    -

    Project Memory for LLM Systems

    -

    A concise argument for entity graphs, specs, and memory-like structure around LLM operating systems.

    -

    specdog blog

    -

    An LLM operating system needs more than chat history. It needs a durable map of entities, relationships, constraints, and actions. Without that map, every task begins with rediscovery.

    A project memory layer should tell the model what the important things are, how they connect, and which surface is authoritative. That is a different job from autocomplete or summarization.

    Why graphs help

    Entity graphs reduce ambiguity. Instead of asking a model to scan a pile of prose and infer relationships, the project can expose names, links, states, and constraints directly. The agent can then spend less context on navigation and more context on the actual task.

    This is the reason specdog leans on .dog files and compiled .dag graphs. The graph is not decoration; it is the operational map.

    The site as memory surface

    A public site can participate in that memory layer if it is cleanly structured. The homepage names the product family. The about page explains the purpose. The handbook teaches the workflow. The agent page gives runtime instructions. The blog gives background. The sitemap and llms.txt make those pages easier to discover.

    -
    For agents: start with /agents, then use /handbook, /sitemap.xml, and /llms.txt to discover the project surface.
    -

    ← Back to blog

    -
    +
    +
    +

    Field guide / Practical workflows

    +

    Archived article

    + +

    This older opinion piece is no longer part of the current product guidance.

    Read the current product notes or source-backed research.

    +
    + diff --git a/blog/leash-control-boundaries/index.html b/blog/leash-control-boundaries/index.html new file mode 100644 index 0000000..a0bdf0a --- /dev/null +++ b/blog/leash-control-boundaries/index.html @@ -0,0 +1,53 @@ + + + + + +Leash: keep the agent separate from device authority | specdog + + + + + + + + + +
    + +
    +
    +

    From the pack / Product notes

    +

    Leash: keep the agent separate from device authority

    +

    · By Justin DiClemente

    +

    A language model can propose an action. A robotics runtime must decide whether that action is allowed to reach a device. Leash keeps that boundary explicit.

    +

    A different product, a different responsibility

    +

    Leash is a Rust robotics runtime with CLI, HTTP and MCP interfaces. Its current documentation describes simulation/replay, typed telemetry, bounded navigation, scoped agent capabilities and feature-gated hardware adapters.

    +

    This is separate from Dotdog's spec/code graph tooling. Dotdog's optional type and REA workflows do not require robotics, a simulator, sensors or a provisioned cloud account.

    +

    One control boundary

    +

    Leash's documented architecture routes requests through the runtime before a robot adapter receives a command. Planners, ROS 2 providers, model outputs and CUDA results supply requests or evidence; they do not become an additional motor writer.

    +

    Depending on the physical operation, the documented checks include authorization, approval, ownership, freshness, deadman state, collision/distance limits, Stop and E-stop. Those are implementation boundaries to inspect and test, not a blanket certification that a robot is safe in every environment.

    +

    Start without hardware

    +

    The project's simulation entry points let a developer inspect command/telemetry behavior without actuating a physical robot. Follow the current quickstart and distinguish a simulation result from hardware evidence.

    +

    Record the runtime revision, configuration, inputs and observed stop behavior when evaluating a workflow. A replay that matches a recorded run is useful evidence about that case, not proof of every future physical condition.

    +

    Types help connect the pieces

    +

    Typed control and sensor contracts make units, states and expected fields explicit. Runtime checks are still required for stale observations, authorization and device faults. This is the same separation used in type-driven software development: representable states, runtime input checks and behavioral evidence each do different work.

    +

    What this article does not claim

    +

    This is a source-backed product overview, not a new hardware trial, field certification or reproduction of every ROS/CUDA configuration. Consult the repository's actual adapter-specific evidence before making a physical-deployment decision.

    +
    Leash overviewRuntime documentationContribute
    +
    + + + diff --git a/collar.html b/collar.html index d5fa6a3..4721ae2 100644 --- a/collar.html +++ b/collar.html @@ -4,72 +4,36 @@ collar — DAG-first agent harness | specdog - - - + + + +
    - +
    +
    Friendly robot wearing a specdog collar

    collar

    -

    DAG-first AI agent harness — Entity→Target:verb(card). Reads .dag files. Rust router at 3ms.

    +

    DAG-first AI agent harness — Entity→Target:verb(card). Reads .dag files for graph-backed context.

    - v1.4.0 + Latest published Collar release MIT Python 3.11+ Semver 2.0.0 @@ -113,20 +77,20 @@

    Architecture

    Projects*.dagJSON v2/v3MCP dotdog -

    Key Numbers

    - - - - -
    95% compression383k → 17k (skills)
    74% compression15k → 4k (system prompt)
    0 legacy refs6974+ renamed
    - +

    Evaluate the workflow

    +

    Compare complete runs, task correctness, model/provider settings and repeated measurements before making token or timing claims. Compression of one artifact is not proof of lower total cost or better agent outcomes.

    +

    Read the Collar product notes for its relationship to Dotdog and the evidence boundaries.

    Links

    GitHub · dotdog · specdog org

    +
    + - diff --git a/dogbench.html b/dogbench.html index b342c54..93913df 100644 --- a/dogbench.html +++ b/dogbench.html @@ -3,33 +3,41 @@ -Redirecting to specdog - - - - +Dogbench | specdog + + + + + + + +
    -

    Redirecting to specdog.

    - +
    +
    +

    Field guide / Practical workflows

    +

    Dogbench

    + +

    Experimental local tooling for agent usage comparisons. No public scoreboard, guaranteed savings, or model-quality ranking.

    +

    Dogbench collects usage from supported agent clients and explores token, timing and cost comparisons. Check the current source and setup requirements before running it; provider-backed runs can incur usage charges.

    +

    What a useful report needs

    +

    The website has not independently reproduced the complete Dogbench provider/comparison surface. Older README sample numbers are not live results.

    +
    Measurement guideGitHubScoped Dotdog release measurements
    +
    + diff --git a/dogbench/index.html b/dogbench/index.html index b342c54..32ab660 100644 --- a/dogbench/index.html +++ b/dogbench/index.html @@ -3,33 +3,41 @@ -Redirecting to specdog - - - - +Dogbench | specdog + + + + + + + +
    -

    Redirecting to specdog.

    - +
    +
    +

    Field guide / Practical workflows

    +

    Dogbench

    + +

    Experimental local tooling for agent usage comparisons. No public scoreboard, guaranteed savings, or model-quality ranking.

    +

    Dogbench collects usage from supported agent clients and explores token, timing and cost comparisons. Check the current source and setup requirements before running it; provider-backed runs can incur usage charges.

    +

    What a useful report needs

    +

    The website has not independently reproduced the complete Dogbench provider/comparison surface. Older README sample numbers are not live results.

    +
    Measurement guideGitHubScoped Dotdog release measurements
    +
    + diff --git a/dogfood.html b/dogfood.html index 20ca5af..820e06d 100644 --- a/dogfood.html +++ b/dogfood.html @@ -3,179 +3,39 @@ -dotdog Dogfood Dashboard - - - + + + +
    - -

    dotdog Dogfood 🐕

    -

    dotdog validates itself. This page shows real output from running dotdog on its own spec. No mock data. No demos. The tool eating its own dogfood.

    - -
    -
    -
    7
    -
    .dog files
    -
    -
    -
    100%
    -
    complete
    -
    -
    -
    8
    -
    nodes in .dag
    -
    -
    -
    94%
    -
    token savings
    -
    -
    -
    28/28
    -
    tests passing
    -
    -
    -
    6/6
    -
    simulate
    -
    -
    - -

    Spec Files

    -
    - SPEC.dog - data-model.dog - constitution.dog - DESIGN-SYSTEM.dog - plan.dog - INDEX.dog - COPY.dog -
    - -

    Compile

    -
    8563 → 512 tokens (94% savings)
-8 nodes, 4 edges
-8051 tokens saved
    - -
    - dotdog savings badge -
    - -

    Predictions

    - -
    -
    ✅ Correct
    -
    .dag token savings exceed 90%
    -
    90% confidence — verified at 94% actual
    -
    - -
    -
    ✅ Correct
    -
    First external dotdog adopter
    -
    50% confidence — community contributors merged
    -
    - -
    -
    ⏳ Pending
    -
    dotdog reaches 200 PRs by July 2026
    -
    80% confidence — tracking at current velocity
    -
    - -

    Simulation

    -
    Scenario: Node, Task, Prediction → Compile → DAG
-
-[1/6] Write Node, Task, and Prediction specs       ✓
-[2/6] Compile parses entities into a DAG graph     ✓
-[3/6] DAG has token savings exceeding prediction   ✓
-[4/6] Validate Task and Node completeness at 100%  ✓
-[5/6] Prediction list shows forecasts with status  ✓
-[6/6] DAG served via MCP to AI agents              ✓
-
-RESULT: Success (6/6 steps passed)
    - -

    The Pipeline

    -
    -.spec files → dotdog validate  → 100% complete
-            → dotdog compile   → 94% savings
-            → dotdog simulate   → 6/6 passed
-            → dotdog staleness  → spec matches reality
-            → dotdog badge      → shields.io SVG
-            → dotdog serve      → AI agents query specs
    - -

    For AI Agents

    -

    This page's data comes from dotdog commands. An AI agent can query the same data via MCP:

    -
    getEntity("Node")    → exact properties
-traverse("DAG", 2)   → full compile graph
-search("Prediction") → all predictions
    -

    Read the for agents page for setup instructions.

    - +
    +
    +

    Release evidence

    +

    From dogfood to reproducible checks.

    +

    The old dashboard has been retired. Its fixed counts and savings figures were not a live verification feed.

    +

    Use the published release record, source CI and reproducible guides instead. They state the version, inputs, checks and limitations.

    +
    1.0 release evidenceResearch and findingsPractical guides
    +
    - + diff --git a/dotdog.html b/dotdog.html index 1f0fcd3..f32a21f 100644 --- a/dotdog.html +++ b/dotdog.html @@ -6,36 +6,31 @@ dotdog | specdog - + + + + +
    +
    +
    + +
    + diff --git a/dotdog/index.html b/dotdog/index.html index 6a487e2..c7c50c5 100644 --- a/dotdog/index.html +++ b/dotdog/index.html @@ -5,63 +5,27 @@ dotdog — CLI and MCP tooling | specdog - - + + + +
    - +
    +
    specdog dog logo

    dotdog

    @@ -105,7 +69,11 @@

    Capabilities

    Links

    npm · GitHub · guide

    +
    + - diff --git a/github.html b/github.html index 6ad6757..a709a0d 100644 --- a/github.html +++ b/github.html @@ -7,29 +7,31 @@ - + + + + +
    -

    Redirecting to For AI Agents.

    +
    +
    +

    Redirecting to For AI Agents.

    +
    + diff --git a/github/index.html b/github/index.html index 6ad6757..a709a0d 100644 --- a/github/index.html +++ b/github/index.html @@ -7,29 +7,31 @@ - + + + + +
    -

    Redirecting to For AI Agents.

    +
    +
    +

    Redirecting to For AI Agents.

    +
    + diff --git a/guides/rea-graphs/index.html b/guides/rea-graphs/index.html new file mode 100644 index 0000000..100ae0f --- /dev/null +++ b/guides/rea-graphs/index.html @@ -0,0 +1,65 @@ + + + + + +REA and Ghidra graphs with Dotdog | specdog + + + + + + + + + +
    + +
    +
    +

    Field guide / Practical workflows

    +

    REA and Ghidra graphs with Dotdog

    + +

    Use Dotdog to navigate saved native call relationships. SolidState/REA owns Ghidra analysis; Dotdog imports the evidence and answers bounded graph questions.

    +
    Try the public fixtureQuery a pathUse your own analysisInterpret coverage
    +

    What each tool does

    +
    ToolResponsibility
    Ghidra through SolidState/REASelect the target, analyze functions, produce native-call evidence and manage the analysis session.
    DotdogImport a saved NativeCallGraph body, preserve provenance and query paths, context and impact.
    YouChoose the correct artifact and producer direction, review coverage and decide which conclusions the evidence supports.
    +

    Dotdog is not another decompiler and never launches the analyzed binary. Importing a saved graph does not require a running Ghidra session.

    +

    1. Download a versioned, public export

    +

    The release fixture records a resolved call from _dotdog_validate to _dotdog_scale. Its original static-analysis check preserved the binary digest and did not execute it.

    +
    mkdir rea-guide
+cd rea-guide
+curl -fsSL https://raw.githubusercontent.com/specdog/dotdog/v1.0.0/examples/native/callgraph-ghidra.json -o native-calls.json
+shasum -a 256 native-calls.json
    +

    The export SHA-256 must be 5fc1e4c996fa5608b4ea4fedb000c6be5b9afc0fe78bf79749e9553b863c7ad2. That identifies the JSON export, not the binary. The separate binary digest below belongs to the recorded build.

    +

    2. Import with explicit direction and identity

    +
    npx dotdog@1.0.0 graph import native-calls.json --format rea-callgraph --project native --rea-direction forward --artifact-sha256 472ee07be89864cb67ded8c7cd1de7f211bfdc34bb04968f417d4801c5e1b201
    +

    Expect two imported nodes and one edge in .doghouse/imported/native.dag. Use --rea-direction backward only for a backward producer request. The bare export does not encode direction, and guessing can reverse call meaning.

    +

    3. Ask a bounded graph question

    +
    npx dotdog@1.0.0 path '0x100000340' '0x100000328' --dag .doghouse/imported/native.dag --json
+npx dotdog@1.0.0 context '0x100000340' --dag .doghouse/imported/native.dag --json
+npx dotdog@1.0.0 impact '0x100000328' --dag .doghouse/imported/native.dag --json
    +

    The path is one caller → callee hop. Addresses and identities refer to this exact build, not every recompilation. Imported projects are also available through the existing dotdog serve stdio MCP server.

    +

    4. Bring your own saved REA analysis

    +
    1. Select a binary you are authorized to analyze and record its SHA-256.
    2. Use your configured solidstate reverse workflow for Ghidra analysis. Select a function, direction and depth; save the returned NativeCallGraph body and the request settings.
    3. Keep raw provider responses private until reviewed: they can contain local paths and unrelated evidence. An arbitrary REA Evidence envelope is not a supported import body.
    4. Import the reviewed body with its actual direction and binary digest. If no binary digest is available, Dotdog scopes identities to export bytes and reports binary identity as unknown.
    5. Check identifiers, coverage, unresolved/external calls and truncation before drawing conclusions. Re-import new evidence after changing the target or analysis.
    +

    For the configured-host Ghidra reproduction and recorded evidence, see the public native fixture. This guide does not install a provider or create a second REA integration.

    +

    What the graph does not prove

    +

    Ghidra exposes function and call-reference APIs, but the export's resolved references are not complete runtime behavior. Indirect calls, unresolved functions, thunks and external targets need explicit interpretation.

    +

    A bounded no_path means no connection was found in the supplied graph within the search bounds. It does not prove two procedures are independent. Preserve maxHops, truncated, coverage and limitations in any report.

    +

    There is no automatic source-to-binary join or requirement proof. Use explicit reviewed mappings if you connect native evidence to specs, source code or tests.

    +
    + + + diff --git a/guides/type-driven-development/index.html b/guides/type-driven-development/index.html new file mode 100644 index 0000000..ce65566 --- /dev/null +++ b/guides/type-driven-development/index.html @@ -0,0 +1,91 @@ + + + + + +Type-driven development with Dotdog | specdog + + + + + + + + + +
    + +
    +
    +

    Field guide / Practical workflows

    +

    Type-driven development with Dotdog

    + +

    Start with the states and operations your domain permits. Use the compiler to reject invalid combinations, then keep the resulting contracts connected to spec and test evidence.

    +
    Model the domainInspect and queryTry an invalid callKnow the limits
    +

    What type-driven development means here

    +

    Specs describe the intended rule. Types express the parts your language can enforce. Graphs connect those artifacts for navigation. Test-driven development is a separate practice; spelling out “type-driven” avoids confusing the two uses of TDD.

    +

    This walkthrough uses a small order workflow. A shipped order needs tracking data, and only a paid order can be passed to the shipping operation. It does not arrange delivery or prove a payment happened.

    +

    1. Use a compatible project

    +

    Dotdog's optional adapter requires Node.js 22.12+ and a trusted project-installed TypeScript 7.0.2. Core Dotdog does not require a compiler. If your application uses another version, use a separate scratch project rather than changing its compiler for this guide.

    +
    mkdir type-guide
+cd type-guide
+npm init -y
+npm install --save-dev typescript@7.0.2
+mkdir src

    Create tsconfig.json with:

    {
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "target": "ES2022",
+    "module": "NodeNext"
+  },
+  "include": ["src/**/*.ts"]
+}
    +

    2. Model valid states before implementation

    +

    Create src/order.ts:

    export type Draft = { state: "draft"; id: string };
+export type Paid = { state: "paid"; id: string; receipt: string };
+export type Shipped = {
+  state: "shipped";
+  id: string;
+  receipt: string;
+  tracking: string;
+};
+export type Order = Draft | Paid | Shipped;
+
+export function ship(order: Paid, tracking: string): Shipped {
+  return { ...order, state: "shipped", tracking };
+}
    +

    The discriminant keeps receipt and tracking fields with the states that require them. A collection of unrelated booleans and optional fields would permit more invalid combinations. See TypeScript's discriminated-union documentation.

    +

    3. Inspect, save, and query a selected contract

    +
    npx dotdog@1.0.0 types inspect Order --file src/order.ts --project tsconfig.json --json > order-contract.json &&
+npx dotdog@1.0.0 graph import order-contract.json --project types
+npx dotdog@1.0.0 context 'src/order.ts#Paid' --dag .doghouse/imported/types.dag --json
+npx dotdog@1.0.0 impact 'src/order.ts#Paid' --dag .doghouse/imported/types.dag --json
+npx dotdog@1.0.0 graph audit --dag .doghouse/imported/types.dag --profile evidence --json
    +

    Only import a successful inspection: the shell's && prevents importing failed compiler output. Expect an ok: true inspection, an imported graph, and explicit partial coverage. Impact describes references in this selected graph, not every call site in your application.

    +

    Saved node evidence retains compiler/configuration/input identities. After changing source, configuration, compiler or dependencies, inspect again and replace the saved graph. A freshness audit checks recorded inputs; it cannot discover every new or unloaded file.

    +

    4. Try a call the compiler must reject

    +

    Create src/invalid.ts:

    +
    import { ship, type Draft } from "./order.js";
+
+const draft: Draft = { state: "draft", id: "order-1" };
+ship(draft, "TRACK-1");
    npx dotdog@1.0.0 types inspect Order --file src/order.ts --project tsconfig.json --json
    +

    The configured project now fails checking and Dotdog exits nonzero. Repair the example by passing a Paid value with a receipt, then repeat inspection. Keep negative compile checks alongside runtime and integration tests in real applications.

    +

    5. Keep the boundaries honest

    + +

    For supported aliases, processing bounds and evidence limitations, read the full type-contract reference. For the design rationale and newer compiler research, read the research notes.

    +
    + + + diff --git a/handbook.html b/handbook.html index 11fe38f..ef23941 100644 --- a/handbook.html +++ b/handbook.html @@ -5,71 +5,27 @@ Spec-Driven Development | specdog - - + + + + + +
    +
    +

    Spec-Driven Development

    Spec-Driven Development (SDD) is a methodology that makes software specs the ground truth for AI coding agents. Instead of the agent reading prose and guessing, it queries a compiled knowledge graph.

    @@ -89,6 +45,8 @@

    The DAG: a compressed index, not a summary

    A .dag is an index of the compiled model, not a replacement for source evidence or tests. Prefer bounded context, impact and path queries over loading every artifact.

    Spec graphs retain entities, properties, states, lifecycles, relationships and descriptions. Imported and observed graphs carry their own identities, provenance and coverage. Missing edges and truncated queries do not prove independence.

    +

    Practical field guides

    +
    Type-driven development

    Model states, inspect a selected TypeScript contract, query its graph, and reject invalid usage.

    REA and Ghidra graphs

    Import a versioned native-call export and follow its evidence without running the binary.

    The practice

    1. Specify — write .dog files: entities with properties, states, lifecycles, and relationships
      2. @@ -183,12 +141,12 @@

      Further reading

    2. For AI Agents: how to work with dotdog projects
    3. Martin Fowler on SDD
      4. - - +
    + diff --git a/homebrew.html b/homebrew.html index b759588..663c794 100644 --- a/homebrew.html +++ b/homebrew.html @@ -4,69 +4,34 @@ dotdog — Homebrew - - + + + +
    -

    dotdog / Homebrew

    -

    macOS-native install. No config.

    +
    +
    +

    Dotdog / Homebrew

    +

    A separately maintained distribution; verify the formula version before installing.

    brew tap specdog/dotdog
 brew install dotdog
 dotdog --version
    +

    The existing formula pins Dotdog 0.3.5. It is not the 1.0 distribution. For current Dotdog 1.0 use npm or Bun; do not assume the tap has been upgraded.

    What this does

    Downloads dotdog from npm. Installs globally via Homebrew. Depends only on Node.js.

    @@ -80,7 +45,11 @@

    Formula

    ← Back to specdog
    +
    + - diff --git a/index.html b/index.html index 49fd01e..4f2cb72 100644 --- a/index.html +++ b/index.html @@ -6,117 +6,24 @@ specdog — Feed the dog. Ship with specs. - + - + + +