Skip to content
OpenSmartRoute
Skillv1.0.0

doc-brd

Create a Business Requirements Document (BRD) - Layer 1 of the SDD flow, defining business needs, objectives, and success criteria. Use when starting a new project or feature. Single-document authorin

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-brd/SKILL.md). Install upstream with npx skills add vladm3105/aidoc-flow-framework --skill doc-brd. Copyright stays with the author.

doc-brd

Purpose

Create a Business Requirements Document (BRD) — Layer 1 of the SDD flow. A BRD captures business objectives, stakeholders, scope, and success criteria in business language, before any product or technical detail.

Layer: 1 (entry point, no upstream). Downstream: PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code.

One MVP iteration = 5–15 focused requirements total, spread across as many BRD documents as that needs: a single BRD SHOULD carry at most 5 functional requirements (GD-14), so a cycle needs at least ceil(N/5) documents — a floor, not a ceiling. Beyond five, start BRD-02. New features also get a new BRD. Use @depends: BRD-NN only for a genuine hard prerequisite; a document created because the previous one hit the cap is a sibling, recorded in the BRD-00 index.

When to Use

Use doc-brd when:

  • Starting a new project or feature and defining business requirements.
  • Documenting strategic alignment, market context, and success criteria.
  • Translating an implementation plan back into business-language requirements.

For end-to-end generation from reference docs, a prompt, or an IPLAN, use ../doc-brd-autopilot/SKILL.md. For a new project skeleton, run ../project-init/SKILL.md first.

Prerequisites

BRD is the entry point, so there are no upstream artifacts to verify. Before writing, read:

  1. Template (source of truth): ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml
  2. Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/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

Confirm no ID collision: ls docs/01_BRD/. Never invent placeholders like BRD-XXX or reference non-existent documents.

Layer Guidance

Platform vs Feature BRD (decide first)

Signal Type
Defines infrastructure, technology stack, or cross-cutting concerns Platform
Other BRDs will depend on its architectural choices Platform
Describes one user-facing workflow / feature Feature
Builds on capabilities an existing Platform BRD established Feature
  • Platform BRD — file BRD-NN_platform_{slug}; ADRs are created before the PRD to validate architectural choices; §8 (Architecture Decision Topics) is populated with the Selected categories that downstream BRDs will depend on.
  • Feature BRD — file BRD-NN_{feature_slug}; standard layer flow (BRD → PRD → EARS → BDD → ADR); §8 references the Platform BRD's adopted topics rather than introducing new architectural decisions.

Required structure (16 sections)

document_control is Section 1 (project name, version, date YYYY-MM-DD, owner, prepared-by, status, revision-history table). Then:

  1. Executive Summary (OPTIONAL — derived; toggled by section_toggles) ·
  2. Introduction · 4. Business Objectives · 5. Project Scope · 6. Stakeholders ·
  3. Functional Requirements · 8. Architecture Decision Topics (adr_topics) ·
  4. Quality Expectations · 10. Constraints and Assumptions ·
  5. Acceptance Criteria and Success Validation · 12. Business Risk Management ·
  6. Approval · 14. Traceability · 15. Glossary ·
  7. Seed Disposition (seed_disposition — OPTIONAL, _required: false; the seed→SDD absorption ledger, GD-08 / SEED_CONTRACT.md).

The template additionally defines two structural blocks alongside the numbered sections: a Diagrams Registry (diagrams:) and a Lifecycle Reference appendix (appendix:) — see those template keys for the required shape. Section numbers and section identifiers come from the template's own numbering and top-level YAML keys; the template is the source of truth, and this skill's list is a navigation aid, not a parallel definition.

See BRD-TEMPLATE.yaml for per-section content and cross_section_rules.

Section 8 — Architecture Decision Topics (mandatory)

Identify architectural topics needing decisions, with cost-focused, alternatives-based analysis, across the 7 categories. Do not reference ADR numbers — ADRs do not exist yet.

# Category When N/A
1 Infrastructure Pure data/analytics project
2 Data Architecture No persistent data
3 Integration Standalone system
4 Security Internal tool, no sensitive data
5 Observability MVP/prototype only
6 AI/ML No AI/ML components
7 Technology Selection Using an existing stack

