docs(#5952): remove stale customized/ directory references

[fullsend-ai-coder]

Summary

Remove all stale customized/ directory references from user-facing documentation. The customized/ overlay mechanism (ADR-0064) was fully removed by PRs #5697, #5836, and #5866 — this PR completes the cleanup by updating ~13 doc locations across 11 files to point users to base: composition and config-driven agent registration instead.

Related Issue

Closes #5952

Changes

High priority — guide rewrites:

• customizing-agents.md: Replaced the deprecated "Layered Configuration Resolution" section with a concise "base: Composition" section; removed customized/ paths from harness intro, skill/agent/harness override examples, and pre-commit tool resolution docs
• building-custom-agents.md: Updated all file paths from .fullsend/customized/ to .fullsend/, removed the overlay workflow step from the GHA example, updated file checklist to include config.yaml

Medium priority — actionable instruction fixes:

• triage.md, review.md: Replaced customized/skills/ paths with config-driven registration references
• architecture.md: Rewrote the "Decided" section to describe the current agent configuration model
• runtimes.md: Simplified Layer 3 diagram to remove customized/skills/ lines
• running-agents-locally.md: Replaced cp -r customized/ steps with config-driven workflow
• customizing-with-skills.md: Rewrote "Overriding built-in skills" section to use base: composition

Low priority — cross-reference fixes:

• default-vs-custom.md, customizing-with-agents-md.md, cli-internals.md, tier-conventions.md, gitlab-cron-polling-implementation.md, guides/README.md, bring-your-own-agent.md: Updated link text, table entries, and minor references

Testing

• Verified no stale customized/ references remain in user-facing docs (excluding ADRs, plans, and glossary)
• scan-secrets passed on all changed files
• gitlint passed on commit message
• Pre-commit could not run (sandbox network restrictions) — post-script runs authoritative check

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• No secrets or sensitive data in changes
• All changes are documentation-only — no code, test, or config changes

---

Closes #5952

Post-script verification

• Branch is not main/master (agent/5952-remove-customized-dir-refs)
• Secret scan passed (gitleaks — ad9b3ced5c978656450d716a9e7dbab071401cf0..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:59 PM UTC · Completed 8:19 PM UTC
Commit: 282ce4a · View workflow run →

[github-actions]

Site preview

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

Commit: 597ecc1f3020b10462019fd20d1fbdabb226b9a1

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Looks good to me

Previous run

Review

Findings

Medium

• [logic-error] docs/guides/user/running-agents-locally.md:342 — The "Simulating Fullsend's real customization layers" section instructs users to clone fullsend-ai/agents to /tmp/agents/ but that clone is never referenced by any subsequent command. The PR removed the cp -r overlay steps that previously used /tmp/agents/, but left the initial clone instruction. Users following these steps will clone a repository they never use, while --fullsend-dir is pointed at /tmp/org-fullsend/.

Low

• [stale-reference] docs/guides/user/customizing-agents.md:197 — The Prerequisites subsection still references "L2 per-repo registries" but the L1/L2 naming convention was removed from this same section. The heading was renamed to "Two-layer resolution" and the L1/L2 labels were removed from the table.

• [scope-creep] docs/architecture.md:461 — The source reference changed from fullsend-ai/fullsend@v0 to fullsend-ai/agents, extending slightly beyond issue Remove stale customized/ directory references from user-facing docs #5952's stated scope. The change is factually accurate.

• [stale-reference] docs/agents/topics/escalation-ladder.md:194 — The "See also" link to the customizing-agents guide still describes it as "harness configuration and layered content resolution". The PR updates the same link text in docs/guides/README.md and docs/guides/user/bring-your-own-agent.md but missed this file.

Previous run (2)

Review

Findings

Low

• [stale-reference] docs/doc-site.md:75 — The "When to revisit" section lists customized/ removal as a hypothetical future event, but the removal has already occurred (PRs chore(#5694): remove deprecated customized/ scaffold #5697, chore(#5824): remove CUSTOM_BASE overlay loop from reusable workflows #5836, chore(#5864)!: remove migrate-customizations command #5866). Consider updating to reflect this trigger has been resolved.

• [stale-reference] docs/guides/dev/testing-workflows.md:50 — References fullsend-ai/fullsend@v0 as the location for upstream reusable workflows. This may still be correct for reusable workflows (distinct from agent content at fullsend-ai/agents), but warrants verification.

• [stale-implementation-step] docs/plans/deprecate-per-org-install.md:212 — Migration command step references copying customized/ directories. The step is already annotated as removed (Remove fullsend agent migrate-customizations command (ADR-0064 cleanup) #5864) and the plan is a historical record.

• [scope-creep] docs/architecture.md — The source reference changed from fullsend-ai/fullsend@v0 to fullsend-ai/agents, extending slightly beyond issue Remove stale customized/ directory references from user-facing docs #5952's stated scope. The change is factually accurate.

• [stale-reference] docs/glossary.md:35 — The "Base Composition" entry says it "Replaces the deprecated customized/ directory overlay." Since the Customized Directory entry already says "Removed.", consider using past tense for consistency.

---

Labels: PR modifies only documentation files under docs/

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:26 PM UTC · Completed 9:42 PM UTC

Commit: 57fcd76 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:46 PM UTC · Completed 10:01 PM UTC

Commit: 597ecc1 · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 11:36 PM UTC · Completed 11:51 PM UTC

Commit: 597ecc1 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5955 — Remove stale customized/ directory references

This docs-only PR followed a clean workflow: issue #5952 (filed by ggallen with detailed per-file instructions) -> triage (3 min) -> code agent (11 min, 17 files changed) -> review -> human fix -> re-review -> merge. The code agent produced comprehensive coverage across all locations listed in the issue.

Timeline

Time (UTC)	Event
Aug 5 19:42	Issue #5952 filed by ggallen
Aug 5 19:43-19:46	Triage agent (run 31040692236) confirms unblocked
Aug 5 19:47-19:58	Code agent (run 31041010088) creates PR with commit 282ce4a
Aug 5 19:59-20:19	1st review (run 31041924324) approves with 4 low findings
Aug 10 21:25	Human rebases/pushes 57fcd76
Aug 10 21:26-21:42	2nd review (run 31433826348) finds 1 medium + 3 low, posts 3 inline comments
Aug 10 21:45	Human fixes 2 findings, dismisses 1 scope-creep, pushes 597ecc1
Aug 10 21:46-22:01	3rd review (run 31435341113) approves
Aug 10 23:30	Human approves
Aug 10 23:34	PR merged

Key finding: orphaned setup step

The code agent removed the cp -r customized/ overlay steps from running-agents-locally.md and changed --fullsend-dir from /tmp/agents/ to /tmp/org-fullsend/, but left the git clone ... /tmp/agents/ instruction that was only needed for those removed steps. This was confirmed present in the original code agent commit (282ce4a) — the first review (agents@5e98b13) missed it entirely, while the second review (agents@6bdcab6, 5 days later) caught it as a medium-severity logic error. The human fixed it in ~3 minutes.

The issue's verification command (grep -rn 'customized/' docs/) would not have caught this because the orphaned step uses the URL fullsend-ai/agents, not the customized/ path. This is a logical consistency issue (clone something and never use it) rather than a stale string reference.

Evidence for existing issues (no new proposals needed)

• agents#656 and agents#657: The orphaned git clone step is additional evidence that the code agent needs a post-change verification step. If the agent had grepped for /tmp/agents/ after its changes, it would have found the orphaned clone. agents#657 (grep for stale path references when deleting) is directly applicable.
• fullsend#3695: The review agent found a stale reference in docs/agents/topics/escalation-ladder.md:194 (link text still says "layered content resolution") but couldn't post an inline comment because the file wasn't in the PR diff. This finding was effectively lost — exactly the pattern Review agent should flag out-of-diff documentation consistency findings as follow-up candidates #3695 aims to address.
• agents#427: This PR adds a data point for docs-only PR autonomy tracking. The review agent caught a genuine medium-severity logic error, and the human's review was largely aligned (fixed 2 findings, correctly dismissed 1). Human-only contributions were editorial, not correctness-critical.

Review quality note

The first review (Aug 5, agents@5e98b13) and second review (Aug 10, agents@6bdcab6) ran on effectively identical diffs but produced different findings — the first missed the medium-severity orphaned clone that the second caught. This is likely attributable to the agents repo version change between runs rather than a systemic consistency problem.