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
1. Edit the ADR to add context, options, and decision
2. Change status to 'proposed' when ready for review
3. 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