architecture-decision-record

ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.

Jump to install

Repository: yonatangross/orchestkit
Last source activity: July 31, 2026 at 13:08
Detected SKILL.md language: English
Stars: 219
Forks: 20

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/yonatangross/orchestkit --skill architecture-decision-record

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

17 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

chain-patterns

Chain patterns for multi-phase pipelines: MCP detection, handoff files, checkpoint-resume, worktree agents, CronCreate monitoring. Use when building or debugging a pipeline skill.

2026-08-12

doctor

OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks.

2026-08-12

telemetry-inspect

Inspects the OrchestKit telemetry pipeline for the current project — lists all known telemetry files with write counts, sizes, schema status, growth trend, and orphan detection. Use when verifying the observability pipeline is healthy, debugging a missing writer, or auditing which files have schema locks vs. which are drift-vulnerable. Read-only — never modifies telemetry files.

2026-08-12

View all from this repository

Architecture Decision Records

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions along with their context and consequences. This skill provides templates, examples, and best practices for creating and maintaining ADRs in your projects.

Overview

Making significant technology choices (databases, frameworks, cloud providers)
Designing system architecture or major components
Establishing patterns or conventions for the team
Evaluating trade-offs between multiple approaches
Documenting decisions that will impact future development

Why ADRs Matter

ADRs serve as architectural memory for your team:

Context Preservation: Capture why decisions were made, not just what was decided
Onboarding: Help new team members understand architectural rationale
Prevent Revisiting: Avoid endless debates about settled decisions
Track Evolution: See how architecture evolved over time
Accountability: Clear ownership and decision timeline

ADR Format (Nygard Template)

Each ADR should follow this structure:

1. Title

Format: ADR-####: [Decision Title] Example: ADR-0001: Adopt Microservices Architecture

2. Status

Current state of the decision:

Proposed: Under consideration
Accepted: Decision approved and being implemented
Superseded: Replaced by a later decision (reference ADR number)
Deprecated: No longer recommended but not yet replaced
Rejected: Considered but not adopted (document why)

3. Context

What to include:

Problem statement or opportunity
Business/technical constraints
Stakeholder requirements
Current state of the system
Forces at play (conflicting concerns)

4. Decision

What to include:

The choice being made
Key principles or patterns to follow
What will change as a result
Who is responsible for implementation

Be specific and actionable:

✅ "We will adopt microservices architecture using Node.js with Express"
❌ "We will consider using microservices"

5. Consequences

What to include:

