git-adr

git-adr Skill

Comprehensive skill for managing Architecture Decision Records using the git-adr CLI tool.

Auto-Context Loading

At session start, if in a git-adr repository, automatically load ADR summary:

# Silent detection and load
git notes --ref=adr list &>/dev/null && git adr list --format oneline 2>/dev/null

This provides awareness of existing decisions without consuming excessive context. See workflows/session-start.md for full behavior.

On-Demand Hydration

Use progressive loading for token efficiency:

Trigger	Action
"Show me ADR {id}"	git adr show {id} → full content
"What did we decide about X"	git adr search "X" → snippets
"Record this decision"	Guided creation workflow

See workflows/decision-recall.md for recall patterns. See workflows/decision-capture.md for creation flow.

CRITICAL RULES

NEVER modify user configuration without explicit permission.

• Do NOT run git-adr config --set or git config adr.* commands unless the user explicitly asks to change config
• Do NOT "check" config by running set commands - use git config --get or git-adr config --get only
• Before using AI features, READ the existing config with git config --local --list | grep adr - do NOT assume or set values
• If AI config is missing, ASK the user what provider/model they want - do NOT set defaults
• The user's config is sacred - treat it as read-only unless explicitly told otherwise

What is git-adr?

git-adr is a command-line tool that manages ADRs using git notes instead of files:

• Non-intrusive: ADRs don't clutter the working tree
• Portable: Travel with git history
• Linkable: Associate decisions with commits
• Syncable: Push/pull like regular git content

Quick Command Reference

Command	Description
git adr init	Initialize ADR tracking
git adr new "<title>"	Create new ADR
git adr list	List all ADRs
git adr show <id>	Display an ADR
git adr edit <id>	Edit an ADR
git adr search "<query>"	Search ADRs
git adr supersede <old-id> "<title>"	Supersede a decision
git adr link <id> <commit>	Link ADR to commit
git adr sync --push	Push ADRs to remote
git adr sync --pull	Pull ADRs from remote
git adr stats	Show statistics
git adr export	Export to files
git adr config list	Show configuration

For full command documentation, see references/commands.md.

Execution Patterns

Before Executing Commands

Always verify the environment:

# 1. Check git-adr is installed
git adr --version

# 2. Verify in a git repository
git rev-parse --is-inside-work-tree

# 3. For most commands, check if initialized
git notes --ref=adr list 2>/dev/null || echo "Not initialized"

Error Handling

If git-adr is not installed:

git-adr is not installed. Install with:
  cargo install git-adr
  # or
  brew tap zircote/tap && brew install git-adr

If not in a git repository:

git-adr requires a git repository. Initialize with:
  git init
  git adr init

If ADRs not initialized:

ADR tracking not initialized. Run:
  git adr init

Format Selection

Reading Project Configuration

Always check the project's configured template before generating content:

# Get configured template (defaults to madr if not set)
TEMPLATE=$(git config --get adr.template 2>/dev/null || echo "madr")
echo "Using template: $TEMPLATE"

Available Formats

Format	Config Value	Best For
MADR	madr	General purpose, option analysis (default)
Nygard	nygard	Quick, minimal decisions
Y-Statement	y-statement	Ultra-concise, single sentence
Alexandrian	alexandrian	Pattern-based, forces analysis
Business Case	business	Stakeholder approval, ROI
Planguage	planguage	Measurable quality requirements

For format templates, see references/formats/.

Creating ADRs

Workflow

1. Check format: Read adr.template config
2. Load template: Read appropriate format from references/formats/
3. Generate content: Fill template with user's context
4. Execute command: git adr new "<title>" with content

Example: Creating a MADR

# Create ADR (opens editor with template)
git adr new "Use PostgreSQL for primary database"

# Or with specific format override
git adr new "Use PostgreSQL" --template nygard

When generating content, follow the structure in the appropriate format template.

Common Workflows

New Project Setup

git adr init
git adr new "Record architecture decisions"
git adr sync --push

Team Collaboration

git adr sync --pull        # Get latest
git adr new "Add caching"  # Create decision
git adr sync --push        # Share with team

Linking to Implementation

# After implementing a decision
git adr link 20250115-use-postgresql abc1234

# View linked commits
git adr show 20250115-use-postgresql

Superseding Decisions

# When replacing a decision
git adr supersede 20250101-use-mysql "Migrate to PostgreSQL"

For more workflows, see references/workflows.md.

Configuration

Common configuration options:

# Set default template
git adr config adr.template madr

# Set editor
git adr config --global adr.editor "code --wait"

# Enable auto-sync
git adr config adr.sync.auto_push true
git adr config adr.sync.auto_pull true

For all configuration options, see references/configuration.md.

ADR Best Practices

When to Write an ADR

Write an ADR for decisions that are:

• Significant: Affects architecture or design
• Structural: Changes system organization
• Hard to reverse: Would require substantial effort to change

What Makes a Good ADR

• Clear context: Explains the situation and constraints
• Explicit decision: States what was decided
• Documented consequences: Lists positive, negative, and neutral effects
• Alternatives considered: Shows options evaluated

Common Mistakes

• Too detailed (specification, not decision)
• Too brief (no context or rationale)
• Not updating status when decisions change
• Writing long after the decision was made

For complete guidance, see references/best-practices.md.

Progressive Loading Guide

Load reference files based on user intent:

User Intent	Load File
"Create an ADR"	references/formats/{template}.md
"What commands are available?"	references/commands.md
"Configure git-adr"	references/configuration.md
"What is an ADR?"	references/best-practices.md
"Set up for my team"	references/workflows.md
"Find decisions about X"	references/search-patterns.md
"Record this decision"	workflows/decision-capture.md
"What did we decide"	workflows/decision-recall.md

ADR Content Generation

When generating ADR content:

1. Read the project's configured format
2. Load the corresponding template from references/formats/
3. Ask clarifying questions if context is insufficient:
   • What problem are you solving?
   • What alternatives did you consider?
   • What are the constraints?
4. Fill the template with the gathered information
5. Execute the command to create the ADR

Content Quality Checklist

Before creating an ADR, ensure:

• Context explains the situation clearly
• Decision is explicitly stated
• Consequences are categorized (positive/negative/neutral)
• Alternatives were considered (for MADR format)
• Status is appropriate (proposed/accepted)

Reference Files

File	Purpose
references/commands.md	Full command documentation
references/configuration.md	All config options
references/best-practices.md	ADR writing guidance
references/workflows.md	Common workflow patterns
references/search-patterns.md	Natural language → search mapping
references/formats/madr.md	MADR template
references/formats/nygard.md	Nygard template
references/formats/y-statement.md	Y-Statement template
references/formats/alexandrian.md	Alexandrian template
references/formats/business-case.md	Business Case template
references/formats/planguage.md	Planguage template
workflows/session-start.md	Auto-context loading behavior
workflows/decision-capture.md	Guided ADR creation workflow
workflows/decision-recall.md	Find past decisions workflow