Menu
Create and maintain spec-docs — knowledge that code alone cannot adequately convey.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Pre-scan Markdown files before reading. Use `sspec tool mdtoc` to get file size + heading structure with line numbers (L<n> format) before reading long docs, SKILLs, or spec-docs. Eliminates blind reads.
Assess scale, create change, fill spec.md + design.md, align with user. Use after clarify when ready to define the solution.
Execute tasks from tasks.md. Implement code changes, update progress. Use after plan approval.
Break design into concrete tasks. Fill tasks.md with file-level execution plan. Use after design alignment.
User acceptance and feedback loop. Handle argue-improve cycles until user is satisfied.
Build shared understanding through dialogue and investigation. Produces Problem Statement + direction sketch. Reusable posture, not rigid phase.
| name | write-spec-doc |
| description | Create and maintain spec-docs — knowledge that code alone cannot adequately convey. |
| metadata | {"author":"frostime","version":"4.0.0"} |
Code is the local ground truth. Spec-docs reduce the cost of recovering that ground truth for agents.
Two categories of knowledge that justify a spec-doc:
A) In code, but scattered or implicit — Cross-module architecture (call chains, data flows, layer relationships) distributed across many files; implicit specifications (state machines, invariants, schema contracts) that are implemented but never declared; design norms embedded in implementation choices; deliberate trade-offs whose rationale is invisible from outcomes alone. Reconstructing any of these demands expensive multi-file traversal and inference.
B) Outside code entirely — Platform rules, API quirks, business constraints, deployment assumptions. Code reflects these as outcomes, but the constraints themselves cannot be inferred from it. Example: a SQLite-over-Postgres choice is invisible without knowing the single-machine deployment constraint.
Write-gate: "If an agent read only the code (including comments), could they obtain this information — fully and without excessive effort?" Yes → don't create. No → create.
Don't create when:
project.md Conventions or Notes is sufficient| Command | Use |
|---|---|
sspec doc new "<name>" | Create single-file spec-doc from template |
sspec doc new "<name>" --dir | Create multi-file spec-doc (directory + index.md) |
sspec doc list | List all spec-docs with metadata |
Always use CLI to create — it scaffolds from template with correct frontmatter. Do not hand-create spec-doc files.
All fields required:
---
name: Authentication System
description: JWT-based auth with refresh tokens and rate limiting
updated: 2026-01-27
scope:
- /src/auth/**
- /src/middleware/auth.ts
---
scope lists file paths (glob patterns) this spec-doc covers. Agents use it to locate relevant code. Include primary implementation and tests; omit generic utilities.
Start with ## Overview. Beyond that, invent sections that fit the content. Example structures:
Self-check for every section: Would removing this force an agent into expensive reconstruction — multi-file traversal, cross-reference inference, external research, or guessing? If the agent could reach the same understanding from code alone at comparable cost, the section is redundant — cut it.
Representation: Complex relationships — call chains, state transitions, data flows, hierarchies — are more precisely conveyed through diagrams, pseudocode, or tables than through prose. Prefer semi-formal representations; they are easier for both agents and humans to verify and navigate.
After creating a spec-doc, add an entry to project.md Spec-Docs Index. This is the agent's responsibility — the CLI does not automate it.
Format: - [Name](spec-docs/<filename>.md) — one-sentence description
When a change creates or heavily depends on a spec-doc, add to the change's spec.md frontmatter:
reference:
- source: "spec-docs/<name>.md"
type: "doc"
Spec-docs are navigable knowledge graphs, not dead-end prose.
Every named entity — symbol, concept, external reference — MUST be traceable to its source (file path, URL, or another spec-doc). Establish the reference on first mention; subsequent uses within the same document need not repeat the link when the referent is unambiguous from context.
Source types: file path · URL · relative link to another spec-doc. Omit line numbers — they go stale with code changes.
BAD — agent must search to resolve:
The `AuthManager` handles token refresh. Rate limits follow Stripe's rules.
GOOD — traceable on first mention, concise thereafter:
[`AuthManager`](/src/auth/manager.ts) handles token refresh.
Rate limits follow [Stripe's API rules](https://docs.stripe.com/rate-limits) (≤100 req/s per key).
... later in the same doc ...
`AuthManager` delegates to the refresh service when tokens expire.
/src/core.py). Same-level or sub-directory may use ./When a change modifies code covered by a spec-doc's scope:
spec-docs/<name>.md"updated field and affected sectionsscope still matches actual filesSpec-docs MUST NOT be silently outdated by a change.
Mark deprecated: true + replacement: /path/to/new.md in frontmatter. Move to spec-docs/archive/. Strip details; keep only: what it was, why deprecated, link to replacement.
Use sspec doc new "<name>" --dir. Entry point is index.md with overview + navigation. Each sub-file has its own frontmatter with narrowed scope. Cross-references use relative paths.