Doc Bridge Pattern

AgentHandoff for your monorepo — deterministic routing so agents edit the right roots, run the right checks, and stay linked to human documentation.

Published pattern for Agents Playbook. Export with:

ak-docs playbook pattern --text
ak-docs playbook pattern --json

Problem

Coding agents guess package ownership. They edit sibling modules, run repo-wide tests, and ship changes without a bridge to human-facing guides. Wikis and RAG explain concepts but weakly answer where to act.

Solution (three artifacts)

Artifact	Role
AgentHandoff	JSON handoff: `startHere`, `editRoots`, `checks`, `humanDoc`, `bridge`
DocBridgeIndex	Deterministic index + `contentHash` for CI freshness gates
Self-describe	`llms.txt`, `capabilities.json` for discovery

Four loops

Loop	Command	Outcome
Act	`ak-docs query package <id> --agent`	Agent edits only `editRoots`
Bridge	`ak-docs bootstrap agent-docs`	Link agent corpus ↔ human site
Learn	`ak-docs memory promote --pr`	HITL draft PR from agent memory
Explain	`ak-docs ask "<question>"`	Local consult + handoff preview

60-second proof

npm i -D @agentskit/doc-bridge
npx ak-docs demo --text
ak-docs mcp install --cursor

AgentHandoff example

{
  "type": "agent-handoff",
  "startHere": "docs/for-agents/packages/auth.md",
  "editRoots": ["packages/auth"],
  "checks": ["pnpm --filter @demo/auth test"],
  "humanDoc": "/docs/guides/auth",
  "bridge": { "humanDoc": "linked" }
}

When humanDoc is missing, handoffs surface bridge.action: "ak-docs bootstrap agent-docs" — a feature, not a silent gap.

MCP contract

Agents call handoff.resolve before editing packages/*:

Read startHere
Stay inside editRoots
Run every checks command
Link humanDoc or escalate missing bridge

CI gate

- uses: AgentsKit-io/doc-bridge@v1.2.1

Or: ak-docs index && ak-docs gate run — stale index fails the PR.

Coverage metric

ak-docs doctor --text
ak-docs doctor --badge

Teams track handoff % and human-bridge % daily.

When to use

pnpm/npm monorepos with real package ownership
Fumadocs / Docusaurus human sites + dense agent corpus
Cursor / Claude / Codex agents that should not guess edit roots

When not to use

Single-file repos with no ownership boundaries (AGENTS.md may suffice)
Hosted doc chat as primary product (doc-bridge is routing + bridge, not SaaS chat)

Promotion to Playbook

Review this file for secrets and private paths
Open PR to agents-playbook under content/docs/pillars/ai-collaboration/
Or run ak-docs memory promote --pr for memory-sourced findings

References

npm: https://www.npmjs.com/package/@agentskit/doc-bridge
repo: https://github.com/AgentsKit-io/doc-bridge
skill: doc-bridge skill
landing: https://doc-bridge.agentskit.io/