# Architecture Definition Record

> >

- **Type:** Skill
- **Install:** `agentstack add skill-shadowx4fox-solutions-architect-skills-architecture-definition-record`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shadowX4fox](https://agentstack.voostack.com/s/shadowx4fox)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shadowX4fox](https://github.com/shadowX4fox)
- **Source:** https://github.com/shadowX4fox/solutions-architect-skills/tree/main/skills/architecture-definition-record

## Install

```sh
agentstack add skill-shadowx4fox-solutions-architect-skills-architecture-definition-record
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Architecture Definition Record Skill

## Purpose

This skill is the **single owner of all ADR write operations**. It creates, updates, and manages Architecture Decision Records (ADRs) — immutable documents that capture the context, rationale, and consequences of significant architectural choices.

**Other skills read `adr/*.md` directly** for context loading, compliance, review, and export. They must **delegate here** when they need to create or modify any ADR file.

---

## When to Invoke This Skill

- User asks to create a new ADR or document an architectural decision
- User asks to update an ADR's status (Accepted, Deprecated, Rejected)
- User asks to supersede an existing decision with a new one
- User asks to list, audit, or review the ADR inventory
- User says: "add an ADR for…", "document this decision as an ADR", "mark ADR-XXX as accepted"
- Another skill triggers ADR file generation (e.g., after ARCHITECTURE.md creation)
- Use `/skill architecture-definition-record`

**Do NOT invoke for:**
- Reading ADRs as editing context → read `adr/*.md` directly
- Exporting ADRs to Word → use `architecture-docs-export` skill
- Reviewing ADR quality → use `architecture-peer-review` skill
- Referencing ADRs in compliance → compliance agents read `adr/README.md` directly

---

## Files in This Skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file — entry point and all workflows |
| `ADR_GUIDE.md` | Comprehensive guide: template structure, best practices, status lifecycle, comparison table standards |
| `adr/ADR-000-template.md` | Canonical ADR template — 10 sections, usage guide, file naming convention |

---

## Canonical Template Rule (ALL Workflows)

Every ADR file written by this skill MUST use the full 10-section canonical template from:
```
[plugin_dir]/skills/architecture-definition-record/adr/ADR-000-template.md
```

**No workflow may write an ADR file without first loading this template.** If the template cannot be loaded, the workflow MUST abort with:
```
TEMPLATE LOAD FAILURE: Could not load ADR-000-template.md. ADR generation aborted.
```

This applies to Workflows 1, 2, and 4. There are no exceptions.

---

## Workflows

### Workflow 1 — Generate ADRs from ARCHITECTURE.md Section 12 Table

**Trigger**: Called by `architecture-docs` after ARCHITECTURE.md creation, after Section 12 ADR table updates, or by user explicitly.

**Objective**: Extract the ADR table from ARCHITECTURE.md and generate `adr/ADR-XXX-title.md` files.

#### Step 1.0: Present ADR Generation Prompt

After ARCHITECTURE.md is created, display:

```
✅ Architecture documentation created successfully!

═══════════════════════════════════════════════════════════
📋 Architecture Decision Records (ADRs) Setup
═══════════════════════════════════════════════════════════

Your ARCHITECTURE.md includes an ADR table. I can automatically generate
ADR files using the standard template.

Would you like me to generate the ADR files now?

1. [Yes - Generate ADRs] - Create all ADR files listed in the table
2. [Preview First]       - Show me which ADRs will be created
3. [No Thanks]           - I'll create them manually later
4. [Learn More]          - Tell me about ADRs and the template

Recommended: Option 1 (Generate ADRs) - Saves time and ensures consistency
```

**Wait for user response.**

#### Step 1.1: Handle User Selection

- **Option 1 (Yes)** → Step 1.2
- **Option 2 (Preview)** → Step 1.2, then show preview, re-prompt yes/no
- **Option 3 (No)** → Show skip message with manual instructions
- **Option 4 (Learn More)** → Show ADR overview from `ADR_GUIDE.md`, re-prompt

#### Step 1.2: Locate ADR Table

Read `ARCHITECTURE.md` in full and parse the ADR table:

```bash
grep -E "^\| \[ADR-" ARCHITECTURE.md
```

**If no ADR table found:**
```
⚠️  ADR table not found in ARCHITECTURE.md
Options:
1. [Add ADR Table]       - Add the ADR section to ARCHITECTURE.md
2. [Skip ADR Generation] - Continue without generating ADRs
3. [Manual Review]       - Let me check the navigation index first
```

#### Step 1.3: Extract ADR List

For each line matching `^\| \[ADR-`:
1. Extract ADR number (e.g., `001`)
2. Extract file path (e.g., `adr/ADR-001-name.md`)
3. Extract slug from file path (or generate from title)
4. Extract title, status, date, impact
5. Extract Scope if a Scope column is present (see scope handling below)

**Regex:**
```
^\| \[ADR-(\d{3})\]\(adr\/ADR-\d{3}(-[a-z0-9-]+)?\.md\) \| (.+?) \| (.+?) \| (.+?) \| (.+?) \|
```

**Validate**: Check for duplicate ADR numbers — warn and halt if found.

**Scope handling — two cases:**

**Case A — Section 12 table has an explicit `Scope` column:**

Extract the Scope value from each row (`Institutional` or `User`). Validate that:
- Institutional rows use numbers 001–100
- User rows use numbers 101+

If mismatched (e.g., a "User" row with number 042), warn before generating:
```
⚠️  ADR-042 is labeled "User" but uses an institutional number (001–100).
    Options:
      1. [Reclassify to Institutional] — keep number 042, set Scope=Institutional
      2. [Renumber]                    — assign next available User slot (ADR-{next_user})
      3. [Keep as-is]                  — not recommended (breaks scope partition)
```

**Case B — Section 12 table has no `Scope` column (legacy / existing projects):**

Infer scope from the ADR number range: 001–100 → Institutional, 101+ → User.

Before writing any files, present an inferred-scope confirmation:
```
═══════════════════════════════════════════════════════════
INFERRED SCOPES (no Scope column in ARCHITECTURE.md Section 12)
═══════════════════════════════════════════════════════════
  ADR-001  [Title]   → Institutional  (number in range 001–100)
  ADR-002  [Title]   → Institutional  (number in range 001–100)
  ADR-101  [Title]   → User           (number ≥ 101)
═══════════════════════════════════════════════════════════
Proceed with these inferred scopes?  [all / specify overrides (e.g. 001=User) / cancel]
```

User can override individual ADRs before generation proceeds.

**If empty table:**
```
ℹ️  ADR table is empty. This is normal for newly created ARCHITECTURE.md files.
Create ADRs as architectural decisions are made using Workflow 2 (Create Individual ADR).
```

#### Step 1.4: Load Template

Resolve plugin directory and load the canonical template:

```bash
PLUGIN_DIR=$(find "$HOME" -maxdepth 10 -type d -name "solutions-architect-skills" ! -path "*/node_modules/*" 2>/dev/null | head -1)
Read(file_path="$PLUGIN_DIR/skills/architecture-definition-record/adr/ADR-000-template.md")
```

Store template content in memory for reuse across all ADR files.

#### Step 1.5: Generate Each ADR File

> **CRITICAL**: Use the **full canonical template** (all 10 sections). Do NOT produce abbreviated stubs with empty body sections. Every section for which architecture documentation provides relevant context MUST be populated. Only Implementation Plan and Success Metrics may remain as optional stubs.

> **Institutional content discipline**: When generating any ADR with `Scope: Institutional` (numbers 001–100), apply the rules in `ADR_GUIDE.md § Institutional ADR Content Discipline` — no "Institutional Inheritance Note", no "Project Application" sections, no component/operator/budget/timeline specifics, no cross-refs to ADR-101+. If source material from `ARCHITECTURE.md` contains those specifics, generalize them in the institutional ADR (and optionally retain the specifics in a paired User/Project ADR).

For each ADR in the list:

**Generate file path:**
- Slug from table path if present, else generate from title (lowercase, hyphens, strip special chars, max 50 chars)
- Placeholder title `[Title]` → slug `untitled`

**Check for existing file (never auto-overwrite):**
```
⚠️  ADR file conflict: adr/ADR-001-old-title.md already exists
1. [Skip This ADR]   - Keep existing file
2. [Rename New ADR]  - Create as ADR-{next_available}
3. [Overwrite]       - Replace existing (destructive)
4. [Review Existing] - Show me what's in the existing file first
```

**Load relevant architecture docs for this ADR** — before populating, identify which `docs/` files are relevant based on the ADR title/topic:

| ADR Topic Keywords | Architecture Files to Load |
|---|---|
| database, storage, data, persistence | `docs/04-data-flow-patterns.md`, `docs/06-technology-stack.md` |
| API, protocol, REST, gRPC, HTTP | `docs/05-integration-points.md`, `docs/06-technology-stack.md` |
| security, auth, encryption, identity | `docs/07-security-architecture.md` |
| scaling, performance, cache, latency | `docs/08-scalability-and-performance.md` |
| deployment, infrastructure, cloud | `docs/09-operational-considerations.md`, `docs/06-technology-stack.md` |
| framework, language, runtime, library | `docs/06-technology-stack.md` |
| architecture pattern, layer, structure | `docs/03-architecture-layers.md` |
| messaging, events, queue, stream, kafka | `docs/04-data-flow-patterns.md`, `docs/05-integration-points.md` |

Always also read `ARCHITECTURE.md` (navigation index) and `docs/02-architecture-principles.md` for every ADR — they provide universal context (constraints, principles, design drivers).

**Populate template — section by section from architecture documentation:**

| Template Section | How to populate |
|---|---|
| **Header metadata** | ADR number, title from table, status, date, authors: "Architecture Team" |
| **`**Scope**` field** | Case A: from the Scope column in Section 12 table; Case B: from inferred range (confirmed by user in Step 1.3) |
| **Context → Problem Statement** | Infer from ADR title + relevant docs — why did this decision need to be made? What gap or requirement prompted it? |
| **Context → Functional Requirements** | Extract from the relevant docs/ section — what the system must do that drives this decision |
| **Context → Non-Functional Requirements** | From S3 (principles) + S10 (scalability) + S9 (security) as applicable |
| **Context → Constraints** | From S3 principles and S8 tech stack constraints |
| **Context → Business Drivers** | From S1+S2 system overview — business goals that made this decision necessary |
| **Decision → Summary** | The chosen approach stated in the ADR title (e.g., "Use PostgreSQL as the primary relational database") |
| **Decision → Detailed Decision** | From the relevant architecture section — the specific technology/pattern/approach and how it is used |
| **Decision → Scope** | What is included in this decision; what is explicitly excluded |
| **Rationale → Primary Drivers** | From architecture principles (S3) and design drivers — why this choice satisfies the requirements; include quantitative evidence from architecture docs where available |
| **Rationale → Comparison Summary table** | Build a real comparison table with actual data from architecture docs — **never use placeholder rows**; include at least 3 evaluation criteria with the chosen option and at least one rejected alternative |
| **Consequences → Positive** | Benefits the decision delivers, mapped to architecture goals |
| **Consequences → Negative** | Trade-offs and costs accepted; mitigation strategy for each |
| **Consequences → Trade-offs** | What was gained vs. what was given up |
| **Alternatives Considered** | Extract alternatives from architecture context (tech stack alternatives, pattern alternatives); for each: what it is, why it was considered, why it was rejected |
| **Implementation Plan** | Mark as `[OPTIONAL — populate during implementation planning]` |
| **Success Metrics** | Mark as `[OPTIONAL — populate during implementation planning]` |
| **References** | Cite architecture docs sections used: e.g., `docs/06-technology-stack.md`, `docs/03-architecture-layers.md`; add any external references if known |

If the ADR title is a placeholder (`[Title]`, `[title]`, `Title`), add at the top:
```
> **TODO**: Auto-generated with placeholder title. Update title, filename, and all sections with the actual architectural decision.
```

**Step 1.5a — Length Validation Gate (BLOCKING)**: Before the file is written, verify both length constraints from `ADR_GUIDE.md § Title and Problem Statement Length Constraints`:

1. **Title length** — extract the text after `# ADR-NNN: ` from the populated H1 line and count characters. Must be ≤ 50.
2. **Problem Statement length** — extract the body between `### Problem Statement` and the next `### ` (or `---`) heading, strip any HTML comments, trim whitespace, and count characters. Must be ≤ 200.

```bash
# Title check (in-memory before write):
title_text=""
[ ${#title_text} -le 50 ] || echo "FAIL P1: title is ${#title_text} chars (>50)"

# Problem Statement check (in-memory before write):
ps_body=""
[ ${#ps_body} -le 200 ] || echo "FAIL P2: Problem Statement is ${#ps_body} chars (>200)"
```

On any FAIL: revise the field per the guide ("drop weak words, prefer single concrete nouns" for titles; "compress to one tight sentence, move requirements to `### Requirements`" for Problem Statement) and re-run the gate. Cap at 3 revision rounds. Round 4 → escalate to user with the actual lengths and current text; ask whether to split the ADR into sub-decisions (the recommended fix when content genuinely cannot fit).

**No waiver mechanism**: if the decision cannot fit, split it into multiple ADRs.

**Step 1.5b — ADR ID Format Gate (BLOCKING)**: Run the **ADR ID Format Gate** against the proposed `adr/ADR-{NNN}-{slug}.md` path and the in-file H1 `# ADR-{NNN}: {Title}` line. See `## ADR ID Format Gate (BLOCKING)` near the bottom of this file for the regex and abort message. Abort on failure — do not write the file.

**Write file** and report: `✅ Created: adr/ADR-101-technology-stack.md`

#### Step 1.6: Summary Report

```
✅ ADR Generation Complete
Generated {N} of {total} ADR files in ./adr/

Created: [list]
Skipped: [list with reason]
Failed:  [list with error]

Next steps:
1. Review and refine populated sections — verify accuracy against your intent
2. Strengthen the comparison table with benchmark data, POC results, or vendor metrics
3. Add Implementation Plan and Success Metrics when implementation planning begins
4. Update status to "Accepted" once reviewed and approved by the architecture team
5. Link related ADRs in the "Related" field
```

---

### Workflow 2 — Create Individual ADR (Interactive)

**Trigger**: User asks to create a new ADR for a specific decision.

**Objective**: Guided interview → writes a complete `adr/ADR-XXX-title.md`.

#### Step 2.1: Determine Scope and Next ADR Number

**Step 2.1a — Ask scope** (default = User/Project):

```
Is this an Institutional or User/Project ADR?

  1. [User / Project]  (default) — decision local to this project → numbered 101+
  2. [Institutional]             — organization-wide Architecture Team decision → numbered 001–100
```

If the user does not explicitly choose, default to **User / Project**.

**Step 2.1b — Compute next number for the chosen scope**:

For each existing `adr/ADR-*.md` file, read its `**Scope**` header line. Partition into:
- `institutional_numbers` = numbers from files with `**Scope**: Institutional`
- `user_numbers` = numbers from files with `**Scope**: User`, **plus** legacy ADR files with no `**Scope**` field whose number is ≥ 101 (legacy files with no scope field and number ≤ 100 are treated as institutional by default)

**For Institutional scope:**
```
next = max(n for n in institutional_numbers where n ≤ 100) + 1
```
- If no institutional ADRs exist → `next = 1`
- If `next > 100` (range full) → **abort** with:
  ```
  ⚠️  Institutional ADR range (001–100) is full ({count} institutional ADRs).

  Options:
    1. Supersede an existing institutional ADR (use Workflow 4)
    2. Reclassify this decision as User/Project (next User slot: ADR-{user_next})
    3. Cancel
  ```

**For User/Project scope:**
```
next = max(n for n in user_numbers where n ≥ 101) + 1
```
- If no user ADRs exist → `next = 101`

**Step 2.1c — Collision guard**: if a file named `adr/ADR-{NNN}-

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shadowX4fox](https://github.com/shadowX4fox)
- **Source:** [shadowX4fox/solutions-architect-skills](https://github.com/shadowX4fox/solutions-architect-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-shadowx4fox-solutions-architect-skills-architecture-definition-record
- Seller: https://agentstack.voostack.com/s/shadowx4fox
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.