Review knowledge when code changes.
AgentDoc compares a pull request's exact base and head commits. It flags verified claims linked to changed code, reports paths without knowledge coverage, and names the role that needs to review a claim. The assessment makes no model calls and works without a Claude token.
- Changed path
- crates/auth/src/config.rs
- Affected verified claim
- auth.session.idle-timeout
- Reviewer of record
- check whether this claim still describes the changed code.
What reviewers see
The report appears in a pull request comment when GitHub permits comments. It also writes a job summary and annotations. A changed code link asks for human review; it does not mean the claim is wrong or that anyone has approved a replacement.
Reports can also show uncovered or excluded paths, structural diagnostics, and proposed updates. A report can be incomplete when assessment fails; this is reported as a failed check even in advisory mode.
Set it up
Add this file to .github/workflows/agentdoc.yml in a repo configured for AgentDoc. The example pins the published alpha and fetches the commits needed for the comparison.
name: AgentDoc
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
agentdoc:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false
- uses: agentdoc-dev/action@v2.0.0-alpha.22
# Optional. Without a token you still get the full report.
# Create one with "claude setup-token" and store it as a repo secret.
# with:
# claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
# Or use an Anthropic API key instead:
# anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
This uses v2.0.0-alpha.22. The workflow needs contents: read to assess the PR and pull-requests: write to post its comment. Without comment permission, the report remains in the job summary and annotations. Fork and Dependabot PRs receive that deterministic output; this workflow does not run the model or deliver drafts for them.
Need a first AgentDoc source? Start with one repository.
Optional Claude drafting
To enable drafts, run claude setup-token and save its token as the repository secret CLAUDE_CODE_OAUTH_TOKEN. Uncomment the with lines in the workflow. You can use anthropic-api-key with an Anthropic API key instead; that key takes precedence if both are set, so configure one.
With credentials, propose: true (the default) lets Claude Code draft claims for eligible changed paths. Without credentials, this stage skips and the deterministic report still runs. The default propose-delivery: comment shows draft patches for review; it does not change the PR branch.
What leaves the runner
When a model stage runs, selected exact-revision code diffs and Knowledge Object bodies go to Claude Code and Anthropic. The GitHub token is not sent to the model.
Provider handling depends on your Anthropic account. Before a patch is shown or delivered, AgentDoc checks and applies it, then runs adoc check and builds in a disposable worktree. A person still decides whether a draft is correct.
Defaults and opt-ins
Everything is advisory until you opt in. The last column says what can turn the check red.
| Setting | Default | What the opt-in changes | Can fail the check |
|---|---|---|---|
| enforcement | advisory | Reports structural errors without failing for them. Set strict to fail on errors in the selected scope. | Assessment and setup failures, even in advisory |
| sync-policy | advisory | Reports knowledge drift. Set required to keep the check red until the baseline is ready and any delivered knowledge PR is merged. | Only when required |
| propose-coverage | bounded | With semantic review off, reviews up to propose-max-paths: 10 uncovered changed paths. full reviews every non-excluded changed path within assessment limits and can draft updates to existing claims. | No |
| semantic-review | false | Set true for experimental cited review. This also allows model-assisted updates to existing claims and sends selected code and claim text to Claude. | No |
| propose-delivery | comment | Use commit to fast-forward the same-repo PR branch, or pr to open a draft follow-up PR. Both require explicit configuration and a valid draft. | No |
| propose-on-error | warn | Optional model-stage failures remain advisory. Set fail to make an explicitly requested model operation fail the check after the report is finalized. | Only when fail |
The Action never approves or merges a PR. See the pinned Action inputs (opens in a new tab) for the full configuration, or the CLI reference (opens in a new tab) for AgentDoc commands.