Governance

Governance Documentation

Creates and manages governance documents: ADRs for architectural decisions, CRs for requirement changes.

Document Selection

ADR Workflow

Documentation-only task. Creating an ADR is a documentation-only task. No code compilation, test execution, or linting is required.

Use this checklist when creating an Architecture Decision Record:

- [ ] Read the template: templates/ADR.md
- [ ] Check docs/adr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/adr/ADR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Set status to "proposed"

Template frontmatter: The template file contains its own frontmatter (name: adr-template, description: Template for creating Architecture Decision Records (ADRs)., and metadata fields) that describe the template itself. Do not copy these values into created documents. Each ADR must have its own unique name and description reflecting the specific decision. Created ADR documents MUST omit the metadata.copyright and metadata.version frontmatter fields.

Strict requirements:

• File naming: ADR-NNNN-{title}.md (four-digit number, lowercase, hyphens)
• Initial status: proposed
• Location: project's docs/adr/ folder

Flexible (adapt to context):

• Level of detail in alternatives section
• Number of consequences listed
• Diagram inclusion (recommended for complex decisions)

CR Workflow

Documentation-only task. Creating a CR is a documentation-only task. No code compilation, test execution, or linting is required.

Use this checklist when creating a Change Request:

- [ ] Read the template: templates/CR.md
- [ ] Check docs/cr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/cr/CR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Write acceptance criteria in Gherkin format
- [ ] Set status to "proposed"

Template frontmatter: The template file contains its own frontmatter (name: cr-template, description: Template for creating Change Requests (CRs)., and metadata fields) that describe the template itself. Do not copy these values into created documents. Each CR must have its own unique name and description reflecting the specific change request. Created CR documents MUST omit the metadata.copyright and metadata.version frontmatter fields.

Strict requirements:

• File naming: CR-NNNN-{title}.md (four-digit number, lowercase, hyphens)
• Initial status: proposed
• Location: project's docs/cr/ folder
• Acceptance criteria: Gherkin format (Given-When-Then)
• Requirements keywords: RFC 2119 (MUST, SHOULD, MAY)

Flexible (adapt to context):

• Document length (minimum 250 lines for complex changes)
• Number of diagrams
• Depth of impact assessment

Templates

• ADR: templates/ADR.md
• CR: templates/CR.md

Reference Guides

For detailed lifecycle information, best practices, and examples:

• ADR Guide: reference/adr-guide.md
• CR Guide: reference/cr-guide.md

Commit Message Format

Committing governance documents is the human's responsibility. When ready to commit, use these formats:

• ADR: docs(adr): add ADR-NNNN {title}
• CR: docs(cr): add CR-NNNN {title}

Converted and distributed by TomeVault — claim your Tome and manage your conversions.