docs(#2215): extend forge abstraction scope to action.yml

[fullsend-ai-coder]

The forge abstraction rule in CLAUDE.md and AGENTS.md was written with Go-specific examples (exec.Command, net/http) and did not explicitly cover action.yml bash scripts. This led the code agent in PR #2150 to correctly use forge.Client in Go but also add parallel inline gh api calls in action.yml, requiring substantial rework.

Both files now state that new GitHub API operations in action.yml steps should be implemented as fullsend CLI subcommands (under internal/cli/) that use forge.Client, not as inline gh api calls. Existing gh api calls are grandfathered but should be migrated when touched.

Note: make lint could not run in sandbox due to shellcheck installation failure (network restriction). This is a docs-only change with no code to test.

---

Closes #2215

Post-script verification

• Branch is not main/master (agent/2215-forge-action-yml-scope)
• Secret scan passed (gitleaks — 9c19aa5cc7bd8f1d0d499453d12855e03c8b7f9c..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[github-actions]

Site preview

Preview: https://ccc04aee-site.fullsend-ai.workers.dev

Commit: ccb76b7e0a983b1fdb1678e64aab07bdaf8a27b7

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:11 PM UTC · Completed 12:18 PM UTC
Commit: e2ccaab · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] AGENTS.md — Protected governance file modified. The PR is authorized by issue Clarify forge abstraction scope to cover action.yml bash scripts #2215 (retrospective from PR fix(#2149): finalize orphaned status comments on hard process termination #2150) and the description clearly explains the rationale. Human approval is required for all protected-path changes regardless of context.

Info

• [terminology-precision] AGENTS.md:65 — The header "Action workflows" may cause confusion: in GitHub Actions terminology, "workflows" refers to .github/workflows/*.yml files, while action.yml defines a composite action. The parenthetical (action.yml) disambiguates in practice, but consider using "Composite actions" or "Action definitions" for terminological precision in a document that serves as authoritative guidance for agents.

Previous run

Review

Findings

Medium

• [protected-path] AGENTS.md, CLAUDE.md — Both modified files are protected paths requiring human approval. The PR is properly authorized by issue Clarify forge abstraction scope to cover action.yml bash scripts #2215 (retrospective from PR fix(#2149): finalize orphaned status comments on hard process termination #2150) and the description explains the rationale clearly. Human approval is still required for all protected-path changes regardless of context.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:49 PM UTC · Completed 5:58 PM UTC
Commit: 38cfc04 · View workflow run →

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 10:01 AM UTC · Completed 10:11 AM UTC
Commit: ccb76b7 · View workflow run →

[fullsend-ai-retro]

PR #2219 was a 2-line docs-only change to AGENTS.md that extended the forge abstraction scope to cover action.yml bash scripts. It originated from a retro on PR #2150, where the code agent correctly used forge.Client in Go but also added parallel inline gh api calls in action.yml — requiring 8 review cycles and ~29 hours of rework. The retro system worked well end-to-end: retro identified root cause → filed issue #2215 → code agent created minimal fix → merged. Two inefficiencies stand out: (1) the retro agent's issue directed the code agent to edit CLAUDE.md (a one-line pointer to AGENTS.md), causing an unnecessary modification that a human reviewer had to fix via force push 3 days later; (2) the 2-line docs change took 25 days from creation to merge — first human approval came in 3.5 hours, but a second approval wasn't received until 25 days later. Both are instances of known open issues (#2290 and #2004 respectively). Additionally, the review agent raised a valid terminology precision point about 'Action workflows' being ambiguous in GitHub Actions context, which was not addressed before merge.

Proposals filed

• Evidence for #2290: retro agent directed code agent to edit CLAUDE.md despite it being a one-line redirect (in fullsend-ai/fullsend)
• Evidence for #2004: 25-day merge latency on trivially approved 2-line docs PR (in fullsend-ai/fullsend)
• Fix 'Action workflows' terminology in AGENTS.md forge abstraction section (in fullsend-ai/fullsend)