Skip to content

feat(vbrief): extend vBRIEF source-of-truth to all agent-generated MD artifacts (ROADMAP.md, PRD.md) #308

@MScottAdams

Description

@MScottAdams

Problem

The vBRIEF source-of-truth principle is currently enforced only for SPECIFICATION.md. All other agent-generated MD artifacts (ROADMAP.md, PRD.md, and future structured documents) are written directly by agents without a machine-readable source file. This means:

  • No schema validation on those artifacts
  • No structured diff or changelog between versions
  • No audit trail linking artifact content to the intent that produced it
  • Direct edits to MD bypass any structural integrity checks
  • #86 (artifact-branch binding) has no stable anchor -- binding requires a source file, not a rendered output

Current State

Artifact vBRIEF Source Enforced?
SPECIFICATION.md vbrief/specification.vbrief.json Yes (main.md + vbrief.md)
ROADMAP.md None No -- written directly
PRD.md None No -- written directly
Future structured docs None No

The vbrief/vbrief.md taxonomy currently defines exactly 5 file types (specification, plan, continue, playbook, specification-{name}). There is no slot for roadmap, PRD, or other durable structured artifacts.

Proposed Change

Extend the vBRIEF source-of-truth pattern to all durable agent-generated MD artifacts:

  1. Define new vBRIEF file types in vbrief/vbrief.md taxonomy for: roadmap.vbrief.json, prd.vbrief.json, and a generic artifact-{name}.vbrief.json slot for other structured docs
  2. Add render tasks (task roadmap:render, task prd:render) that generate the MD from the vBRIEF source
  3. Add oplus rules to main.md and vbrief/vbrief.md prohibiting direct writes to these artifacts -- parallel to the existing SPECIFICATION.md prohibition
  4. Add schema coverage for new artifact types (or reuse the existing specification.vbrief.json schema where shape matches)
  5. Migrate existing ROADMAP.md and PRD.md to be generated artifacts with source files in vbrief/

Out of Scope

  • CHANGELOG.md -- append-driven by convention, not generated from a structured source; exclude from this initiative
  • AGENTS.md, README.md -- human-maintained, not agent-generated artifacts
  • plan.vbrief.json / continue.vbrief.json -- already covered by vBRIEF taxonomy (no MD render needed)

Acceptance Criteria

  • vbrief/vbrief.md taxonomy includes roadmap.vbrief.json and prd.vbrief.json (and generic artifact-{name}.vbrief.json) with lifecycle rules
  • main.md contains prohibition rule: do not write ROADMAP.md or PRD.md directly -- edit the vBRIEF source and run the render task
  • Render tasks exist for each new artifact type
  • ROADMAP.md and PRD.md are generated from their vBRIEF sources (migration included)
  • scripts/spec_validate.py or equivalent validates new source files against schema before render
  • Tests cover render pipeline and direct-write prohibition
  • Existing SPECIFICATION.md pipeline is unchanged

Related Issues

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions