mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-16 22:16:52 +03:00
Magnus HedemarkandGitHub
b5ba3a7793
* feat: add adr-authoring skill Signed-off-by: Magnus Hedemark <magnus919@pm.me> * fix: remove host-specific port assumptions Signed-off-by: Magnus Hedemark <magnus919@pm.me> --------- Signed-off-by: Magnus Hedemark <magnus919@pm.me>
103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# Bootstrapping ADR Conventions in a New Project
|
|
|
|
A repeatable workflow for establishing Architecture Decision Records in a codebase that doesn't have them yet.
|
|
|
|
## Quick Checklist
|
|
|
|
- [ ] Choose a template (default: MADR)
|
|
- [ ] 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)
|
|
- [ ] Add `.hermes/` to `.gitignore` if it doesn't exist
|
|
- [ ] Create initial batch of ADRs for the design decisions already made
|
|
- [ ] File as a single PR: issue → branch → ADRs + docs → PR
|
|
|
|
## Step-by-Step
|
|
|
|
### 1. Choose a Template
|
|
|
|
| When | Template | Sections |
|
|
|------|----------|----------|
|
|
| Quick decision, single rationale | **Nygard** | Status, Context, Decision, Consequences |
|
|
| Multi-option trade-off analysis | **MADR** (default) | 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
|
|
|
|
```text
|
|
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:
|
|
|
|
```markdown
|
|
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. Issue-First PR Workflow
|
|
|
|
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. Add `.hermes/` to `.gitignore` if missing (local dev artifacts should not be committed)
|
|
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)
|
|
|
|
```text
|
|
proposed → accepted → [deprecated | superseded by ADR-NNNN | rejected]
|
|
```
|
|
|
|
- **Immutable rule:** Existing ADRs are never edited after acceptance. To change a decision, write a new ADR and update the old one's status.
|
|
- **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
|