docs(#366): add API pattern replication guidance to AGENTS.md

[fullsend-ai-coder]

Instruct code agents to read existing sibling methods before implementing new methods that call the same API endpoint or use the same multi-step API pattern. Covers replicating error handling (truncation checks, 404-to-ErrNotFound mapping), retry logic (retryOnTransient), and response validation.

Prevents a class of medium-severity review findings where new methods omit error handling that existing methods already implement for the same endpoint.

---

Closes #366

Post-script verification

• Branch is not main/master (agent/366-api-pattern-replication)
• Secret scan passed (gitleaks — aa6585ddb3dff17dccfd4dba8b6c5c306275156a..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:56 AM UTC · Completed 12:02 PM UTC
Commit: aa6585d · View workflow run →

[fullsend-ai-review]

Review — PR #418

Verdict: approve

Summary

Docs-only PR adding a 4-line "API pattern replication" section to AGENTS.md, traceable to issue #366. The guidance instructs code agents to replicate error handling, retry logic, and response validation from existing sibling methods when implementing new methods that use the same API endpoint.

Technical accuracy: All claims verified against source — commitFilesTo (line 647), truncation handling (lines 697–702), retryOnTransient (line 561), and ErrNotFound 404 mapping (line 84) exist and behave as described. The Git Trees API pattern (refs → commit → tree) is accurately characterized.

Editorial note: The PR correctly omitted retryOnRepoRace from the examples, which issue #366 included — this function does not exist in the codebase.

Security: No injection patterns, secrets, Unicode steganography, or bidirectional text overrides detected in the diff or PR body.

Findings

#	Severity	Category	File	Description
1	low	style	AGENTS.md	Heading level: The new section uses ## API pattern replication, creating a top-level peer to "Forge abstraction" and "Architecture Decision Records." The document's convention for implementation-specific guidance within a domain section is bold-label paragraphs (e.g., **Mint function:**, **When reviewing PRs:**). Issue #366 itself proposed **API pattern replication:** (bold label). Consider reformatting as a bold-label paragraph within "Forge abstraction" to match the document's organizational pattern.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

Previous run

Review — PR #418

Verdict: ✅ Approve

Summary

This PR adds a 4-line "API pattern replication" section to AGENTS.md, instructing code agents to replicate error handling, retry logic, and response validation from existing sibling methods when implementing new methods that use the same API endpoint. The change closes #366.

Dimensions evaluated

Dimension	Result
Correctness	✅ All technical claims verified against internal/forge/github/github.go: commitFilesTo (line 647) implements the Git Trees API pattern with truncation checks (lines 697–703), retryOnTransient (line 561) is used throughout, and 404-to-ErrNotFound mapping exists in APIError.Unwrap() (lines 82–84).
Security	✅ No injection patterns, secrets, permission changes, or Unicode steganography detected.
Intent & coherence	✅ Change traces directly to issue #366. Scope matches the proposed change exactly. Placement after "Forge abstraction" section is consistent with the issue's proposal.
Style & conventions	✅ Heading level (##), inline code formatting, and paragraph structure follow existing AGENTS.md patterns.
Documentation currency	✅ All referenced identifiers exist in the codebase. No other documentation files require updates.
Cross-repo contracts	⏭ Skipped — no exported interfaces or API surfaces modified.

No findings at low severity or above.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

Previous run (2)

Review

Verdict: Approve

Summary

Clean, well-scoped docs-only change that adds API pattern replication guidance to AGENTS.md. The PR directly addresses issue #366 and the added text is technically accurate.

Verification

• Technical accuracy: All claims verified against source. commitFilesTo exists (line 647 of internal/forge/github/github.go), implements the Git Trees API pattern (ref → commit → tree → new tree → new commit → update ref), and includes truncation checks (lines 702–703). retryOnTransient exists (line 561). 404-to-ErrNotFound mapping exists (lines 82–84 via APIError.Unwrap()).
• Editorial judgment: The issue proposed mentioning retryOnRepoRace as an example, but the PR correctly omits it — that function does not exist in the codebase. Good catch.
• Scope: The change matches issue [ARCHIVED] Benchmark issue 366 #366's proposed text with minor, non-expanding editorial differences. Placement after the "Forge abstraction" section is correct per the issue's specification.
• Security: No secrets, prompt injection patterns, Unicode steganography, or permission changes.

Findings

#	Severity	Category	File	Description
1	Low	formatting	AGENTS.md	The two adjacent ## sections ("Forge abstraction" and "Architecture Decision Records") use bold subsection headers (e.g., **When reviewing PRs:**) to organize multi-paragraph guidance. The new section uses running prose without structural labels. This is fine for a single-paragraph section, but if guidance grows here later, consider adding bold headers for consistency. Not blocking.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

---

Labels: PR modifies only AGENTS.md documentation

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:08 PM UTC · Completed 1:13 PM UTC
Commit: aa6585d · View workflow run →

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 1:43 PM UTC · Completed 1:48 PM UTC
Commit: aa6585d · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

No fixes applied. Review body was empty and no human instruction was provided. The PR's sole changed file (AGENTS.md) is a protected path.

Disagreed (1):

1. no actionable review feedback: Review body is empty (no findings from reviewer) and HUMAN_INSTRUCTION is 'none'. The only file in this PR (AGENTS.md) is a protected path that the fix agent cannot modify. No code changes are warranted.

Tests: passed

_{Updated by fullsend fix agent}

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:19 AM UTC · Completed 6:26 AM UTC
Commit: e49ecd5 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[low] style

Heading level: the new section uses ## (top-level heading) for a single paragraph of forge-specific implementation guidance. The document convention for this kind of guidance is bold-label paragraphs within an existing section (e.g., Mint function:, When reviewing PRs:). Issue #366 proposed bold-label format. Consider reformatting as a bold-label paragraph within the Forge abstraction section to match the organizational pattern.