From 68fd2059eb95b3a30cd9be2c9fa3cd6df917828b Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 13:28:47 +0530 Subject: [PATCH 1/7] feat(skills): add architecture-decision-records skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a skill that captures architectural decisions made during coding sessions as structured ADR documents (Michael Nygard format). Features: - Auto-detects decision moments from conversation signals - Records context, alternatives considered with pros/cons, and consequences - Maintains numbered ADR files in docs/adr/ with an index - Supports ADR lifecycle (proposed → accepted → deprecated/superseded) - Categorizes decisions worth recording vs trivial ones to skip - Integrates with planner, code-reviewer, and codebase-onboarding skills Includes Antigravity support via .agents/skills/ and openai.yaml. --- .../architecture-decision-records/SKILL.md | 34 ++++ .../agents/openai.yaml | 7 + skills/architecture-decision-records/SKILL.md | 171 ++++++++++++++++++ 3 files changed, 212 insertions(+) create mode 100644 .agents/skills/architecture-decision-records/SKILL.md create mode 100644 .agents/skills/architecture-decision-records/agents/openai.yaml create mode 100644 skills/architecture-decision-records/SKILL.md diff --git a/.agents/skills/architecture-decision-records/SKILL.md b/.agents/skills/architecture-decision-records/SKILL.md new file mode 100644 index 000000000..f942aeb44 --- /dev/null +++ b/.agents/skills/architecture-decision-records/SKILL.md @@ -0,0 +1,34 @@ +--- +name: architecture-decision-records +description: Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. +origin: ECC +--- + +# Architecture Decision Records + +Capture architectural decisions as they happen during coding sessions, producing structured ADR documents that live alongside the code. + +## When to Activate + +- User says "let's record this decision" or "ADR this" +- User chooses between significant alternatives (framework, library, pattern, database) +- User says "we decided to..." or "the reason we're doing X instead of Y is..." +- During planning phases when architectural trade-offs are discussed + +## Workflow + +1. **Detect** the decision moment from conversation signals +2. **Gather** context, constraints, and alternatives considered +3. **Write** a structured ADR to `docs/adr/NNNN-decision-title.md` +4. **Update** the ADR index at `docs/adr/README.md` + +## ADR Format + +Each ADR includes: Context (the problem), Decision (what we chose), Alternatives Considered (with pros/cons/why-not for each), and Consequences (positive, negative, risks). + +## Key Principles + +- Record the **why**, not just the what +- Always include rejected alternatives +- Keep each ADR readable in 2 minutes +- Superseded decisions link to their replacement diff --git a/.agents/skills/architecture-decision-records/agents/openai.yaml b/.agents/skills/architecture-decision-records/agents/openai.yaml new file mode 100644 index 000000000..ebee56a5f --- /dev/null +++ b/.agents/skills/architecture-decision-records/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Architecture Decision Records" + short_description: "Capture architectural decisions as structured ADRs during coding sessions" + brand_color: "#8B5CF6" + default_prompt: "Record this architectural decision as an ADR with context, alternatives, and consequences" +policy: + allow_implicit_invocation: true diff --git a/skills/architecture-decision-records/SKILL.md b/skills/architecture-decision-records/SKILL.md new file mode 100644 index 000000000..54f47f05a --- /dev/null +++ b/skills/architecture-decision-records/SKILL.md @@ -0,0 +1,171 @@ +--- +name: architecture-decision-records +description: Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is. +origin: ECC +--- + +# Architecture Decision Records + +Capture architectural decisions as they happen during coding sessions. Instead of decisions living only in Slack threads, PR comments, or someone's memory, this skill produces structured ADR documents that live alongside the code. + +## When to Activate + +- User explicitly says "let's record this decision" or "ADR this" +- User chooses between significant alternatives (framework, library, pattern, database, API design) +- User says "we decided to..." or "the reason we're doing X instead of Y is..." +- User asks "why did we choose X?" (read existing ADRs) +- During planning phases when architectural trade-offs are discussed + +## ADR Format + +Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: + +```markdown +# ADR-NNNN: [Decision Title] + +**Date**: YYYY-MM-DD +**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN +**Deciders**: [who was involved] + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +[2-5 sentences describing the situation, constraints, and forces at play] + +## Decision + +What is the change that we're proposing and/or doing? + +[1-3 sentences stating the decision clearly] + +## Alternatives Considered + +### Alternative 1: [Name] +- **Pros**: [benefits] +- **Cons**: [drawbacks] +- **Why not**: [specific reason this was rejected] + +### Alternative 2: [Name] +- **Pros**: [benefits] +- **Cons**: [drawbacks] +- **Why not**: [specific reason this was rejected] + +## Consequences + +What becomes easier or more difficult to do because of this change? + +### Positive +- [benefit 1] +- [benefit 2] + +### Negative +- [trade-off 1] +- [trade-off 2] + +### Risks +- [risk and mitigation] +``` + +## Workflow + +### Capturing a New ADR + +When a decision moment is detected: + +1. **Identify the decision** — extract the core architectural choice being made +2. **Gather context** — what problem prompted this? What constraints exist? +3. **Document alternatives** — what other options were considered? Why were they rejected? +4. **State consequences** — what are the trade-offs? What becomes easier/harder? +5. **Assign a number** — scan existing ADRs in `docs/adr/` and increment +6. **Write the file** — save to `docs/adr/NNNN-decision-title.md` +7. **Update the index** — append to `docs/adr/README.md` + +### ADR Directory Structure + +``` +docs/ +└── adr/ + ├── README.md ← index of all ADRs + ├── 0001-use-nextjs.md + ├── 0002-postgres-over-mongo.md + ├── 0003-rest-over-graphql.md + └── template.md ← blank template for manual use +``` + +### ADR Index Format + +```markdown +# Architecture Decision Records + +| ADR | Title | Status | Date | +|-----|-------|--------|------| +| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 | +| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 | +| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 | +``` + +## Decision Detection Signals + +Watch for these patterns in conversation that indicate an architectural decision: + +**Explicit signals** +- "Let's go with X" +- "We should use X instead of Y" +- "The trade-off is worth it because..." +- "Record this as an ADR" + +**Implicit signals** +- Comparing two frameworks or libraries +- Discussing database schema design choices +- Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL) +- Deciding on authentication/authorization strategy +- Selecting deployment infrastructure +- Establishing testing strategy or coverage targets + +## What Makes a Good ADR + +### Do +- **Be specific** — "Use Prisma ORM" not "use an ORM" +- **Record the why** — the rationale matters more than the what +- **Include rejected alternatives** — future developers need to know what was considered +- **State consequences honestly** — every decision has trade-offs +- **Keep it short** — an ADR should be readable in 2 minutes +- **Use present tense** — "We use X" not "We will use X" + +### Don't +- Record trivial decisions — variable naming or formatting choices don't need ADRs +- Write essays — if the context section exceeds 10 lines, it's too long +- Omit alternatives — "we just picked it" is not a valid rationale +- Backfill without marking it — if recording a past decision, note the original date +- Let ADRs go stale — superseded decisions should reference their replacement + +## ADR Lifecycle + +``` +proposed → accepted → [deprecated | superseded by ADR-NNNN] +``` + +- **proposed**: decision is under discussion, not yet committed +- **accepted**: decision is in effect and being followed +- **deprecated**: decision is no longer relevant (e.g., feature removed) +- **superseded**: a newer ADR replaces this one (always link the replacement) + +## Categories of Decisions Worth Recording + +| Category | Examples | +|----------|---------| +| **Technology choices** | Framework, language, database, cloud provider | +| **Architecture patterns** | Monolith vs microservices, event-driven, CQRS | +| **API design** | REST vs GraphQL, versioning strategy, auth mechanism | +| **Data modeling** | Schema design, normalization decisions, caching strategy | +| **Infrastructure** | Deployment model, CI/CD pipeline, monitoring stack | +| **Security** | Auth strategy, encryption approach, secret management | +| **Testing** | Test framework, coverage targets, E2E vs integration balance | +| **Process** | Branching strategy, review process, release cadence | + +## Integration with Other Skills + +- **Planner agent**: when the planner proposes architecture changes, suggest creating an ADR +- **Code reviewer agent**: flag PRs that introduce architectural changes without a corresponding ADR +- **Codebase onboarding**: point new developers to the ADR directory for design context From fd3aff22ea7349e628648bd1a9da1dec3f5eb749 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 13:43:12 +0530 Subject: [PATCH 2/7] fix: address review feedback on ADR skill - Add missing "why did we choose X?" read-ADR trigger to .agents/ copy - Add canonical-reference link to .agents/ SKILL.md pointing to full version - Remove integration reference to non-existent codebase-onboarding skill --- .agents/skills/architecture-decision-records/SKILL.md | 3 ++- skills/architecture-decision-records/SKILL.md | 1 - 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/skills/architecture-decision-records/SKILL.md b/.agents/skills/architecture-decision-records/SKILL.md index f942aeb44..feae24078 100644 --- a/.agents/skills/architecture-decision-records/SKILL.md +++ b/.agents/skills/architecture-decision-records/SKILL.md @@ -6,13 +6,14 @@ origin: ECC # Architecture Decision Records -Capture architectural decisions as they happen during coding sessions, producing structured ADR documents that live alongside the code. +Capture architectural decisions as they happen during coding sessions, producing structured ADR documents that live alongside the code. Canonical full reference: [`/skills/architecture-decision-records/SKILL.md`](/skills/architecture-decision-records/SKILL.md). ## When to Activate - User says "let's record this decision" or "ADR this" - User chooses between significant alternatives (framework, library, pattern, database) - User says "we decided to..." or "the reason we're doing X instead of Y is..." +- User asks "why did we choose X?" (read existing ADRs) - During planning phases when architectural trade-offs are discussed ## Workflow diff --git a/skills/architecture-decision-records/SKILL.md b/skills/architecture-decision-records/SKILL.md index 54f47f05a..025b55656 100644 --- a/skills/architecture-decision-records/SKILL.md +++ b/skills/architecture-decision-records/SKILL.md @@ -168,4 +168,3 @@ proposed → accepted → [deprecated | superseded by ADR-NNNN] - **Planner agent**: when the planner proposes architecture changes, suggest creating an ADR - **Code reviewer agent**: flag PRs that introduce architectural changes without a corresponding ADR -- **Codebase onboarding**: point new developers to the ADR directory for design context From e443efbe4b7f01ff3b3e9e4e984b1717f6ad1bd4 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 14:28:31 +0530 Subject: [PATCH 3/7] fix: add initialization step and sync .agents/ trigger - Add Step 1 to workflow: initialize docs/adr/ directory, README.md index, and template.md on first use when directory doesn't exist - Add "API design" to .agents/ alternatives trigger to match canonical version --- .../skills/architecture-decision-records/SKILL.md | 2 +- skills/architecture-decision-records/SKILL.md | 15 ++++++++------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.agents/skills/architecture-decision-records/SKILL.md b/.agents/skills/architecture-decision-records/SKILL.md index feae24078..1e768f199 100644 --- a/.agents/skills/architecture-decision-records/SKILL.md +++ b/.agents/skills/architecture-decision-records/SKILL.md @@ -11,7 +11,7 @@ Capture architectural decisions as they happen during coding sessions, producing ## When to Activate - User says "let's record this decision" or "ADR this" -- User chooses between significant alternatives (framework, library, pattern, database) +- User chooses between significant alternatives (framework, library, pattern, database, API design) - User says "we decided to..." or "the reason we're doing X instead of Y is..." - User asks "why did we choose X?" (read existing ADRs) - During planning phases when architectural trade-offs are discussed diff --git a/skills/architecture-decision-records/SKILL.md b/skills/architecture-decision-records/SKILL.md index 025b55656..c90484a01 100644 --- a/skills/architecture-decision-records/SKILL.md +++ b/skills/architecture-decision-records/SKILL.md @@ -73,13 +73,14 @@ What becomes easier or more difficult to do because of this change? When a decision moment is detected: -1. **Identify the decision** — extract the core architectural choice being made -2. **Gather context** — what problem prompted this? What constraints exist? -3. **Document alternatives** — what other options were considered? Why were they rejected? -4. **State consequences** — what are the trade-offs? What becomes easier/harder? -5. **Assign a number** — scan existing ADRs in `docs/adr/` and increment -6. **Write the file** — save to `docs/adr/NNNN-decision-title.md` -7. **Update the index** — append to `docs/adr/README.md` +1. **Initialize (first time only)** — if `docs/adr/` does not exist, create the directory, an empty `README.md` index, and a blank `template.md` for manual use +2. **Identify the decision** — extract the core architectural choice being made +3. **Gather context** — what problem prompted this? What constraints exist? +4. **Document alternatives** — what other options were considered? Why were they rejected? +5. **State consequences** — what are the trade-offs? What becomes easier/harder? +6. **Assign a number** — scan existing ADRs in `docs/adr/` and increment +7. **Write the file** — save to `docs/adr/NNNN-decision-title.md` +8. **Update the index** — append to `docs/adr/README.md` ### ADR Directory Structure From 8868f772acabadb2a81d18a21d1f54782c7ab9b9 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 16:35:21 +0530 Subject: [PATCH 4/7] fix: address ADR workflow gaps and implicit signal safety - Init step: seed README.md with index table header so Step 8 can append rows correctly on first ADR - Add read-path workflow: graceful handling when docs/adr/ is empty or absent ("No ADRs found, would you like to start?") - Implicit signals: add "do not auto-create without user confirmation" guard, tighten triggers to require conclusion/rationale not just discussion, remove overly broad "testing strategy" trigger --- skills/architecture-decision-records/SKILL.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/skills/architecture-decision-records/SKILL.md b/skills/architecture-decision-records/SKILL.md index c90484a01..ee5d43b11 100644 --- a/skills/architecture-decision-records/SKILL.md +++ b/skills/architecture-decision-records/SKILL.md @@ -73,7 +73,7 @@ What becomes easier or more difficult to do because of this change? When a decision moment is detected: -1. **Initialize (first time only)** — if `docs/adr/` does not exist, create the directory, an empty `README.md` index, and a blank `template.md` for manual use +1. **Initialize (first time only)** — if `docs/adr/` does not exist, create the directory, a `README.md` seeded with the index table header (see ADR Index Format below), and a blank `template.md` for manual use 2. **Identify the decision** — extract the core architectural choice being made 3. **Gather context** — what problem prompted this? What constraints exist? 4. **Document alternatives** — what other options were considered? Why were they rejected? @@ -82,6 +82,15 @@ When a decision moment is detected: 7. **Write the file** — save to `docs/adr/NNNN-decision-title.md` 8. **Update the index** — append to `docs/adr/README.md` +### Reading Existing ADRs + +When a user asks "why did we choose X?": + +1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?" +2. If it exists, scan `docs/adr/README.md` index for relevant entries +3. Read matching ADR files and present the Context and Decision sections +4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?" + ### ADR Directory Structure ``` @@ -116,13 +125,12 @@ Watch for these patterns in conversation that indicate an architectural decision - "The trade-off is worth it because..." - "Record this as an ADR" -**Implicit signals** -- Comparing two frameworks or libraries -- Discussing database schema design choices +**Implicit signals** (suggest recording an ADR — do not auto-create without user confirmation) +- Comparing two frameworks or libraries and reaching a conclusion +- Making a database schema design choice with stated rationale - Choosing between architectural patterns (monolith vs microservices, REST vs GraphQL) - Deciding on authentication/authorization strategy -- Selecting deployment infrastructure -- Establishing testing strategy or coverage targets +- Selecting deployment infrastructure after evaluating alternatives ## What Makes a Good ADR From b3456398712ba0368d2a39b19909340f32ff5fc5 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 16:40:49 +0530 Subject: [PATCH 5/7] fix: require user confirmation before creating files - Canonical SKILL.md: init step now asks user before creating docs/adr/ - .agents/ condensed version: add confirmation gate for implicit signals and explicit consent step before any file writes --- .agents/skills/architecture-decision-records/SKILL.md | 9 +++++---- skills/architecture-decision-records/SKILL.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.agents/skills/architecture-decision-records/SKILL.md b/.agents/skills/architecture-decision-records/SKILL.md index 1e768f199..07f968fd0 100644 --- a/.agents/skills/architecture-decision-records/SKILL.md +++ b/.agents/skills/architecture-decision-records/SKILL.md @@ -18,10 +18,11 @@ Capture architectural decisions as they happen during coding sessions, producing ## Workflow -1. **Detect** the decision moment from conversation signals -2. **Gather** context, constraints, and alternatives considered -3. **Write** a structured ADR to `docs/adr/NNNN-decision-title.md` -4. **Update** the ADR index at `docs/adr/README.md` +1. **Detect** the decision moment from conversation signals — for implicit signals, **suggest** recording an ADR and wait for user confirmation before proceeding +2. **Confirm** with the user before creating any files (especially `docs/adr/` on first use) +3. **Gather** context, constraints, and alternatives considered +4. **Write** a structured ADR to `docs/adr/NNNN-decision-title.md` +5. **Update** the ADR index at `docs/adr/README.md` ## ADR Format diff --git a/skills/architecture-decision-records/SKILL.md b/skills/architecture-decision-records/SKILL.md index ee5d43b11..b67e30125 100644 --- a/skills/architecture-decision-records/SKILL.md +++ b/skills/architecture-decision-records/SKILL.md @@ -73,7 +73,7 @@ What becomes easier or more difficult to do because of this change? When a decision moment is detected: -1. **Initialize (first time only)** — if `docs/adr/` does not exist, create the directory, a `README.md` seeded with the index table header (see ADR Index Format below), and a blank `template.md` for manual use +1. **Initialize (first time only)** — if `docs/adr/` does not exist, ask the user for confirmation before creating the directory, a `README.md` seeded with the index table header (see ADR Index Format below), and a blank `template.md` for manual use. Do not create files without explicit consent. 2. **Identify the decision** — extract the core architectural choice being made 3. **Gather context** — what problem prompted this? What constraints exist? 4. **Document alternatives** — what other options were considered? Why were they rejected? From 67b6543c8f9a8fe08cd5bb7a188e40eb99d19941 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Tue, 17 Mar 2026 17:20:56 +0530 Subject: [PATCH 6/7] fix: require user approval before writing ADR file, add refusal path --- skills/architecture-decision-records/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/architecture-decision-records/SKILL.md b/skills/architecture-decision-records/SKILL.md index b67e30125..54be3aea3 100644 --- a/skills/architecture-decision-records/SKILL.md +++ b/skills/architecture-decision-records/SKILL.md @@ -79,7 +79,7 @@ When a decision moment is detected: 4. **Document alternatives** — what other options were considered? Why were they rejected? 5. **State consequences** — what are the trade-offs? What becomes easier/harder? 6. **Assign a number** — scan existing ADRs in `docs/adr/` and increment -7. **Write the file** — save to `docs/adr/NNNN-decision-title.md` +7. **Confirm and write** — present the draft ADR to the user for review. Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files. 8. **Update the index** — append to `docs/adr/README.md` ### Reading Existing ADRs From ee8621b286280e4f82f2a3bae9d0749abf42959f Mon Sep 17 00:00:00 2001 From: vazidmansuri005 Date: Fri, 20 Mar 2026 10:52:14 +0530 Subject: [PATCH 7/7] fix: remove .agents/ duplicate, keep canonical in skills/ --- .../architecture-decision-records/SKILL.md | 36 ------------------- .../agents/openai.yaml | 7 ---- 2 files changed, 43 deletions(-) delete mode 100644 .agents/skills/architecture-decision-records/SKILL.md delete mode 100644 .agents/skills/architecture-decision-records/agents/openai.yaml diff --git a/.agents/skills/architecture-decision-records/SKILL.md b/.agents/skills/architecture-decision-records/SKILL.md deleted file mode 100644 index 07f968fd0..000000000 --- a/.agents/skills/architecture-decision-records/SKILL.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: architecture-decision-records -description: Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. -origin: ECC ---- - -# Architecture Decision Records - -Capture architectural decisions as they happen during coding sessions, producing structured ADR documents that live alongside the code. Canonical full reference: [`/skills/architecture-decision-records/SKILL.md`](/skills/architecture-decision-records/SKILL.md). - -## When to Activate - -- User says "let's record this decision" or "ADR this" -- User chooses between significant alternatives (framework, library, pattern, database, API design) -- User says "we decided to..." or "the reason we're doing X instead of Y is..." -- User asks "why did we choose X?" (read existing ADRs) -- During planning phases when architectural trade-offs are discussed - -## Workflow - -1. **Detect** the decision moment from conversation signals — for implicit signals, **suggest** recording an ADR and wait for user confirmation before proceeding -2. **Confirm** with the user before creating any files (especially `docs/adr/` on first use) -3. **Gather** context, constraints, and alternatives considered -4. **Write** a structured ADR to `docs/adr/NNNN-decision-title.md` -5. **Update** the ADR index at `docs/adr/README.md` - -## ADR Format - -Each ADR includes: Context (the problem), Decision (what we chose), Alternatives Considered (with pros/cons/why-not for each), and Consequences (positive, negative, risks). - -## Key Principles - -- Record the **why**, not just the what -- Always include rejected alternatives -- Keep each ADR readable in 2 minutes -- Superseded decisions link to their replacement diff --git a/.agents/skills/architecture-decision-records/agents/openai.yaml b/.agents/skills/architecture-decision-records/agents/openai.yaml deleted file mode 100644 index ebee56a5f..000000000 --- a/.agents/skills/architecture-decision-records/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Architecture Decision Records" - short_description: "Capture architectural decisions as structured ADRs during coding sessions" - brand_color: "#8B5CF6" - default_prompt: "Record this architectural decision as an ADR with context, alternatives, and consequences" -policy: - allow_implicit_invocation: true