Design-skill

A skill for coding agents that keeps a project's design decisions in a design tree: each decision written down with the reason it was made and the alternatives it beat, approved by the project's owner before it reaches the main line, and checked against the code that implements it.

It works with Claude Code and Codex, and it is written for any project. Its checks are a small Python script and a test suite that run locally and in CI.

Why

Agents write a lot of code quickly, and the reasons behind it are easy to lose: they end up spread over pull request threads and conversations, or are never written down at all. Later work then proposes again an alternative that was already rejected, or quietly contradicts a choice nobody can find. A design tree keeps the reasons in the repository, next to the code, in a form short enough to read and strict enough to check:

• One place for decisions. The tree is organized by concept, not by code structure. Each node holds one or more decisions and the alternatives they refused.
• The owner decides. An agent may change the tree freely on a draft branch, but the owner rules on its design cards before merge, and the branch cannot become ready until its newest log entry names every changed node. CI enforces the log check.
• Code follows the decisions. At completion, a separate reviewer checks the tree's changes and checks the code against the decisions it implements (the Design Correspondence Review).

What a tree looks like

A project keeps its tree in a directory, usually design/: one Markdown file per node, children in a directory named after their parent, and a change log beside the root nodes.

design/
  log.md            one entry per tree change, newest first
  pipeline.md       a root node
  pipeline/
    style.md        a child of pipeline
    layout.md

A node holds Decision: lines, each stating the choice, its reason after because and the alternative after instead of, and an optional Rejected: list:

Decision: Layout lengths are 1/64-pixel fixed-point integers, because fixed
point adds and compares exactly and keeps layout independent of
floating-point rounding, instead of f32 or f64 lengths.

Rejected:
- f64 lengths: rejected because a layout would depend on evaluation order.

Each field is one line in the file; the example wraps it for reading. A log entry names the nodes it changed:

## 2026-10-01 Use fixed-point layout lengths

Nodes: vocabulary

Summary: Layout lengths become 1/64-pixel integers; the measurements are in
research/investigations/vocabulary/DESIGN.md.

The full procedure (the node format, what counts as a decision, how the owner's decisions are gathered into decision cards in reports, the log format and the review checks) lives in the owner's agent instructions, which the agents load at every session start; this repository holds its checker.

Contents

File	Purpose
lint.py	Form check of a tree and, with --require-approval, the readiness check
review-base.sh	Picks the base revision a CI job compares the tree with
test_lint.py	Tests for the two scripts above

The scripts need Python 3, Git and a POSIX shell.

Using it in a project

A project adds this repository as a Git submodule, which pins the commit it uses. The skill is changed only here, and a project adopts a change by moving its pin.

1. Add the submodule, for example at design/skill:

   git submodule add https://github.com/Ming-Research/Design-skill.git design/skill

   A fresh clone then needs git clone --recurse-submodules, or git submodule update --init afterwards, and CI checks out submodules (submodules: true in actions/checkout). Until the submodule is initialized, the checks cannot run.

2. Map its roles in the project's agent instructions (AGENTS.md or CLAUDE.md): where the live tree and the log live, where research records and deferred work go, and which commands run the checks.

3. Wire the checks, for example in a Makefile:

   DESIGN_REVIEW_BASE ?= origin/main
   design-lint:
   	python3 -B -m unittest discover -s design/skill -p 'test_lint.py'
   	python3 -B design/skill/lint.py --root design --trees pipeline --base "$(DESIGN_REVIEW_BASE)"
   design-ready:
   	python3 -B design/skill/lint.py --root design --trees pipeline --base "$(DESIGN_REVIEW_BASE)" --require-approval

   Run design-lint on every push, and design-ready on pull requests that are ready for review and on the main line. In CI, pick the base with review-base.sh, which needs the full history (fetch-depth: 0):

   base=$(sh design/skill/review-base.sh "$GITHUB_EVENT_NAME" "$GITHUB_REF" "$PUSH_BEFORE")
   make design-ready DESIGN_REVIEW_BASE="$base"

   where PUSH_BEFORE is ${{ github.event.before }}. A pull request is compared with its fork point from the branch it targets, which the script reads from GITHUB_BASE_REF, so a pull request stacked on another work branch answers only for its own tree changes. A draft branch may change the tree freely; design-ready checks that its newest log entry is new and names every changed node.

Changing the skill

Change it here, by pull request, with the tests passing. A project then moves its submodule to the merged commit in its own pull request, which names the Design-skill revision it adopts and why:

git -C design/skill fetch origin && git -C design/skill checkout <commit>
git add design/skill

Projects using it

• Whitefoot, an optimizer-first systems language designed to be written by AI
• Snowghost-wf, a renderer for user interfaces built with web technology, written in Whitefoot

License

MIT; see LICENSE.