doc-ref
Create Reference Documents (REF) - free-format supplements for BRD and ADR that sit outside the formal traceability chain. Use for project overviews, strategic vision, or technology/infrastructure summaries.
How do I install this agent skill?
npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-refIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a utility for managing reference documentation in a development workflow. It uses standard shell commands to list and organize local files according to a structured naming convention and template. No security risks, remote dependencies, or malicious patterns were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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. NNis a variable-length sequence (2+ digits), independent per parent type:BRD-REF-01,BRD-REF-102,ADR-REF-01are 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
- Determine the parent type — business context → BRD-REF; architecture context → ADR-REF.
- Allocate the next number —
ls docs/01_BRD/*-REF-* 2>/dev/null(or05_ADR) and take the next freeNN. - 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. - Place the file in the parent type directory with the correct H1.
Required sections (4, mandatory)
- YAML frontmatter (
artifact_type: REF). - Document Control (version, date, author, status).
- Document Revision History.
- 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vladm3105/aidoc-flow-framework/doc-ref">View doc-ref on skillZs</a>