update DoD

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

@@ -33,6 +33,8 @@ description: Phase 2 skill. Use when issue scope is locked by Product Owner (Pha
 3. **Write plan and post on issue**
    - List implementation steps with verification criteria.
    - List files to change.
+   - State whether `README.md` or `.env.example` must change.
+   - State whether an ADR is required or not required.
    - Flag risks or tradeoffs.
    - Post plan as comment: `mcp__gitea__.issue_write` (`method: "add_comment"`).
    - **Wait for "Approved" before coding.** Stop here.
@@ -48,18 +50,32 @@ description: Phase 2 skill. Use when issue scope is locked by Product Owner (Pha
      git worktree add .worktrees/<branch-name> main
      ```
    - 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/**`.
    - Run validation:
      ```
      gofmt -l .
-     go vet ./...
      go test ./...
+     go vet ./...
+     staticcheck ./...
      ```
+   - Post an implementation summary comment on the issue with sections:
+     - `Summary`
+     - `Changes`
+     - `Test Plan`
+     - `Refactor`
+     - `Docs/ADR`
+     - `Risks/Follow-ups`
 
 5. **Create PR**
    - Use `mcp__gitea__.pull_request_write` (`method: "create"`).
    - PR body must include:
-     - Summary of changes
+     - `Summary`
-     - Test evidence (exact commands and output)
+     - `Changes`
+     - `Test Plan` with exact commands and output
+     - `Refactor`
+     - `Docs/ADR`
+     - `Risks/Follow-ups`
      - `Fixes #<issue-id>`
    - Add reviewer.
 
@@ -76,6 +92,8 @@ description: Phase 2 skill. Use when issue scope is locked by Product Owner (Pha
 - Use Gitea MCP tools for all issue/PR operations.
 - Preserve existing assignees when adding yourself unless the user explicitly asks to replace them.
 - Never edit remote files directly — always work on local branch.
+- Satisfy the repo Definition of Done before claiming completion.
+- 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.

.codex/skills/review-pr/SKILL.md

@@ -47,8 +47,9 @@ description: Phase 2 skill. Use when a PR is created or updated. Review PR again
    - Run checks:
      ```
      gofmt -l .
-     go vet ./...
      go test ./...
+     go vet ./...
+     staticcheck ./...
      ```
    - Remove worktree when done:
      ```
@@ -57,6 +58,11 @@ description: Phase 2 skill. Use when a PR is created or updated. Review PR again
 
 5. **Evaluate**
    - Does PR address **all** Final Requirements from the issue?
+   - Does PR satisfy the repo Definition of Done?
+     - relevant tests for behavior/config changes
+     - required `README.md` / `.env.example` updates
+     - ADR present when the change locks in a durable decision
+     - required implementation evidence exists on the issue and in the PR body
    - Does PR contain unrelated changes or refactoring? → FAIL immediately.
    - Code correctness, style, test coverage.
 
@@ -85,6 +91,7 @@ Validation:
 - gofmt -l .: OK
 - go vet ./...: OK
 - go test ./...: OK
+- staticcheck ./...: OK
 
 Non-blocking:
 - <optional note>
@@ -106,6 +113,7 @@ Validation:
 - Do not add yourself as reviewer twice; check requested reviewers and existing reviews first.
 - Do NOT edit code on the PR.
 - FAIL if PR contains unrelated changes or scope creep.
+- FAIL if the PR misses required DoD evidence, docs, or ADR work for the accepted change.
 - Post review proactively if verdict is clear.
 - Do not post a verdict until PR discussion comments have been checked.
 - Mention validation commands you actually ran.

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

@@ -27,6 +27,8 @@ description: Phase 1 skill. Use when a Gitea issue is created or updated and nee
    - Is the problem statement clear?
    - Is the scope well-defined or too broad?
    - Is it technically feasible?
+   - What acceptance criteria will prove the change is done?
+   - Will the change require docs updates or a durable ADR?
    - If needed, read relevant code: `mcp__gitea__.get_file_contents`.
 
 3. **Decide**
@@ -34,8 +36,9 @@ description: Phase 1 skill. Use when a Gitea issue is created or updated and nee
      - Post clarifying questions: `mcp__gitea__.issue_write` (`method: "add_comment"`).
      - Stop. Wait for user to respond, then re-run this skill.
    - **Clear and feasible:**
-     - Post Final Requirements (see format below).
+     - Post Final Requirements (see format below) with specific acceptance criteria.
-     - If the change likely needs a durable ADR, add a note: "ADR recommended: this change locks in a behavior/contract that future work must preserve."
+     - State whether docs updates are expected.
+     - State whether an ADR is required, recommended, or not needed.
      - This locks the scope and signals Phase 2 can begin.
 
 ## Final Requirements format
@@ -55,11 +58,18 @@ description: Phase 1 skill. Use when a Gitea issue is created or updated and nee
 **Acceptance criteria:**
 - <verifiable check 1>
 - <verifiable check 2>
+
+**Documentation impact:**
+- <README.md / .env.example updates required or not required>
+
+**ADR:**
+- <required / recommended / not needed, with one-line reason>
 ```
 
 ## Rules
 - Use Gitea MCP tools for all operations.
 - Do NOT write code, create branches, or create PRs.
+- Make acceptance criteria specific enough that Dev and Reviewer can verify Definition of Done without guessing.
 - Do NOT proceed to Phase 2 — that is a separate skill.
 
 ## Next skill

AGENT.md

@@ -28,6 +28,24 @@ All work starts from a Gitea issue. Two phases, each with a dedicated role:
 1. **Phase 1 — Requirement Refinement** (Product Owner): Clarify and lock scope.
 2. **Phase 2 — Requirement Implementation** (Developer & Reviewer): Plan, code, review, merge.
 
+### 2.1 Definition of Done
+
+A change is done only when all of the following are true:
+
+- The issue has locked **Final Requirements** with verifiable acceptance criteria.
+- The implementation stays within approved scope; unrelated refactors are not allowed.
+- Behavior, contract, or config changes have relevant tests added or updated, or the change record explains why tests were not added.
+- Validation passes with fresh output: `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`.
+- `README.md` and `.env.example` and related documents are updated when config, endpoint, or runtime behavior changes.
+- A new ADR is added in `docs/adr/**` when the change introduces a durable architecture, contract, behavior, or workflow decision.
+- The implementation evidence is posted on the issue and reflected in the PR body:
+  - what changed
+  - what tests were run
+  - whether any refactor was included
+  - whether docs or ADRs were added or not needed
+  - risks or follow-ups
+- After merge, the linked issue is verified closed.
+
 ---
 
 ## 3. Phase 1: Requirement Refinement
@@ -55,13 +73,16 @@ All work starts from a Gitea issue. Two phases, each with a dedicated role:
 
 1. Read the locked issue and any clarification comments.
 2. Read relevant code to understand current state.
-3. Write an implementation plan — list steps, files to change, risks.
+3. Write an implementation plan — list steps, files to change, risks, verification criteria, and any docs/ADR impact.
 4. **Comment the plan on the issue. Wait for "Approved" before coding.**
 5. Once approved:
    - Create a feature branch from `main`.
    - Implement following the plan (surgical changes only).
-   - Run validation: `go test ./...`, `go vet ./...`, `gofmt -l .`.
+   - Update `README.md` and `.env.example` if config, endpoint, or runtime behavior changes.
-   - Create PR with `Fixes #<issue>` in the body so Gitea auto-closes the issue on merge.
+   - If the change locks in a durable decision, write/update an ADR in `docs/adr/**`.
+   - Run validation: `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`.
+   - Post an implementation summary comment on the issue with sections: `Summary`, `Changes`, `Test Plan`, `Refactor`, `Docs/ADR`, `Risks/Follow-ups`.
+   - Create PR with the same evidence in the body plus `Fixes #<issue>` so Gitea auto-closes the issue on merge.
    - After merge, verify the issue is closed. If not (e.g. missing keyword), close it manually with a summary comment.
 6. **Own the PR until merged:**
    - Monitor for review feedback.
@@ -74,10 +95,15 @@ All work starts from a Gitea issue. Two phases, each with a dedicated role:
 
 1. Re-read the original issue — verify PR addresses the locked requirement.
 2. Read PR diff, review history, and PR discussion comments.
-3. Validate in worktree if needed (`.worktrees/pr-<number>`, run `go test`, `go vet`, `gofmt`).
+3. Validate in worktree if needed (`.worktrees/pr-<number>`, run `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`).
 4. Check for scope creep — FAIL if PR contains unrelated changes or refactoring.
-5. Write verdict — start with **PASS** or **FAIL**.
+5. Verify the repo Definition of Done:
-6. Post review proactively if verdict is clear:
+   - relevant tests exist for behavior/config changes
+   - docs and `.env.example` were updated when required
+   - ADR exists when a durable decision was introduced
+   - the issue comment and PR body contain the required implementation evidence
+6. Write verdict — start with **PASS** or **FAIL**.
+7. Post review proactively if verdict is clear:
    - `PASS` → `APPROVED`
    - `FAIL` → `REQUEST_CHANGES`
    - Non-blocking note → `COMMENT`
@@ -101,8 +127,10 @@ PASS
 No blocking issues found.
 
 Validation:
+- gofmt -l .: OK
 - go test ./...: OK
 - go vet ./...: OK
+- staticcheck ./...: OK
 
 Non-blocking:
 - <optional note>
@@ -115,7 +143,7 @@ FAIL
 2. [Medium] <issue with path:line and impact>
 
 Validation:
-- go test ./...: OK
+- <list only the commands you actually ran and their result>
 ```
 
 ---
@@ -132,6 +160,7 @@ Validation:
 ## 8. Comment Style
 
 - Use readable multiline markdown.
-- Use short sections (Summary, Changes, Test Plan).
+- Use short sections (`Summary`, `Changes`, `Test Plan`).
+- Implementation completion comments should also include `Refactor`, `Docs/ADR`, and `Risks/Follow-ups`.
 - Concise bullet points and explicit line breaks.
 - No bracketed author/tool tags.