From 64b2bd002dba92b502c79bf496bdc54082fa391e Mon Sep 17 00:00:00 2001 From: packet-mover Date: Sun, 5 Apr 2026 15:26:16 +0200 Subject: [PATCH 1/2] docs: refine AGENTS.md for VS Code workflow and add review gate - Reframe protocol for Claude Code VS Code extension (not GitHub issues) - Add Phase 3 review gate: user reviews changes before PR is created - Add commit guidance (commit after tests pass in Phase 2) - Add branch naming convention (type/short-description) - Add escape hatch for trivial changes (skip design brief) - Require pulling latest main before branching - Add .claude/ to repo layout diagram - Replace "reviewer"/"issue thread" language with "user"/"chat" Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 46 ++++++++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fb04af6..3de60ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,13 +13,17 @@ Domain specification (rules, report structure) lives in `README.md`. ## Operating protocol (must follow) +This protocol assumes you are running inside the Claude Code VS Code extension, interacting with the user directly in chat. All communication (design briefs, questions, approvals) happens in the chat — not via GitHub issue comments. + ### Phase 1 - Clarify and design (no code) +For trivial changes (typo, config tweak, single-line fix), skip the design brief and go straight to Phase 2. + **Step 1: Clarify inputs.** -If the issue description is missing information (expected behavior, constraints, edge cases), post a comment asking brief questions. Wait for answers before proceeding. If inputs are clear, skip to Step 2. +If the task description is missing information (expected behavior, constraints, edge cases), ask the user brief questions. Wait for answers before proceeding. If inputs are clear, skip to Step 2. -**Step 2: Post a design brief.** -Before writing any code, post a comment with a design brief. It must be concrete enough that the reviewer can predict what the code will look like. +**Step 2: Present a design brief.** +Before writing any code, present a design brief in chat. It must be concrete enough that the user can predict what the code will look like. Structure (use these headers): @@ -52,31 +56,40 @@ For each change, include: - Error handling strategy - What stays backward compatible, what breaks (if anything) -End the comment with: +End the design brief with: - "Reply OK to proceed to implementation. If you want changes, tell me what to adjust." -- Do not write code until the reviewer replies with explicit "OK". +- Do not write code until the user replies with explicit "OK". -### Phase 2 - Implement, test, and open PR +### Phase 2 - Implement and test After design approval: -1. Create a feature branch from `main`. +1. Pull latest `main`, then create a feature branch. Branch name must match the pattern `type/short-description` using the same types as PR titles (e.g., `feat/add-ci-workflow-rule`, `fix/pass-rate-calculation`). 2. Implement the full approved design. -3. Include tests in the same PR (see "Testing approach" below). Tests are mandatory — a PR without tests will not be merged. -4. Run `go test ./...` and ensure all tests pass. If any test fails, fix the code or the test before proceeding. Do not open a PR with failing tests. -5. Open a pull request targeting `main`. +3. Include tests (see "Testing approach" below). Tests are mandatory. +4. Run `go test ./...` and ensure all tests pass. If any test fails, fix the code or the test before proceeding. +5. Commit all changes to the feature branch with a message following the PR title convention. + +### Phase 3 - Review and open PR + +After implementation is complete, tests pass, and changes are committed: +1. Present a summary of all changes (files added/modified, what each does). +2. Wait for the user to review the changes in their editor. If the user requests changes, apply them, re-run tests, and commit before proceeding. +3. Explicitly ask: "Ready to push and create the PR?" +4. Do not push or open a PR until the user confirms. If the user declines, ask what needs to change. +5. Push the branch and open a pull request targeting `main`. **PR requirements:** - **Title** must follow conventional commits: `type: description` (e.g., `feat: add CI workflow rule`, `fix: correct pass rate calculation`, `refactor: extract report formatting`). Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. -- **Description** must include a summary of the design brief (problem, approach, files changed) so the PR is self-contained without reading the full issue thread. -- **Link** the PR to the originating issue. +- **Description** must include a summary of the design brief (problem, approach, files changed) so the PR is self-contained without reading the full chat history. +- **Link** the PR to the originating GitHub issue, if one exists. ### Handling PR review comments -When the reviewer requests changes on the PR: +When the user requests changes on the PR (either in chat or via GitHub review comments): - Push follow-up commits to the same branch addressing each comment. -- Do not force-push or squash on the branch — the reviewer needs to see what changed since their review. -- If a review comment requires a design change (not just a code tweak), post a comment explaining the updated approach before implementing it. -- After pushing fixes, run `go test ./...` again. Do not mark review comments as resolved if tests fail. +- Do not force-push or squash on the branch — the user needs to see what changed since their review. +- If a review comment requires a design change (not just a code tweak), explain the updated approach in chat before implementing it. +- After pushing fixes, run `go test ./...` again. --- @@ -93,6 +106,7 @@ Start flat — all `.go` files in the root, all in `package main`: ``` . +├── .claude/ # Claude Code settings ├── AGENTS.md ├── README.md ├── go.mod From 82b99a8b8976d4de0da8b0ff5bba3b983a810d86 Mon Sep 17 00:00:00 2001 From: packet-mover Date: Sun, 5 Apr 2026 15:27:40 +0200 Subject: [PATCH 2/2] chore: add shared Claude Code permission settings Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/settings.json | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .claude/settings.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..3501fdc --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,11 @@ +{ + "permissions": { + "allow": [ + "Bash(git *)", + "Bash(gh *)", + "Bash(go *)", + "Bash(rm *)", + "Bash(ls *)" + ] + } +}