diff --git a/.codex/skills/implement-task/SKILL.md b/.codex/skills/implement-task/SKILL.md index 3ff1f9e..b8fe20c 100644 --- a/.codex/skills/implement-task/SKILL.md +++ b/.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/ 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 - - Test evidence (exact commands and output) + - `Summary` + - `Changes` + - `Test Plan` with exact commands and output + - `Refactor` + - `Docs/ADR` + - `Risks/Follow-ups` - `Fixes #` - 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. diff --git a/.codex/skills/review-pr/SKILL.md b/.codex/skills/review-pr/SKILL.md index 8ca6fa5..ad957b5 100644 --- a/.codex/skills/review-pr/SKILL.md +++ b/.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: - @@ -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. diff --git a/.codex/skills/validate-issue/SKILL.md b/.codex/skills/validate-issue/SKILL.md index 3b1274b..7a06c7f 100644 --- a/.codex/skills/validate-issue/SKILL.md +++ b/.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). - - 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." + - 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. - 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:** - - + +**Documentation impact:** +- + +**ADR:** +- ``` ## 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 diff --git a/AGENT.md b/AGENT.md index 159745a..44f7b0e 100644 --- a/AGENT.md +++ b/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 .`. - - Create PR with `Fixes #` in the body so Gitea auto-closes the issue on merge. + - Update `README.md` and `.env.example` if config, endpoint, or runtime behavior changes. + - 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 #` 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-`, run `go test`, `go vet`, `gofmt`). +3. Validate in worktree if needed (`.worktrees/pr-`, 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**. -6. Post review proactively if verdict is clear: +5. Verify the repo Definition of Done: + - 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: - @@ -115,7 +143,7 @@ FAIL 2. [Medium] Validation: -- go test ./...: OK +- ``` --- @@ -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.