Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

setup-adrs

Create the foundational Architecture Decision Record (ADR) sequence for a new project. Use after bootstrap-project, when establishing decision documentation, or when standardizing ADR practices.

jrjsmrtn · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add jrjsmrtn/project-orchestration-skills --skill setup-adrs

About this skill


name: setup-adrs description: Create the foundational Architecture Decision Record (ADR) sequence for a new project. Use after bootstrap-project, when establishing decision documentation, or when standardizing ADR practices. metadata: author: "Georges Martin jrjsmrtn@gmail.com" version: "0.1.34" license: MIT

Foundation ADRs

Create the foundational Architecture Decision Record (ADR) sequence for a new project.

When to Use

  • After running bootstrap-project skill
  • When establishing decision documentation for an existing project
  • When standardizing ADR practices across projects

Required Inputs

  1. Project name and description (from CLAUDE.md or user)
  2. Project type: Development, Infrastructure, or Hybrid
  3. Technology stack decision and rationale
  4. Development practices to adopt (can use defaults)
  5. Operations requirements (critical for Infrastructure projects)
  6. Project-specific constraints or requirements

Foundational ADR Framework

Every project should have these foundational ADRs:

ADRPurposeScopeCritical For
ADR-0001HOW TO DECIDEDecision methodologyAll projects
ADR-0002HOW TO DEVELOPDevelopment practicesAll projects
ADR-0003WHAT TECHTechnology stackAll projects
ADR-0004HOW TO OPERATEOperations practicesInfrastructure, Hybrid (optional)

Note: ADR-0004 is only needed for Infrastructure and Hybrid projects. Skip it for pure development projects (libraries, CLI tools, web apps without self-hosting concerns).

Audience Traceability

ADRs serve the Contribution audience category (maintainers, contributors, future architects). They provide the "understanding-oriented" content in Diátaxis terms, explaining why decisions were made.

If a SPARK Audience Registry exists for the project, tag ADRs with the registry's identifier for the Contribution audience:

---
audience: contribution  # or the project's registry ID for maintainers/contributors
---

Pattern Reference: See AUDIENCE-DRIVEN ARTIFACTS

ADR Numbering Convention

Before creating ADRs, check for existing ones to prevent conflicts:

# Check highest ADR number
ls docs/adr/*.md 2>/dev/null | grep -E '[0-9]{4}-' | sort -V | tail -1

# If no ADRs exist, start with 0001

Filename: NNNN-title-with-hyphens.md (e.g., 0001-record-architecture-decisions.md) Title: # N. Title using adr-tools format (e.g., # 1. Record Architecture Decisions). This format is required for Structurizr !adrs integration.

Workflow

ADR-0001: Record Architecture Decisions

Create docs/adr/0001-record-architecture-decisions.md:

# 1. Record Architecture Decisions

Date: [YYYY-MM-DD]

## Status

Accepted

## Context

[Project name] requires a systematic approach to documenting significant architectural and technical decisions. As the project evolves, we need to maintain a clear record of why decisions were made, what alternatives were considered, and what trade-offs were accepted.

This is especially important for AI-assisted development, where decisions made in one session need to be understood in future sessions.

## Decision

We will use Architecture Decision Records (ADRs) to document significant architectural decisions.

**ADR Location**: All ADRs stored in `docs/adr/` directory

**ADR Format**: Following the format established by Michael Nygard:
- **Title**: Short noun phrase (ADR-NNNN: Title)
- **Status**: Proposed, Accepted, Deprecated, Superseded
- **Context**: Forces at play, including technical, business, and social
- **Decision**: The response to these forces
- **Consequences**: Resulting context after applying the decision

**Numbering**: Sequential four-digit format (0001, 0002, ...) with no gaps

**What Warrants an ADR**:
- Technology stack choices
- Architectural patterns adopted
- Build/deployment approaches
- Integration decisions
- Security-related choices
- Decisions that would be costly to reverse

## Consequences

**Positive**:
- Clear record of why decisions were made
- Context preserved for future maintainers and AI assistants
- Reduced repeated discussions about settled decisions
- Audit trail for architectural evolution

**Negative**:
- Overhead of writing and maintaining ADRs
- Risk of ADRs becoming outdated if not maintained

## References

- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - Michael Nygard
- [ADR GitHub Organization](https://adr.github.io/)

ADR-0002: Adopt Development Best Practices

Create docs/adr/0002-adopt-development-best-practices.md:

Scale the detail to the project. A small CLI tool needs ~100 lines; a multi-subsystem application may need 300-700 lines. Include only sections that apply.

# 2. Adopt Development Best Practices

Date: [YYYY-MM-DD]

## Status

Accepted

## Context

[Project name] is a [type] project using [technology stack]. We need consistent development practices that enable high-quality, maintainable code while supporting AI-assisted development workflows.

This project follows [AI-Assisted Project Orchestration patterns](https://github.com/jrjsmrtn/ai-assisted-project-orchestration).

## Decision

### 1. Testing Strategy

- **Framework**: [ecosystem-specific: ExUnit, pytest, cargo test, etc.]
- **Approach**: TDD — Red-Green-Refactor cycle
- **Coverage target**: >80% for core logic
- **Test organization**:
  - `test/unit/` or `test/[app]/` — unit tests (fast, isolated)
  - `test/integration/` — integration tests (slower, may require external services)

[For Elixir: add property-based testing with StreamData if applicable]
[For Elixir: add contract tests if defining behaviours]

### 2. BDD with Gherkin (user-facing projects)

[Include th
Read the complete source ↗