Agent-Skills.md

Agent Skills: Docs Adr

Create numbered Architecture Decision Records (ADR) documenting architectural

UncategorizedID: mgiovani/cc-arsenal/docs-adr

Repository

mgiovani/cc-arsenal
mgiovaniLicense: MIT
21

Install this agent skill to your local

pnpm dlx add-skill https://github.com/mgiovani/cc-arsenal/tree/HEAD/skills/docs-adr

Skill Files

Browse the full folder contents for docs-adr.

Download Skill

Loading file tree…

skills/docs-adr/SKILL.md

Skill Metadata

Name
docs-adr
Description
Create numbered Architecture Decision Records (ADR) documenting architectural

Docs Adr

Cross-Platform AI Agent Skill This skill works with any AI agent platform that supports the skills.sh standard.

Create Architecture Decision Record

Create a new Architecture Decision Record (ADR) documenting an architectural decision.

Anti-Hallucination Guidelines

CRITICAL: ADRs document REAL decisions about REAL code. Before writing:

  1. Verify the technology exists - If ADR mentions "Redis", confirm Redis is actually used
  2. Reference actual files - Do not invent file paths; grep/glob to find real ones
  3. Quote real code - If mentioning a pattern, find an actual example
  4. Check current state - The "Context" section must reflect verified reality

Workflow

Phase 1: Explore Context (Explore Codebase)

Before writing an ADR, explore the codebase using available search and analysis tools to understand the relevant codebase context:

Phase 2: Parse Arguments

  1. Extract decision title from command arguments
  2. Check for variant keyword: lightweight, full, or madr
  3. If variant found, remove it from title
  4. Default variant: nygard (Nygard style)

Phase 3: Determine ADR Number

  • Scan docs/adr/ directory
  • Find highest existing ADR number (format: XXXX-*)
  • Increment by 1
  • If no ADRs exist, start with 0001
  • Format as 4-digit padded number (e.g., 0001, 0023)

Phase 4: Sanitize Title for Filename

  • Convert title to kebab-case
  • Remove special characters
  • Lowercase all letters
  • Example: "Use Redis for Caching" -> use-redis-for-caching

Phase 5: Gather Context

  • Search codebase for relevant information about the decision topic
  • Look for related code, configs, or documentation
  • Understand current state and alternatives
  • Keep context concise but informative

Phase 6: Load and Populate Template

  • Template location: assets/templates/
  • Select based on variant:
  • nygard -> nygard.md (default)
  • lightweight -> lightweight.md
  • full -> full.md
  • madr -> madr.md

Replace placeholders:

  • {{ADR_NUMBER}} - 4-digit number
  • {{ADR_TITLE}} - Original title (Title Case)
  • {{DATE}} - Current date (YYYY-MM-DD)
  • {{CONTEXT}} - Gathered context from codebase
  • {{PROJECT_NAME}} - Git repo or directory name

Phase 7: Create ADR File

  • Filename: docs/adr/XXXX-kebab-case-title.md
  • Ensure docs/adr/ directory exists
  • Write populated content
  • Set initial status to "Proposed"

Phase 8: Report Creation

  • Show ADR number and title
  • Display file path
  • Provide next steps

Template Variants

Nygard Style (Default)

Michael Nygard's ADR format - concise and focused.

Sections: Title with number, Status, Context, Decision, Consequences

Use when: Most decisions, balanced detail

Lightweight

Minimal ADR for quick decisions.

Sections: Title with number, Status, Decision, Rationale

Use when: Simple, straightforward decisions

Full

Comprehensive ADR with detailed sections.

Sections: Title with number, Status, Context, Decision Drivers, Considered Options, Decision, Consequences (Positive, Negative, Neutral), Pros and Cons, Related Decisions, References

Use when: Complex, high-impact decisions

MADR

Markdown Architectural Decision Records format.

Sections: Title with number, Status, Context and Problem Statement, Decision Drivers, Considered Options, Decision Outcome, Consequences

Use when: Following MADR standard

Usage Examples

Basic ADR creation (uses Nygard template):

docs-adr "Database Migration Strategy"
docs-adr "API Authentication Approach"
docs-adr "Microservices Communication Pattern"
With template variant override:

docs-adr lightweight "Use Redis for Session Storage" docs-adr full "Adopt Event-Driven Architecture" docs-adr madr "Select Database Technology"

