doc-spec
Purpose
Create a Technical Specification (SPEC) — Layer 6 of the SDD flow. A SPEC is
the implementation-ready, C4-L3 (Component) contract for a single software
component: its interfaces, data models, and behavior — written before any
downstream test or code.
Layer: 6 — the unified specification. A SPEC subsumes what older revisions
split into component/data/ux/risk/process specs; there is now one SPEC
artifact per component.
Upstream: EARS, BDD, ADR (per the necessary-upstream contract; ADR is the
primary source. Upstream PRD/BRD lineage is reachable transitively via the
@-tag chain).
Downstream: TDD → IPLAN → Code.
When to Use
Use doc-spec when:
- Architecture decisions (ADR) are settled and you need to specify a component.
- Turning EARS/BDD acceptance contracts into concrete interfaces, data models,
and behavior rules.
- You need an implementation-ready contract before writing TDD test cases.
For end-to-end generation from BDD/ADR, a prompt, or an IPLAN, use
../doc-spec-autopilot/SKILL.md.
Prerequisites
SPEC sits at Layer 6, so verify the required upstream artifacts (EARS, BDD,
ADR) exist before writing. Reference only documents that already exist; never
invent placeholders like SPEC-XXX or ADR-XXX. Before writing, read:
- Template (source of truth):
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
- Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Authoring style:
${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
- Upstream ADR (primary) plus the BDD/EARS acceptance contracts the
component must satisfy.
Confirm existing upstream artifacts and no ID collision:
ls docs/05_ADR/ docs/06_SPEC/ 2>/dev/null.
Layer Guidance
C4-L3 scope (stay at the component level)
SPEC is the Component level. Describe component interfaces and contracts,
not architecture decisions (ADR) or source code (Code).
| Stay here (PASS) |
Out of scope (FAIL) |
AuthService, UserRepository, NotificationQueue |
auth_service.py, async def validate_token() |
| interface signatures, typed data models |
concrete SQL tables, Redis key formats |
| behavior rules, state transitions, error contracts |
Kubernetes pod configs, deployment manifests |
Required diagram tags: @diagram: c4-l3, @diagram: dfd-l3 (use
../charts-flow/SKILL.md). Sequence diagrams must include alt/else for error
paths; never embed C4-L4 code/class diagrams.
Required structure (8 sections)
document_control comes first (status, version, date, author, component,
tdd_ready_score). Then:
- Document Control · 2. Component Overview (description,
@adr decision,
language, dependencies) · 3. Interfaces (exports: signatures, types, errors) ·
- Data Models (typed fields, no SQL/ORM) · 5. Behavior (validation rules,
state transitions, error handling — each sourced from
@ears/@bdd) ·
- Implementation Notes (constraints, patterns, performance considerations) ·
- Downstream TDD Contracts (
@tdd: TDD-NN, test-file map) · 8. Traceability.
See SPEC-TEMPLATE.yaml for per-section content. Format is YAML.
Element IDs and tags
- SPEC is a DOCUMENT-level artifact — reference it in dash form
SPEC-NN
(two digits, no extra leading zero: SPEC-01, SPEC-99, SPEC-102).
Downstream artifacts tag it @spec: SPEC-12. There is no dotted
SPEC.NN.SS.xxxx element form for SPEC itself.
- Required upstream tags (per the necessary-upstream contract):
hierarchical refs use the 4-segment element form —
@ears: EARS.NN.SS.xxxx,
@bdd: BDD.NN.SS.xxxx; document-level @adr: ADR-NN. Upstream PRD/BRD
lineage is reachable transitively via the EARS/BDD @-tag chain — do not
emit @brd:/@prd: on SPEC elements.
- Thresholds: never hardcode performance/timeout/rate-limit values — use
@threshold: registry references.
- Removed patterns (do not use):
STEP-XXX, IF-XXX, INT-XXX, DM-XXX,
MODEL-XXX, VR-XXX, 3-digit SPEC-NNN, numeric element-type-code tables,
and the deleted SYS/REQ/CTR upstream layers.
Creation Process
- Read upstream — ADR decisions plus the BDD/EARS contracts the component
satisfies.
- Reserve ID — next free
SPEC-NN under docs/06_SPEC/.
Per-layer independence (CLEANUP-PR-F item 18): pick the next-free
number in YOUR layer's index — the upstream's number is NOT your number
(doc numbers are per-layer sequential and independent; see
framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality).
- Create the nested folder — every SPEC lives in
docs/06_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml, regardless of size. Never
place a SPEC file directly in docs/06_SPEC/.
- Document Control first, then complete all 8 sections from the template.
- Define interfaces and data models with typed signatures; specify
behavior with each rule sourced from
@ears/@bdd.
- Add the required upstream tags (
@ears @bdd @adr per the
necessary-upstream contract) and the downstream @tdd: TDD-NN contract.
- Update the SPEC index
docs/06_SPEC/SPEC-00_index.md in the same change.
- Validate (below) and commit the SPEC and index together.
Validation
This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md and ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md.
| Code |
Meaning |
Severity |
| XDOC-006 |
Tag format invalid |
error |
| XDOC-007 |
Missing required upstream tag |
error |
| XDOC-008 |
Broken internal link |
error |
| XDOC-009 |
Missing traceability section |
error |
Quality gate (blocking): TDD-Ready score ≥ 90/100 before moving on. If
issues are found, fix and re-check; if unfixable, log for manual review.
Next Skill
../doc-tdd/SKILL.md — the TDD references this SPEC (@spec: SPEC-NN) along
with its own required @ears @bdd @adr upstream tags, and defines test cases,
inputs, expected outputs, and thresholds for the SPEC contracts.
Adaptation
Read .aidoc/profile.yaml; honor only this skill's knobs
(section_toggles, glossary). Ignore unknown keys; absent a profile, use
framework defaults. Authority:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.
Related Resources
- Template / authoring rules:
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
- Layer README:
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
- Index template:
${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-00_index.TEMPLATE.md
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Upstream decisions:
../doc-adr/SKILL.md · Downstream tests: ../doc-tdd/SKILL.md
- Quality gate:
../doc-spec-audit/SKILL.md · Fixes: ../doc-spec-fixer/SKILL.md
- Generation pipeline:
../doc-spec-autopilot/SKILL.md
Quick Reference
|
|
| Purpose |
Specify a component: interfaces, data models, behavior |
| Layer |
6 (C4-L3 Component) |
| Upstream tags |
@ears @bdd @adr (per necessary-upstream contract) |
| Document ID |
Dash form SPEC-NN (document-level; no dotted element IDs) |
| Must include |
Document Control (first), 8 sections, @threshold for numbers |
| Format |
YAML |
| Next |
doc-tdd |
1---
2name: doc-spec
3description: Create a Technical Specification (SPEC) - Layer 6 of the SDD flow, defining component interfaces, data models, and behavior contracts. Use when ADR decisions are settled and you need an implementation-ready spec before TDD. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-spec-autopilot`) drives this skill.
4metadata:
5 tags:
6 - sdd-workflow
7 - layer-6-artifact
8 custom_fields:
9 layer: 6
10 artifact_type: SPEC
11 skill_category: core-workflow
12 upstream_artifacts: [EARS, BDD, ADR]
13 downstream_artifacts: [TDD, IPLAN]
14 version: "0.25.0"
15 framework_spec_version: "0.51.0"
16 last_updated: "2026-05-23"
17 adapts: [section_toggles, glossary]
18---
19
20# doc-spec
21
22## Purpose
23
24Create a **Technical Specification (SPEC)** — Layer 6 of the SDD flow. A SPEC is
25the implementation-ready, C4-L3 (Component) contract for a single software
26component: its interfaces, data models, and behavior — written before any
27downstream test or code.
28
29**Layer**: 6 — the unified specification. A SPEC subsumes what older revisions
30split into component/data/ux/risk/process specs; there is now **one** SPEC
31artifact per component.
32**Upstream**: EARS, BDD, ADR (per the necessary-upstream contract; ADR is the
33primary source. Upstream PRD/BRD lineage is reachable transitively via the
34@-tag chain).
35**Downstream**: TDD → IPLAN → Code.
36
37## When to Use
38
39Use `doc-spec` when:
40
41- Architecture decisions (ADR) are settled and you need to specify a component.
42- Turning EARS/BDD acceptance contracts into concrete interfaces, data models,
43 and behavior rules.
44- You need an implementation-ready contract before writing TDD test cases.
45
46For end-to-end generation from BDD/ADR, a prompt, or an IPLAN, use
47`../doc-spec-autopilot/SKILL.md`.
48
49## Prerequisites
50
51SPEC sits at Layer 6, so verify the required upstream artifacts (EARS, BDD,
52ADR) exist before writing. Reference only documents that already exist; never
53invent placeholders like `SPEC-XXX` or `ADR-XXX`. Before writing, read:
54
551. **Template (source of truth):** `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml`
562. **Layer README:** `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md`
573. **ID & tag standards:** `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
584. **Authoring style:** `${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md`
595. **Upstream ADR (primary)** plus the BDD/EARS acceptance contracts the
60 component must satisfy.
61
62Confirm existing upstream artifacts and no ID collision:
63`ls docs/05_ADR/ docs/06_SPEC/ 2>/dev/null`.
64
65## Layer Guidance
66
67### C4-L3 scope (stay at the component level)
68
69SPEC is the **Component** level. Describe component interfaces and contracts,
70not architecture decisions (ADR) or source code (Code).
71
72| Stay here (PASS) | Out of scope (FAIL) |
73|------------------|---------------------|
74| `AuthService`, `UserRepository`, `NotificationQueue` | `auth_service.py`, `async def validate_token()` |
75| interface signatures, typed data models | concrete SQL tables, Redis key formats |
76| behavior rules, state transitions, error contracts | Kubernetes pod configs, deployment manifests |
77
78Required diagram tags: `@diagram: c4-l3`, `@diagram: dfd-l3` (use
79`../charts-flow/SKILL.md`). Sequence diagrams must include `alt/else` for error
80paths; never embed C4-L4 code/class diagrams.
81
82### Required structure (8 sections)
83
84`document_control` comes **first** (status, version, date, author, component,
85`tdd_ready_score`). Then:
86
871. Document Control · 2. Component Overview (description, `@adr` decision,
88language, dependencies) · 3. Interfaces (exports: signatures, types, errors) ·
894. Data Models (typed fields, no SQL/ORM) · 5. Behavior (validation rules,
90state transitions, error handling — each sourced from `@ears`/`@bdd`) ·
916. Implementation Notes (constraints, patterns, performance considerations) ·
927. Downstream TDD Contracts (`@tdd: TDD-NN`, test-file map) · 8. Traceability.
93
94See `SPEC-TEMPLATE.yaml` for per-section content. Format is **YAML**.
95
96### Element IDs and tags
97
98- **SPEC is a DOCUMENT-level artifact** — reference it in dash form `SPEC-NN`
99 (two digits, no extra leading zero: `SPEC-01`, `SPEC-99`, `SPEC-102`).
100 Downstream artifacts tag it `@spec: SPEC-12`. There is **no** dotted
101 `SPEC.NN.SS.xxxx` element form for SPEC itself.
102- **Required upstream tags** (per the necessary-upstream contract):
103 hierarchical refs use the 4-segment element form — `@ears: EARS.NN.SS.xxxx`,
104 `@bdd: BDD.NN.SS.xxxx`; document-level `@adr: ADR-NN`. Upstream PRD/BRD
105 lineage is reachable transitively via the EARS/BDD @-tag chain — do not
106 emit `@brd:`/`@prd:` on SPEC elements.
107- **Thresholds:** never hardcode performance/timeout/rate-limit values — use
108 `@threshold:` registry references.
109- **Removed patterns** (do not use): `STEP-XXX`, `IF-XXX`, `INT-XXX`, `DM-XXX`,
110 `MODEL-XXX`, `VR-XXX`, 3-digit `SPEC-NNN`, numeric element-type-code tables,
111 and the deleted SYS/REQ/CTR upstream layers.
112
113## Creation Process
114
1151. **Read upstream** — ADR decisions plus the BDD/EARS contracts the component
116 satisfies.
1172. **Reserve ID** — next free `SPEC-NN` under `docs/06_SPEC/`.
118 *Per-layer independence (CLEANUP-PR-F item 18):* pick the next-free
119 number in YOUR layer's index — the upstream's number is NOT your number
120 (doc numbers are per-layer sequential and independent; see
121 `framework/governance/ID_NAMING_STANDARDS.md` §Cross-layer cardinality).
1223. **Create the nested folder** — every SPEC lives in
123 `docs/06_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml`, regardless of size. Never
124 place a SPEC file directly in `docs/06_SPEC/`.
1254. **Document Control first**, then complete all 8 sections from the template.
1265. **Define interfaces and data models** with typed signatures; **specify
127 behavior** with each rule sourced from `@ears`/`@bdd`.
1286. **Add the required upstream tags** (`@ears @bdd @adr` per the
129 necessary-upstream contract) and the downstream `@tdd: TDD-NN` contract.
1307. **Update the SPEC index** `docs/06_SPEC/SPEC-00_index.md` in the same change.
1318. **Validate** (below) and commit the SPEC and index together.
132
133## Validation
134
135**This skill is the validator** (no runtime code). Apply against `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md` and `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`.
136
137- [ ] YAML parses; Document Control is the first section.
138- [ ] All 8 sections present and non-empty; format is YAML (not markdown).
139- [ ] Component-level only (no code/SQL/deployment detail; C4-L3 scope holds).
140- [ ] Document ID is dash form `SPEC-NN`; no dotted SPEC element IDs; no removed
141 patterns.
142- [ ] Required upstream tags present (`@ears @bdd @adr` per necessary-upstream
143 contract); downstream `@tdd: TDD-NN` contract present.
144- [ ] Quantitative values use `@threshold:` references (no magic numbers).
145- [ ] Diagram contract: `@diagram: c4-l3` and `@diagram: dfd-l3` present (use
146 `../charts-flow/SKILL.md`).
147- [ ] Traceability matrix / index created or updated; no broken links.
148
149| Code | Meaning | Severity |
150|------|---------|----------|
151| XDOC-006 | Tag format invalid | error |
152| XDOC-007 | Missing required upstream tag | error |
153| XDOC-008 | Broken internal link | error |
154| XDOC-009 | Missing traceability section | error |
155
156**Quality gate (blocking):** TDD-Ready score ≥ 90/100 before moving on. If
157issues are found, fix and re-check; if unfixable, log for manual review.
158
159## Next Skill
160
161`../doc-tdd/SKILL.md` — the TDD references this SPEC (`@spec: SPEC-NN`) along
162with its own required `@ears @bdd @adr` upstream tags, and defines test cases,
163inputs, expected outputs, and thresholds for the SPEC contracts.
164
165## Adaptation
166
167Read `.aidoc/profile.yaml`; honor only this skill's knobs
168(`section_toggles`, `glossary`). Ignore unknown keys; absent a profile, use
169framework defaults. Authority:
170`${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md`.
171
172## Related Resources
173
174- Template / authoring rules: `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml`
175- Layer README: `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md`
176- Index template: `${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-00_index.TEMPLATE.md`
177- ID & tag standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
178- Upstream decisions: `../doc-adr/SKILL.md` · Downstream tests: `../doc-tdd/SKILL.md`
179- Quality gate: `../doc-spec-audit/SKILL.md` · Fixes: `../doc-spec-fixer/SKILL.md`
180- Generation pipeline: `../doc-spec-autopilot/SKILL.md`
181
182## Quick Reference
183
184| | |
185|---|---|
186| **Purpose** | Specify a component: interfaces, data models, behavior |
187| **Layer** | 6 (C4-L3 Component) |
188| **Upstream tags** | `@ears @bdd @adr` (per necessary-upstream contract) |
189| **Document ID** | Dash form `SPEC-NN` (document-level; no dotted element IDs) |
190| **Must include** | Document Control (first), 8 sections, `@threshold` for numbers |
191| **Format** | YAML |
192| **Next** | `doc-tdd` |
vladm3105