Skip to content

fix(docs): convert cross-tree hand-written links to GitHub source (#2113) - #2119

Merged
bdfinst merged 1 commit into
mainfrom
claude/dev-team-setup-ly5u4w
Sep 4, 2026
Merged

fix(docs): convert cross-tree hand-written links to GitHub source (#2113)#2119
bdfinst merged 1 commit into
mainfrom
claude/dev-team-setup-ly5u4w

Conversation

@bdfinst

@bdfinst bdfinst commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Summary

  • 9 hand-written docs pages under plugins/dev-team/docs/ linked into skills/, agents/, commands/, knowledge/, hooks/, and scripts/ via relative ../<dir>/... paths. scripts/assemble-docs.sh never copies those directories into the published MkDocs site (_mkdocs_src) — only each plugin's own docs/ — 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 generated skills.md catalog.
  • Converted all 133 real cross-tree links (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}.md inside a fenced code example in agent_info.md) untouched.

Not included in this PR — blocked on permissions

Issue #2113 also asks to close the CI gap: link-check.yml's nav-integrity job already runs mkdocs build against 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 the workflow OAuth scope needed to push a .github/workflows/*.yml change (both git push and the GitHub API content-write calls were rejected/failed for that reason). The exact diff is ready — happy to apply it once given workflow scope, or a maintainer can paste it in directly. The change is a single new step appended to the existing nav-integrity job 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 — clean
  • Full local suite: python3 -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 failed
  • scripts/ci-local.sh (full local CI mirror, run by pre-push) — all checks green
  • Verified no cross-tree relative links remain in the 9 files (only the intentional code-block placeholder)

Closes #2113

🤖 Generated with Claude Code


Generated by Claude Code

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
@bdfinst
bdfinst enabled auto-merge (squash) September 4, 2026 16:16
@bdfinst
bdfinst merged commit e453828 into main Sep 4, 2026
15 checks passed
@bdfinst
bdfinst deleted the claude/dev-team-setup-ly5u4w branch September 4, 2026 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: hand-written docs pages have ~134 more cross-tree links that 404 on the published site

2 participants