mcpField
D
doc-naming

doc-naming

github.com/vladm3105Documents1758 installsUpdated 1d ago
Repository

About doc-naming

doc-naming is a document-naming validation skill for teams using the 8-layer SDD flow. It checks IDs and tags against the naming standards and identifies legacy patterns, without producing artifacts.

Key features

  1. 01Validate document ID formats
  2. 02Validate element IDs and threshold tags
  3. 03Flag legacy patterns and suggest migration targets
  4. 04Check naming rules for file names

Use cases

  1. 01Check IDs before creating or editing an artifact
  2. 02Find deprecated IDs during document maintenance

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-naming

After installing, type/doc-namingin Claude Code to confirm it loaded.

Details

From the project README

doc-naming

Purpose

The naming authority for the 8-layer SDD flow. doc-naming validates document IDs, element IDs, threshold tags, and file names against ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md, and flags removed/legacy patterns. It produces no artifacts — it is the declarative ID validator (the framework ships no runtime code).

Layer: cross-cutting utility (applies to all 8 layers).

When to Use

Use before creating or editing any artifact, to:

  • verify a document or element ID format,
  • check a @threshold: tag, or
  • detect removed/legacy ID patterns and get the migration target.

Do NOT use for cross-document traceability or content review — use ../doc-validator/SKILL.md.

Behavior

1. Document ID — TYPE-NN

^[A-Z]{2,8}-[0-9]{2,}$ — uppercase type, single dash, 2+ digit sequence (no extra leading zeros beyond two: BRD-01, ADR-99, IPLAN-102). File name: TYPE-NN_descriptive_slug.md.

2. Element ID — TYPE.NN.SS.xxxx (4-segment)

^[A-Z]+\.[0-9]{2,}\.[0-9]{2,}\.[a-f0-9]{4,8}$

SegmentMeaningFormat
TYPEArtifact prefixBRD PRD EARS BDD ADR TDD
NNDocument number2+ digits
SSSource section number2+ digits
xxxxStable content identifier, 4 hex (8 on collision) — see below[a-f0-9]{4,8}

Example: BRD.01.07.a7f3. Element IDs appear as markdown headings (### BRD.01.07.a7f3: Title).

3. Reference granularity (element vs document)

There are no numeric element-type codes — identity is the section + hash, not a fixed code.

LayerReference formExample
BRD, PRD, EARS, BDD, TDDelement (dotted) TYPE.NN.SS.xxxxPRD.01.09.1dbc
ADRboth: document ADR-NN and element ADR.NN.SS.xxxxADR-05, ADR.05.03.e5b1
SPEC, IPLANdocument (dash) TYPE-NNSPEC-06, IPLAN-01

Traceability tags carry these refs: @brd: BRD.01.07.a7f3, @spec: SPEC-06, @iplan: IPLAN-01.

4. Threshold tags

@threshold: {TYPE}.{NN}.{key} where key is category.subcategory.attribute[.qualifier]. Categories: perf timeout rate retry circuit alert cache pool queue batch. Doc reference is mandatory and dot-separated — @threshold: PRD.035.timeout.partner.bridge (valid); @threshold: timeout.partner.bridge (missing doc ref — invalid). Threshold sources: BRD (business SLAs), PRD (product metrics), ADR (technical limits).

5. Reserved-ID and REF exemptions
  • TYPE-00_* (indexes, templates, glossaries) — framework infrastructure; skip element-ID and traceability checks.
  • TYPE-REF-NN_{slug}.md (BRD/ADR only, via ../doc-ref/SKILL.md) — free-format reference targets; no element IDs, no quality gates.
6. Removed / legacy patterns (reject)

Migrate every match to TYPE.NN.SS.xxxx (or a dash doc ref for SPEC/IPLAN):

RemovedApplies to
AC-XXX, FR-XXX, BC-XXX, BA-XXX, QA-XXX, BO-XXX, RISK-XXX, METRIC-XXX, Feature F-XXXBRD, PRD
Event-XXX, State-XXXEARS
DEC-XXX, ALT-XXX, CON-XXXADR
3-segment TYPE.NN.xxxxall element layers

Detect with grep, e.g. grep -E "(AC|FR|BC|BA|QA|BO|NFR|RISK|METRIC)(-[A-Za-z0-9]+)*-[0-9]+" file.md (the optional (-[A-Za-z0-9]+)* catches compound forms like FR-CICD-001). Migration: derive TYPE/NN from the file name, SS from the source section, and xxxx as a stable 4-hex identifier distinct within its section; replace all occurrences and re-verify. Do not compute SHA-256 by hand. For BRD §7 — the one layer with a defined field-extraction boundary — call the generator: python -m sdd_doc_lint.rehash --compute --doc-id NN --section-id SS --title T --description D. Authority: framework/governance/ID_NAMING_STANDARDS.md.

7. ISO 8601 timestamps

Date/time fields (frontmatter last_updated, created_date; review_date, fix_date, approval_date, decision_date) use YYYY-MM-DDTHH:MM:SS (optionally Z or ±HH:MM), enabling same-day drift detection. Date-only values are deprecated.

Pre-flight checklist
  • Document ID is TYPE-NN; file name is TYPE-NN_slug.md.
  • Element IDs are 4-segment TYPE.NN.SS.xxxx with a 4–8 hex hash, unique within the document; SPEC/IPLAN use dash doc refs.
  • @threshold: tags include the doc reference and an approved category.
  • No removed/legacy patterns; no 3-segment element IDs.
  • Traceability tag prefixes (@brd: … @tdd:) are correct and targets exist.

Related Resources

  • ID & tag authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • Threshold rules: ${CLAUDE_PLUGIN_ROOT}/framework/governance/THRESHOLD_NAMING_RULES.md
  • Layer registry (roster, chains, folders): ${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml
  • Per-layer templates & READMEs: ${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/
  • Cross-document validation: ../doc-validator/SKILL.md
  • Workflow routing: ../doc-flow/SKILL.md
  • Diagrams: ../charts-flow/SKILL.md

Comments

Markdown supported