diff --git a/AGENTS.md b/AGENTS.md index 5075d1f..0403d6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,6 +134,7 @@ When the user mentions these keywords, load the corresponding skill: | "technical-documentation", "technical documentation" | [technical-documentation](technical-documentation/SKILL.md) | | "security-audit-methodology", "security audit methodology" | [security-audit-methodology](security-audit-methodology/SKILL.md) | | "mermaid-diagrams", "mermaid diagrams" | [mermaid-diagrams](mermaid-diagrams/SKILL.md) | +| "adr-authoring", "adr authoring" | [adr-authoring](adr-authoring/SKILL.md) | ## Use-When Sections Every skill description must identify when to load it. Skills with meaningful overlap should also include a `## When not to use` section naming the nearest alternative or prerequisite. Keep these sections trigger-oriented and concise; implementation details belong in references. diff --git a/README.md b/README.md index 618c8c4..bde7f1c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ A collection of AI agent skills — reusable workflows, protocols, and knowledge ## Skills +### [adr-authoring](adr-authoring/SKILL.md) + +Preserve the reasoning behind consequential architecture choices so later contributors can understand, revisit, or supersede them responsibly. + ### [agent-council](agent-council/SKILL.md) Multi-agent structured debate system — spawn a panel of expert agents to debate any question with convergence-aware iteration. Produces a decision landscape with confidence diagnostics, shared risks, remaining disagreements, and a principal's path narrative. Ships as a pip-installable Python package built on PydanticAI + PydanticGraph. `pip install pydantic-ai && pip install agent-council` and one API key to run your first debate. diff --git a/adr-authoring/README.md b/adr-authoring/README.md new file mode 100644 index 0000000..838993f --- /dev/null +++ b/adr-authoring/README.md @@ -0,0 +1,36 @@ +# Adr Authoring + +Preserve the reasoning behind consequential architecture choices so later contributors can understand, revisit, or supersede them responsibly. + +## Why Install This Skill + +Preserve the reasoning behind consequential architecture choices so later contributors can understand, revisit, or supersede them responsibly. It preserves a practical method, local reference material, and reusable templates so an agent can do more than produce a generic answer. + +Use it when the work needs a repeatable process and an inspectable result. It is portable across Agent Skills-compatible clients and does not require a profile system or a particular task orchestrator. + +## What You Get + +| Path | What it provides | +|---|---| +| `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. | +| `references/` | Reference material: `adr-format.md`, `adr-to-pyramid-mapping.md`, `decision-sustainability.md`, `fitness-functions.md`, `project-setup-guide.md` | + +## Quick Start + +Read `SKILL.md` for the decision workflow, then start from `references/adr-format.md`. + +Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below. + +## Triggers + +- Write, review, and maintain architecture decision records with clear context, alternatives, consequences, and lifecycle governance. Use when a consequential technical decision must remain understandable. +- Requests involving the method, deliverables, or review process described in `SKILL.md`. +- Work where a reusable template or reference from this skill would reduce avoidable mistakes. + +## Requirements + +No runtime dependency. + +## Source and maintenance + +This skill was extracted from [`magnus919/hermes-profiles`](https://github.com/magnus919/hermes-profiles) at commit [`867a555`](https://github.com/magnus919/hermes-profiles/commit/867a555). The portable methodology was retained; Hermes-specific profile, orchestration, and memory assumptions were removed. diff --git a/adr-authoring/SKILL.md b/adr-authoring/SKILL.md new file mode 100644 index 0000000..b10a7b7 --- /dev/null +++ b/adr-authoring/SKILL.md @@ -0,0 +1,122 @@ +--- +name: adr-authoring +description: Write, review, and maintain architecture decision records with clear context, alternatives, consequences, and lifecycle governance. Use when a consequential technical decision must remain understandable. +license: MIT +compatibility: No runtime dependency. +metadata: + source_repo: https://github.com/magnus919/hermes-profiles + source_commit: 867a555 +--- + + +# ADR Authoring + +Architecture Decision Records for capturing design rationale. ADRs supply the temporal dimension — decisions over time — that structure-only views (C4) miss. + +## ADR-to-Pyramid Mapping + +| ADR State | Pyramid Layer | Path | +|-----------|--------------|------| +| Navigation index | L1 (Summary) | 01-summary/adr-index.md | +| Active ADRs | L2 (Analysis) | 02-analysis/architecture-decisions/ADR-NNN.md | +| Superseded ADRs | L3 (Dossiers) | 03-dossiers/adr-superseded.md | + +Without ADRs, an agent sees a snapshot of the structure but cannot reconstruct the path that led to it. Active ADRs in L2 provide the decision rationale. Superseded ADRs in L3 preserve the history of rejected alternatives. + +## ADR Lifecycle + +ADRs progress through six stages, each with a gate criterion: + +``` +Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting +``` + +| Stage | Status | Pyramid Layer | Consumer | +|-------|--------|--------------|----------| +| Initiating | `proposed` | L2 (02-analysis/) | Engineers evaluating | +| Researching | `proposed` | L2 (02-analysis/) | Engineers evaluating | +| Evaluating | `proposed` | L2 (02-analysis/) | Engineers deciding | +| Implementing | `accepted` | L2 (02-analysis/) | Implementers, reviewers | +| Maintaining | `accepted` | L2 (02-analysis/) | New team members, auditors | +| Sunsetting | `deprecated`/`superseded` | L3 (03-dossiers/) | Historians | + +All live ADRs (proposed + accepted) stay in L2. Only superseded/deprecated ADRs move to L3. Proposed ADRs that are rejected should be moved to L3 with status `rejected` and a note on why. + +### Alternative Lifecycle: AWS ADR Process + +AWS Prescriptive Guidance defines a complementary lifecycle with a structured review process for teams that prefer formal immutability over living documents. + +**States:** `proposed → accepted | rejected | superseded` + +**Key difference:** AWS treats ADRs as strictly immutable once accepted. Changing a decision requires a new ADR that supersedes the old one. The community ADR repo's teamwork advice prefers mutable living documents with date-stamped updates. Choose the model that fits your team's culture. + +**AWS Review Process:** + +1. **Proposal** — any team member creates an ADR in `proposed` state. The author is the ADR owner. +2. **Review meeting** — dedicated time slot with structured format: + - **10-15 minutes silent reading** — each member reads the ADR and adds comments + - **Comment read-out** — the owner reads each comment aloud; team discusses + - **Action points** — identified issues get an assignee; tracked to resolution +3. **Decision** — three outcomes: + - **Accepted** → owner adds timestamp, version, stakeholder list. State → `accepted`. Immutable. + - **Rework** → state stays `proposed`. Owner resolves action points and re-schedules review. + - **Rejected** → owner documents rejection reason (prevents future re-litigation). State → `rejected`. File moves to L3. +4. **Superseding** — new decision invalidates an accepted ADR? Create a new ADR. On acceptance, update old ADR status to `superseded` and move it to L3. + +``` +[Identify need] → [Draft (proposed)] → [10-15m silent read] → [Discuss] + ↓ ↓ ↓ + [Rework/review] ← [Needs rework] [Accepted] → [Immutable] + [Rejected] → [L3] +``` + +## Template Selection + +| When | Template | Sections | +|------|----------|----------| +| Quick decision, single rationale | **Nygard** | Status, Context, Decision, Consequences | +| Multi-option trade-off analysis | **MADR** | Decision Drivers, Considered Options, Pros/Cons, Links | +| High-stakes, regulatory, compliance | **Tyree & Akerman** | 12 sections: Issue, Positions, Argument, Implications, etc. | +| Vendor/procurement decision | **Business Case** | Evaluation criteria, Cost/SWOT, Recommendations | +| QA/contract-driven environment | **Planguage** | Tag, Gist, Priority, Stakeholders, Risks | + +Full catalog with section-by-section guidance in `references/adr-format.md`. + +## File Naming Conventions + +Use present tense imperative verb phrases, lowercase-dashes, `.md` extension: + +``` +001-choose-database.md +002-format-timestamps.md +003-manage-secrets.md +``` + +Status lives in the document header, not the filename — status changes shouldn't require renames. + +## Teamwork & Governance + +- **Who can create:** Any team member who has read the ADR process docs +- **What justifies:** Decisions affecting future "why", cross-team coordination, long-term maintainability, external interfaces +- **What does NOT:** Limited scope/time/risk, already covered by standards, temporary workarounds/POCs +- **Roles per ADR:** Primary contact, secondary contact, accountable team +- **Living documents preferred:** Insert new info with date stamps rather than superseding ADRs for every update. Immutability is ideal in theory; mutability works better in practice. + +See `references/adr-format.md` for the full governance model and teamwork questions. + +## Contents + +- `references/adr-format.md` — template catalog (11 formats: Nygard, MADR, Tyree & Akerman, Business Case, Planguage, Alexandrian, ITD, arc42, EdgeX, Gareth Morgan, NHS Wales), template selection decision tree, lifecycle stages, file naming, team governance, examples reference +- `references/adr-to-pyramid-mapping.md` — active→L2, superseded→L3, consumer routing +- `references/fitness-functions.md` — decisions as code: ArchUnit, ArchUnitTS, AI-assisted fitness functions, pyramid mapping (fitness functions → L3) +- `references/decision-sustainability.md` — 5 sustainability criteria + 8 guidelines for evaluating ADR quality before acceptance +- `references/project-setup-guide.md` — bootstrapping ADRs in a new project: directory setup, README index, CONTRIBUTING.md/AGENTS.md docs, issue-first PR workflow with worked example + +## Canonical Reference + +- Architecture Decision Record community repo — https://github.com/architecture-decision-record/architecture-decision-record +- Michael Nygard, "Documenting Architecture Decisions" — https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions + +## Portability + +This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format. diff --git a/adr-authoring/references/adr-format.md b/adr-authoring/references/adr-format.md new file mode 100644 index 0000000..fbe5db5 --- /dev/null +++ b/adr-authoring/references/adr-format.md @@ -0,0 +1,639 @@ +# ADR Format & Authoring Guide + +Complete catalog of Architecture Decision Record formats from the community ADR repository (https://github.com/architecture-decision-record/architecture-decision-record), with selection guidance by decision type and worked examples. + +## Template Selection Guide + +| Decision Type | Recommended Template | Why | +|---|---|---| +| Routine technology choice (library, framework) | **Nygard** | Lightweight: Status, Context, Decision, Consequences | +| Multi-option trade-off with explicit comparison | **MADR** | Decision Drivers + Considered Options with pros/cons | +| High-stakes / regulatory / compliance | **Tyree & Akerman** | 12 sections covering Issue, Assumptions, Constraints, Positions, Argument, Implications, Related decisions/requirements/artifacts/principles | +| Vendor / procurement / build-vs-buy | **Business Case** | Evaluation criteria, cost analysis, SWOT, opinions/recommendations | +| QA-contract / SLAs / non-functional requirements | **Planguage** | Tag, Gist, Priority, Stakeholders, Risks, Defined terms | +| Quick internal consensus, no formal review | **Alexandrian** | Context-specific, minimal structure | +| C-suite / executive review | **ITD (Important Technical Decisions)** | Decision-first, optimized for fast executive scanning | + +--- + +## Template Catalog + +### 1. Michael Nygard (Simple & Popular) + +**Origin:** http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions + +**When to use:** Everyday decisions where the rationale is straightforward and options are few. The default choice unless you need more structure. + +``` +# Title (present tense imperative verb phrase) + +## Status + +proposed | accepted | rejected | deprecated | superseded by ADR-NNN + +## Context + +What is the issue that we're seeing that motivates this decision or change? + +## Decision + +What is the change we're proposing and/or doing? + +## Consequences + +What becomes easier or more difficult to do because of this change? +``` + +**Section guidance:** +- **Title:** Short imperative phrase like "Use PostgreSQL for transaction storage" or "Adopt event-driven messaging between services" +- **Status:** Single value. Use lifecycle stages for more precision. +- **Context:** The forces at play — business need, technical constraint, team capability, timeline pressure. Include why this decision is being made *now*. +- **Decision:** The outcome. Concrete and unambiguous. "We will use X" not "We considered using X." +- **Consequences:** Both positive and negative. What trade-offs are being accepted? What follow-up decisions does this create? + +**Pitfalls:** +- Too terse for multi-stakeholder decisions where options need explicit comparison +- No natural place for decision driver documentation +- Temptation to skip "Consequences" when they're the most important section + +--- + +### 2. MADR — Markdown Any Decision Records (Structured) + +**Origin:** https://adr.github.io/madr/ + +**When to use:** Most decisions that involve multiple options with explicit trade-off comparison. The best default for most engineering teams. + +``` +# [short title of solved problem and solution] + +* Status: proposed | rejected | accepted | deprecated | superseded by ADR-NNN +* Deciders: [list everyone involved in the decision] +* Date: YYYY-MM-DD + +Technical Story: [description | ticket/issue URL] + +## Context and Problem Statement + +[Describe the context and problem statement. You may want to articulate the + problem in form of a question.] + +## Decision Drivers + +* [driver 1, e.g., a force, facing concern] +* [driver 2] +* ... + +## Considered Options + +* [option 1] +* [option 2] +* [option 3] + +## Decision Outcome + +Chosen option: "[option 1]", because [justification]. + +### Positive Consequences + +* [e.g., improvement of quality attribute satisfaction] +* ... + +### Negative Consequences + +* [e.g., compromising quality attribute] +* ... + +## Pros and Cons of the Options + +### [option 1] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] + +### [option 2] + +* Good, because [argument a] +* Bad, because [argument b] + +## Links + +* Refined by [ADR-0005](0005-example.md) +* Supersedes [ADR-0002](0002-example.md) +``` + +**Section guidance:** +- **Decision Drivers:** The non-negotiable constraints that any solution must satisfy. These are your selection criteria. If the decision doesn't need explicit criteria, consider using Nygard instead. +- **Considered Options:** Exhaustive enough that no reviewer asks "Did you think about X?" but not so exhaustive it becomes noise. 3-5 options is typical. +- **Pros and Cons:** Each option gets its own subsection with bullet-point pros and cons. Be specific — "Good, because reduces latency by 40% under peak load" not "Good, because faster." +- **Links:** Bidirectional links to related ADRs. Use semantic link types: supersedes, refines, contradicts, extends. + +**Pitfalls:** +- "Considered Options" sections can balloon. Cap at 5 options; group similar alternatives. +- Decision Drivers are often just listed not ranked. Prioritize them (Must-have vs Nice-to-have). + +--- + +### 3. Jeff Tyree & Art Akerman (Heavyweight / Enterprise) + +**Origin:** https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf + +**When to use:** High-stakes decisions with regulatory, compliance, or cross-team implications. Decisions that will be audited or referenced for years. + +| Section | Purpose | +|---|---| +| **Issue** | The architectural design issue being addressed, with clear rationale for why *now* | +| **Decision** | The architecture's direction — the position selected | +| **Status** | pending, decided, approved | +| **Group** | Ontology grouping: integration, presentation, data, event, calendar, location | +| **Assumptions** | Underlying environmental assumptions (cost, schedule, technology, accepted standards) | +| **Constraints** | Additional constraints the chosen alternative imposes | +| **Positions** | Viable options considered. Include models, diagrams. This prevents "Did you think about X?" in review | +| **Argument** | Why you selected the position: implementation cost, TCO, time-to-market, resource availability. As important as the decision itself | +| **Implications** | Follow-on effects: new required decisions, new/modified requirements, additional constraints, scope/ schedule changes, training needs | +| **Related decisions** | Traceability matrix, decision trees, or metamodels. Links to related AD decisions | +| **Related requirements** | Direct mapping to business objectives. If a decision doesn't contribute to a requirement, don't make it | +| **Related artifacts** | Architecture, design, or scope documents this decision impacts | +| **Related principles** | Enterprise principles this decision is consistent with. Ensures cross-system alignment | +| **Notes** | Running notes from the socialization process | + +**When to skip:** Routine choices, single-developer decisions, temporary workarounds. + +--- + +### 4. Business Case (Procurement / Vendor) + +**When to use:** Build-vs-buy, vendor selection, technology procurement — decisions where cost and organizational impact are primary drivers. + +**Top-level structure:** +- Title +- Status +- Evaluation criteria +- Candidates to consider +- Research and analysis of each candidate + - Does/doesn't meet criteria + - Cost analysis (licensing, training, operating, metering) + - SWOT analysis (Strengths, Weaknesses, Opportunities, Threats) + - Internal and external opinions/feedback +- Recommendation + +**Cost analysis dimensions:** +- **Licensing:** contract agreements, legal commitments, vendor lock-in risk +- **Training:** upskilling, change management, ramp time +- **Operating:** support, maintenance, incident response +- **Metering:** bandwidth, CPU, API calls, data egress + +**Pitfalls:** +- External opinions can be biased toward whatever the vendor recommends. Cross-reference. +- Cost estimates age fast — include date stamps on all pricing references. + +--- + +### 5. Planguage (QA / NFR Focused) + +**Origin:** Tom Gilb, https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf + +**When to use:** Decisions driven by quality attributes, SLAs, or non-functional requirements where precision and measurability matter. + +| Keyword | Purpose | +|---|---| +| **Tag** | Unique, persistent identifier | +| **Gist** | Brief summary of the requirement or area | +| **Requirement** | The requirement text | +| **Rationale** | Reasoning justifying the requirement | +| **Priority** | Statement of priority and claim on resources | +| **Stakeholders** | Parties materially affected | +| **Status** | Draft, reviewed, committed | +| **Owner** | Person responsible for implementing | +| **Author** | Person who wrote it | +| **Revision** | Version number | +| **Date** | Most recent revision date | +| **Assumptions** | Things that could cause problems if untrue | +| **Risks** | Things that could cause malfunction or delay | +| **Defined** | Glossary terms | + +--- + +### 6. Alexandrian Pattern (Context-First) + +**When to use:** Decisions where the context is the main driver and the solution space is tightly constrained. + +``` +## [Title] + +## Context + +[The forces at play — when does this pattern apply?] + +## Problem + +[The specific problem this decision addresses] + +## Solution + +[The decision, stated as the resolution of the forces] + +## Consequences + +[What follows from applying this solution] +``` + +--- + +### 7. Important Technical Decisions — ITD (Executive) + +**Origin:** Ignacio Larrañaga + +**When to use:** Decisions that need executive sign-off. Lean and decision-first — optimized for fast scanning, not detailed deliberation. + +``` +# [Decision title] + +## Decision + +[One-line statement of what was decided] + +## Why + +[Brief rationale — why this decision, why now] + +## Impact + +[What changes as a result — one paragraph] +``` + +--- + +### 8. arc42 ADR Template (Full Documentation Structure) + +**Origin:** https://arc42.org/overview — License: CC-BY-SA 4.0 + +**When to use:** Decisions that need to be documented within the full arc42 architecture documentation framework. This is the ADR-specific template by the arc42 team, distinct from the arc42 full documentation template (used by the `arc42-context` skill for system context/constraint documentation). + +**Sections:** + +| arc42 Section | Purpose | +|---|---| +| **1. Introduction & Goals** | Requirements, driving forces, quality goals, stakeholders | +| **2. Constraints** | Anything constraining design/implementation freedom | +| **3. Context & Scope** | System boundary, external interfaces, business/technical context | +| **4. Solution Strategy** | Fundamental decisions shaping the architecture | +| **5. Building Block View** | Static decomposition — modules, components, layers | +| **6. Runtime View** | Behavior via scenarios — use cases, errors, operations | +| **7. Deployment View** | Infrastructure, environments, mapping of building blocks | +| **8. Crosscutting Concepts** | Patterns, rules, regulations spanning multiple building blocks | +| **9. Architectural Decisions** | Important decisions including rationale (this is the ADR proper) | +| **10. Quality Requirements** | Quality scenarios, quality tree | +| **11. Risks & Technical Debt** | Known risks, debt; ordered by priority | + +**Relationship to arc42-context skill:** Our arc42-context skill uses the full arc42 template for documenting system constraints at the project level. This ADR template is a *lightweight version* focused on a single decision within that framework. Use this when documenting a decision inside existing arc42 documentation. + +--- + +### 9. EdgeX Template (Platform / IoT) + +**Origin:** https://docs.edgexfoundry.org/2.3/design/adr/template/ + +**When to use:** Decisions involving platform components, service boundaries, or API changes — especially IoT/edge contexts where multiple services are impacted. + +``` +# [Title] + +## Submitters + +- Name (Organization) + +## Change Log + +- [Status](URL of PR) YYYY-MM-DD + Status: pending, approved, amended, deprecated. + +## Referenced Use Case(s) + +- [Use Case Name](URL) + +## Context + +- How the design is architecturally significant +- High-level design approach + +## Proposed Design + +Details without implementation: + +- Services/modules impacted (changed) +- New services/modules to be added +- Model and DTO impact (additions/removals) +- API impact (additions/removals) +- Configuration impact +- DevOps impact + +## Considerations + +Alternatives, concerns, issues from debate. Resolution status. + +## Decision + +Caveats, future considerations, remaining or deferred issues. +Requirements not satisfied by the proposed design. + +## Other Related ADRs + +- [ADR Title](URL) — Relevance + +## References +``` + +**Distinctive features:** Change Log with state/date/PR URL; Referenced Use Case(s); unusually detailed Proposed Design (model/DTO/API/config/devops). Good for when the ADR serves as both decision record AND preliminary design document. + +--- + +### 10. Gareth Morgan Template (Summary-Driven) + +**Origin:** Gareth Morgan + +**When to use:** Decisions needing an executive summary first, followed by structured option analysis. Summary → Drivers → Options → Analysis → Recommendation structure mirrors modern product decision-making. + +``` +# [Title] + +**Status:** Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated +**Updated:** YYYY-MM-DD + +## Summary + +Executive summary / elevator pitch. 2-4 sentences stating the core problem +and a hint at the decision. Think abstract of a technical paper. + +## Drivers + +Why this decision is being made now: + +- {We are developing a new feature that needs...} +- {We need to improve performance, accessibility...} +- {The current approach imposes limitations...} + +## Options + +List of options with facts, links: + +### {Option 1} +Description + +### {Option n} +... + +## Options Analysis + +### {Option 1 Assessment} +- Pro: {Specific advantage} +- Con: {Specific disadvantage, risk, or cost} +- Other: {Relevant point} + +### {Option n Assessment} +... + +## Recommendation + +Clear statement of the final decision and why it best addresses the Drivers. + +### Consequences + +- Pro: {Positive outcome} +- Con: {Accepted downside or risk} +- Other: {Matter-of-fact consequence} + +### Confirmation + +- How implementation will be verified (reviews, tests, demos) +- How compliance will be maintained (automated checks, audits) +- Metrics/indicators showing intended outcomes +- Responsible owner + +## More Information + +Supplementary info, links, re-evaluation timeframe. +``` + +**Distinctive features:** Summary-first (elevator pitch before detail); explicit Drivers section (why *now*); Consequences classified as Pro/Con/Other; **Confirmation section** — a verification plan with compliance monitoring, metrics, and ownership. Rare in ADR templates and essential for high-stakes decisions. + +--- + +### 11. GIG Cymru NHS Wales Template (Governance-Focused) + +**Origin:** NHS Wales / GIG Cymru + +**When to use:** Regulated environments (healthcare, finance, infrastructure) where compliance monitoring, governance, and visual options analysis are required. + +``` +# [Title] + +**Status:** DRAFT | ACTIVE | DEPRECATED by [000] | SUPERSEDES [000] + +## Context + +Problem(s) this ADR addresses and why they exist. + +## Decided Approach + +Architecturally significant decision and how it solves the problem. + +## Consequences + +Impact on architecture characteristics and functional requirements. + +## Governance + +How will outcomes be monitored? How will compliance be ensured? + +## Options Analysis + +Trade-off analysis with traffic-light comparison tables. + +### Key + +Green = good fit Amber = moderate Red = poor fit ++ = positive comment - = negative comment + +### High-Level Overview + +| Summary | Option 1 | Option 2 | Option 3 | +|---|---|---|---| +| Ease of Implementation | + Quick (green) | - Tricky (amber) | - Complex (red) | +| Timescales | + Fast (green) | - Slow (amber) | - Very slow (red) | +| Strategic Value | - Tactical (red) | + Improves (amber) | + Ideal (green) | + +### Functional Requirements + +| Scenario | Option 1 | Option 2 | Option 3 | +|---|---|---|---| +| Scenario 1 | | | | + +### Non-Functional Requirements + +| Characteristic | Option 1 | Option 2 | Option 3 | +|---|---|---|---| +| Scalability | | | | +| Performance | | | | +| Availability | | | | +``` + +**Distinctive features:** **Governance section** — unique among templates, asks explicitly about compliance monitoring. **Traffic-light comparison tables** — color-coded visual evaluation across summary, functional, and NFR dimensions. Designed for audited environments where decisions must be enforced, not just recorded. + +--- + +### Template Selection Decision Tree + +``` +Is the decision quick, single-rationale? + → YES → Nygard + → NO → Multiple options being compared? + → YES → Regulatory/governance requirement? + → YES → Compliance monitoring needed? + → YES → NHS Wales (governance + traffic-light tables) + → NO → Cost a primary driver? + → YES → Business Case (cost/SWOT) + → NO → Platform/service boundary change? + → YES → EdgeX (Change Log + Proposed Design) + → NO → MADR (structured option comparison) + → NO → MADR (default for multi-option) + → NO → QA/NFR-driven? → Planguage + → NO → C-suite consumption? → ITD + → NO → Context-first? → Alexandrian +``` + +--- + +### Examples Reference + +The community ADR repository includes ~50+ worked examples across multiple domains for learning and inspiration: + +| Domain | Example Topics | +|---|---| +| **Frameworks** | CSS framework, React, Svelte, Vue, Rails, SvelteKit, Tailwind CSS | +| **Databases** | MySQL, PostgreSQL, Database technology choice | +| **Languages** | Go, Rust, Java, Python | +| **Infrastructure** | Docker Swarm, Kubernetes, AWS, GCP, Azure, CI, Secrets storage | +| **APIs & Protocols** | JSON vs gRPC, snake_case vs camelCase, Timestamp format | +| **Team & Process** | 4-day work week, Agile, High-trust teamwork, Work from home | +| **Cross-cutting** | Monorepo vs multirepo, Environment variable config, Metrics | + +Browse the full collection at: https://github.com/architecture-decision-record/architecture-decision-record/tree/main/locales/en/examples/ + +Study 2-3 examples from your domain before writing a first ADR to internalize the conventions. + +--- + +## Worked Example: MADR Format + +``` +# Use PostgreSQL for Service Transaction Storage + +* Status: accepted +* Deciders: Magnus Hedemark, Sarah Chen, DevOps Team +* Date: 2026-06-05 + +Technical Story: Service requires durable, ACID-compliant storage for +customer transaction records across geographic regions. + +## Context and Problem Statement + +The service needs to store customer transaction data with strong consistency +guarantees. The current prototype uses in-memory storage which is unacceptable +for production. We need a database that supports ACID transactions, replication +across regions, and has a proven operational track record. + +## Decision Drivers + +* Must support ACID transactions (non-negotiable — regulatory requirement) +* Must support active-passive replication across 2 regions +* Team has existing PostgreSQL expertise (3 senior DBAs) +* Must fit within existing $500/mo infrastructure budget + +## Considered Options + +* PostgreSQL — relational, ACID, mature replication (pglogical / Patroni) +* MySQL — relational, ACID, Group Replication +* CockroachDB — distributed SQL, natively multi-region +* DynamoDB + transactions — managed NoSQL with limited ACID + +## Decision Outcome + +Chosen option: "PostgreSQL", because it satisfies all decision drivers, +eliminates team learning curve, and has the lowest operational cost for our +scale. + +### Positive Consequences + +* ACID compliance guaranteed within existing team expertise +* Active-passive replication via Patroni (deploy this week) +* No licensing costs; fits within infrastructure budget + +### Negative Consequences + +* Manual sharding may be needed above 5TB (unlikely in year 1) +* Single-writer limitation in active-passive mode + +## Pros and Cons of the Options + +### PostgreSQL + +* Good, because full ACID with serializable isolation +* Good, because existing team expertise eliminates ramp time +* Good, because mature replication tooling (Patroni, repmgr) +* Bad, because single-writer topology limits write throughput + +### MySQL + +* Good, because ACID with InnoDB +* Good, because Group Replication supports multi-writer +* Bad, because less team expertise (1 DBA vs 3 for Postgres) +* Bad, because Group Replication has known stability issues in async mode + +### CockroachDB + +* Good, because natively multi-region with strong consistency +* Bad, because 2x infrastructure cost for equivalent hardware +* Bad, because operational complexity requires dedicated SRE support + +### DynamoDB + Transactions + +* Good, because zero operations overhead +* Bad, because transaction API has 25-item / 4MB limits +* Bad, because vendor lock-in to AWS +* Bad, because $0.50/hr per replica is over budget at scale + +## Links + +* Refined by [ADR-0010](0010-patroni-cluster-configuration.md) +* Supersedes [ADR-0003](0003-in-memory-storage-poc.md) +``` + +--- + +## Architecture Decision Log (ADL) Conventions + +### File Naming + +``` +NNN-short-present-tense-phrase.md +``` + +Rules: +- **Number:** Zero-padded sequence (001, 002, ... 010). Avoid gaps; renumber on conflict. +- **Phrase:** Present tense imperative verb phrase — like a good commit message. + - Good: `012-use-postgresql-for-transaction-storage.md` + - Bad: `012-postgresql.md` (no verb), `012-decided-to-use-postgresql.md` (past tense) +- **Case:** Lowercase with hyphens (kebab-case). +- **Extension:** `.md` for easy rendering. + +### Directory Naming + +Consider naming the directory `decisions/` instead of `adr/` — some teams respond better to plain language. The template is content-neutral; you can document vendor decisions, planning decisions, and scheduling decisions in the same format. + +### Numbering Scheme + +- Sequential across the entire project (not per-category) +- Never reuse a number — if an ADR is rejected, leave the number retired +- Consider prefix for multi-project orgs: `PLAT-012-use-postgresql.md` diff --git a/adr-authoring/references/adr-to-pyramid-mapping.md b/adr-authoring/references/adr-to-pyramid-mapping.md new file mode 100644 index 0000000..d014b98 --- /dev/null +++ b/adr-authoring/references/adr-to-pyramid-mapping.md @@ -0,0 +1,21 @@ +# ADR-to-Pyramid Mapping + +## Mapping Table + +| ADR State | Pyramid Layer | What Lives There | Consumer | +|-----------|--------------|------------------|----------| +| Navigation index | **L1** (01-summary/) | List of all ADRs with status, link to each | Orchestrator needing to find a decision | +| Active ADRs | **L2** (02-analysis/) | Full decision record: context, options, rationale, consequences | Engineers, reviewers | +| Superseded ADRs | **L3** (03-dossiers/) | Historical decisions that have been replaced | Historians, anyone challenging a current decision | + +## Why ADRs Need Three Layers + +ADRs are modular by nature — each decision is a single document. But they still benefit from progressive disclosure: + +- **L1:** A navigation index helps an agent find the right ADR without reading all of them +- **L2:** Active ADRs provide the decision rationale alongside the C4 views they relate to +- **L3:** Superseded ADRs preserve decision history without cluttering active analysis + +## Relationship to C4 + +Every ADR in L2 should reference the C4 Container or Component it affects. Every C4 Container/Component diagram should reference the ADRs that shaped it. diff --git a/adr-authoring/references/decision-sustainability.md b/adr-authoring/references/decision-sustainability.md new file mode 100644 index 0000000..ffaff81 --- /dev/null +++ b/adr-authoring/references/decision-sustainability.md @@ -0,0 +1,120 @@ +# Decision Sustainability Framework + +A framework for evaluating whether an Architecture Decision Record (ADR) will survive contact with reality. Based on the InfoQ article "Sustainable Architectural Design Decisions" and documented in the community ADR repository. + +**Concept origin:** https://www.infoq.com/articles/sustainable-architectural-design-decisions/ — also at `locales/en/documents/decision-sustainability-criteria/` and `locales/en/documents/guidelines-to-achieve-sustainable-decisions/` in the ADR community repo. + +## Five Sustainability Criteria + +Every ADR should be evaluated against these criteria before acceptance. They form a quality gate checklist for the ADR review process. + +### 1. Strategic + +**Question:** Does this decision consider long-term impact? + +A strategic decision accounts for future operations, maintenance, and evolution — not just the immediate problem. It explicitly addresses the downstream consequences of the choice. + +**Checklist:** +- [ ] What is the projected lifespan of this decision? (6 months? 2 years? 10 years?) +- [ ] How will this decision affect future maintenance burden? +- [ ] Does this decision lock the team into a specific technology or pattern? +- [ ] Are the switching costs documented? + +**Pitfall:** A decision that optimizes for today at the expense of the next 6-12 months may still be correct — but only if the short-term horizon is explicit in the rationale. + +### 2. Measurable and Manageable + +**Question:** Can this decision be objectively evaluated over time? + +A sustainable decision has measurable outcomes. You should be able to look back in 6 months and determine whether the decision was correct. + +**Checklist:** +- [ ] Are the criteria for success or failure defined? +- [ ] Are numeric targets specified where possible? (latency p99 < 200ms, cost < $500/mo) +- [ ] Is the decision granular enough to be traceable? (too fine-grained = noise, too coarse = ambiguity) +- [ ] Are dependencies between this decision and other decisions documented? + +**Pitfall:** "Improve performance" is not measurable. "Reduce p99 latency from 800ms to under 200ms" is measurable. Quality attribute scenarios (from arc42) are the right tool here. + +### 3. Achievable and Realistic + +**Question:** Is this the "good enough" choice, not the perfect one? + +A sustainable decision is grounded in what the team can actually deliver. Over-engineering for hypothetical future needs is a common failure mode. + +**Checklist:** +- [ ] Can the team implement this given current skills and capacity? +- [ ] Does this decision avoid over-engineering? (Is there a simpler alternative that was considered and rejected for a documented reason?) +- [ ] Is the implementation timeline realistic? +- [ ] Are the operational costs within budget? + +**Pitfall:** A technically elegant decision that the team cannot execute is a failure of architecture, not of the team. The "good enough" test: does this decision get us 80% of the benefit with 20% of the complexity? + +### 4. Rooted in Requirements + +**Question:** Does this decision trace back to real business or technical requirements? + +A sustainable decision is grounded in the actual problem — company context, team makeup, user needs — not an abstract "best practice." + +**Checklist:** +- [ ] Is this decision directly tied to a specific requirement or constraint? +- [ ] Have team skills, training budget, and organizational context been considered? +- [ ] If the requirements change, would this decision need revisiting? (If yes, flag it.) +- [ ] Are external dependencies (vendors, platforms, regulations) documented? + +**Pitfall:** "Everyone uses Kubernetes" is not a requirement. "We need horizontal scaling for predictable traffic patterns our current single-server setup can't handle" is a requirement. Decisions rooted in bandwagon effects rather than actual requirements age poorly. + +### 5. Timeless + +**Question:** Is this decision based on knowledge unlikely to be outdated soon? + +A sustainable decision favors durable knowledge over fashionable technology. Platform-neutral patterns and architectural tactics outlast specific tools. + +**Checklist:** +- [ ] Is the decision based on architectural patterns/tactics rather than specific tool versions? +- [ ] If the chosen vendor/product disappeared tomorrow, would the architecture survive? +- [ ] Is the rationale still valid if underlying technology choices change? +- [ ] Does the ADR distinguish between "what" (the pattern) and "which" (the specific tool)? + +**Example:** Choosing event sourcing because "we need an audit trail" is a timeless architectural decision. Choosing event sourcing because "Kafka is trendy" is not. The ADR should articulate the timeless principle, not just the tool choice. + +## Eight Guidelines for Sustainable Decisions + +From the InfoQ article, these guidelines help put the criteria into practice: + +| # | Guideline | Applies to | +|---|-----------|-----------| +| 1 | **Use a lean/minimalistic approach for initial documentation.** Don't write a Tyree & Akerman on day one. Start with Nygard or MADR. | ADR drafting | +| 2 | **Prioritize and capture all important decisions first.** Identify what matters before elaborating. | ADR identification | +| 3 | **Detail important decisions after initial approval.** Full-blown templates come after stakeholders agree the direction is right. | ADR review | +| 4 | **Use lean versions for trivial decisions.** Not every decision needs Options Analysis. For obvious choices, a paragraph in the index or a Nygard ADR is enough. | Template selection | +| 5 | **Reuse existing architectural knowledge.** Don't reinvent patterns documented in arc42, Martin Fowler, or your own past ADRs. Reference them. | ADR writing | +| 6 | **Establish traceability links between decisions, requirements, and code.** Every ADR should link back to the requirement that drove it and forward to the code that implements it. | ADR structure | +| 7 | **Provide automated consistency checking for traceability links.** See `references/fitness-functions.md` for how to make this mechanical. | CI/governance | +| 8 | **Enforce justifications forcefully.** The rationale is the most important part of any ADR. A decision without justification is not a decision — it's an opinion. | ADR quality | + +## Using the Framework: ADR Review Checklist + +Before accepting an ADR, evaluate it against these questions: + +``` +1. STRATEGIC — Does this consider long-term impact beyond the immediate problem? + If no: add a "Future considerations" section to the ADR. + +2. MEASURABLE — Are success/failure criteria defined, ideally with numeric targets? + If no: add quality attribute scenarios before accepting. + +3. ACHIEVABLE — Is this "good enough," not over-engineered for hypothetical futures? + If no: document what simpler alternatives were considered and why the extra complexity is justified now. + +4. ROOTED — Does this trace back to a specific requirement, constraint, or team context? + If no: identify the actual requirement and link it. If none exists, re-evaluate whether the decision is needed. + +5. TIMELESS — Is the rationale based on durable architectural knowledge, not today's trends? + If no: reframe the ADR to articulate the architectural principle, not the specific tool name. +``` + +## Further Reading + +- InfoQ — "Sustainable Architectural Design Decisions": https://www.infoq.com/articles/sustainable-architectural-design-decisions/ +- ADR community repo — sustainability criteria: https://github.com/architecture-decision-record/architecture-decision-record (see `locales/en/documents/decision-sustainability-criteria/` and `guidelines-to-achieve-sustainable-decisions/`) diff --git a/adr-authoring/references/fitness-functions.md b/adr-authoring/references/fitness-functions.md new file mode 100644 index 0000000..3e9a661 --- /dev/null +++ b/adr-authoring/references/fitness-functions.md @@ -0,0 +1,167 @@ +# Fitness Functions for Decisions as Code + +Fitness functions are automated checks, written as code, that verify architectural decisions are being maintained. An ADR documents the decision; a fitness function *assures* it. + +**Concept origin:** https://github.com/architecture-decision-record/architecture-decision-record — based on the "Fitness Functions for Decisions as Code" document in the ADR community repo. + +## How Fitness Functions Connect to ADRs + +``` +ADR: "We use event sourcing for audit requirements" + ↓ +Fitness function: CI test asserting that every state change produces an event + ↓ +If a commit introduces a code path that mutates state without emitting an event → test fails +``` + +The ADR captures the *intent*. The fitness function enforces the *execution*. + +## Why Fitness Functions Matter + +| Benefit | Description | +|---------|-------------| +| **Objective measurement** | Pass/fail, not opinions. Work is visible and clear. | +| **Continuous enforcement** | Run on every commit, build, and deployment. Living rules. | +| **Confidence to refactor** | Automated catching of decision-rule violations during changes. | +| **Scalable governance** | Assure standards across a growing codebase without creating human bottlenecks. | + +## Fitness Function Approaches + +### 1. Architecture Unit Testing (Java — ArchUnit) + +[ArchUnit](https://www.archunit.org/) checks architecture rules using plain Java unit test frameworks (JUnit, TestNG). + +```java +// Example: Enforce that services don't directly access repositories +@Test +public void services_should_not_access_repositories_directly() { + JavaClasses classes = new ClassFileImporter().importPackages("com.myapp"); + ArchRule rule = classes() + .that().resideInAPackage("..service..") + .should().onlyAccessClassesThat() + .resideInAnyPackage("..service..", "..api.."); + rule.check(classes); +} +``` + +**What ADR patterns it can enforce:** +- Layered architecture violations (UI → Service → Repository direction) +- Dependency injection rules (no `new` for certain interfaces) +- Package cycle detection +- Naming conventions matching architectural roles + +### 2. Architecture Unit Testing (TypeScript — ArchUnitTS) + +[ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS) provides the same pattern for TypeScript/JavaScript using Jest, Vitest, Jasmine, etc. + +```typescript +// Example: Controllers should depend on services, not repositories +const rule = ArchRule.of('controllers') + .should().onlyDependOn() + .packages(['services', 'dto']); +``` + +### 3. AI-Assisted Fitness Functions + +For decisions that can't be expressed as static code checks, use LLM-based fitness functions with a structured prompt template: + +```txt +IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning. +IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search. + +This is a fitness function to evaluate if our work is +using all our decisions, and is correct and accurate. + +- Our decisions are here: {url to ADR index} +- Our work to evaluate is here: {url to code/PR/design doc} + +Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive. +``` + +**When to use AI-assisted fitness functions:** +- Evaluating PRs against multiple ADRs simultaneously +- Checking logical consistency across a set of related decisions +- Validating architectural compliance in design documents or proposals +- Auditing decisions that don't have a mechanical enforcement mechanism + +## Mapping to the Artifact Pyramid + +| Layer | What Lives There | Fitness Function Relevance | +|-------|-----------------|---------------------------| +| L1 (01-summary/) | ADR navigation index | — | +| L2 (02-analysis/) | Active ADRs (decision rationale) | ADRs declare *what* should be enforced | +| L3 (03-dossiers/) | Superseded ADRs, operational artifacts | Fitness functions live HERE | + +**Fitness functions are NOT part of the ADR itself.** They are operational governance artifacts — they live in the test suite or CI pipeline, not in the decision log. The ADR should *reference* any fitness function that enforces it (via a Links section or a `Confirmed by` note), but the function code itself belongs in the project's test infrastructure. + +## When to Write a Fitness Function + +| When | Example | +|------|---------| +| The decision affects a measurable architectural characteristic | "All services must log structured JSON" → Test asserting log output format | +| The decision has a clear pass/fail condition | "No circular dependencies between packages" → ArchUnit test | +| Decision compliance would be expensive to verify manually | "Every gRPC endpoint must have a rate limit" → CI integration test | +| Regulatory or compliance requirements demand audit trails | "All state mutations must be logged" → Middleware test | + +When an ADR explicitly states a rule that can be mechanically verified, create a fitness function for it. If the decision is about cost or organizational trade-offs (where fitness functions don't apply), skip automated enforcement and rely on the ADR's rationale for governance. + +## Relationship to Decision Governance + +Fitness functions operationalize the **Governance** and **Confirmation** sections found in advanced ADR templates (NHS Wales, Gareth Morgan). If your ADR template includes a Governance section, list any fitness functions there: + +```markdown +## Governance + +Compliance with this decision is verified by: +- ArchUnit test `NoServiceDirectDatabaseAccessTest` (runs on every PR) +- AI-assisted audit every release cycle against {link to ADR index} +``` + +## Structurizr CI Checks as Fitness Functions + +When using Structurizr DSL for C4 model documentation, the Structurizr CLI provides two commands that serve as fitness functions for architecture documentation consistency: + +### validate + +Checks that the DSL file is syntactically valid and structurally consistent: + +```bash +structurizr-cli validate -w docs/arch/model/system.dsl +``` + +Use as a pre-merge CI gate: if the DSL doesn't parse, the architecture model is broken. This prevents commits that would produce no diagrams or corrupted diagrams. + +### inspect + +Checks for architectural drift against the model. Verifies that the C4 model remains consistent with the ADRs it references via `!adrs`: + +```bash +structurizr-cli inspect -w docs/arch/model/system.dsl +``` + +Run in CI on every PR that touches either the DSL or the ADR directory. This catches: +- ADR files referenced but missing from the `!adrs` path +- Elements referenced in views that are not defined in the model +- Relationship inconsistencies between model and documentation + +### CI Pipeline Integration + +```yaml +# .github/workflows/architecture-checks.yml (or similar) +steps: + - name: Validate Structurizr DSL + run: structurizr-cli validate -w docs/arch/model/system.dsl + + - name: Inspect for drift + run: structurizr-cli inspect -w docs/arch/model/system.dsl +``` + +These are syntactic and structural checks. For semantic validation (does the architecture match the ADRs?), pair them with the AI-assisted fitness function prompt from the "AI-Assisted Fitness Functions" section above. Together they form a complete verification pipeline: syntax → structure → rationale. + +Full pipeline templates with validation, export, and deployment for GitHub Actions, GitLab CI, and ForgeJo are in `references/ci-pipeline-templates.md` (c4-diagramming skill). + +## Further Reading + +- ArchUnit: https://www.archunit.org/ +- ArchUnitTS: https://github.com/LukasNiessen/ArchUnitTS +- ADR community repo fitness functions: https://github.com/architecture-decision-record/architecture-decision-record (see `locales/en/documents/fitness-functions-for-decisions-as-code/`) diff --git a/adr-authoring/references/project-setup-guide.md b/adr-authoring/references/project-setup-guide.md new file mode 100644 index 0000000..9704262 --- /dev/null +++ b/adr-authoring/references/project-setup-guide.md @@ -0,0 +1,102 @@ +# 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 diff --git a/adr-authoring/references/source-index.md b/adr-authoring/references/source-index.md new file mode 100644 index 0000000..6249e1b --- /dev/null +++ b/adr-authoring/references/source-index.md @@ -0,0 +1,6 @@ +# Source index + +- **Source repository:** https://github.com/magnus919/hermes-profiles +- **Inspected commit:** `867a555` +- **Imported source directory:** `architecture/adr-authoring` +- **Porting boundary:** Retained portable methodology, templates, scripts, and references. Removed or generalized Hermes profile, task-orchestration, memory, and rigid response-handoff assumptions.