fix(#2705): fetch full skill directories from URL bases via forge API

[fullsend-ai-coder]

URL-base skill resolution (introduced in PR #2690) only fetched SKILL.md via plain HTTP, silently dropping companion files (sub-agents/, scripts/, meta-prompts/). This broke the review agent for all per-org .fullsend installations because pr-review depends on sub-agents/*.md to dispatch parallel specialized reviewers.

The fix adds a ForgeClient field to ComposeOpts and uses the forge API (ListDirectoryContents + GetFileContentAtRef) to fetch the complete skill directory tree when resolving skills from URL-referenced bases. The raw raw.githubusercontent.com URL is parsed to extract owner/repo/ref/path for forge API calls.

When ForgeClient is not available (e.g., no GitHub token), the existing SKILL.md-only fallback is preserved with the warning from PR #2697. When the base URL is not a raw.githubusercontent.com URL, it also falls back gracefully.

Changes:

• compose.go: Add ForgeClient to ComposeOpts, add fetchBaseSkillViaForge
  for full directory fetch, add parseRawGitHubContentURL helper, extract
  fetchBaseSkillFallback for non-GitHub URL bases
• run.go: Create ForgeClient before LoadWithBase (best-effort from
  GH_TOKEN/GITHUB_TOKEN/gh auth)
• lock.go: Same ForgeClient creation for lock command
• compose_test.go: Add tests for forge-based fetch (with companion files,
  cache hit, non-raw URL fallback, nil ForgeClient), and unit tests for
  parseRawGitHubContentURL

---

Closes #2705

Post-script verification

• Branch is not main/master (agent/2705-url-base-skill-companion-files)
• Secret scan passed (gitleaks — a06f8626676fdf389f65cc18ea89798f846f689e..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[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]

Site preview

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

Commit: 07f198dc614b695faabe8da83cfc89e190ac60e1

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 45 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/harness/compose.go	68.29%	19 Missing and 20 partials ⚠️
internal/cli/run.go	33.33%	2 Missing and 2 partials ⚠️
internal/cli/lock.go	66.66%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity in the last month. It will be closed in 2 weeks if no further activity occurs. Remove the stale label to reset the inactivity timer.

[ralphbean]

Duplicate of #2707

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 7:04 PM UTC · Completed 7:19 PM UTC
Commit: 07f198d · View workflow run →

[fullsend-ai-retro]

Retro: PR #2706 — agent fix for #2705 closed as duplicate

What happened

Issue #2705 reported a critical production outage: v0.22.0 URL-base skill resolution dropped companion files (sub-agents/, scripts/, meta-prompts/), breaking the review agent across all per-org installations. The triage agent correctly classified it as priority/critical and applied ready-to-code within 5 minutes.

The code agent produced PR #2706 in ~18 minutes — a structurally sound fix adding ForgeClient to ComposeOpts and using the forge API to fetch full skill directory trees. However, the review agent was never dispatched due to a missing [bot]$ bypass in the per-org dispatch.yml (shim run 28266166214 logged "No stage matched — skipping dispatch").

Meanwhile, the issue reporter (waynesun09) opened a competing human-authored PR #2707 just 24 minutes later. PR #2707 received thorough human review from ggallen (5 substantive issues found), was iterated on, and merged the next day. PR #2706 sat unreviewed for 35 days until ralphbean closed it as a duplicate on 2026-07-31.

Quality delta

The agent and human PRs took the same architectural approach but differed in thoroughness:

Dimension	PR #2706 (agent)	PR #2707 (human)
Files changed	4	9
Net lines	+516/−9	+537/−190
Fallback behavior	Preserved SKILL.md-only fallback (the exact failure mode that caused the outage)	Removed fallback entirely — fail-fast
Security	No allowlist path-scope validation	Added directory-level allowlist validation
Cache compat	Not addressed	Added FullListing field to distinguish v0.23+ cache entries
Dead code cleanup	None	Cleaned up 190 lines

The human reviewer (ggallen) caught the critical flaw that the agent missed: preserving the silent fallback path meant the fix could still silently degrade to the exact behavior that caused the outage.

Corroborating evidence for existing issues

All improvement opportunities from this retro are already tracked by existing open issues:

• Add bot carve-out to review dispatch path for pull_request_target events #5706 (closed today): The missing [bot]$ carve-out in the review dispatch path has now been fixed. Both review dispatch paths fail simultaneously for bot-authored PRs when ready-for-review label is missing #5757 (open) tracks the broader dual-path failure — the label-based fallback path is still unresolved.
• Auto-close orphaned agent PRs when linked issue is closed by a different PR #2292: PR fix(#2705): fetch full skill directories from URL bases via forge API #2706 sat open for 35 days after fix(harness): fetch full skill directory from URL base via ForgeClient #2707 was merged, a textbook case for auto-closing orphaned agent PRs when the linked issue is resolved by a different PR.
• Code agent should validate its fix eliminates the reported failure mode, not just add the missing capability #2712: The code agent preserved the flawed fallback behavior instead of eliminating the reported failure mode — exactly the pattern this issue proposes to address via "failure mode elimination check" guidance.
• Review agent should flag when a PR supersedes or conflicts with an open agent-created PR #4258: Neither agent nor human flagged PR fix(#2705): fetch full skill directories from URL bases via forge API #2706 as superseded when PR fix(harness): fetch full skill directory from URL base via ForgeClient #2707 was merged. The review agent should detect conflicting or superseding PRs.
• Auto re-dispatch review after consecutive infrastructure failures with backoff #2711: While the review agent infrastructure failures referenced in this issue occurred on PR fix(harness): fetch full skill directory from URL base via ForgeClient #2707's timeline, the complete absence of review dispatch on PR fix(#2705): fetch full skill directories from URL bases via forge API #2706 shows a related gap.

Assessment

The code agent performed well on speed (18-minute turnaround) and took a structurally correct approach. The primary failure was systemic, not agent-quality: the review dispatch gap meant no feedback loop existed to iterate the agent's PR toward the quality level that human review drove on PR #2707. With review enabled, the agent fix could have been iterable. The dispatch gap has now been addressed by #5706, and the remaining cleanup and quality improvements are tracked by the issues above. No new proposals are warranted.