docs-kit Guide

A design-doc management tool for AI-assisted coding.

Design docs stay plain Markdown + YAML front matter. On top of that, docs-kit adds commit-SHA-based freshness verification, which prevents the failure mode where an AI trusts an outdated design doc without question and skews the implementation to match it. A single Go binary with no runtime dependencies.

status: v1.1.0 Both the core + CLI and the stdio MCP server are shipped. v1.1.0 adds the schema command, which prints the front matter schema.

docs-kit in 30 seconds

At the top of each design doc, record the code it is responsible for and the commit at which it was last reconciled against the implementation.

---
id: SPEC-editing-model
title: Editing model
status: current
scope: [src/core/editing/**]                          # code this doc is responsible for
verified_at: 8f3a1c2e0b7d4a91c3f6e2d8b5a704c1e9f3d602 # last reconciled against the code
---

From there, git history does the judging.

docs-kit stale

SPEC-editing-model  stale    code-changed: 3 files changed since 8f3a1c2
  - src/core/editing/model.ts (2 commits)
  - src/core/editing/undo.ts
ARCH-overview       ok       (verified at 8f3a1c2)

ok 1 / stale 1 / broken 0 / skipped 0

If code inside scope changed after verified_at, the doc is stale. CI fails, and the AI is told plainly: this one is out of date, trust the code instead.

How to read this guide

Page	Contents	Read it when
Concept and design principles	What problem this solves, why this shape, and what was deliberately left unbuilt	Evaluating adoption / curious about the reasoning
Documentation workflow	Four layers, front matter, freshness checks, daily operation, AI integration, CI	You want the full picture. This is the main page
Installation	Binary / `go install` / CI / registering the MCP server with Claude Code	You just want it running
Project setup	From a fresh repo to your first `current` document	Starting from zero
Adopting in an existing project	Bringing existing Markdown under management, step by step	You already have design docs

New here? Go Installation → Project setup → Workflow. Already have a pile of design docs? Go Concept → Adopting in an existing project.

Requirements


OS	macOS / Linux / Windows (amd64, arm64; Windows arm64 is not distributed)
Required	`git` (shelled out to, read-only)
Runtime	None (single binary)
AI integration (optional)	An MCP-capable client such as Claude Code

docs-kit Guide

docs-kit in 30 seconds

How to read this guide

Requirements

Links