Governance Documentation
Creates and manages governance documents: ADRs for architectural decisions, CRs for requirement changes.
Document Selection
| Need | Document | Guide |
|---|---|---|
| Technical/architectural decision | ADR | reference/adr-guide.md |
| Requirement or scope change | CR | reference/cr-guide.md |
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}