Directory separation between scaffold-managed and user-added agent files

[ascerra]

Summary

Define and implement a clear directory separation in the fullsend repo between files managed by the fullsend installer/scaffold and files added by org admins for custom agents.

Problem

When an org admin adds a custom agent directly to their fullsend repo, the agent's files end up interspersed with scaffold-managed files in the same directories. For example, a harness directory may contain one user-created file alongside three or four scaffold-owned files. This creates confusion about:

• Ownership: Which files did the installer lay down vs. which did the admin create?
• Upgrade safety: Which files will the installer overwrite on upgrade vs. which are user-maintained?
• Git hygiene: PRs touching scaffold files and user files are hard to distinguish

As the team adopts the "prototype in fullsend first, promote to first-class later" workflow, this problem will compound — the repo will accumulate custom agent files rapidly and become difficult to navigate.

Proposal (for discussion)

Consider one of:

1. Subdirectory convention: e.g., .fullsend/agents/system/ (scaffold-managed) vs .fullsend/agents/custom/ (user-managed)
2. Manifest/ownership file: A .fullsend/manifest.json that declares which files are scaffold-managed, so tooling can warn before overwriting user files
3. Naming convention: Prefix or suffix to distinguish system vs. custom agent files

The chosen approach must work with the installer's upgrade logic and be documentable in the adding-custom-agents guide.

Related

• docs: add automated regression test for the adding-custom-agents guide #554 — Regression test for the adding-custom-agents guide (must reflect whatever convention is chosen)
• Modify workflows to support easy addition/replacement of agents #335 — Modify workflows to support easy addition/replacement of agents
• ADR 0024 — Harness definitions and shared directory layout

[ascerra]

@ralphbean my thought here is to just get the three custom agents (prioritize, scribe, and classify) running on our .fullsend repo. Then consider this issue. if not I fear this will be a blocker for our agents for longer then it should be.

[ben-alkov]

IMO, a combo of #1 and #2

• the subdirectory idea is optimal, except that there's no way to tell whether or not a given file should actually be in a given directory (it's only a convention)
• the manifest would dictate which file should live where (the enforcement)

With both, we would only need to manifest our files - anything in ".fullsend/agents/system/", but not in the manifest would need to be moved.

[ralphbean]

we would only need to manifest our files - anything in ".fullsend/agents/system/", but not in the manifest would need to be moved.

Ah, this makes sense! The installer should lay down a manifest of the things it owns. When it upgrades the users' files, it updates that manifest. Anything not in the manifest is user-owned (and we should throw up a warning if it appears in the system/ dir.

[ggallen]

we would only need to manifest our files - anything in ".fullsend/agents/system/", but not in the manifest would need to be moved.

Ah, this makes sense! The installer should lay down a manifest of the things it owns. When it upgrades the users' files, it updates that manifest. Anything not in the manifest is user-owned (and we should throw up a warning if it appears in the system/ dir.

Do we really need both? IMO the directory is enough.

the manifest would dictate which file should live where (the enforcement)

Why can't this just be the contents of what's in the git repository at fullsend-ai/fullsend? With a manifest file, we'd just be keeping that in sync with what is in that repository anyway.

[fullsend-ai-triage]

RICE Priority Score: 0.7

Score breakdown

Dimension	Score	Reasoning
Reach	1.5	This affects every org that adds custom agents to their fullsend repo. All three strategic customers (konflux-ci, openkaiden, guacsec) will encounter this as they onboard and begin customizing, and the internal team is already hitting it during dogfooding. However, none of the strategic customers have raised this issue themselves yet — it was filed internally by ascerra.
Impact	1	The impact is moderate — it causes confusion about file ownership and upgrade safety, but workarounds exist (being careful, checking git blame). It improves developer experience and reduces risk of accidental overwrites during upgrades, but does not block any core workflow today. The comment from ascerra suggests deprioritizing it relative to getting custom agents running first.
Confidence	0.7	The issue is well-described with concrete proposals, active discussion from multiple contributors, and clear related issues/ADRs. The main uncertainty is around the final design choice (subdirectory vs manifest vs both) and how much installer rework is needed, which slightly lowers confidence on effort.
Effort	1.5	Requires designing a directory convention, modifying the installer's scaffold and upgrade logic, potentially implementing a manifest file, updating the adding-custom-agents guide, and coordinating with regression test issue #554. Touches multiple components (installer, directory layout, documentation) and needs design consensus — the team is still debating approaches in comments.

Formula: (1.5 × 1 × 0.7) / 1.5 = 0.7