skill create-adr

.codex/skills/create-adr/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: create-adr
+description: Use when a change introduces or updates a durable cross-cutting technical decision that future work in this repository must preserve, such as dependency, storage, integration, workflow, or quality-gate policy changes
+---
+
+# Create ADR
+
+## Overview
+
+Create a new ADR in `docs/adr/**` when the current task locks in a durable technical decision.
+Do not use this for bug fixes, styling changes, routine refactors, or ordinary test additions.
+
+## Use This Skill For
+
+- introducing or removing a major dependency
+- choosing or changing a storage strategy
+- defining release, branch, or workflow policy
+- changing how agents, jobs, or external tools are integrated
+- adopting or tightening repository quality gates
+- changing a behavior-defining contract future work must preserve
+
+## Do Not Use This Skill For
+
+- bug fixes
+- styling-only changes
+- routine refactors
+- ordinary test additions
+- temporary plans or execution notes
+
+## Workflow
+
+1. Check whether an active ADR already covers the same decision.
+   - Read `docs/adr/README.md` and scan existing files under `docs/adr/`.
+   - If the current change is only implementing an already-recorded decision, do not create a new ADR.
+2. If the new decision changes or replaces an older ADR, create a new ADR that supersedes it.
+   - Do not rewrite the meaning of an active ADR in place.
+3. Find the next numeric ID under `docs/adr/`.
+4. Create `docs/adr/NNNN-short-kebab-title.md`.
+5. Use this template:
+
+```md
+---
+type: ADR
+id: "NNNN"
+title: "Short decision title"
+status: active
+date: YYYY-MM-DD
+---
+
+## Context
+
+What changed? Why does this decision need to exist now?
+
+## Decision
+
+**State the decision clearly in one or two sentences.**
+
+## Options considered
+
+- **Option A** (chosen): description with pros and cons
+- **Option B**: description with pros and cons
+- **Option C**: description with pros and cons
+
+## Consequences
+
+What becomes easier?
+What becomes harder?
+What risks were accepted?
+What would trigger re-evaluation?
+
+## Advice
+
+Optional. Capture important external guidance or review input.
+```
+
+6. Add the new ADR to the index in `docs/adr/README.md`.
+7. Commit the ADR in the same change as the implementation it documents.
+8. Mention the ADR in the issue comment and PR body under `Docs/ADR`.
+
+## Rule Of Thumb
+
+If the decision changes how future work should be done across the repository, it probably deserves an ADR.
+
+## Repository Rules
+
+- Keep one decision per file.
+- Name files `NNNN-short-kebab-title.md`.
+- Keep the `docs/adr/README.md` index aligned with the files on disk.
+- Prefer concise, durable wording over implementation detail.

.codex/skills/create-adr/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Create ADR"
+  short_description: "Record a new architecture decision for durable repo changes"

.codex/skills/implement-task/SKILL.md

@@ -35,6 +35,7 @@ description: Phase 2 skill. Use when issue scope is locked by Product Owner (Pha
    - List files to change.
    - State whether `README.md` or `.env.example` must change.
    - State whether an ADR is required or not required.
+   - If ADR is required or recommended, invoke `create-adr` before finalizing the implementation summary and PR body.
    - Flag risks or tradeoffs.
    - Post plan as comment: `mcp__gitea__.issue_write` (`method: "add_comment"`).
    - **Wait for "Approved" before coding.** Stop here.
@@ -51,7 +52,7 @@ description: Phase 2 skill. Use when issue scope is locked by Product Owner (Pha
      ```
    - Implement following the plan (surgical changes only).
    - Update `README.md` and `.env.example` when config, endpoint, or runtime behavior changes.
-   - If the change introduces a durable behavior, contract, architecture, or workflow decision, create/update `docs/adr/**`.
+   - If the change introduces a durable behavior, contract, architecture, or workflow decision, use `create-adr` and create/update `docs/adr/**`.
    - Run validation:
      ```
      gofmt -l .
@@ -96,7 +97,7 @@ description: Phase 2 skill. Use when issue scope is locked by Product Owner (Pha
 - Missing required tests, docs, `.env.example` updates, or ADRs is a quality failure unless explicitly justified in both the issue comment and PR body.
 - Never claim completion without fresh verification output.
 - Keep changes strictly scoped to the approved plan.
-- If the change needs durable documentation, create/update `docs/adr/**`. Do not commit `docs/superpowers/**` planning artifacts.
+- If the change needs durable documentation, use `create-adr` and create/update `docs/adr/**`. Do not commit `docs/superpowers/**` planning artifacts.
 
 ## Next skill
 After PR is created, the user invokes `/review-pr <pr-number>` on the Reviewer agent.

.codex/skills/validate-issue/SKILL.md

@@ -39,6 +39,7 @@ description: Phase 1 skill. Use when a Gitea issue is created or updated and nee
      - Post Final Requirements (see format below) with specific acceptance criteria.
      - State whether docs updates are expected.
      - State whether an ADR is required, recommended, or not needed.
+     - If ADR is `required` or `recommended`, tell the Developer to use `create-adr` during implementation.
      - This locks the scope and signals Phase 2 can begin.
 
 ## Final Requirements format