feat: add design-decision-gate agentic workflow for ADR enforcement

[Copilot]

Addresses the pattern where AI lowers the perceived cost of deferring design decisions, causing codebase drift. This workflow enforces explicit Architecture Decision Records (ADRs) before implementation PRs can merge.

Workflow: .github/workflows/design-decision-gate.md

Engine: Claude

Triggers

• PR labeled implementation (always enforces)
• PR marked as ready for review

No ADR path

1. AI analyzes the PR diff to infer implicit design decisions
2. Generates a draft ADR and commits it to docs/adr/ on the PR branch
3. Posts a blocking comment explaining what to complete and how to link it
4. Submits REQUEST_CHANGES review to prevent merge

ADR present path

• AI verifies the implementation matches the stated decision
• APPROVE if aligned; REQUEST_CHANGES with specific divergences if not

Safe outputs used: add-comment, push-to-pull-request-branch, submit-pull-request-review

Sub Agent: .github/agents/adr-writer.agent.md

A dedicated adr-writer sub agent is imported by the workflow and provides best-practice ADR writing capabilities. Each ADR is structured in two parts:

Part 1 — Narrative (Human-Friendly)

• Context — the problem, constraints, and forces that motivated the decision (3–5 sentences)
• Decision — active-voice statement of what was decided and why
• Alternatives Considered — ≥2 genuine alternatives with honest rejection rationale
• Consequences — real positive, negative, and neutral trade-offs

Part 2 — Normative Specification (RFC 2119)

• Precise, testable requirements using MUST / SHOULD / MAY keywords per RFC 2119
• Requirements grouped into named subsections by concern area
• Ends with a Conformance paragraph defining what it means to satisfy the ADR

Additional agent capabilities:

• Storage convention — docs/adr/NNNN-kebab-case-title.md with sequential numbering
• Status lifecycle — Draft → Proposed → Accepted → Deprecated/Superseded
• Procedures for writing new ADRs from scratch, inferring implicit decisions from PR diffs, and verifying implementation alignment against existing ADRs

[pelikhan]

@copilot create an "adr-writer" sub agent (.github/agents/...) that implements a best practice ADR writer. Store ADRs under the adr folder.

[Copilot]

@copilot create an "adr-writer" sub agent (.github/agents/...) that implements a best practice ADR writer. Store ADRs under the adr folder.

Created .github/agents/adr-writer.agent.md (commit 1d7adec) — a best-practice ADR writer sub agent that:

• Follows the Michael Nygard template with all four required sections (Context, Decision, Alternatives Considered, Consequences)
• Stores ADRs in docs/adr/ using sequentially numbered filenames (NNNN-kebab-case-title.md)
• Covers status lifecycle (Draft → Proposed → Accepted → Deprecated/Superseded)
• Includes procedures for writing from scratch, analyzing PR diffs to identify implicit decisions, and verifying implementation alignment against an existing ADR

The design-decision-gate.md workflow now imports this agent via imports: - ../agents/adr-writer.agent.md.

[pelikhan]

@copilot adrs should have a human friendly part, then a precise RFC2119/W3

Use Claude for AW

[Copilot]

@copilot adrs should have a human friendly part, then a precise RFC2119/W3

Use Claude for AW

Done in commit d8e5e8e:

• ADR template now has two explicit parts:
  • Part 1 — Narrative: human-friendly Context, Decision, Alternatives Considered, and Consequences sections
  • Part 2 — Normative Specification: RFC 2119 requirements (MUST/SHOULD/MAY in bold) grouped by concern area, with a Conformance paragraph
• Writing quality standards updated with an RFC 2119 keyword usage table and rules for deriving normative statements from the narrative
• Workflow engine changed from copilot to claude

[pelikhan]

@copilot ready for review instead

[Copilot]

The PR is ready for review. All changes are in three new files only:

• .github/agents/adr-writer.agent.md — ADR writer sub agent with two-part template (narrative + RFC 2119 normative spec)
• .github/workflows/design-decision-gate.md — workflow using Claude engine
• .github/workflows/design-decision-gate.lock.yml — compiled lock file

[pelikhan]

@copilot trigger on labeled and ready-for-review

[Copilot]

Done in commit fd26b46. Added ready_for_review to the pull_request event types:

types: [labeled, opened, synchronize, ready_for_review]

The workflow will now also trigger when a draft PR is marked as ready for review.

[pelikhan]

@copilot remove opened, synchronize events in on pull_request

