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:
- 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
- Add render tasks (
task roadmap:render, task prd:render) that generate the MD from the vBRIEF source
- Add oplus rules to
main.md and vbrief/vbrief.md prohibiting direct writes to these artifacts -- parallel to the existing SPECIFICATION.md prohibition
- Add schema coverage for new artifact types (or reuse the existing
specification.vbrief.json schema where shape matches)
- 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
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:#86(artifact-branch binding) has no stable anchor -- binding requires a source file, not a rendered outputCurrent State
SPECIFICATION.mdvbrief/specification.vbrief.jsonmain.md+vbrief.md)ROADMAP.mdPRD.mdThe
vbrief/vbrief.mdtaxonomy 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:
vbrief/vbrief.mdtaxonomy for:roadmap.vbrief.json,prd.vbrief.json, and a genericartifact-{name}.vbrief.jsonslot for other structured docstask roadmap:render,task prd:render) that generate the MD from the vBRIEF sourcemain.mdandvbrief/vbrief.mdprohibiting direct writes to these artifacts -- parallel to the existingSPECIFICATION.mdprohibitionspecification.vbrief.jsonschema where shape matches)ROADMAP.mdandPRD.mdto be generated artifacts with source files invbrief/Out of Scope
CHANGELOG.md-- append-driven by convention, not generated from a structured source; exclude from this initiativeAGENTS.md,README.md-- human-maintained, not agent-generated artifactsplan.vbrief.json/continue.vbrief.json-- already covered by vBRIEF taxonomy (no MD render needed)Acceptance Criteria
vbrief/vbrief.mdtaxonomy includesroadmap.vbrief.jsonandprd.vbrief.json(and genericartifact-{name}.vbrief.json) with lifecycle rulesmain.mdcontains prohibition rule: do not writeROADMAP.mdorPRD.mddirectly -- edit the vBRIEF source and run the render taskROADMAP.mdandPRD.mdare generated from their vBRIEF sources (migration included)scripts/spec_validate.pyor equivalent validates new source files against schema before renderSPECIFICATION.mdpipeline is unchangedRelated Issues