feat(cli)!: rename --fullsend-dir to --agent-dir with deprecation alias

[fullsend-ai-coder]

Summary

• Introduce --agent-dir as the primary CLI flag for specifying the agent definitions directory, replacing the now-misleading --fullsend-dir name (post agent-extraction migration, ADR 0058)
• Keep --fullsend-dir as a hidden backward-compatible alias that emits a deprecation warning to stderr
• Error when both --agent-dir and --fullsend-dir are specified simultaneously
• Update help text to reference "agent definitions" instead of ".fullsend layout"
• Update user-facing docs and internal scripts to use the new flag name

Related Issue

Closes #5288

Changes

New file: internal/cli/agentdir.go

• registerAgentDirFlag() — registers --agent-dir as primary flag and --fullsend-dir as hidden deprecated alias
• resolveAgentDirFlag() — merges values, enforces mutual exclusivity, emits deprecation warning, validates required

Modified: internal/cli/run.go, lock.go, agent.go, migrate.go

• All 7 leaf commands (run, lock, agent add/list/update/remove, agent migrate-customizations) now use the shared registerAgentDirFlag/resolveAgentDirFlag helpers
• Removed MarkFlagRequired("fullsend-dir") — requirement is now enforced by resolveAgentDirFlag
• Updated example text in agent add help to use --agent-dir

New file: internal/cli/agentdir_test.go

• Tests for: primary flag acceptance (no warning), deprecated flag acceptance (with warning), both-flags error, neither-flag error, hidden flag verification across all 7 commands, help text content, and deprecated alias works across all command types

Updated docs

• docs/guides/user/running-agents-locally.md — all examples use --agent-dir
• docs/guides/user/building-custom-agents.md — workflow example uses --agent-dir
• docs/guides/dev/cli-internals.md — CLI tree updated to --agent-dir
• eval/scripts/run-fullsend.sh — updated to --agent-dir

Not changed (intentionally)

• action.yml and reusable workflow files — these pass fullsend-dir as an action input name (separate from CLI flag naming) and use the deprecated alias which continues to work. They can be migrated independently.

Testing

• go vet ./... passes
• go test ./internal/cli/... passes (only pre-existing TestStartFetchService_* failures unrelated to this change)
• New TestAgentDirFlag_* tests cover all deprecation behaviors
• Existing tests updated to use --agent-dir
• scan-secrets --staged passes
• gofmt passes

Checklist

• Changes are minimal and scoped to the issue
• Commit message follows COMMITS.md conventions (includes ! for breaking change)
• BREAKING CHANGE trailer included
• Tests added for new behavior
• Docs updated

---

Closes #5288

Post-script verification

