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

[fullsend-ai-coder]

Add a new section after "Forge abstraction" in the Go code guidance. When implementing a method that calls the same API endpoint as an existing method, read the existing implementation first and replicate its error handling, retry logic, and response validation. Uses the Git Trees API truncation pattern as a concrete example.

This prevents review findings like the one on upstream PR fullsend-ai#2360, where a missing truncation check required a full fix iteration.

---

Closes #243

Post-script verification

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

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 12:57 PM UTC · Completed 12:57 PM UTC
Commit: c776c24 · View workflow run →

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:57 PM UTC · Completed 4:04 PM UTC
Commit: d8e3df7 · View workflow run →

[fullsend-ai-review]

Review — PR #264

Verdict: Approve

Summary

This PR adds a 4-line "API pattern replication" section to AGENTS.md, placed after the "Forge abstraction" section. The new guidance instructs code agents to read existing implementations before writing new methods that use the same API endpoint, and to replicate error handling, retry logic, and response validation patterns. It uses the Git Trees API truncation handling in commitFilesTo as a concrete example.

Sub-agent results

Dimension	Model	Result
Correctness	opus	✅ All technical claims verified against source (commitFilesTo at L647, truncation check at L702, retryOnTransient at L561, 404→ErrNotFound at L82-84, recursive trees endpoint used only in commitFilesTo)
Security	opus	✅ No secrets, injection patterns, bidi overrides, or security control weakening. Unicode confirmed clean (only U+2192 →, U+2014 —)
Intent & coherence	sonnet	✅ Traces to issue #243, placement matches issue instructions, content matches proposal, no scope creep
Style & conventions	sonnet	✅ Heading level, bold keywords, backtick usage, and section placement all match existing AGENTS.md conventions
Docs currency	sonnet	✅ All referenced identifiers exist in codebase. No cross-reference updates needed
Cross-repo contracts	—	⏭ Skipped (no exported interfaces modified)

Notes

• Prior review: First review (no prior review to anchor against).
• The change is well-scoped: exactly what issue [RTK+Ponytail] Code agent should replicate error handling from sibling methods using the same API endpoint #243 requested, nothing more.
• All five referenced code identifiers (commitFilesTo, retryOnTransient, ErrNotFound, the Git Trees API pattern, and the truncation check) were verified to exist at the described locations in internal/forge/github/github.go.

---

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 — comment

PR: #264 — docs(#243): add API pattern replication guidance to AGENTS.md
Author: fullsend-ai-coder[bot] | Base: main | Head: bd27241

Summary

Docs-only change adding a 4-line "API pattern replication" section to AGENTS.md, placed between the existing "Forge abstraction" and "Architecture Decision Records" sections. The PR scope correctly matches issue #243's authorization. No security, permission, or injection concerns.

One medium-severity technical accuracy finding and two low-severity findings.

Findings

1. retryOnRepoRace does not exist — medium / correctness

The new guidance says:

retry logic (e.g., retryOnTransient, retryOnRepoRace)

retryOnRepoRace does not exist anywhere in the repository. Only retryOnTransient exists (defined at internal/forge/github/github.go:561). Referencing a fabricated identifier in agent-facing guidance will cause confusion — an agent following this instruction would either search for a nonexistent function or hallucinate one.

Remediation: Remove retryOnRepoRace from the example list. The parenthetical should read: retry logic (e.g., retryOnTransient).

2. "Several methods" claim is inaccurate — low / correctness

The internal/forge/github/github.go file has several methods that share the Git Trees API pattern (refs → commit → tree)

Only commitFilesTo (line 647) implements the full refs→commit→tree pattern. CommitFiles and CommitFilesToBranch are thin wrappers that delegate to it — the pattern is already centralized, not duplicated across "several methods." The truncation check at line 702 already covers all callers by design.

The guidance is forward-looking (preventing future duplication), which is reasonable, but the present-tense factual claim is misleading.

Remediation: Reword to reflect the current architecture, e.g.: "...the Git Trees API pattern (refs → commit → tree) currently centralized in commitFilesTo — new methods using the same endpoint should replicate its truncation handling."

3. Missing bold structural markers — low / style-consistency

The adjacent "Forge abstraction" section uses bold markers to delineate guidance categories ("Prohibited outside...", "When writing code:", "When reviewing PRs:"). The new section is a single unstructured paragraph without these markers, creating a visual inconsistency.

Remediation: Optional — consider adding a bold lead-in like "When implementing a new method:" for consistency.

---

Labels: PR adds documentation guidance to AGENTS.md

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 5:38 PM UTC · Completed 5:45 PM UTC
Commit: d8e3df7 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all 3 review findings in a single line edit: removed nonexistent retryOnRepoRace reference, corrected the 'several methods' claim to name commitFilesTo, and added bold lead-in for consistency.

Fixed (3):

1. retryOnRepoRace does not exist: Removed retryOnRepoRace from the example list. Only retryOnTransient exists in the codebase (internal/forge/github/github.go:561).
2. Several methods claim is inaccurate: Reworded to reflect that the Git Trees API pattern is centralized in commitFilesTo, and new methods using the same endpoint should replicate its truncation handling.
3. Missing bold structural markers: Added bold lead-in 'When implementing a new method' for visual consistency with adjacent Forge abstraction section.

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:47 PM UTC · Completed 5:53 PM UTC
Commit: d8e3df7 · View workflow run →