fix(docs): convert cross-tree hand-written links to GitHub source (#2113) - #2119
Merged
Conversation
scripts/assemble-docs.sh copies only each plugin's docs/ directory into the published MkDocs site, never skills/, agents/, commands/, knowledge/, hooks/, or scripts/. 9 hand-written docs pages under plugins/dev-team/docs/ linked into those un-copied directories with relative ../<dir>/... paths that resolve in a repo checkout (and pass the repo-tree-scoped lychee check) but 404 once deployed. Same root cause and fix as #2103's generated skills.md catalog: link to the file's GitHub source instead. Converted all 133 real cross-tree links across agent_info.md, test-evaluation.md, triage-workflow.md, code-review-process.md, developer-notes.md, workflows.md, agent-architecture.md, context-management.md, and test-improve.md. Left one template placeholder (../skills/{file}.md inside a fenced code example in agent_info.md) untouched -- it's illustrative prose, not a real link. Fixes #2113 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01URnco7Z5bKfKBMdNiZGQL4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
plugins/dev-team/docs/linked intoskills/,agents/,commands/,knowledge/,hooks/, andscripts/via relative../<dir>/...paths.scripts/assemble-docs.shnever copies those directories into the published MkDocs site (_mkdocs_src) — only each plugin's owndocs/— so every one of those links resolves in a repo checkout but 404s on https://devteam.bryanfinster.com/. Same root cause and fix as docs: Links to skills on https://devteam.bryanfinster.com/plugins/dev-team/docs/skills/ lead to 404 #2103's generatedskills.mdcatalog.agent_info.md,test-evaluation.md,triage-workflow.md,code-review-process.md,developer-notes.md,workflows.md,agent-architecture.md,context-management.md,test-improve.md) to GitHub source links. Left one template placeholder (../skills/{file}.mdinside a fenced code example inagent_info.md) untouched.Not included in this PR — blocked on permissions
Issue #2113 also asks to close the CI gap:
link-check.yml'snav-integrityjob already runsmkdocs buildagainst the assembled site, so a small advisory step there (never blocking — a first local run found 60 more pre-existing broken links/anchors spanning many other files, filed as #2118, so hard-failing today would deadlock every unrelated PR) would report the count. I prepared and verified this change locally, but this session's git/API credentials lack theworkflowOAuth scope needed to push a.github/workflows/*.ymlchange (bothgit pushand the GitHub API content-write calls were rejected/failed for that reason). The exact diff is ready — happy to apply it once givenworkflowscope, or a maintainer can paste it in directly. The change is a single new step appended to the existingnav-integrityjob in.github/workflows/link-check.yml; ask and I'll paste the full file content again here.Test Plan
python3 scripts/check_md_references.py— cleanpython3 -m pytest plugins/dev-team/tests tests/repo tests/agents tests/commands tests/docs tests/knowledge tests/stack_aware tests/skills tests/scripts tests/hooks -q -n auto --dist loadgroup— 10,359 passed, 0 failedscripts/ci-local.sh(full local CI mirror, run bypre-push) — all checks greenCloses #2113
🤖 Generated with Claude Code
Generated by Claude Code