# Agent Instructions ## 1. Coding Principles ### 1.1 Simplicity First - No out-of-scope features. - No abstractions for single-use code. - If 50 lines work instead of 200, write 50. ### 1.2 Surgical Changes - Only change lines directly related to the request. - Never refactor adjacent code unless asked. - Remove orphaned imports/variables/functions your changes created. ### 1.3 Goal-Driven Execution - Define success criteria before coding. - Verify each step before moving to the next. --- ## 2. Workflow Overview 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 **Role:** Product Owner (PO) **Goal:** Turn a raw issue into a clear, scoped, feasible requirement. **Constraint:** PO must NOT write code or create PRs. ### Steps 1. Read and analyze the issue. 2. Is the requirement clear and well-scoped? - **No:** Comment clarifying questions on the issue. Stop and wait for user response. - **Yes:** Comment a summary and lock the scope (Final Requirements). 3. Locked issue moves to Phase 2. --- ## 4. Phase 2: Requirement Implementation **Roles:** Developer (Dev) and Reviewer (Rev) **Goal:** Implement the locked requirement from Phase 1. ### 4.1 Developer: Plan & Implement 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, 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). - 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. - Fix feedback on the correct branch (checkout or worktree, never edit remote via API). - Always reply on PR after pushing a fix. ### 4.2 Reviewer: Review PR **Constraint:** Reviewer must NOT edit code on the PR. 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 `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`). 4. Check for scope creep — FAIL if PR contains unrelated changes or refactoring. 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` --- ## 5. Gitea Tools - Always use Gitea MCP tools in this project. - Scope: read PR/issue, list comments, post replies, create/edit PRs, reviews. - Use `tea` CLI only as fallback when MCP is unavailable. - Local CLI tools (`git`, `go`, `rg`) are fine for local validation. --- ## 6. Review Format ``` PASS No blocking issues found. Validation: - gofmt -l .: OK - go test ./...: OK - go vet ./...: OK - staticcheck ./...: OK Non-blocking: - ``` ``` FAIL 1. [High] 2. [Medium] Validation: - ``` --- ## 7. Documentation Rules - Durable architecture or behavior decisions belong in `docs/adr/**`. - `docs/superpowers/**` is for agent execution artifacts and must not be merged as part of product implementation PRs. - If a PR needs a lasting technical rationale, author an ADR in `docs/adr/` instead. - Reviewers should treat temporary plan/spec docs as scope creep, but accept ADRs that directly document the accepted behavior of the change. --- ## 8. Comment Style - Use readable multiline markdown. - 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.