Avoid duplicate HEY skills in Codex

[almirsarajcic]

Closes#287.

Problem

Current Codex discovers personal skills from ~/.agents/skills, so copying the same HEY skill into ~/.codex/skills creates two indistinguishable entries.

Change

• Make the shared Agent Skills location the single source used by Codex.
• Stop creating a second Codex-specific skill copy.
• Update Codex setup, health checks, refresh behavior, and documentation to use the shared path.
• During explicit setup and once-per-version refresh, remove an older Codex-specific copy only when hey-cli's ownership marker proves it is managed.
• Preserve unmarked user-authored copies.
• Preserve a managed legacy copy until the shared replacement has been installed and verified healthy.

The existing hey setup agents --remove path remains the supported uninstall flow. This PR does not change skill invocation policy; HEY remains available for normal implicit selection.

Verification

• TMPDIR=/tmp go test ./internal/...
• TMPDIR=/tmp go test ./internal/cmd ./internal/harness ./skills
• go vet ./...
• formatting and tidy checks
• command-surface check
• golangci-lint: 0 issues

The short TMPDIR avoids unrelated Unix-domain socket path-length failures in macOS TUI tests.

---

Summary by cubic

Stops Codex from seeing duplicate HEY skills by making the shared ~/.agents/skills location the single source. Setup, hey skill install, health checks, and version refresh no longer copy the skill into ~/.codex/skills; Codex discovers the shared skill directly.

Migration

• Removes an existing legacy ~/.codex/skills/hey copy only during explicit setup or once-per-version refresh, and only when the ownership marker proves hey-cli created it and the shared replacement is healthy.
• Leaves unmarked user-authored copies untouched, and keeps the legacy copy if installing or refreshing the shared skill fails.
• Skips removal when CODEX_HOME aliases ~/.agents, so the shared skill is never deleted as its own legacy copy.
• A managed legacy duplicate makes the Codex health check fail with a hint to run hey setup codex.
• hey setup agents --remove remains the supported uninstall flow.

^{Written for commit 0cfb6ae. Summary will update on new commits.}

[Copilot]

🟡 Changes recommended

The full setup wizard can short-circuit before removing a managed legacy Codex copy, leaving the duplicate integration in place.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Moves Codex integration to the shared Agent Skills path and safely migrates managed legacy copies.

Changes:

• Uses ~/.agents/skills/hey for Codex setup and health checks.
• Removes managed legacy Codex copies during installation or refresh.
• Updates tests and documentation for the shared-path behavior.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File summaries

File	Description
README.md	Documents Codex shared-skill discovery and migration.
AGENTS.md	Updates repository integration guidance.
internal/harness/harness.go	Adds the canonical shared skill path.
internal/harness/codex.go	Moves Codex health checks to the shared path.
internal/harness/codex_test.go	Tests shared-path health behavior.
internal/cmd/skill_refresh.go	Removes managed legacy copies during refresh.
internal/cmd/skill_refresh_test.go	Covers refresh migration and preservation rules.
internal/cmd/skill_install.go	Stops Codex-specific copying and adds migration.
internal/cmd/skill_install_test.go	Tests installation and legacy-copy safety.
internal/cmd/setup_test.go	Updates wizard behavior coverage.
internal/cmd/setup_agents_test.go	Updates agent setup and removal coverage.
internal/cmd/setup_agents_remove.go	Removes the legacy path during uninstall.
internal/cmd/setup_agent.go	Connects Codex through the shared skill.

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cubic-dev-ai]

All reported issues were addressed across 13 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[almirsarajcic]

Addressed all current review findings in 0cfb6ae:

• make Codex health/preflight detect a managed legacy duplicate so repeated hey setup migrates it
• never remove the legacy copy after a failed refresh
• treat aliased shared/legacy paths as the same file, including CODEX_HOME=$HOME/.agents
• migrate immediately after the shared install, before optional Claude setup
• report shared Agent Skills home-resolution failures accurately
• assert unmanaged legacy directories are never claimed

Added regression coverage for each path. Verified with go test ./internal/... (using TMPDIR=/tmp on macOS to keep Unix socket paths short), go vet ./..., make fmt-check, and golangci-lint v2.11.1 (0 issues).