Restructure docs around case studies and patterns - #84
Merged
Merged
Conversation
The site described a Goose-first, single-guide world that no longer matches what these repositories do. Rebuild it around the repositories themselves. New: - docs/case-studies/: one page per repository running agents on real curation. Ontologies (GO, Uberon, Mondo, Cell Ontology, EFO) and the mechs (DisMech, AI Gene Review, CommunityMech, HabitatMech and the CultureBot family). - docs/patterns/: nine practices that appear in more than one repository, each linking to the repositories that use it. - docs/evidence.md: where the skill, subagent and workflow counts come from. - docs/tutorials/first-curation-session.md: a cloud-first first session, replacing the Goose, OWL-MCP and Protege walkthrough. - docs/reference/harnesses.md: replaces six client stub pages. Changed: - Goose is now documented as historic throughout. It stays described because it is still deployed, but it is no longer recommended for new setups. - Canonical site URL is now ai4curation.io/aidocs, matching the CNAME. - CLAUDE.md is a pointer to AGENTS.md, so this repository follows the one-source-of-instructions pattern it documents. - set-up-github-actions.md leads with Claude Code Action; the dragon-ai-agent and Goose route moves to a historic section. - author-skills.md no longer ends in a TODO, and its skill counts are current. Removed: - Six client comparison stubs, examples.md, and the Goose tutorial. Their content is covered by the case studies and the harnesses page. Infrastructure: - mkdocs build is now --strict in deploy, and a new docs-checks workflow runs the strict build plus a link check on pull requests and weekly. Outbound links to other repositories are the main thing that rots here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017tKFksxqHZJNLoH1zJ5WXm
Contributor
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
The link check on the previous commit found 11 errors out of 456 links. All of them were real except the bot-blocked hosts. Genuine mistakes in the new pages: - HabitatMech's term requests page is at pages/term-requests.html. The link in HabitatMech's own README is missing the pages/ segment and 404s. - geneontology/go-jupyter is not a public repository. Describe the shared JupyterHub setup without linking to it, in three places. Pre-existing errors the check surfaced: - owl-mcp is ai4curation/owl-mcp, not monarch-initiative/owl-mcp. - dismech renamed stale-pr-reassign.yml to pr-shepherd.yml. Excluded from the check: claude.ai and learn.deeplearning.ai return 403 to automated requests. Both links are correct in a browser. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017tKFksxqHZJNLoH1zJ5WXm
Contributor
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
"Agent" was covering three different things: the software, the subagent, and the GitHub identity work appears under. Split off the last one and call it a bot, which is the word GitHub already puts in the byline (ai4c-agent[bot]). The frame: the agent is the software that does the work, the bot is the identity it works under, and one agent can work under different bots in different repositories. New docs/reference/bots.md covers: - The bots in use: ai4c-agent, ai4c-reviewer, claude, copilot-swe-agent, github-actions, dragon-ai-agent. - GitHub Apps versus machine accounts, and why Apps are preferable for new setups: per-run tokens, per-repository permissions, no seat. - Why DisMech runs two of its own. GitHub does not let an identity approve its own pull request, so ai4c-agent writes and ai4c-reviewer supplies the approving review that branch protection requires. Without that split, every agent pull request would need a human approval. - Setting the commit author so App commits attribute correctly. - Reading a byline to work out what produced a change. Corrected elsewhere: dragon-ai-agent is semi-retired, not simply "still running". Mondo still runs the machine account on a PAT; DisMech retired the account and keeps @dragon-ai-agent as a trigger keyword only, with the work done by the ai4c-agent App. The same mention means different things in the two repositories, which is worth knowing when reading old issue threads. Updated: harnesses.md, github-integrations.md, the DisMech and Mondo case studies, the untrusted-surface pattern, glossary, and nav. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017tKFksxqHZJNLoH1zJ5WXm
Contributor
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
Restructure docs/reference/bots.md into docs/reference/bots/ with an overview plus one page per bot: ai4c-agent, ai4c-reviewer, claude, copilot-swe-agent, dragon-ai-agent. Drop the "bots you will meet" heading. Corrected: GO runs both ai4c-agent and ai4c-reviewer. The previous version listed them for DisMech and AI Gene Review only. GO's two agent workflows turn out to be the best-documented examples of this setup anywhere in these repositories, and their header comments supply several things worth writing down: - A GitHub App cannot be @-mentioned. "@ai4c-agent" renders as plain text, so every bot mention is really a trigger keyword that a workflow matches against comment text. This generalises the dragon-ai-agent case rather than being an exception to it, and it means a keyword can be migrated without touching the identity. GO honours @dragon-ai-agent as a legacy handle during that move. - An App has two different numbers. The app id mints the token; the bot account's user id is what commit attribution needs. Using the wrong one silently unlinks commits from the App. - Review actions skip bot-authored pull requests by default, so the editing bot has to be named in allowed_bots or the highest-value reviews never happen. - GO keeps the review rubric in the pr-review skill rather than the workflow prompt, so humans and bots apply the same criteria. - Authorized triggerers are listed in .github/ai-controllers.json. Also updated the GO case study, which had described the two workflows without naming the identities they run as. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017tKFksxqHZJNLoH1zJ5WXm
Contributor
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
The link check failed on one link out of 506: the DRAGON-AI paper at pubmed.ncbi.nlm.nih.gov/39415214/. PubMed answers automated clients with 203 Non-Authoritative Information rather than 200, so lychee rejected it. Verified the link is correct through the NCBI esummary API: PMID 39415214 is Toro S et al., "Dynamic Retrieval Augmented Generation of Ontologies using Artificial Intelligence (DRAGON-AI)", J Biomed Semantics 15, 2024. The fix belongs in the checker, not the citation. 203 is a success code, so accept it generally rather than excluding PubMed. Any future PubMed citation on this site would hit the same thing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017tKFksxqHZJNLoH1zJ5WXm
Contributor
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
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
2 participants
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.
This PR reorganizes the documentation to center on real working repositories rather than abstract how-tos. The new structure makes it easier for curators to find and copy working setups.
Key changes
Added case studies section with pages for 9 repositories (GO, Uberon, Mondo, Cell Ontology, EFO, DisMech, AI Gene Review, CommunityMech, HabitatMech) that run agents on real curation work. Each page points to the actual files and folders to copy.
Added patterns section with 10 short pages describing practices that appear in multiple repositories (skills, scanners, validation, guards, etc.). Each pattern names the repositories that use it.
Simplified how-tos by removing the detailed GitHub Actions setup guide and replacing it with a pointer to Claude Code's built-in
install-github-appcommand.Added "Your first curation session" tutorial for non-technical curators to try an agent in the cloud without installing anything.
Rewrote home page to emphasize that agents are already working in real repositories, and this site points at those repositories so you can copy working setups.
Added Evidence page documenting where the observations on the site come from (agent-watcher reports).
Updated CLAUDE.md to point to AGENTS.md as the authoritative guidance file.
Removed outdated content: deleted the "Using local AI tools" tutorial, the "Examples" page, and individual client app reference pages that duplicated information.
Updated mkdocs.yml navigation to reflect the new structure with case studies and patterns as top-level sections.
The documentation now follows the principle stated in the repository: repositories are the source of truth, not centralized guidance. If a page disagrees with a repository, readers are directed to trust the repository.
https://claude.ai/code/session_017tKFksxqHZJNLoH1zJ5WXm