From daf1e6295d2d8b6835a97fac74b7373aa819871b Mon Sep 17 00:00:00 2001 From: Justin Diclemente Date: Sat, 31 Oct 2026 19:38:18 -0400 Subject: [PATCH 1/8] docs: add researched type-driven design workflow --- README.md | 2 ++ about.html | 1 + agents.html | 4 ++++ handbook.html | 36 +++++++++++++++++++++++++++++++++++- index.html | 2 +- 5 files changed, 43 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4ede8cd..d2c61a8 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ > Feed the dog. Ship with specs. +[Guide](https://specdog.github.io/handbook) — spec-driven development with [type-driven design](https://specdog.github.io/handbook#type-driven-design): domain types, valid states, operation contracts, and checked runtime boundaries. + **[dotdog](https://specdog.github.io/dotdog)** — structured, AI-queryable specs. [npm](https://npmjs.com/package/dotdog) | [GitHub](https://github.com/specdog/dotdog) **[dogbench](https://specdog.github.io/dogbench)** — token-savings benchmark for Collar and dotdog. [GitHub](https://github.com/specdog/dogbench) diff --git a/about.html b/about.html index b873341..3e80d7b 100644 --- a/about.html +++ b/about.html @@ -58,6 +58,7 @@

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.

+

The type-driven design workflow connects spec rules to domain types, state transitions, and explicit failures in application code, with runtime parsing at external boundaries.

What we build

diff --git a/agents.html b/agents.html index 1dfda37..f4aa681 100644 --- a/agents.html +++ b/agents.html @@ -123,6 +123,10 @@

MCP: live queries

+

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.

+

Commands reference

diff --git a/handbook.html b/handbook.html index 5e17815..74b65f7 100644 --- a/handbook.html +++ b/handbook.html @@ -4,7 +4,7 @@ Spec-Driven Development | specdog - + - + + +
+
+
+ Dotdog 1.0 Available now · Read the release notes +

Good specs.
Less guesswork.

+

Local-first specs, code graphs, and type contracts for coding agents. Keep what you intend separate from what the code shows — and give your agent the context to work with both.

+ + +
+
+

Feed the dog. Ship with specs.

+
-
🐕 Spec
-
- - - -
- -

specdog

-

Specs that ship. Agents that don't hallucinate.

-

specdog is a small family of tools for spec-driven development: write structured specs, map repos into agent-readable graphs, describe multi-repo workspaces, benchmark token savings, and run agent harnesses from the same source of truth. Pair the specs with type-driven design to model valid states and operation contracts before implementation.

+ +

Spec is on the case.

+
+ + + +
+ +
-
- specs - graphs - agents - benchmarks -
+
+
+

Start in your repository.

+

Refresh the local graph, then ask focused questions about context, impact, and paths.

+
+
+
+
+
+ + +
+ +
+
npx dotdog@1.0.0 refresh --json
+

+
+

Node.js 22.12+ or Bun 1.3+. Optional type inspection also requires Node and a trusted project-installed TypeScript 7.0.2 compiler.

+
+
-
-
npm install -g dotdog
-dotdog workspace init --id example-product
-dotdog workspace validate
-dotdog workspace graph --json
- -
+
+
+

Three perspectives. One workflow.

+

Intent, implementation, and evidence stay connected — not confused.

+
+
+
+

01 / Specs

+

Make intent queryable.

+

Write structured specs, check completeness, and keep human-owned rules separate from generated code observations.

+ Explore spec-driven design +
+
+

02 / Graphs

+

Follow the evidence.

+

Query context, impact, and paths. Import saved REA/Ghidra call graphs with artifact identity, coverage, and limits intact.

+ Explore graph workflows +
+ +
+
- +
+
+

New to 1.0? Start here.

+

What's changed, how to upgrade, and what the tools actually check.

+
+ +
-
-
dotdog

CLI and MCP tooling for `.dog` specs, `.dag` graphs, repo mapping, and multi-repo workspace manifests.

-
collar

DAG-first agent harness for loading graph-backed behavior.

-
leash

Robotics harness for simulation-safe agent control.

+
+

More from the pack

+
+
collar

An agent harness for graph-backed behavior.

+
leash

A separate robotics harness for simulation-first agent control.

+
dogbench

Retrieval and token-cost benchmarks for the tooling.

+
-
dotdog@0.5.0 · MIT
+
+

specdog · Feed the dog. Ship with specs.

+

dotdog@1.0.0 · npm · MIT

+
CommandWhen to use