• Branch is not main/master (agent/5288-deprecate-fullsend-dir-flag)
• Secret scan passed (gitleaks — 0ecb0229723378ef631cb472e09f0cbd28d0b011..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 2:07 PM UTC · Completed 2:23 PM UTC
Commit: ee18ce1 · View workflow run →

[github-actions]

Site preview

Preview: https://6b0e69f6-site.fullsend-ai.workers.dev

Commit: 5d7925b322a6edebb1bf5246fe7d36e27fbffe48

[codecov]

Codecov Report

❌ Patch coverage is 72.97297% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/cli/agent.go	57.14%	3 Missing and 3 partials ⚠️
internal/cli/lock.go	50.00%	1 Missing and 1 partial ⚠️
internal/cli/migrate.go	33.33%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [stale-reference] internal/cli/run.go:427 — The lock-stale warning message still recommends --fullsend-dir: Run 'fullsend lock %s --fullsend-dir %s' to update. This directs users to the deprecated flag instead of --agent-dir.
  Remediation: Replace --fullsend-dir with --agent-dir in the format string.

• [stale-doc] docs/plans/agent-registration.md:134 — CLI command examples in the agent registration plan still reference --fullsend-dir (three instances at lines 134-136).
  Remediation: Replace --fullsend-dir with --agent-dir in the CLI examples.

• [stale-doc] docs/plans/agent-extraction-to-agents-repo.md:602 — Test verification command references --fullsend-dir.
  Remediation: Replace with --agent-dir.

• [stale-doc] docs/plans/gitlab-cron-polling-implementation.md:1495 — GitLab CI pipeline example references --fullsend-dir.
  Remediation: Replace with --agent-dir.

• [stale-doc] docs/plans/universal-harness-access-phase3.md:59 — CLI command examples reference --fullsend-dir (also at line 81).
  Remediation: Replace with --agent-dir.

Low

• [stale-reference] action.yml:333 — The composite action invokes fullsend run with --fullsend-dir, which will emit a deprecation warning to stderr on every CI run. The PR body acknowledges this as an intentional deferral ("can be migrated independently").

• [stale-doc] docs/ADRs/0033-per-repo-installation-mode.md:199 — ADR describes --fullsend-dir in architectural context. This is a point-in-time record; updating is optional.

• [stale-doc] docs/superpowers/specs/2026-04-17-installer-agent-content-design.md:274 — Spec references --fullsend-dir in a command example.

• [stale-doc] docs/ADRs/0035-layered-content-resolution.md:77 — Superseded ADR (by ADR 0064) mentions --fullsend-dir.

• [stale-doc] docs/plans/deprecate-per-org-install.md:831 — Plan mentions fullsend-dir in context of code removal tasks.

• [stale-reference] internal/cli/migrate_test.go:291 — Test comment references --fullsend-dir.

[rh-hemartin]

I agree with the intent, there are some issues raised by the bot, please resolve them.

[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.

[waynesun09]

Closing in favor of #5424. After investigating what the --fullsend-dir directory actually contains (config.yaml, harness/, lock.yaml, profiles/, providers/, AGENTS.md, and everything harness files reference), the flag name --fullsend-dir is correct — the directory is the .fullsend/ project configuration root, not a directory of agent definitions. Renaming to --agent-dir would be equally misleading. #5424 keeps the flag name and only updates the stale help text from ".fullsend layout" to ".fullsend configuration directory".

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 10:08 PM UTC · Completed 10:21 PM UTC
Commit: 5d7925b · View workflow run →

[fullsend-ai-retro]

Retro: PR #5291 — rename --fullsend-dir to --agent-dir (closed, not merged)

What happened

1. Issue #5288 filed by waynesun09 proposing to deprecate --fullsend-dir in favor of --agent-dir, arguing the flag name became misleading after agent-extraction (ADR 0058).
2. Triage agent (run 29646075838) categorized it as a low-severity CLI UX improvement and labeled it ready-to-code without questioning whether --agent-dir was actually a more accurate name.
3. Code agent (run 29646475439, $8.07) implemented the full rename across 22 files (364 additions, 86 deletions) — new flag helpers, deprecation warnings, comprehensive tests, documentation updates.
4. Review agent ran twice (run 29647406542, $6.37; run 29647597859). Both failed with GitHub API 422 errors when trying to submit inline comments for findings on lines outside the PR diff hunks. The review did identify stale --fullsend-dir references in plan docs (medium severity) but did not question the fundamental premise of the rename.
5. Human review — rh-hemartin approved on 2026-07-21, asking to resolve the bot's findings.
6. PR closed — waynesun09 (the original issue author) closed the PR after investigating what the .fullsend/ directory actually contains (config.yaml, harness/, lock.yaml, profiles/, providers/, AGENTS.md). Conclusion: --fullsend-dir is correct — the directory is the project configuration root, not an agent directory. --agent-dir would be equally misleading.
7. Replacement — PR #5424 created with just 17 additions / 17 deletions across 8 files, updating only the help text description.

Waste

~$14.44 in token costs, 3 days of calendar time, and human review effort — all for a change that was closed because the premise was incorrect. The actual fix was a 95% smaller documentation-only PR.

Evidence for existing issues

• #5140 (post-review 422 on out-of-hunk findings): Both review runs on this PR hit the same 422 failure pattern — findings on lines outside diff hunks were included in the inline comments array, causing the entire review submission to fail. This prevented the review from posting its findings and labeling the PR.
• agents#193: Same 422 root cause from the agents-repo perspective.
• #1890 (review agent should challenge factual premises): This PR is another instance of the exact pattern described in Review agent should challenge the factual premise of agent-generated fix PRs #1890 — the review agent evaluated code quality (finding stale references) but never questioned whether --agent-dir was actually more accurate than --fullsend-dir. Had the review agent examined the directory contents, it could have flagged the premise as incorrect.
• #1701 (code agent should investigate root cause before implementing): The code agent faithfully implemented the rename without investigating whether the proposed name was semantically correct — a related but distinct gap from the triage-layer proposal below.

Proposals filed

• Triage agent should validate semantic accuracy of rename/refactor proposals before marking ready-to-code (in fullsend-ai/agents)