Schema reference

Overview

A SpecPad project lives in docs/specpad/ inside your git repository and consists of up to five JSON files:

Snapshot files are cached under docs/specpad/.specpad/; that sub-folder is regenerable from git history and is never the source of truth. Each release entry carries a snapshot path (or null if not yet cached) pointing to the corresponding raw document copy.

Schema versioning

Every file carries a schemaVersion field. Version "1.0" maps to the pinned editor build at /v01/. When a new schema version ships, its editor build is deployed at a new path (e.g. /v02/) and the old path remains live forever — so existing documents always open in an editor that understands them.

What is and isn't stored

Git owns history. The files contain no modifiedBy, modifiedDate, author, or change-list fields — git commits carry that context. Nothing derived is stored. Test counts, pass/fail roll-ups, and change diffs are computed on read from the raw JSON; storing them would create a drift hazard.

Field reference

Field descriptions are authoritative — they are read directly from the JSON Schema definitions at build time. A missing description is a build error.

Governance rules

JSON Schema validates structure only (required fields, types, enums). These policy rules run in both the skill and the editor from one shared module (src/shared/governance.ts) — they cannot drift.

Annotated example

A real requirement from SpecPad's own SRS (DOC-1) and its verifying test (TEST-1), showing how the key fields relate.

{
  "id":   "r_a101",
  "code": "DOC-1",
  "text": "The system shall store project documentation as JSON files under docs/specpad/: one project index, one SRS, and one VTP.",
  "tags": ["schema"]
}

{
  "id":       "t_c001",
  "code":     "TEST-1",
  "text":     "Confirm docs/specpad/ holds the three core files and each parses as JSON.",
  "verifies": ["r_a101"],
  "expected": "All three files exist and parse without error.",
  "result":   "passed",
  "notes":    "dogfood.test.ts"
}

• id r_a101 / t_c001 — stable machine identifiers generated once and never changed. Renaming code (the human label) never touches id.
• code DOC-1 / TEST-1 — freely renameable display labels. The editor shows them; the skill increments them; traceability links ignore them entirely.
• verifies ["r_a101"] — the test links to the requirement by id, never by code, so renaming DOC-1 to ARCH-1 cannot break the link.
• expected "All three files exist…" — a non-empty expected result is required on every non-heading test (governance rule missing-expected).

Install & use the skill

The SpecPad Claude Code skill lets you create and maintain SRS/VTP documents directly from your AI assistant, with full validation and governance checks.

1. Download specpad-skill.zip and unzip it into ~/.claude/skills/ so that ~/.claude/skills/specpad/SKILL.md exists.
2. In any repo, tell Claude Code: "set up specpad" — it scaffolds docs/specpad/ with a project index, an empty SRS, and an empty VTP.
3. Use natural language to manage your spec. Trigger phrases:
   • write a spec
   • formalize requirements
   • add a requirement
   • write tests for
   • check traceability
4. Before finishing any task the skill validates structure and runs all three governance rules — so the JSON files on disk are always editor-ready.
5. Open the same files in the hosted visual editor at specpad.com/v01/ to review, edit, and record test results through a full UI. Git is the shared history layer; both halves read and write the same JSON.