fix(install): resolve Codex agents path on Windows (#340)

[tirth8205]

Summary

Closes #340.

On Windows + Codex CLI, /understand fails to dispatch its subagents because the relative agents/<name>.md paths emitted by the skill aren't auto-resolved to ~/.understand-anything-plugin/agents/<name>.md. The reporter confirmed the agents load when the full path is typed manually, so the underlying junction is fine — it's the implicit path resolution that breaks.

This PR ships a two-pronged, defensive fix:

1. understand-anything-plugin/skills/understand/SKILL.md + hooks/auto-update-prompt.md: every agents/<name>.md reference now reads $PLUGIN_ROOT/agents/<name>.md, using the plugin-root variable that the SKILL.md already resolves in Phase 0 step 1.5. This mirrors the pattern already used in understand-domain/SKILL.md ("Read the domain-analyzer agent prompt from $PLUGIN_ROOT/agents/domain-analyzer.md") and gives every host — Claude Code, Codex, opencode, gemini, pi, anything else — an unambiguous absolute path, so it no longer matters whether the host auto-traverses the universal junction.

2. install.ps1 only: for the codex, opencode, and pi platforms, also create a vendor-specific plugin-root junction (e.g. ~/.codex/understand-anything/understand-anything-plugin). These paths are already in the SKILL.md fallback chain, so even on the worst-case Windows host that won't traverse ~/.understand-anything-plugin, the plugin is still discoverable through the vendor-specific junction. POSIX symlinks already resolve the universal junction correctly, so install.sh is intentionally untouched — the SKILL.md change is the symmetric fix that helps every platform equally.

Diagnosis

/understand's SKILL.md resolves a $PLUGIN_ROOT via a bash chain that probes $CLAUDE_PLUGIN_ROOT, ~/.understand-anything-plugin, ~/.agents/skills/understand/../.. (after realpath), and several vendor-specific paths. Once resolved, subsequent phases used to say:

Dispatch a subagent using the project-scanner agent definition (at agents/project-scanner.md).

That bare agents/... reference is what hosts have to guess at. On Claude Code the runtime knows the plugin layout and finds it. On Codex Linux/macOS the LLM appears to chase the $PLUGIN_ROOT variable and read $PLUGIN_ROOT/agents/... anyway. On Codex Windows the path stays unresolved relative to whatever the host's notion of cwd is, the read fails, and dispatch silently drops. Making the absolute path explicit removes the guess.

Why install.ps1 also changed

I want a belt-and-suspenders mitigation for Windows users. Even with the SKILL.md fix, the plugin-root resolution chain itself depends on bash (realpath, readlink -f, $() substitution). If a Windows host doesn't run bash at all and only the universal ~/.understand-anything-plugin junction is created, and the host happens to also refuse to traverse it, the fallback chain has nothing left to try. Mirroring the junction at ~/.codex/understand-anything/understand-anything-plugin (which is already in the fallback chain) adds another lifeline.

What I could verify (and what I couldn't)

I'm developing on macOS, so I cannot reproduce the Windows + Codex symptom directly. What I did verify:

• install.ps1 parses as valid PowerShell (manual review — pwsh is not installed on this machine). The new Link-Extra-Plugin-Root helper uses standard Test-Path / Split-Path / New-Item calls and reuses the existing Remove-Reparse for uninstall. The $cfg.Contains('ExtraPluginLink') -and $cfg.ExtraPluginLink guard is short-circuited so the .ExtraPluginLink access never runs when the key is missing.
• All agents/<name>.md references in dispatch context were updated; only two intentional doc cross-references remain (auto-update-prompt.md:40 describes "same semantics as Step 2.5 in agents/project-scanner.md" and extract-import-map.mjs:11 is a comment about prior prose docs) — neither is a dispatch path.
• pnpm lint is clean.
• No version bump (per the PR template — internal/install-fix, no user-visible behavior change in the dashboard or skill output).

What I cannot verify from macOS:

• Whether the SKILL.md change alone is enough on Windows + Codex.
• Whether the new vendor-specific junction actually gets picked up by Codex on Windows.

Asking the reporter (and any Windows Codex users): please re-run the installer (iwr -useb https://raw.githubusercontent.com/tirth8205/Understand-Anything/fix/windows-codex-agents-path/install.ps1 | iex, then ./install.ps1 codex), verify that the new junction at ~/.codex/understand-anything/understand-anything-plugin exists, then run $understand-anything:understand --language en --full and confirm the agent definitions load without specifying the full path.

Linked issue

• Closes [Windows] Codex fails to locate agents under ~/.understand-anything-plugin/agents/ unless full path is specified #340

How I tested this

• pnpm lint (clean)
• Diff review of all agents/<name>.md references — every dispatch now uses $PLUGIN_ROOT/agents/<name>.md
• Manual PowerShell review of install.ps1 (no pwsh available locally to parse)
• Needs Windows verification — reporter, please confirm

Versioning

• Version bumped in all five manifests, OR
• N/A — internal/docs-only change

🤖 Generated with Claude Code