Skip to content
OpenSmartRoute
Skillv1.0.0

doc-spec

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

by vladm3105(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from vladm3105/aidoc-flow-framework (platforms/claude-code-plugin/skills/doc-spec/SKILL.md). Install upstream with npx skills add vladm3105/aidoc-flow-framework --skill doc-spec. Copyright stays with the author.

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:

  1. Template (source of truth): ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
  2. Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
  3. ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. Authoring style: ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
  5. 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:

  1. Document Control · 2. Component Overview (description, @adr decision, language, dependencies) · 3. Interfaces (exports: signatures, types, errors) ·
  2. Data Models (typed fields, no SQL/ORM) · 5. Behavior (validation rules, state transitions, error handling — each sourced from @ears/@bdd) ·
  3. Implementation Notes (constraints, patterns, performance considerations) ·
  4. 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

  1. Read upstream — ADR decisions plus the BDD/EARS contracts the component satisfies.
  2. 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).
  3. 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/.
  4. Document Control first, then complete all 8 sections from the template.
  5. Define interfaces and data models with typed signatures; specify behavior with each rule sourced from @ears/@bdd.
  6. Add the required upstream tags (@ears @bdd @adr per the necessary-upstream contract) and the downstream @tdd: TDD-NN contract.
  7. Update the SPEC index docs/06_SPEC/SPEC-00_index.md in the same change.
  8. 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.

  • YAML parses; Document Control is the first section.
  • All 8 sections present and non-empty; format is YAML (not markdown).
  • Component-level only (no code/SQL/deployment detail; C4-L3 scope holds).
  • Document ID is dash form SPEC-NN; no dotted SPEC element IDs; no removed patterns.
  • Required upstream tags present (@ears @bdd @adr per necessary-upstream contract); downstream @tdd: TDD-NN contract present.
  • Quantitative values use @threshold: references (no magic numbers).
  • Diagram contract: @diagram: c4-l3 and @diagram: dfd-l3 present (use ../charts-flow/SKILL.md).
  • Traceability matrix / index created or updated; no broken links.
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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/vladm3105-aidoc-flow-framework-doc-spec/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

vladm3105-aidoc-flow-framework-doc-spec.ocm.jsonjson
{
  "ocm": "1",
  "id": "vladm3105-aidoc-flow-framework-doc-spec",
  "kind": "skill",
  "name": "doc-spec",
  "description": "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.",
  "publisher": "vladm3105",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "sdd-workflow",
      "layer-6-artifact",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/vladm3105/aidoc-flow-framework",
      "path": "platforms/claude-code-plugin/skills/doc-spec/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/platforms/claude-code-plugin/skills/doc-spec/SKILL.md",
      "key": "vladm3105/aidoc-flow-framework/platforms/claude-code-plugin/skills/doc-spec/SKILL.md"
    }
  },
  "instructions": "# doc-spec\n\n## Purpose\n\nCreate a **Technical Specification (SPEC)** — Layer 6 of the SDD flow. A SPEC is\nthe implementation-ready, C4-L3 (Component) contract for a single software\ncomponent: its interfaces, data models, and behavior — written before any\ndownstream test or code.\n\n**Layer**: 6 — the unified specification. A SPEC subsumes what older revisions\nsplit into component/data/ux/risk/process specs; there is now **one** SPEC\nartifact per component.\n**Upstream**: EARS, BDD, ADR (per the necessary-upstream contract; ADR is the\nprimary source. Upstream PRD/BRD lineage is reachable transitive",
  "cost": {
    "context_tokens": 2064
  }
}

Fetch it by URL: GET /api/v1/registry/vladm3105-aidoc-flow-framework-doc-spec/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.