64. Deprecate customized/ directory overlay

Date: 2026-06-30

Status

Accepted

Supersedes ADR 0035 (layered content resolution).

Context

ADR 0035 introduced a three-tier layering model for agent customization: upstream defaults are copied into the workspace at runtime, then files from customized/ (per-org) or .fullsend/customized/ (per-repo) are overlaid on top, replacing upstream files with matching names. The overlay is file-level replacement with no field-level merging — customizing a single harness field requires copying the entire upstream YAML and modifying it.

Three subsequent ADRs have introduced mechanisms that cover every customization scenario the overlay handled, with better ergonomics:

• ADR 0045 added base: composition for harness files. A thin wrapper inherits an upstream harness by URL and overrides only the fields that differ, with proper merge semantics (scalars override, skills concatenate, runner_env merges).

• ADR 0038 added URL-based references for declarative resources (agents, skills, policies, schemas). Resources can be referenced from any trusted source without copying them into a local directory.

• ADR 0058 added config-based agent registration. Agents are discovered from agents: entries in config (URLs or local paths), not from directory scanning.

Together these make the customized/ directory overlay redundant:

What customized/ did	Replacement
Override a harness	base: composition (ADR 0045)
Override an agent definition	Harness agent: field with path or URL (ADR 0038)
Add/remove agents	agents: list in config (ADR 0058)
Add custom skills	Harness skills: list with paths or URLs (ADR 0038); concatenated via base: (ADR 0045)
Override policies/schemas	Harness fields with paths or URLs (ADR 0038)
Custom scripts	pre_script/post_script in harness; inherited from base: (ADR 0045)
Custom env vars	env: in harness; merged via base: (ADR 0045)

The customized/ directories currently contain only .gitkeep placeholders. The overlay loop in reusable workflows runs every agent invocation but copies zero files.

Decision

Deprecate and remove the customized/ directory overlay mechanism introduced by ADR 0035.

The implementation plan is in docs/plans/deprecate-customized-directory-overlay.md.

This ADR should be implemented once ADRs 0038, 0045, and 0058 are fully implemented and in production.

Consequences

• Users who placed files in customized/ must migrate to base: composition, URL references, or config-based registration.
• Deprecation warnings during install and updated documentation will guide migration.
• The reusable workflows become simpler — no overlay loop, no install_mode branching for customization paths.
• The scaffold produces fewer files — no .gitkeep placeholders in customized/ subdirectories.
• fullsend admin install no longer creates customized/ directories.
• A single, consistent customization model replaces the split between directory overlay (ADR 0035) and harness composition (ADR 0045).