From fac874e747f388a71ad6946703d47c6202014d86 Mon Sep 17 00:00:00 2001 From: thuanle Date: Wed, 29 Apr 2026 00:38:11 +0700 Subject: [PATCH] skill create-adr --- .codex/skills/create-adr/SKILL.md | 89 +++++++++++++++++++++ .codex/skills/create-adr/agents/openai.yaml | 3 + .codex/skills/implement-task/SKILL.md | 5 +- .codex/skills/validate-issue/SKILL.md | 1 + 4 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 .codex/skills/create-adr/SKILL.md create mode 100644 .codex/skills/create-adr/agents/openai.yaml diff --git a/.codex/skills/create-adr/SKILL.md b/.codex/skills/create-adr/SKILL.md new file mode 100644 index 0000000..c0c1d5b --- /dev/null +++ b/.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. diff --git a/.codex/skills/create-adr/agents/openai.yaml b/.codex/skills/create-adr/agents/openai.yaml new file mode 100644 index 0000000..31d5993 --- /dev/null +++ b/.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" diff --git a/.codex/skills/implement-task/SKILL.md b/.codex/skills/implement-task/SKILL.md index b8fe20c..466f9ff 100644 --- a/.codex/skills/implement-task/SKILL.md +++ b/.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 ` on the Reviewer agent. diff --git a/.codex/skills/validate-issue/SKILL.md b/.codex/skills/validate-issue/SKILL.md index 7a06c7f..54613fc 100644 --- a/.codex/skills/validate-issue/SKILL.md +++ b/.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