Create Architecture Decision Record
Create numbered ADRs with category-based organization and status workflow.
Prerequisites
Verify ADR entity is enabled in the secondbrain project:
-
Check for .claude/data/adrs/records.yaml
-
If not found, suggest running secondbrain-init with ADRs enabled
Workflow
Step 1: Gather Information
Collect from user or conversation context:
Category (determines number range):
-
infrastructure (0001-0999) — Architecture & infrastructure
-
feature (2000-2999) — Feature implementation
-
process (3000-3999) — Process & workflow
Title — Brief decision title (will be slugified for filename)
Context — What problem prompted this decision?
Step 2: Determine ADR Number
-
Load .claude/data/adrs/records.yaml
-
Find highest number in selected category range
-
Increment to get next number
-
Format: ADR-XXXX (zero-padded)
Number Ranges:
infrastructure: 0001 - 0999 feature: 2000 - 2999 process: 3000 - 3999
Step 3: Generate ADR Document
Use template from ${CLAUDE_PLUGIN_ROOT}/templates/entities/adr/TEMPLATE.md :
Filename: docs/adrs/ADR-XXXX-<title-slug>.md
Frontmatter:
id: ADR-XXXX status: draft date_created: YYYY-MM-DD date_updated: YYYY-MM-DD author: <author> category: <category>
Step 4: Update Records
Add entry to .claude/data/adrs/records.yaml :
- number: XXXX title: "<title>" status: draft category: <category> created: YYYY-MM-DD file: docs/adrs/ADR-XXXX-<slug>.md author: <author>
Update last_number if this is the new highest.
Step 5: Sidebar Note
DO NOT manually add ADRs to VitePress sidebar.
ADRs are automatically listed via the EntityTable component on docs/adrs/index.md , which reads from .claude/data/adrs/records.yaml . No sidebar modification needed.
Step 6: Confirm Creation
ADR Created
ID: ADR-0012 Title: Kubernetes Migration Strategy Category: infrastructure Status: draft File: docs/adrs/ADR-0012-kubernetes-migration-strategy.md
Next Steps
- Edit the ADR to add context, options, and decision
- Change status to 'proposed' when ready for review
- Use /secondbrain-adr-status to update status
Status Workflow
draft → proposed → admitted → applied → implemented → tested
Status Workflow
Draft → Proposed → Admitted → Applied → Implemented → Tested ↘ Rejected ↘ Canceled
Status Description
draft Initial creation, under development
proposed Ready for review
admitted Approved, pending implementation
applied Implementation started
implemented Implementation complete
tested Verified in production
rejected Not approved
canceled Abandoned
Additional Resources
- references/adr-template.md — Full ADR template