Each Selected topic carries a BRD.NN.08.xxxx element ID and includes a status, business driver, business constraints, an Alternatives Overview table (with cost estimates), a Cloud Provider Comparison (GCP/Azure/AWS), a recommended selection, and the PRD requirements it implies. Layer separation: BRD §8 = what & why & how much; PRD = how to evaluate; ADR = the decision.

Element IDs and tags

  • Element IDs: BRD.{doc_id}.{section_id}.{hash}. Do not compute the hash in this prompt — call the generator: python -m sdd_doc_lint.rehash --compute --doc-id NN --section-id SS --title T --description D (--length 8 on collision). Authority: framework/governance/ID_NAMING_STANDARDS.md; never restate the algorithm here.
  • Layer 1 carries no @ upstream tags; downstream tags it (@brd: BRD.01.06.a7f3).
  • Removed patterns: AC-XXX, FR-XXX, BO-XXX, BC-XXX, legacy 3-segment BRD.NN.xxxx.

Upstream source configuration

Most BRDs are authored from stakeholder input — keep the default upstream_mode: "none". Only when content derives from docs/00_REF/ docs set upstream_mode: "ref" and list upstream_ref_path (relative to the BRD file).

Creation Process

  1. Determine type — Platform vs Feature (table above).
  2. Reserve ID — next free BRD-NN (two digits, no leading zero beyond two: BRD-01, BRD-99, BRD-102). 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 BRD lives in docs/01_BRD/BRD-NN_{slug}/ regardless of size. Monolithic: BRD-NN_{slug}.md inside it; section-based (>25 KB): BRD-NN.S_{section}.md + index from ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-00_index.TEMPLATE.md.
  4. Document Control (Section 1) first, then complete the 14 remaining required sections + the diagrams registry + appendix per template; toggle §2 (Executive Summary) per section_toggles.
  5. Fill §8 (Architecture Decision Topics) across the 7 categories.
  6. Configure upstream mode (none default; ref if from docs/00_REF/).
  7. Update the BRD index docs/01_BRD/BRD-00_index.md in the same change.
  8. Validate (below) and commit the BRD and index together.

Draft mode (saga-driven)

When invoked via the saga-driven autopilot subprocess pattern (per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md and the saga loop in ../doc-brd-autopilot/SKILL.md), this skill is the entry point for the draft phase of the create→review→revise loop. The invocation looks like:

claude --plugin-dir "$PLUGIN_DIR" -p \
  "/aidoc-flow:doc-brd Draft BRD-<id> at <path>; use BRD-TEMPLATE.yaml + the source input at <seed-path>. Write to docs/01_BRD/BRD-<id>_<slug>/."

