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

[fullsend-ai-coder]

Agent definitions, skills, and harness configs have moved to the fullsend-ai/agents repository. The copies under internal/scaffold/fullsend-repo/ are stale and will be removed.

Add an "Agent definitions and skills" section to AGENTS.md documenting the migration and listing the deprecated scaffold paths. Add README.md deprecation markers to each affected scaffold directory (agents/, skills/, harness/) so contributors encountering these files are redirected to the correct repo.

The harness/ README notes that those configs are still actively embedded via //go:embed and must remain in this repository, unlike agents/ and skills/ which are fully deprecated.

---

Closes #238

Post-script verification

• Branch is not main/master (agent/238-document-agent-content-migration)
• Secret scan passed (gitleaks — d8e3df7c018996e396c79b8ecd59e4145a628a6f..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 4:42 PM UTC · Completed 4:51 PM UTC
Commit: d8e3df7 · View workflow run →

[fullsend-ai-review]

Review — comment

Well-scoped docs PR that matches issue #238's request: AGENTS.md section documenting the migration to fullsend-ai/agents, plus deprecation/redirect READMEs in the three scaffold subdirectories. The differentiated treatment of harness/ ("do not edit directly" vs "deprecated") is the right call since harness YAML has a runtime dependency the other two don't.

One medium finding on technical precision, and a docs-currency observation for follow-up.

Findings

1. Imprecise technical claim — "runtime layering system" (Medium · correctness)

File: AGENTS.md (new section, paragraph 2)

The text states:

Harness configs must remain in this repository because the runtime layering system resolves harness content from the local scaffold, not from fullsend-ai/agents directly.

The actual dependency is scaffold.HarnessContentHash() in internal/scaffold/baseurl.go, which reads embedded harness YAML via content.ReadFile("fullsend-repo/harness/...") to compute SHA-256 integrity hashes. These hashes are appended as #sha256=... fragments to raw.githubusercontent.com URLs constructed by HarnessBaseURLWithHash(). The harness files serve double duty: embedded content for hash computation and a fetchable URL source at the same internal/scaffold/fullsend-repo/harness/ path.

The phrase "runtime layering system" doesn't describe this mechanism. A contributor following this documentation to understand the constraint would look at WalkFullsendRepo (the actual layering/installation code), which skips harness files entirely — the opposite of "resolving" them. The imprecision could send someone down the wrong code path.

Suggested replacement:

Harness configs must remain in this repository because the CLI reads embedded harness YAML at build time to compute content hashes for integrity-checked base URLs (see internal/scaffold/baseurl.go). The HarnessBaseURLWithHash function constructs raw.githubusercontent.com URLs pointing to these same files, so they must exist both in the embed and at the served path.

2. Other guides reference scaffold paths without migration context (Low · docs-currency)

Several user-facing guides reference internal/scaffold/fullsend-repo/ paths and instruct users to clone/checkout from them:

• docs/guides/user/running-agents-locally.md (lines ~111, 137, 157, 183, 244, 268)
• docs/guides/user/building-custom-agents.md (lines ~383-395)
• docs/guides/user/customizing-agents.md (line ~158)
• docs/guides/dev/cli-internals.md (lines ~424-447)

These aren't stale yet — the scaffold files still exist and work. But they'll need migration notices when agents/ and skills/ are actually removed. Worth tracking as follow-up work, potentially on the same issue or a successor.

Security

No findings. Diff is clean ASCII + UTF-8 em dashes. No secrets, no injection patterns, no permission changes.

Scope & intent

The PR is well-authorized by issue #238 and stays within its requested scope (AGENTS.md section + README markers). The choice of README.md files over HTML comments (the issue offered both) is appropriate — READMEs are visible in directory listings on GitHub and in editors, making them more effective as contributor guardrails than inline HTML comments.

---

Verdict: comment — medium finding on documentation precision. The PR is useful and correctly scoped; the imprecise "runtime layering system" claim is worth fixing before merge to avoid misleading future contributors about the actual technical constraint.

Previous run

Review — comment

Scope: Documentation-only PR (4 files, +37/−0) adding deprecation notices for agent/skill/harness scaffold content that has moved to fullsend-ai/agents. Traces to #238.

Intent alignment: ✅ The PR implements exactly what #238 requested — an AGENTS.md section documenting the migration and README deprecation markers in each scaffold directory. No scope creep.

Security: ✅ No secrets, no permission changes, no injection patterns.

Style: ✅ The new AGENTS.md section follows the existing heading structure and imperative prose style.

Findings

1. AGENTS.md — inaccurate runtime mechanism description

Severity	medium
Category	technical-accuracy
File	AGENTS.md (new section, lines ~27–31)

The added text states:

Harness configs must remain in this repository because the runtime layering system resolves harness content from the local scaffold, not from fullsend-ai/agents directly.

This is inaccurate. At runtime, harness content is not resolved from the local embedded scaffold. The actual mechanism is:

1. At install time, HarnessWrappersLayer.Install() generates thin wrapper YAML files containing a base: URL pointing to raw.githubusercontent.com/fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/<name>.yaml.
2. The embedded scaffold copy is used only to compute the SHA-256 integrity hash appended to that URL (via HarnessContentHash() in internal/scaffold/baseurl.go).
3. At runtime, the base: URL is fetched from GitHub — not from the embedded filesystem.

The harness files must remain in this repo because (a) they are the content served via raw.githubusercontent.com URLs that wrappers reference, and (b) the embedded copy provides the integrity hash baseline at install time.

Suggested fix: Replace the sentence with something like:

Harness configs must remain in this repository because they are the source of truth served via raw.githubusercontent.com URLs that wrapper harnesses reference at runtime, and the embedded copies are used to compute integrity hashes at install time.

2. internal/scaffold/fullsend-repo/harness/README.md — ambiguous "canonical" framing

Severity	low
Category	internal-consistency
File	internal/scaffold/fullsend-repo/harness/README.md

The README says fullsend-ai/agents is the "canonical editing source," while the files in this repo are what raw.githubusercontent.com actually serves at runtime. The word "canonical" could lead a reader to believe these files can be safely removed if fullsend-ai/agents has them — when in fact the opposite is true (this repo is the canonical runtime source). The intended message ("author changes in agents repo, sync back here") comes through in context, so this is minor.

Previous run (2)

Review — comment

Documentation-only PR that adds migration notices to AGENTS.md and deprecation READMEs to three scaffold directories. The change faithfully implements issue #238 and is well-scoped. One medium-severity accuracy concern worth noting before merge.

Findings

1. Embed and test dependencies on "stale" directories — medium

File: AGENTS.md (new section, lines ~18–21)

The new section states that copies under internal/scaffold/fullsend-repo/agents/ and internal/scaffold/fullsend-repo/skills/ "are stale and will be removed." However, the actual embed directive at internal/scaffold/scaffold.go:11 is:

//go:embed all:fullsend-repo
var content embed.FS

This embeds the entire fullsend-repo/ tree — including agents/ and skills/, not just harness/. Additionally, scaffold_test.go actively asserts against files in these directories:

• FullsendRepoFile("agents/code.md") (line 369)
• FullsendRepoFile("skills/code-implementation/SKILL.md") (line 378)
• FullsendRepoFile("agents/triage.md") (line 541)
• FullsendRepoFile("agents/prioritize.md") (line 846)

Deleting these files would break both the embed and these tests. The claim that they "will be removed" is directionally correct but creates an impression they can simply be deleted.

Suggested fix: Soften to "are deprecated and will be removed after their embed and test dependencies are migrated," or note the dependency in the AGENTS.md section.

2. Imprecise //go:embed framing — low

File: AGENTS.md (new section, lines ~25–28)

The text says harness configs are "actively embedded into the Go binary via //go:embed" as though this is specific to harness/. The embed actually covers the entire fullsend-repo/ subtree, meaning agents/ and skills/ (called "stale" in the same paragraph) are equally embedded. This selective framing could confuse a contributor into thinking only harness files are embedded.

3. Harness README implies automated sync — low

File: internal/scaffold/fullsend-repo/harness/README.md (line 5)

The README states: "these files are synced from the upstream source." No sync mechanism (GitHub Action, script, or Makefile target) exists in the repository. If syncing is manual, this should say "should be kept in sync with" rather than "are synced from" to avoid a contributor editing in fullsend-ai/agents and waiting for an automated sync that doesn't exist.

Dimensions reviewed

Dimension	Result
Correctness	1 medium, 2 low
Security	No findings
Intent & coherence	No findings — scope matches #238 exactly
Style & conventions	No findings — heading level, placement, and link format are consistent
Docs currency	No findings within PR scope
Cross-repo contracts	Skipped — no API/schema changes

---

Labels: PR is documentation-only, adding migration notices and deprecation markers

[guyoron1]

/fs-fix

[fullsend-ai-coder]

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

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all three review findings: softened removal language for agents/ and skills/ to acknowledge embed and test dependencies, clarified that //go:embed covers the entire fullsend-repo/ tree, and fixed harness README to say 'should be kept in sync' instead of implying automated syncing.

Fixed (3):

1. Embed and test dependencies on 'stale' directories — medium (AGENTS.md): Softened 'are stale and will be removed' to 'are deprecated and will be removed after their embed and test dependencies are migrated' to accurately reflect that agents/ and skills/ cannot simply be deleted while //go:embed and tests reference them.
2. Imprecise //go:embed framing — low (AGENTS.md): Replaced harness-specific embed language with accurate statement that the entire fullsend-repo/ tree is embedded via '//go:embed all:fullsend-repo' in scaffold.go.
3. Harness README implies automated sync — low (internal/scaffold/fullsend-repo/harness/README.md): Changed 'are synced from the upstream source' to 'should be kept in sync with the upstream source' since no automated sync mechanism exists.

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-review]

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

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:50 AM UTC · Completed 4:59 AM UTC
Commit: d8e3df7 · View workflow run →