ADR Numbering

  • First ADR: 0001-record-architecture-decisions.md (meta-ADR)
  • Subsequent ADRs: Auto-incremented (0002, 0003, etc.)
  • Format: XXXX-kebab-case-title.md

ADR Status Lifecycle

Update status in the ADR as the decision progresses:

  1. Proposed - Initial proposal (default)
  2. Accepted - Decision approved
  3. Deprecated - No longer recommended
  4. Superseded - Replaced by another ADR

Context Gathering Examples

# For database decisions
!`find . -name "*.sql" -o -name "*models.py" -o -name "*schema.prisma" | head -10`

# For API decisions
!`grep -r "router\|endpoint\|api" --include="*.py" --include="*.ts" --include="*.js" . | head -20`

# For architecture decisions
!`find . -name "docker-compose.yml" -o -name "*.config.js" -o -name "*.config.ts" | head -10`
## Important Notes

- **One Decision per ADR**: Keep focused on a single decision
- **Context Matters**: Include "why" even if it seems obvious
- **Link Related ADRs**: Reference superseded or related decisions
- **Early Documentation**: Create ADRs early in decision process
- **Imperative Language**: Use "we will" not "we should"
- **Status Updates**: Update status as decision progresses

## When to Create ADRs

Create an ADR when making:
- Technology stack decisions
- Architecture pattern choices
- Database or storage decisions
- API design choices
- Security architecture decisions
- Deployment strategy decisions
- Major library/framework selections
- Cross-cutting concerns (logging, caching, etc.)

## Best Practices

- **Create early**: Document decisions before implementation
- **Be honest**: Document the real reasons, not ideal reasons
- **Include alternatives**: Show what was considered
- **Accept trade-offs**: Acknowledge negative consequences
- **Link to code**: Reference implementation in the ADR
- **Review regularly**: Revisit ADRs during retrospectives
- **Update status**: Keep status current as decisions evolve

## Claude Code Enhanced Features

This skill includes the following Claude Code-specific enhancements:

## Workflow

### Phase 1: Explore Context (Use Explore Agent)

Before writing an ADR, use the Explore agent to understand the relevant codebase context:

Use Task tool with Explore agent:

  • prompt: "Search for code related to [DECISION_TOPIC]. Find: 1) Current implementation if any, 2) Related configuration files, 3) Dependencies involved, 4) Any existing documentation. Return verified file paths and relevant code snippets."
  • subagent_type: "Explore"

### Phase 2: Parse Arguments

1. Extract decision title from `$ARGUMENTS`
2. Check for variant keyword: `lightweight`, `full`, or `madr`
3. If variant found, remove it from title
4. Default variant: `nygard` (Nygard style)

### Phase 3: Determine ADR Number

- Scan `docs/adr/` directory
- Find highest existing ADR number (format: `XXXX-*`)
- Increment by 1
- If no ADRs exist, start with `0001`
- Format as 4-digit padded number (e.g., `0001`, `0023`)

### Phase 4: Sanitize Title for Filename

- Convert title to kebab-case
- Remove special characters
- Lowercase all letters
- Example: "Use Redis for Caching" -> `use-redis-for-caching`

### Phase 5: Gather Context

- Search codebase for relevant information about the decision topic
- Look for related code, configs, or documentation
- Understand current state and alternatives
- Keep context concise but informative

### Phase 6: Load and Populate Template

- Template location: `assets/templates/`
- Select based on variant:
  - `nygard` -> `nygard.md` (default)
  - `lightweight` -> `lightweight.md`
  - `full` -> `full.md`
  - `madr` -> `madr.md`

Replace placeholders:
- `{{ADR_NUMBER}}` - 4-digit number
- `{{ADR_TITLE}}` - Original title (Title Case)
- `{{DATE}}` - Current date (YYYY-MM-DD)
- `{{CONTEXT}}` - Gathered context from codebase
- `{{PROJECT_NAME}}` - Git repo or directory name

### Phase 7: Create ADR File

- Filename: `docs/adr/XXXX-kebab-case-title.md`
- Ensure `docs/adr/` directory exists
- Write populated content
- Set initial status to "Proposed"

### Phase 8: Report Creation

- Show ADR number and title
- Display file path
- Provide next steps