docs(#194): document agent content migration to fullsend-ai/agents

[fullsend-ai-coder]

Agent definitions, skills, and harness configs are maintained in fullsend-ai/agents. The stale copies under internal/scaffold/fullsend-repo/agents/ and skills/ have caused three documented incidents of contributors targeting the wrong location (PRs fullsend-ai#2417, fullsend-ai#2927, fullsend-ai#3156 -- all closed as misdirected).

Add an Agent definitions and skills section to AGENTS.md directing contributors to the correct repo. Distinguish stale copies (agents/ and skills/, to be removed) from actively embedded harness configs (still required for //go:embed, do not edit directly). Add deprecation README markers to each scaffold directory so contributors encountering these files are redirected.

Note: pre-commit could not run in sandbox (shellcheck install failed due to network restrictions). The post-script runs pre-commit authoritatively on the runner.

---

Closes #194

Post-script verification

• Branch is not main/master (agent/194-document-agent-migration)
• Secret scan passed (gitleaks — a2afa8b179a351845733c680b839a39a82304db6..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.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:23 AM UTC · Completed 9:28 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-review]

Review — approve

PR: #288
Author: fullsend-ai-coder[bot]
Issue: #194 — document that agent/skill content has moved to fullsend-ai/agents

Summary

Clean, well-scoped documentation change that addresses a recurring contributor problem (three documented misdirected PRs targeting stale scaffold copies). The PR adds:

1. New "Agent definitions and skills" section to AGENTS.md — correctly distinguishes between stale copies (agents/, skills/) and actively embedded content (harness/)
2. Deprecation README.md files — placed in internal/scaffold/fullsend-repo/agents/, skills/, and harness/ to redirect contributors

Verification

Architecture accuracy confirmed:

• scaffold.go uses //go:embed all:fullsend-repo to embed the entire scaffold directory (line 11)
• layeredDirs in scaffold.go includes agents/, skills/, and harness/ — these are skipped during installation (WalkFullsendRepo) and provided at runtime via reusable workflows (per ADR 0035)
• baseurl.go confirms harness content is served from this repo's raw.githubusercontent.com URLs and hash-verified against embedded content — harness files genuinely must remain in this repository
• The PR's distinction (harness = keep, agents/skills = stale) accurately reflects the runtime architecture

No functional impact:

• HarnessNames() filters by .yaml suffix — the new harness/README.md won't appear in the harness name list
• No Go code changes, no test changes needed
• The README.md files are informational markers only

Intent matches issue: The PR implements exactly what issue #194 proposed — AGENTS.md section + deprecation markers in each scaffold directory.

Injection defense: PR body content reviewed — the note about pre-commit not running in the sandbox is informational context about CI limitations, not a directive. The post-script verification checklist confirms authoritative pre-commit ran on the runner.

No findings

No medium-or-higher severity findings. The change is safe and well-aligned with the documented problem.

---

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

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, a protected path requiring human approval. The PR links to issue [ARCHIVED] Original issue 194 #194 with clear justification for the change. Human review and approval is required regardless of automated review outcome.

• [architectural-coherence] AGENTS.md — The new section states agent/skill content "has moved" to fullsend-ai/agents (past tense, definitive), but repository evidence shows the roadmap uses future tense ("agents may eventually move to separate repositories"). The config.yaml confirms fullsend-ai/agents exists as an allowed remote resource, but the completeness of the migration cannot be verified from this repository alone. Consider softening language to reflect current state more precisely (e.g., "are being migrated to" or "are maintained in").

• [scope-authorization] AGENTS.md — The statement "The runtime layering system resolves harness content from the local scaffold, not from fullsend-ai/agents directly" is factually accurate (verified via scaffold.go //go:embed) but describes runtime implementation behavior beyond typical contributor-facing guidance. Consider simpler phrasing like "harness configs must remain in this repository for the build."

Low

• [link-formatting] AGENTS.md:22 — Backticks inside link text are inconsistent with some existing links in the file, though the same file already uses this pattern at line 67. Mixed convention; not a clear violation.

• [readme-title-convention] internal/scaffold/fullsend-repo/agents/README.md:1, internal/scaffold/fullsend-repo/skills/README.md:1 — Using "# Deprecated" as the H1 heading serves the warning purpose but doesn't follow the pattern of descriptive topic titles. Consider "# Agent Definitions" / "# Skills" followed by a deprecation notice.

• [readme-title-convention] internal/scaffold/fullsend-repo/harness/README.md:1 — "# Do not edit directly" as H1 serves as a warning but doesn't identify the content area. This directory is NOT deprecated (unlike agents/ and skills/), so a descriptive title like "# Harness Configurations" followed by edit restrictions would be more informative.

• [architectural-alignment] AGENTS.md — The section states scaffold copies "will be removed" without a tracking issue, timeline, or completion criteria. Consider adding a reference to the removal tracking.

• [deprecated-path-reference] docs/superpowers/plans/2026-05-04-retro-agent.md:393 — Historical plan document references creating files in internal/scaffold/fullsend-repo/skills/, now marked as deprecated. Low priority since plan documents are point-in-time artifacts.

Previous run (2)

Review — ✅ Approve

Clean, well-scoped documentation change that directly addresses the three documented incidents of misdirected PRs (fullsend-ai#2417, fullsend-ai#2927, fullsend-ai#3156 in upstream) caused by missing migration guidance.

What was verified

Check	Result
AGENTS.md section accuracy	✅ Correctly distinguishes stale copies (agents/, skills/) from active embeds (harness/)
Harness claim	✅ baseurl.go reads harness/*.yaml at runtime via embed.FS; HarnessNames() filters to .yaml only — new README.md is inert
Embed safety	✅ WalkFullsendRepo() skips all three dirs (layeredDirs); READMEs won't be installed to target repos
Test impact	✅ No test breakage — TestFullsendRepoFilesExist checks specific files; TestLayeredDirsNotInstalled validates skipping
Section placement	✅ After "How to work in this repo" bullets, before "Go code" — follows established pattern of documenting file-location guidance
PR body injection	✅ No instruction-like patterns detected
Secrets	✅ No secrets or sensitive data

Notes

• The deprecation READMEs appropriately use different messaging: agents/ and skills/ say "Deprecated ... will be removed," while harness/ says "Do not edit directly" — reflecting that harness configs are still required for the //go:embed pipeline.
• The AGENTS.md section follows the established pattern used for the mint function and dispatch workflow dual-location documentation.
• Issue [ARCHIVED] Original issue 194 #194 is well-addressed. The validation criteria in the issue (agents targeting the correct repo on subsequent PRs) will determine effectiveness over time.

---

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: Documentation-only PR updating contributor guidance for agent content location

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 10:19 AM UTC · Ended 10:33 AM UTC
Commit: a2afa8b · View workflow run →

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:19 AM UTC · Completed 10:33 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:34 AM UTC · Completed 10:39 AM UTC
Commit: a2afa8b · View workflow run →

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 11:18 AM UTC · Completed 11:25 AM UTC
Commit: a2afa8b · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

No code changes made. The latest review approved PR #288 with no findings. The human /fs-fix command provided no specific instruction. Previous review iteration findings were superseded by the most recent review which found no issues.

Disagreed (1):

1. No actionable findings to address: The latest review approved the PR with no medium-or-higher severity findings. The human /fs-fix command was issued without a specific instruction (HUMAN_INSTRUCTION='none'). Previous review findings are superseded by the latest approval. No code changes are warranted.

Tests: passed

_{Updated by fullsend fix agent}