Repository navigation
🐛🧑💻 - bug generated agent guidance links to documentation missing in target repositories #539
Description
Is there an existing issue for this?
- I have searched the existing issues.
Which actions are affected?
No response
Which platforms are affected?
No response
Description
Installing Copilot in a repository other than vypdev/copilot generates .copilot/AGENT_GUIDE.md with relative links to ../docs/agents/repository-collaboration.mdx and ../docs/agents/repository-guidance-troubleshooting.mdx. Those files exist in the Copilot source repository but are not installed in the target, so the guide sends contributors to missing local files / GitHub 404s. This is reproduced in vypdev/platform after platform setup PR #166.
Expected: links to shared Copilot documentation resolve to centrally maintained documentation independently of the destination repository; links to installed local artifacts such as ./repository-profile.json remain local.
Recommended fix: use absolute HTTPS links to the documentation in vypdev/copilot, with one canonical version/ref policy, and keep user/project-specific guidance local. The existing source pages are verified at https://github.com/vypdev/copilot/blob/master/docs/agents/repository-collaboration.mdx and https://github.com/vypdev/copilot/blob/master/docs/agents/repository-guidance-troubleshooting.mdx. Audit generated guide/skill/pointer references for the same portability issue.
Keep this bounded bug separate from organization reuse and multi-repository setup issue #538. Copying the whole docs tree into every target would add upgrade/drift ownership and is not the preferred solution.
Reproducing the issue
- Install Copilot with repository agent guidance enabled in a clean target repository without the Copilot docs tree (for example vypdev/platform).
- Open .copilot/AGENT_GUIDE.md and follow its last two documentation links.
- Resolve them relative to .copilot/: the target paths are docs/agents/repository-collaboration.mdx and docs/agents/repository-guidance-troubleshooting.mdx, which setup does not install. GitHub returns 404.
- Compare the same guide in vypdev/copilot, where the files happen to exist and conceal the portability defect.
Acceptance: fresh target installations use canonical absolute documentation URLs; all relative Markdown links in generated guidance resolve to artifacts actually installed in that target; repeated setup upgrades hash-owned old guidance and its manifest safely; edited/unowned guidance is preserved with the normal conflict report; checked-in guidance and packaged CLI/Action outputs match the generator. Add focused regression coverage, refresh related guidance docs/SDD/catalog evidence, and run the existing documentation/package/contract gates.
copilot Version
3.5.5; platform setup at 5554e78a6211decb9a658640af9e07771ab9582e
Relevant Log Output
Generated in .copilot/AGENT_GUIDE.md:
[repository collaboration](../docs/agents/repository-collaboration.mdx)
[guidance troubleshooting](../docs/agents/repository-guidance-troubleshooting.mdx)Additional context and comments
User-reported during Copilot setup dogfooding. The actual generated directory is .copilot (the report mentioned .compilot). Generator: src/application/policies/repository_agent_guidance_policy.ts, renderRepositoryAgentGuide. Reconciliation/ownership: src/utils/repository_agent_guidance.ts. Relevant capability: repository-agent-collaboration; SDD: specs/repository-agent-collaboration-contract.md. No documentation copies or configurable arbitrary documentation hosts are needed for this correction.
Metadata
Metadata
Assignees
Labels
Type
Projects
- Status
Activity
[-]bug: generated agent guidance links to documentation missing in target repositories[/-][+]🐛 - bug generated agent guidance links to documentation missing in target repositories[/+]vypbot commentedon Oct 17, 2026
Hi! I’m @vypbot, the Copilot assistant for this repository.
I can answer questions, explain the codebase, propose implementation and test plans, review issues and pull requests for potential bugs or security problems, and help authorized maintainers apply changes.
Try
/copilot helpto see the available commands, or mention @vypbot with your question.[-]🐛 - bug generated agent guidance links to documentation missing in target repositories[/-][+]🐛🧑💻 - bug generated agent guidance links to documentation missing in target repositories[/+]3 remaining items
vypbot commentedon Oct 17, 2026
Implementation plan
Acceptance: A fresh installation into a target without the Copilot docs tree emits canonical absolute HTTPS links to both shared documentation pages, and every relative Markdown link in generated guidance resolves to an installed artifact; regression coverage confirms safe ownership reconciliation, conflict preservation, and generator-to-package parity.
Need something else? Mention the bot with a question or use
/copilot help.vypbot commentedon Oct 17, 2026
Issue closed — historical progress
Current status: closed as completed.
The last estimate is retained below as history. Closure does not certify a new percentage, tests, or branch alignment.
Action required: none for this closed issue. If work continues, reopen the issue; a fresh assessment can update this same card.
Last assessment before closure (historical)
Merge pull request #540 from vypdev/bugfix/539-bug-generated-agent-gu…
vypbot commentedon Oct 17, 2026
Issue closed: synchronization recommendation retired
No branch synchronization is required for this closed issue.
The previous recommendation is historical. Issue closure does not certify that the branches are synchronized.