Mini Spec

Mini-spec

Load the model first

IMMEDIATELY invoke /minimap using the Skill tool before doing anything else. It carries the structural model this skill builds on: the 3-level spec→design→code layout, what each level is for, where artifacts live, the root spec index, what a summary spec is, and the traceability links (Rn → CRC card → code // CRC:/Seq: comment) that stitch the levels together. Start at the design docs and the root index, not at code — drop into code-level tools (Serena, Grep, etc.) only after they've oriented you. This skill adds the process — phases, traceability maintenance, gaps, migrations, trajectory tracking — on top of that model.

Prerequisite: Version Check and Comment Patterns

First, run ~/.claude/bin/minispec check-version to verify the tool is installed and matches this skill's version. If it fails, warn the user: the tool and skill must be the same version or there will be compatibility issues.

Then, run ~/.claude/bin/minispec query comment-patterns to learn the recognized comment patterns for traceability comments in code files.

MANDATORY: Create Tasks First

BEFORE reading any files or doing any work, create tasks for applicable phases:

TaskCreate: "Spec Phase: [feature name]"
TaskCreate: "Requirements Phase: [feature name]"
TaskCreate: "Design Phase: [feature name]"
TaskCreate: "Implementation Phase: [feature name]"
TaskCreate: "Simplification Phase: [feature name]"
TaskCreate: "Gaps Phase: [feature name]"

Do NOT proceed until tasks exist. This is required for user visibility into progress.

MANDATORY: Check for In-Flight Migrations

Before any phase, run ~/.claude/bin/minispec query migrations. It lists in-flight migration specs (the *.md files in specs/migrations/, excluding complete/). Each file is an in-process migration — record formats, APIs, or internal structures are mid-flux. If any are present:

• Surface them to the user before doing other work.
• In-flight migrations take priority. Do not start unrelated changes

that touch the same code paths until the migration is complete.

• If your task IS the in-flight migration, proceed.

Migrations are temporary by design — see "Migration Workflow" below.

---

Why the levels matter

(The 3-level model itself — what specs, design, and code each are, and where they live — is in /minimap. This skill is the process that builds and maintains them.)

Each level exists because skipping it has a concrete cost:

• Verification — Design is smaller than code. The user can confirm you understood the task before you write hundreds of lines.
• Preview — The design tells the user what you're about to change. Without it, they discover unwanted modifications after the fact.
• Reference — During implementation, you look up the design instead of re-reading all the code. This keeps changes consistent across files.
• Anchor — Without a design document, iterative modifications cause drift: features silently disappear as code evolves across sessions. The design pins what must survive.
• Traceability — The specs→requirements→design chain ensures nothing is lost between what the user asked for and what gets built. When something breaks, you can trace backward to find out why.

The phases are not ceremony. They are cheaper than debugging a misunderstood requirement after 500 lines of code.

Summary specs — maintenance

(What a summary spec is, and the recurring kinds — CLI inventory, storage layout, API surface, capabilities — are in /minimap. This is the maintenance side: when to create one, and how to keep it true.)

When to create one:

• A question of the form "what's the full set of X across this

project?" keeps coming up, and answering it requires touching many per-feature specs.

• A cross-cutting axis has enough items that someone (or some future

you) would want a directory to navigate them.

Maintenance rules:

• Per-feature specs are canonical; summary specs are mirrors.

When the two disagree, the per-feature spec wins. Update the summary to match.

• Per-feature anchoring does not maintain summary specs. Mini-spec's

normal anchoring (specs → requirements → design → code) catches the per-feature edits but cannot tell that a CLI-inventory or capabilities spec should also have been updated. Updating summary specs is the maintainer's job, performed explicitly.

• Pin the summary-spec list somewhere persistent — typically

CLAUDE.md or the project's top-level reference doc — so a future agent or maintainer knows which summary specs to keep in sync when they add, rename, or retire something along the relevant axis.

• Don't anchor new requirements from a summary spec. Rn numbers

belong to the per-feature spec that owns the behavior. A summary spec entry references that spec; it does not own the contract.

Task Tracking

During implementation, break down into per-file tasks:

TaskCreate: "Implement view.ts changes"
TaskCreate: "Implement viewlist.ts changes"
TaskCreate: "Update design docs"

Mark phases complete with TaskUpdate as you finish them. Use Quality Checklist items as tasks before finalizing.

Core Principles

• use SOLID principles, comprehensive unit tests
• when adding code, verify whether it needs to be factored
• Code and specs as MINIMAL as possible
• Before using a callback, see if a collaborator reference would be simpler
• write idiomatic code for the language you use
• avoid holding locks in sections that have significant functionality
• No unanchored design: every design artifact must trace back to a spec item and requirement. If you need to add something to the design, add it to specs first, then requirements, then design. This applies regardless of direction — even when documenting existing code, verify the spec anchor exists before updating design. This prevents features from existing only in the AI's interpretation.
• Supersede at the source: the mirror of "No unanchored design." A change is complete only when every directive describing the old behavior is removed or rewritten at its source — across specs, requirements, AND design prose. Anchoring keeps features from vanishing; superseding keeps stale directives from causing reverts: a future agent reads a leftover spec sentence or design bullet as current intent and "fixes" the code back to match, undoing the change that obsoleted it. Completion test for any change: could an agent reading only specs + design be led to undo it? If yes, a trap remains.
• in HTML, use the slimmest DOM Possible. Fewer elements makes everything in the browser better: less memory, more speed, better responsiveness

Why anchoring matters

Specs and design docs are the project's memory bank. AI context dies every session — code changes compound across sessions without any single agent seeing the full history. Unanchored code has no justification trail: a future session can't tell whether a function was designed or accidental, required or leftover. When that session makes changes, unanchored features silently disappear because nothing in the design said they should exist.

Anchoring is cheap (a few lines of spec + a requirement number). The cost of not anchoring is discovering, three sessions later, that a feature vanished during an unrelated refactor and no one noticed because the design never mentioned it. The spec is the pin that says "this must survive."

Why superseding matters

Anchoring and superseding guard opposite failure directions. Anchoring fights omission — a feature with no spec silently disappears. Superseding fights contradiction — a directive that outlived the behavior it described silently reappears. The second is the more dangerous: a contradiction in the design is a trap that springs in the revert direction. A retired requirement has a forcing function (the retire command strikes it through, appends the Tn, and prints a reconcile reminder), but the prose that spawned it — the originating spec sentence, the CRC bullet, the sequence step — has none. It rots in place until a future agent reads it as current intent and "fixes" the code back to match. So retirement is not done when the Rn is struck out; it is done when every sentence that described the old behavior is gone or rewritten at its source.

Cross-cutting Concerns

design.md Cross-cutting Concerns section: Patterns spanning components (auth, errors, logging, routing, theming). Referenced from other design artifacts: Cards, sequences, and layouts can all say "see cross-cutting: auth"

Traceability

design.md Artifacts section: design files with code file checkboxes.

Use minispec commands for checkbox operations:

# View current artifact states
~/.claude/bin/minispec query artifacts

# Before modifying code: uncheck the artifact
~/.claude/bin/minispec update uncheck design.md crc-Store.md

# After implementation matches design: check the artifact
~/.claude/bin/minispec update check design.md crc-Store.md

Code changes: Uncheck artifact, ask user: "Update design, specs, or defer?" Update design: Read code, update design file, re-check artifact.

Workflow

First: Read specs. Specs must indicate language/environment.

Then: Proceed through phases

1. Spec Phase

Create in specs/: human-readable descriptions organized by feature area. Specs are the user's intent in their own words. For applications, this means behavior and user-facing concepts. For libraries, include the public API signatures — they are the contract that design must satisfy. Do not include internal structure or implementation choices.

Reconcile the root spec index. Whenever you add, rename, or retire a per-feature spec, straighten out the root index (the project's specs/index.md) in the same pass: create it if it doesn't exist yet, then make sure every spec has an entry under a system, with new summary specs and themes registered. Run ~/.claude/bin/minispec query unindexed-specs — it lists any per-feature spec missing from the index (the spec-level analog of query uncovered); the pass is clean when that list is empty.

Upon completion, run ~/.claude/bin/minispec phase spec to verify spec files exist, then offer Requirements Phase. Do not jump to Design.

1. Requirements Phase

Create design/requirements.md: merge all specs into numbered requirements.

Format:

# Requirements

## Feature: [feature-name]
**Source:** specs/feature.md

- **R1:** [requirement from spec]
- **R2:** [requirement from spec]
- **R3:** [inferred requirement - marked as such]

## Feature: [another-feature]
**Source:** specs/another.md

- **R4:** [requirement]

Guidelines:

• Each spec item becomes exactly one numbered requirement (R1, R2, ...)
• Numbering is global across all features (not per-feature)
• Mark inferred requirements explicitly: "R5: (inferred) ..."
• Keep requirement text atomic and testable

Upon completion, run ~/.claude/bin/minispec phase requirements to verify format, then offer Design Phase. Do not jump to Implementation.

1. Design Phase

Create in design/:

• design.md: Intent + Artifacts (design files → code file checkboxes)
• crc-*: CRC cards (see format below)
• seq-*: sequence diagrams (≤150 chars wide; number their steps — see "Numbered Sequence Anchors" below)
• ui-*: ASCII layouts, reference CRC cards
• test-*: test designs (see format below)
• manifest-ui.md: routes, theme, global components

Design Traceability: All design artifacts must reference requirements:

# ClassName
**Requirements:** R1, R3, R7

Use minispec to add requirement references:

~/.claude/bin/minispec update add-ref crc-Store.md R5

Where requirement refs count. minispec validate computes requirements→design coverage from each CRC card's top-line **Requirements:** field only (plus approved gaps). Refs written anywhere else in the card body — e.g. a per-method (R5, R6) annotation on a ## Does bullet — are documentation; the validator does not parse them, so they earn a requirement no coverage. A requirement counts as covered only when it appears in some artifact's top-line field, which is what add-ref maintains. Body-level annotations are fine as human notes, but never let them be the only home for a ref. (Requirements→code coverage is separate: it comes from inline Rn refs in code traceability comments. Retired requirements are skipped by both coverage checks yet still resolve as references, so a ref to a retired Rn is never flagged as unknown.)

Artifacts Format (must be exact for minispec tool parsing):

## Artifacts

### CRC Cards
- [x] crc-Store.md → `src/store.ts`
- [x] crc-View.md → `src/view.ts`, `src/viewlist.ts`

### Sequences
- [x] seq-crud.md → `src/store.ts`, `src/view.ts`

### UI Layouts
- [ ] ui-dashboard.md → `web/html/dashboard.html`

### Test Designs
- [ ] test-Store.md → `src/store_test.ts`

The Artifacts section is a manifest of all design files except design.md and requirements.md. Every crc-, seq-, ui-, test-, and manifest-*.md must be listed.

Format rules:

• Section headers (### CRC Cards, etc.) are optional grouping
• Each line: - [x] design.md → code-file(s) or - [ ] design.md
• Multiple code files: comma-separated after →
• Backticks around code paths are optional
• Checkbox state applies to all code files on that line

Numbered Sequence Anchors: Number the steps in your sequence diagrams using dotted notation so code can pin to specific steps. Place the number wherever the diagram style allows:

• Tree/outline: 1.4. step description on the line itself
• UML actor-lane: 1.4 on its own line directly above the arrow
• Mermaid/pseudo-Mermaid: 1.4 at the start of the step

A file may contain more than one numbered diagram. Items in the first numbered diagram begin with 1., the second with 2., and so on (1, 1.1, 1.1.1, 2, 2.1, ...). The first segment K is the diagram index. Numbers are local to the file: 1.4 in seq-foo.md is unrelated to 1.4 in seq-bar.md.

Reference a numbered step from code with Seq: seq-foo.md#1.4. File-only refs (Seq: seq-foo.md) remain valid for diagrams that aren't numbered.

Why number: the anchor creates a bidirectional, grep-able link.

• Agent generating code: drop seq-foo.md#1.4 in a traceability comment as a promise that this code implements that step.
• Agent making a code change: follow the anchor to verify what the diagram says the step does.
• Human reading code: grep "seq-foo.md#1.4" src/ finds every implementation of that step.

For this to work, the number must be uniquely findable in the diagram source (avoid prose that starts with dotted numbers at the same indentation). Within a single file, every dotted ID may appear at most once. Append new steps with new numbers; renumbering existing steps orphans the code that pins to them — same discipline as Rn IDs.

The validator checks per-K tree contiguity (under K.x, children must be K.x.1, K.x.2, … with no gaps), K-sequence contiguity within the file (Ks are 1, 2, 3, …), and intra-file ID uniqueness. Unnumbered seq files are silently skipped — numbering is opt-in per file.

Upon completion, run ~/.claude/bin/minispec phase design to verify coverage, then offer Implementation Phase. Do not jump to Gaps.

1. Implementation Phase

Add traceability comments with optional inline requirement refs:

// CRC: crc-Store.md | Seq: seq-crud.md#1.4 | R4, R5
add(data): Item {

The third | Rn, Rn section is optional but recommended — it links specific code locations directly to requirements, enabling implementation coverage validation.

What counts as an inline Rn ref (v2.10.0+). minispec validate harvests implementation refs from two comment shapes:

1. The tail of a // CRC: line — `// CRC: | Seq: | R5, R1

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zot
• Source: zot/mini-spec
• License: MIT

Install and usage instructions live in the source repository linked above.