--- 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:

| ADR | Purpose | Scope | Critical For | |-----|---------|-------|--------------| | ADR-0001 | HOW TO DECIDE | Decision methodology | All projects | | ADR-0002 | HOW TO DEVELOP | Development practices | All projects | | ADR-0003 | WHAT TECH | Technology stack | All projects | | ADR-0004 | HOW TO OPERATE | Operations practices | Infrastructure, 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: ```markdown --- audience: contribution # or the project's registry ID for maintainers/contributors --- ```

> **Pattern Reference**: See [AUDIENCE-DRIVEN ARTIFACTS](https://github.com/jrjsmrtn/ai-assisted-project-orchestration/blob/develop/docs/patterns/inception/audience-driven-artifacts.md)

## ADR Numbering Convention

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

```bash # 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`:

```markdown # 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.

```markdown # 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 this section for Web, GUI, TUI, CLI projects. Omit for libraries and infrastructure.]

- **Gherkin feature files**: `features/` or `test/features/` - **Step definitions**: `features/step_definitions/` or `test/features/step_definitions/` - **BDD framework**: [confirm during bootstrap — e.g., Cucumber for Elixir, Behave or pytest-bdd for Python] - **Browser automation**: [Playwright for web projects] - **Tagging**: `@wip`, `@smoke`, `@slow` for selective execution

### 3. Semantic Versioning

- Follow [SemVer 2.0.0](https://semver.org/) - During development: 0.1.x (increment patch per sprint/milestone) - No stable 1.0 until [condition: "Phase N complete", "production-ready", etc.] - Version location: [where the version is defined in the project]

### 4. Git Workflow

- **Gitflow-based**: `main`, `develop`, `feature/*`, `release/*`, `hotfix/*` - **Conventional Commits**: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:` - `main` tracks releases, `develop` is the integration branch

### 5. Change Documentation

- **Keep a Changelog** format in `CHANGELOG.md` - Categories: Added, Changed, Deprecated, Removed, Fixed, Security - Updated with each version bump

### 6. Architecture as Code

- **C4 DSL** models in `docs/architecture/` - Validated and inspected with the consolidated `structurizr/structurizr` container (`validate` and `inspect` subcommands) - Rendered with the same image's `local` subcommand for review

### 7. Documentation Framework

**Diátaxis** structure in `docs/`: - `tutorials/` — learning-oriented - `howto/` — problem-oriented - `reference/` — information-oriented - `explanation/` — understanding-oriented

ADRs in `docs/adr/`, sprint plans in `docs/sprints/`, roadmap in `docs/roadmap/`.

### 8. Sprint-Based Development

- Lightweight sprints aligned with roadmap phases - Sprint plans in `docs/sprints/sprint-NNNN-plan.md` - Retrospectives in `docs/sprints/sprint-NNNN-retrospective.md` (or `.yml`) - Roadmap in `docs/roadmap/roadmap.md`

### 9. Formatting and Editor Configuration

- **Editor configuration**: `.editorconfig` for consistent whitespace across editors - **Markdown formatting**: dprint (preferred) or prettier - **Code formatting**: [ecosystem-specific: mix format, ruff format, cargo fmt, etc.]

### 10. Quality Automation

**Git hooks** — lefthook (preferred) or pre-commit framework:

**Pre-commit** (fast, <30s): - Code formatting check - Markdown formatting check (dprint) - Secret scanning (gitleaks)

**Pre-push** (thorough): - Linting / static analysis ([mix credo, ruff check, eslint, etc.]) - Type checking ([Dialyzer, mypy, tsc, etc.]) - Dependency scanning ([mix deps.audit, pip-audit, npm audit, cargo audit, etc.]) - Fast tests (exclude slow/integration)

**CI** should run all pre-commit + pre-push checks, plus integration tests and coverage.

### 11. Licensing and Copyright

*(Enforce for projects intended for open-source release; skip for closed-source/private ones.)*

- **REUSE compliance** ([reuse.software](https://reuse.software/)) for machine-readable copyright and license declarations - SPDX headers (`SPDX-FileCopyrightText`, `SPDX-License-Identifier`) on source files - License texts in `LICENSES/` directory, bulk/vendored annotations in `REUSE.toml` - **Enforced, not just prescribed**: `reuse lint` runs as a git hook and a CI job (`fsfe/reuse-action`) — see `setup-git-hooks`. Third-party/transitive license compatibility is covered by the mixed-license aggregate analysis where applicable.

### 12. Code Conventions

[Project-specific patterns that AI and human contributors should follow. Examples:] - [Struct definition ordering, validation patterns, error handling conventions] - [Test addresses: RFC 5737 for IPs, RFC 7042 for MACs, RFC 2606 for domains] - [Naming conventions, module organization]

[Omit this section if no project-specific conventions exist yet.]

## Consequences

**Positive**: - Consistent practices across development sessions - AI assistants have clear guidance on standards - Quality gates catch issues early - Automated enforcement reduces review burden

**Negative**: - Initial setup overhead for tooling - [Ecosystem-specific: Dialyzer PLT build time, mypy strictness ramp-up, etc.]

## References

- [AI-Assisted Project Orchestration](https://github.com/jrjsmrtn/ai-assisted-project-orchestration) - [Ecosystem-specific documentation links] ```

**Ecosystem-specific guidance** (confirm choices during project bootstrap):

For **Elixir** projects, expand sections with: - ExUnit + StreamData (property-based testing) - BDD with Cucumber + Playwright (if user-facing) - usage_rules for Ash-based projects (AI documentation lookup) - mix format, mix credo --strict, Dialyzer - JUnit XML test reports

For **Python** projects, expand sections with: - pytest + pytest-asyncio - BDD with Behave or pytest-bdd + Playwright (if user-facing) - ruff (format + lint), mypy (strict mode)

For **Rust** projects, expand sections with: - cargo test + proptest (property-based) - cargo fmt, cargo clippy

For mature/security-sensitive projects, add: - Supply Chain Security (SLSA, EEF Ægis, OpenSSF)

### ADR-0003: Technology Stack Decision

Create `docs/adr/0003-[technology-stack-name].md`:

```markdown # 3. Use [Technology Stack]

Date: [YYYY-MM-DD]

## Status

Accepted

## Context

[Project name] requires [describe the technical needs].

Key requirements: - [Requirement 1] - [Requirement 2] - [Requirement 3]

We evaluated several technology options for [specific technical domain].

## Decision

We will use [Technology Stack] for [project name].

**Core Technologies**: - **Language**: [e.g., Elixir 1.18+, Python 3.12+] - **Framework**: [e.g., Phoenix 1.7+, FastAPI] - **Database**: [e.g., PostgreSQL 16+] - **Additional**: [other key technologies]

**Rationale**: - [Reason 1 with evidence] - [Reason 2 with evidence] - [Reason 3 with evidence]

**Alternatives Considered**:

| Option | Pros | Cons | Decision | |--------|------|------|----------| | [Option A] | [pros] |