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:

git adr show {id}

git adr search "X"

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

git adr init

git adr new "<title>"

git adr list

git adr show <id>

git adr edit <id>

git adr search "<query>"

git adr supersede <old-id> "<title>"

git adr link <id> <commit>

git adr sync --push

git adr sync --pull

git adr stats

git adr export

git adr config list

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

madr

nygard

y-statement

alexandrian

business

planguage

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:

references/formats/{template}.md

references/commands.md

references/configuration.md

references/best-practices.md

references/workflows.md

references/search-patterns.md

workflows/decision-capture.md

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

references/commands.md

references/configuration.md

references/best-practices.md

references/workflows.md

references/search-patterns.md

references/formats/madr.md

references/formats/nygard.md

references/formats/y-statement.md

references/formats/alexandrian.md

references/formats/business-case.md

references/formats/planguage.md

workflows/session-start.md

workflows/decision-capture.md

workflows/decision-recall.md