mcpField
D
doc-ref

doc-ref

github.com/vladm3105Documents1757 installsUpdated 1d ago
Repository

About doc-ref

doc-ref is a skill for creating supplementary reference documents that accompany BRD or ADR artifacts. It defines naming, placement, required sections, and lightweight validation while keeping these documents outside formal traceability.

Key features

  1. 01BRD-REF and ADR-REF document guidance
  2. 02File naming and placement rules
  3. 03Four mandatory document sections
  4. 04Validation without traceability checks

Use cases

  1. 01Writing a project overview for a BRD
  2. 02Adding an architecture guide to an ADR

Install

Copy the command and run it in a terminal.

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

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

Details

From the project README

doc-ref

Purpose

Create Reference Documents (REF) — free-format supplementary documents that support a BRD or ADR without participating in the formal traceability chain. REF documents provide context (overviews, summaries, guides); they carry no element IDs, cumulative tags, ready-scores, or quality gates.

Layer: cross-cutting utility — REF documents are limited to BRD and ADR parent types only.

When to Use

Use doc-ref for supplements such as:

  • BRD-REF — project overviews, executive summaries, strategic vision, stakeholder guides.
  • ADR-REF — technology-stack summaries, architecture overviews, infrastructure guides.

Do NOT use for: anything that should participate in traceability; core artifacts (BRD/PRD/EARS/BDD/ADR/SPEC/TDD/IPLAN — use their doc-* skills); or any parent type other than BRD or ADR.

Behavior

Naming and location
  • File name: {TYPE}-REF-NN_{slug}.md (TYPE ∈ {BRD, ADR}); H1: # {TYPE}-REF-NN: Title.
  • NN is a variable-length sequence (2+ digits), independent per parent type: BRD-REF-01, BRD-REF-102, ADR-REF-01 are separate sequences.
  • Located inside the parent type directory, e.g. docs/01_BRD/BRD-REF-01_project_overview.md, docs/05_ADR/ADR-REF-01_technology_stack_summary.md.
  • Regex — file: ^(BRD|ADR)-REF-[0-9]{2,}_[a-z0-9_]+\.md$; H1: ^#\s(BRD|ADR)-REF-[0-9]{2,}:.+$.
Creation process
  1. Determine the parent type — business context → BRD-REF; architecture context → ADR-REF.
  2. Allocate the next number — ls docs/01_BRD/*-REF-* 2>/dev/null (or 05_ADR) and take the next free NN.
  3. Draft from the parent template, stripped to REF essentials — start from ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml (BRD-REF) or ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml (ADR-REF) and keep only the four mandatory sections, dropping the traceability scaffolding.
  4. Place the file in the parent type directory with the correct H1.
Required sections (4, mandatory)
  1. YAML frontmatter (artifact_type: REF).
  2. Document Control (version, date, author, status).
  3. Document Revision History.
  4. Introduction (purpose and scope).

Optional: Related Documents (cross-references encouraged) and any content sections the reference material needs.

Validation (this skill is the validator)

Blocking checks only: H1 matches {TYPE}-REF-NN: Title; Document Control, Revision History, and Introduction sections are present. Exempt (not checked): cumulative tags, full traceability, quality gates, ready-scores — REF documents do not participate in the chain. No element IDs apply.

Related Resources

  • Parent templates: ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml, ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
  • Naming authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md · ../doc-naming/SKILL.md
  • Governance & per-layer authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ and each ${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md
  • Parent skills: ../doc-brd/SKILL.md · ../doc-adr/SKILL.md
  • Workflow routing: ../doc-flow/SKILL.md
  • Diagrams: ../charts-flow/SKILL.md

Comments

Markdown supported