Because claude -p has no subagent_type CLI parameter, the persona binding (business_analyst lens → aidoc-flow:requirements-analyst agent per ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_CREWS.yaml plus the lens-to-agent table in ../review-team/SKILL.md) moves INTO this SKILL's prompt. When the invocation brief contains the word Draft (case-insensitive) — indicating a saga-driven draft phase — dispatch the author this way:

  1. Dispatch ONE Task subagent with subagent_type=aidoc-flow:requirements-analyst, acting as the business_analyst lens (BRD author per REVIEW_CREWS.yaml's BRD crew).
  2. Brief: the BRD-TEMPLATE.yaml + the source input (REF / prompt / IPLAN seed file at the path passed in) + this SKILL's ## Creation Process (above) as authoring rules.
  3. The subagent writes the BRD to the nested folder docs/01_BRD/BRD-<id>_<slug>/ per the standard layout.
  4. After the subagent returns, write the saga.json transition recording the draft completion: append {"ts": "<now>", "from": "FANOUT_STARTED", "to": "BRANCH_COMPLETED", "scope": "branch:business_analyst"} to transitions[] if a saga.json exists at .aidoc/review/01_BRD/<BRD-id>/saga.json. (If no saga.json exists, this is a standalone invocation — skip the saga write per REVIEW_SAGA.md §"FRAMEWORK_SPEC_VERSION semantics" declaration-vs-implementation rule.)

When invoked outside the saga loop (a user runs /aidoc-flow:doc-brd directly to author a BRD), follow the ## Creation Process above without dispatching the Task subagent (the user is the author in that case). The two modes coexist; the trigger is the presence of Draft in the brief AND an existing <path> argument.

Validation

Validator framing (review_mode-aware). The structural checks below are the deterministic floor and run in every mode. In team mode the content-quality review is performed by ../doc-brd-audit/SKILL.md fanning out the BRD crew (architect/business_analyst/auditor/chaos_engineer/security_engineer); in single_pass mode the audit applies every lens in one pass. Either way this skill (the author) does not score the artifact — it produces it.

This skill is the validator (no runtime code). Apply against ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/README.md and ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md.

  • Document Control (Section 1) is the first section.
  • All required template sections present and non-empty: §1, §3–§15, plus the diagrams registry and appendix; §2 Executive Summary only when section_toggles includes it. Enumerate by reading BRD-TEMPLATE.yaml.
  • §8 covers all 7 ADR-topic categories; no ADR numbers referenced.
  • Element IDs match BRD.NN.SS.xxxx; no removed patterns.
  • Traceability matrix / index created or updated; no broken links.
  • Diagram contract: @diagram: c4-l1 and @diagram: dfd-l1 present (use ../charts-flow/SKILL.md); add a sequence tag if a sequence diagram exists.

Error codes (all severity error): XDOC-006 tag format invalid · XDOC-008 broken internal link · XDOC-009 missing traceability section.

Quality gate (blocking): PRD-Ready score ≥ 90/100 before moving on.

BRD-REF documents (via ../doc-ref/SKILL.md) are free-format references — exempt from ready-scores, cumulative tags, and quality gates.

Next Skill

../doc-prd/SKILL.md — the PRD references this BRD (@brd: BRD.NN.SS.xxxx), defines product features and KPIs, and inherits the §8 architecture topics.

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/01_BRD/BRD-TEMPLATE.yaml
  • Layer README: ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/README.md
  • Index template: ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-00_index.TEMPLATE.md
  • ID & tag standards: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • Quality gate: ../doc-brd-audit/SKILL.md · Fixes: ../doc-brd-fixer/SKILL.md
  • Generation pipeline: ../doc-brd-autopilot/SKILL.md

Quick Reference
Purpose Define business needs and objectives
Layer 1 (entry point)
Upstream tags None
Key decision Platform vs Feature
Must include §1 Document Control, §3–§15 required sections, §8 (7 categories), diagrams registry, appendix
Next doc-prd

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-brd/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-brd.ocm.jsonjson
{
  "ocm": "1",
  "id": "vladm3105-aidoc-flow-framework-doc-brd",
  "kind": "skill",
  "name": "doc-brd",
  "description": "Create a Business Requirements Document (BRD) - Layer 1 of the SDD flow, defining business needs, objectives, and success criteria. Use when starting a new project or feature. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-brd-autopilot`) drives this skill.",
  "publisher": "vladm3105",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "sdd-workflow",
      "layer-1-artifact",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Create a Business Requirements Document (BRD) - Layer 1 of the SDD flow, defining business needs, objectives, and success criteria. Use when starting a new project or feature. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-brd-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-brd/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/vladm3105/aidoc-flow-framework/blob/HEAD/platforms/claude-code-plugin/skills/doc-brd/SKILL.md",
      "key": "vladm3105/aidoc-flow-framework/platforms/claude-code-plugin/skills/doc-brd/SKILL.md"
    }
  },
  "instructions": "# doc-brd\n\n## Purpose\n\nCreate a **Business Requirements Document (BRD)** — Layer 1 of the SDD flow.\nA BRD captures business objectives, stakeholders, scope, and success criteria\nin business language, before any product or technical detail.\n\n**Layer**: 1 (entry point, no upstream).\n**Downstream**: PRD → EARS → BDD → ADR → SPEC → TDD → IPLAN → Code.\n\nOne MVP iteration = 5–15 focused requirements total, spread across as many BRD\ndocuments as that needs: a single BRD **SHOULD** carry at most 5 functional\nrequirements (GD-14), so a cycle needs at least `ceil(N/5)` documents — a floor, not\na ceiling",
  "cost": {
    "context_tokens": 3063
  }
}

Fetch it by URL: GET /api/v1/registry/vladm3105-aidoc-flow-framework-doc-brd/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.