ADR Management Skill

Manage Architectural Decision Records (ADRs) stored in doc/adr/ directory.

Purpose

Provide structured management of architectural decisions:

•Create ADRs with automatic numbering and template
•Read ADR content by number
•Update ADR status through lifecycle
•Delete ADRs when necessary
•List all ADRs with optional filtering
•Validate ADR format using ref-documentation

Available Workflows

Workflow	Purpose	Script Used
list-adrs	List all ADRs with optional filtering	`manage-adr.py list`
create-adr	Create new ADR from template	`manage-adr.py create`
read-adr	Read ADR content	`manage-adr.py read`
update-adr	Update ADR status	`manage-adr.py update`
delete-adr	Delete ADR (with confirmation)	`manage-adr.py delete`
validate-adr	Validate ADR format	ref-documentation workflows

Workflow: list-adrs

List all ADRs with optional status filtering.

Parameters

•status (optional): Filter by status (Proposed, Accepted, Deprecated, Superseded)

Steps

Step 1: Execute List

bash

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr list [--status {status}]

Step 3: Parse Output

Parse JSON output containing ADR list with metadata.

Output

json

{
  "success": true,
  "operation": "list",
  "count": 3,
  "adrs": [
    {"number": 1, "title": "Use PostgreSQL", "status": "Accepted", "path": "doc/adr/001-Use_PostgreSQL.adoc"},
    {"number": 2, "title": "Adopt Quarkus", "status": "Proposed", "path": "doc/adr/002-Adopt_Quarkus.adoc"}
  ]
}

Workflow: create-adr

Create a new ADR with automatic numbering.

Parameters

•title (required): ADR title
•status (optional, default: "Proposed"): Initial status

Steps

Step 1: Create ADR

bash

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr create --title "{title}" [--status "{status}"]

Step 3: Parse Output

Extract created file path from JSON output.

Step 4: Open for Editing

Read the created file and inform user to fill in content sections.

Step 5: Validate Format

code

Skill: pm-documents:ref-documentation
Execute workflow: validate-format
Parameters:
  target: {created_path}

Output

code

ADR Created: doc/adr/004-{title}.adoc
Number: ADR-004
Status: Proposed

Next steps:
1. Edit doc/adr/004-{title}.adoc to fill in:
   - Context
   - Decision
   - Consequences
   - Alternatives
2. Update status to "Accepted" when approved

Workflow: read-adr

Read ADR content by number.

Parameters

•number (required): ADR number (1, 2, 3, etc.)

Steps

Step 1: Read ADR

bash

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr read --number {number}

Step 3: Display Content

Show ADR metadata and content to user.

Workflow: update-adr

Update ADR status through lifecycle.

Parameters

•number (required): ADR number
•status (required): New status (Proposed, Accepted, Deprecated, Superseded)

Steps

Step 1: Update ADR

bash

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr update --number {number} --status {status}

Step 3: Confirm Update

Report updated status to user.

Workflow: delete-adr

Delete ADR with confirmation.

Parameters

•number (required): ADR number
•force (required): Must be true to confirm deletion

Steps

Step 1: Delete ADR

bash

python3 .plan/execute-script.py pm-documents:manage-adr:manage-adr delete --number {number} --force

Step 3: Confirm Deletion

Report deletion to user.

Workflow: validate-adr

Validate ADR format using ref-documentation skill.

Parameters

•number (required): ADR number to validate

Steps

Step 1: Find ADR Path

Use list-adrs workflow to get ADR path by number.

Step 2: Validate Format

code

Skill: pm-documents:ref-documentation
Execute workflow: validate-format
Parameters:
  target: {adr_path}

Step 3: Report Results

Report validation results to user.

Integration with ref-documentation

This skill integrates with ref-documentation for:

•Format validation: Ensures AsciiDoc formatting compliance
•Link verification: Validates cross-references
•Content review: Reviews ADR content quality

ADR Lifecycle

code

Proposed → Accepted → [Deprecated | Superseded]

Status	Meaning
Proposed	Under discussion, not yet approved
Accepted	Approved and active
Deprecated	No longer relevant or applicable
Superseded	Replaced by another ADR

ADR Template Structure

Each ADR contains these sections:

•Status - Current lifecycle status
•Context - Problem context and background
•Decision - The architectural decision made
•Consequences - Positive, negative outcomes and risks
•Alternatives Considered - Options that were not chosen
•References - Related documents and links

File Naming Convention

ADRs follow this naming pattern:

code

doc/adr/{NNN}-{Title_With_Underscores}.adoc

Examples:

•doc/adr/001-Use_PostgreSQL_for_Persistence.adoc
•doc/adr/002-Adopt_Quarkus_Framework.adoc
•doc/adr/003-Implement_CQRS_Pattern.adoc

References

•ref-documentation SKILL - Format validation