Positive outcomes (benefits)
Negative outcomes (costs, risks, trade-offs)
Neutral outcomes (things that change but aren't clearly better/worse)

6. Alternatives Considered

Document at least 2 alternatives:

For each alternative, explain:

What it was
Why it was considered
Why it was not chosen

7. References (Optional)

Links to relevant resources:

Meeting notes or discussion threads
Related ADRs
External research or articles
Proof of concept implementations

ADR Lifecycle

Proposed → Accepted → [Implemented] → (Eventually) Superseded/Deprecated
          ↓
      Rejected

Best Practices

1. Keep ADRs Immutable

Once accepted, don't edit ADRs. Create new ADRs that supersede old ones.

✅ Create ADR-0015 that supersedes ADR-0003
❌ Update ADR-0003 with new decisions

2. Write in Present Tense

ADRs are historical records written as if the decision is being made now.

✅ "We will adopt microservices"
❌ "We adopted microservices"

3. Focus on 'Why', Not 'How'

ADRs capture decisions, not implementation details.

✅ "We chose PostgreSQL for relational consistency"
❌ "Configure PostgreSQL with these specific settings..."

4. Review ADRs as Team

Get input from relevant stakeholders before accepting.

Architects: Technical viability
Developers: Implementation feasibility
Product: Business alignment
DevOps: Operational concerns

5. Number Sequentially

Use 4-digit zero-padded numbers: ADR-0001, ADR-0002, etc. Maintain a single sequence even with multiple projects.

6. Store in Git

Keep ADRs in version control alongside code:

Location: /docs/adr/ or /architecture/decisions/
Format: Markdown for easy reading
Branch: Same branch as implementation

Quick Start Checklist

Option 1: Use Script-Enhanced Generator (Recommended)

Run /create-adr [number] [title] to generate ADR with auto-filled context
ADR number, date, and author are auto-populated
Review and fill in decision details
Set Status to "Proposed" and review with team

Option 2: Use Static Template

Available Scripts

scripts/create-adr.md - Dynamic ADR generator with auto-filled context
- Auto-fills: ADR number, date, author, total ADRs count
- Usage: /create-adr [number] [title]
- Uses $ARGUMENTS and !command for dynamic context
assets/adr-template.md - Static template for manual use

Rules Quick Reference

Rule	Impact	What It Covers
interrogation-scalability	HIGH	Scale questions, data volume, growth projections
interrogation-reliability	HIGH	Data patterns, UX impact, coherence validation
interrogation-security	HIGH	Access control, tenant isolation, attack surface

Common Pitfalls to Avoid

❌ Too Technical: "We'll use Kubernetes with these 50 YAML configs..." ✅ Right Level: "We'll use Kubernetes for container orchestration because..."

❌ Too Vague: "We'll use a better database" ✅ Specific: "We'll use PostgreSQL 15+ for transactional data because..."

❌ No Alternatives: Only documenting the chosen solution ✅ Comparative: Document why alternatives weren't chosen

❌ Missing Consequences: Only listing benefits ✅ Balanced: Honest about costs and trade-offs

❌ No Context: "We decided to use Redis" ✅ Contextual: "Given our 1M+ concurrent users and sub-50ms latency requirement..."

Related Skills

ork:api-design: Use when designing APIs referenced in ADRs
ork:database-patterns: Use when ADR involves database choices
security-checklist: Consult when ADR has security implications

Skill Version: 2.0.0 Last Updated: 2026-01-08 Maintained by: OrchestKit

Capability Details

adr-creation

Keywords: adr, architecture decision, decision record, document decision Solves:

How do I document an architectural decision?
Create an ADR
Architecture decision template

adr-best-practices

Keywords: when to write adr, adr lifecycle, adr workflow, adr process, adr review, quantify impact Solves:

When should I write an ADR?
How do I manage ADR lifecycle?
What's the ADR review process?
How to quantify decision impact?
ADR anti-patterns to avoid
Link related ADRs

tradeoff-analysis

Keywords: tradeoff, pros cons, alternatives, comparison, evaluate options Solves:

How do I analyze tradeoffs?
Compare architectural options
Document alternatives considered

consequences

Keywords: consequence, impact, risk, benefit, outcome Solves:

What are the consequences of this decision?
Document decision impact
Risk and benefit analysis

name	architecture-decision-record
license	MIT
compatibility	Claude Code 2.1.220+.
description	ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.
version	2.0.0
author	OrchestKit
tags	["architecture","documentation","decision-making","backend"]
context	fork
agent

architecture-decision-record

Source facts

Install options

Review the source files

More from this repository

Architecture Decision Records

Overview

Why ADRs Matter

ADR Format (Nygard Template)

1. Title

2. Status

3. Context

4. Decision

5. Consequences

6. Alternatives Considered

7. References (Optional)

ADR Lifecycle

Best Practices

1. Keep ADRs Immutable

2. Write in Present Tense

3. Focus on 'Why', Not 'How'

4. Review ADRs as Team

5. Number Sequentially

6. Store in Git

Quick Start Checklist

Option 1: Use Script-Enhanced Generator (Recommended)

Option 2: Use Static Template

Available Scripts

Rules Quick Reference

Common Pitfalls to Avoid

Related Skills

Capability Details

adr-creation

adr-best-practices

tradeoff-analysis

consequences

More from this repository