magnus919_agent-skills/adr-authoring/references/project-setup-guide.md

Bootstrapping ADR Conventions in a New Project

A repeatable workflow for establishing Architecture Decision Records in a codebase that doesn't have them yet.

Use only after checking that no local convention exists or when the user asks to establish one. Existing repository instructions override every fallback below, including location, template, review workflow, and amendment policy.

Quick Checklist

• Choose a template (default: Nygard; MADR for multi-option analysis)
• Decide directory location (default: docs/adr/)
• Write a README index (docs/adr/README.md)
• Document conventions in CONTRIBUTING.md
• Document ADR location in AGENTS.md (AI agents need to know where to look)
• Create initial batch of ADRs for the design decisions already made
• Deliver through the repository's established review workflow

Step-by-Step

1. Choose a Template

When	Template	Sections
Quick decision, single rationale	Nygard (default)	Status, Context, Decision, Consequences
Multi-option trade-off analysis	MADR	Status, Deciders, Date, Context, Decision Drivers, Considered Options, Outcome, Links
High-stakes / regulatory	Tyree & Akerman	12 sections (Issue, Positions, Argument, Implications, etc.)
Vendor / procurement	Business Case	Evaluation criteria, cost/SWOT analysis
QA / NFR focused	Planguage	Tag, Gist, Priority, Stakeholders, Risks

2. Set Directory Convention

docs/
└── adr/
    ├── README.md          # Index table with statuses + links
    ├── 0001-title.md      # First ADR
    ├── 0002-title.md
    └── ...

Naming convention:

• NNNN-title-with-dashes.md — sequential zero-padded numbers, imperative verb phrase
• Status lives in the document header (Status: accepted), never in the filename
• Extension: .md for easy rendering

Directory naming note: Some teams prefer decisions/ over adr/ for plain-language accessibility. The ADR template format works identically with either name.

3. Write the README Index

The index serves as the entry point for anyone (including AI agents) exploring the decision log. Include:

• Brief explanation of what ADRs are and the convention
• Full table: ADR number, title, status
• Link back to CONTRIBUTING.md for the ADR workflow

See docs/adr/README.md in the GroktoCrawl repo (groktopus/groktocrawl) for a worked example.

4. Document in CONTRIBUTING.md

Add a section covering:

• Convention: file naming, statuses, immutability
• When to write an ADR: new integration/service, changing existing pattern, choosing between significant alternatives, decisions a future contributor would want the "why" on
• Workflow: create ADR with next number → include in PR → on acceptance update the index

5. Document in AGENTS.md

AI agents need a single sentence pointing them to the ADR directory:

Architecture Decision Records (ADRs) live in `docs/adr/` and capture the context
and rationale behind significant design choices. Always check the ADR index at
`docs/adr/README.md` before making architectural changes — existing ADRs may
document constraints or rejected alternatives that inform your approach.

6. Example Issue-First PR Workflow

Use this only if the repository requires an issue-first workflow; do not create issues, commits, or PRs solely because this example lists them.

1. File an issue documenting the adapter/architecture design (L1 summary + L2 key decisions)
2. Branch from main with a descriptive name (feat/adapter-architecture)
3. Create ADR files using the MADR template
4. Document convention in CONTRIBUTING.md
5. Add agent reference in AGENTS.md
6. Ignore generated local artifacts only when relevant to this project
7. Commit with Signed-off-by (DCO) and Refs: #NNN in the commit body
8. Push and open PR referencing the issue (Closes #NNN)

ADR Lifecycle (for ongoing use)

proposed → accepted | rejected
accepted → deprecated | superseded by ADR-NNNN

• Fallback amendment rule (local policy takes precedence): Preserve accepted rationale. To change a decision, write a new ADR and update only the old record's status and successor link.
• Linking: Every ADR's Links section should reference related ADRs with semantic link types: Refined by, Supersedes, Defined by, Contradicts.
• Retired numbers: Never reuse an ADR number — if rejected, leave the number retired in the index with status rejected.

Worked Example

The GroktoCrawl adapter architecture PR at groktopus/groktocrawl#89 demonstrates this full workflow:

• 9 ADRs using the MADR template covering the adapter registry pattern
• README index with status table
• CONTRIBUTING.md update with ADR convention section
• AGENTS.md update with ADR reference