[Copilot]

@copilot remove opened, synchronize events in on pull_request

Done in commit 382b27c. The pull_request triggers are now:

types: [labeled, ready_for_review]

[Copilot]

Pull request overview

Adds an agentic workflow that gates implementation PRs on the presence of an Architecture Decision Record (ADR), with the ability to draft an ADR when missing and block merges via review status.

Changes:

• Introduces a new “Design Decision Gate” agentic workflow definition and its compiled lock file.
• Adds an adr-writer sub-agent defining ADR structure, numbering/storage conventions, and RFC 2119 normative requirements.

Show a summary per file

File	Description
.github/workflows/design-decision-gate.md	Source workflow instructions for ADR enforcement, ADR generation, and merge-blocking behavior
.github/workflows/design-decision-gate.lock.yml	Compiled/locked workflow produced by gh-aw for execution
.github/agents/adr-writer.agent.md	Sub-agent defining the ADR template, quality bar, and procedures

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (3)

.github/workflows/design-decision-gate.md:212

• The instructions require running mkdir -p ${{ github.workspace }}/docs/adr, but mkdir:* is not included in the bash tool allowlist for this workflow. In strict tool mode this will fail and prevent ADR creation. Either add "mkdir:*" to tools.bash or remove the mkdir step and rely on an allowed mechanism to ensure the directory exists (e.g., create the directory via the edit tool or ensure the push-to-pull-request-branch handler creates parent dirs).

Use `push-to-pull-request-branch` to commit the draft ADR to `docs/adr/{NNNN}-{kebab-case-title}.md`.

Ensure the `docs/adr/` directory exists before writing:
```bash
mkdir -p ${{ github.workspace }}/docs/adr

**.github/workflows/design-decision-gate.md:172**
* The draft ADR template here only includes the 4-section Michael Nygard narrative, but this workflow imports `adr-writer.agent.md` and the PR description says ADRs must be two-part (Narrative + RFC2119 Normative Specification). As a result, the gate may generate ADR drafts that fail your own stated ADR standard and makes later “ADR present” verification ambiguous. Align this template (and the “ADR present” criteria) with the `adr-writer` template (incl. Part 2 + Conformance) or explicitly document that Part 2 is optional for this gate.

Generate a draft ADR file following the Michael Nygard template:

# ADR-{NNNN}: {Concise Decision Title}

**Date**: {YYYY-MM-DD}
**Status**: Draft

.github/workflows/design-decision-gate.md:140

• “ADR Detection Criteria” defines an ADR as present if it contains the 4 Nygard sections, but the imported adr-writer template nests these under “Part 1 — Narrative” with ### Context/Decision/... headings and additionally requires a Part 2 RFC2119 section. If your detection is implemented as heading-based checks, this mismatch can cause false negatives. Consider updating the criteria to explicitly accept the adr-writer structure (Part 1 + Part 2) and be robust to heading levels (e.g., ## vs ###).

### ADR Detection Criteria

An ADR is considered **present** if it contains all four required sections from the Michael Nygard template:
1. **Context** — what is the situation and problem being addressed
2. **Decision** — what was decided and why
3. **Alternatives Considered** — what other options were evaluated
4. **Consequences** — what will happen as a result (positive and negative)

• Files reviewed: 3/3 changed files
• Comments generated: 3

[Copilot]

Step 1 Condition B refers to PR events being "opened or synchronized", but this workflow only triggers on pull_request types [labeled, ready_for_review]. As written, the "opened/synchronized" path is unreachable and the ready_for_review path (one of the declared triggers) isn’t covered by either Condition A or B, which can lead to inconsistent/no enforcement on ready-for-review events. Update the trigger types (e.g., include opened/synchronize) and/or rewrite Condition B to explicitly handle ready_for_review (and any other intended actions).

This issue also appears in the following locations of the same file:

• line 134
• line 165

[Copilot]

This “Status Values” table is not valid Markdown because each row starts with || instead of |, so it won’t render as a table in most viewers. Replace the double pipes with single pipes for the header, separator, and data rows.

[Copilot]

Several bash snippets rely on sort and tail (e.g., find ... | sort | tail -5), but sort:* and tail:* are not included in this workflow’s tools.bash allowlist. In strict tool mode the agent won’t be able to run these commands, which can break ADR discovery. Add "sort:*" and "tail:*" to the bash allowlist (or rewrite the commands using only allowed tools).

This issue also appears on line 207 of the same file.