From b396c6a5ce4882f1b8d099da43a11ffab30bc07c Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Wed, 8 Jul 2026 12:09:39 +0000
Subject: [PATCH 1/2] docs(#189): add API pattern replication guidance to
 AGENTS.md

Add a new section after "Forge abstraction" instructing agents to
read existing sibling methods before implementing new ones that
call the same API endpoint or use the same multi-step pattern.
The guidance covers replicating error handling (truncation checks,
404-to-ErrNotFound mapping), retry logic (retryOnTransient), and
response validation, with the Git Trees API pattern in
internal/forge/github/github.go as a concrete example.

Closes #189
---
 AGENTS.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5620b735fd..59bfc1bdc4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,6 +62,10 @@ All git forge operations (GitHub API calls, PR comments, issue creation, workflo
 
 **When reviewing PRs:** Flag any direct `exec.Command("gh", ...)`, raw GitHub API calls, or other forge-specific operations outside `internal/forge/github/` as a medium-severity or higher finding. This is an architectural violation, not a style preference.
 
+## API pattern replication
+
+When implementing a new method that calls the same API endpoint or uses the same multi-step API pattern as an existing method in the file, read the existing implementation first. Replicate its error handling (e.g., truncation checks, 404-to-ErrNotFound mapping), retry logic (e.g., `retryOnTransient`), and response validation. The `internal/forge/github/github.go` file has several methods that share the Git Trees API pattern (refs → commit → tree) — all should handle truncation consistently.
+
 ## Architecture Decision Records (ADRs)
 
 These rules apply whenever you touch `docs/ADRs/` or review a PR that does. Full authoring guidance is in [`skills/writing-adrs/SKILL.md`](skills/writing-adrs/SKILL.md); invoke that skill when writing a new ADR.

From 7a7b13e37e97026de8d6bc8d97efabf171b3d8e8 Mon Sep 17 00:00:00 2001
From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Sat, 11 Jul 2026 11:17:56 +0000
Subject: [PATCH 2/2] fix(#189): improve API pattern replication guidance
 accuracy

- Replace 'several methods' with specific reference to commitFilesTo,
  which is the only method implementing the full Git Trees API pattern
- Add 'When reviewing PRs' paragraph for consistency with adjacent
  Forge abstraction and ADR sections

Addresses review feedback on #205
---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 59bfc1bdc4..53abc3a271 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,7 +64,9 @@ All git forge operations (GitHub API calls, PR comments, issue creation, workflo
 
 ## API pattern replication
 
-When implementing a new method that calls the same API endpoint or uses the same multi-step API pattern as an existing method in the file, read the existing implementation first. Replicate its error handling (e.g., truncation checks, 404-to-ErrNotFound mapping), retry logic (e.g., `retryOnTransient`), and response validation. The `internal/forge/github/github.go` file has several methods that share the Git Trees API pattern (refs → commit → tree) — all should handle truncation consistently.
+When implementing a new method that calls the same API endpoint or uses the same multi-step API pattern as an existing method in the file, read the existing implementation first. Replicate its error handling (e.g., truncation checks, 404-to-ErrNotFound mapping), retry logic (e.g., `retryOnTransient`), and response validation. The `internal/forge/github/github.go` file's `commitFilesTo` method uses the Git Trees API pattern (refs → commit → tree) with truncation handling — any new method using the same endpoint should replicate that handling.
+
+**When reviewing PRs:** Flag new forge methods that omit error handling or retry patterns present in existing methods using the same API endpoint. This is a correctness issue, not a style preference.
 
 ## Architecture Decision Records (ADRs)