engineering-docs-agent
A Claude Code plugin: nightly docs-PR generator with publish verification and tiered content linting.
What it does
- Watches a host repo's Git/PRs/Jira for changes since the last successful run.
- Opens a PR against the host's docs site with:
- What's New entry summarizing changes.
- Updated/new pages authored by a
page-author subagent with voice few-shot.
- Gap flags for non-trivial PRs that have no spec/plan.
- Sends a Slack + email digest.
- After the PR merges, verifies the host's build pipeline succeeded and pages are live.
Install
claude plugin marketplace add <this-repo> — register the marketplace from the local path or remote URL.claude plugin install engineering-docs-agent@engineering-docs-agent-marketplace — install the plugin.claude /engineering-docs-agent-setup — run the setup skill from your host repo's root.
For the comprehensive walkthrough (GitHub App registration, all repo secrets, branch protection, validation, per-language host notes, troubleshooting for every partial-mode failure), see docs/site-src/setup-guide.md. The same content is published on the docs site at setup-guide.html.
Self-hosting (dogfood)
This repo is configured to run the agent against itself — a reference layout for new host repos:
.engineering-docs-agent/config.yml — host config (framework, paths, Jira project keys, voice samples, publishing target)..engineering-docs-agent/state.json — committed state. last_successful_run.head_sha is the source of truth for the next nightly's window. Each merged docs-agent/YYYY-MM-DD PR advances it via normal git merge — no separate promote workflow..engineering-docs-agent/state.example.json — seed template for fresh host repos. This dogfood host already has a real state.json; the example file is preserved for plugin users installing into a new repo..engineering-docs-agent/current_run.json — gitignored ephemeral run state, written every state-update for diagnostics + test observability. Not part of the docs-agent PR.docs/site-src/ — agent-editable area and MkDocs source dir; the agent_editable_paths glob (docs/site-src/**) restricts writes here, and the same tree publishes to GitHub Pages.
Run the agent locally against this host:
python3 scripts/orchestrator_runner.py --repo-root . --no-pr
For per-subagent raw-stdout diagnostics, set DOCS_AGENT_DEBUG_DIR=/tmp/cce-debug before invoking.
Publish-verification is configured against a deploy.yml GitHub Actions workflow that is not yet committed; the --no-pr flag above keeps the bootstrap dry-run only. Wiring up the workflow + end-to-end publish path is tracked separately.
Nightly authoring run
The main authoring pipeline (scripts/orchestrator_runner.py with no subcommand) runs automatically once daily at 07:00 UTC via .github/workflows/docs-agent-nightly.yml. The workflow opens or append-commits to a docs-agent/YYYY-MM-DD PR; per spec §8, a partial run still opens the PR with partial: true in the body so an operational gap is visible, not silent.
To fire it manually:
gh workflow run docs-agent-nightly.yml -f reason="<your reason>"
gh run watch
The reason input is a free-text label surfaced in the run summary alongside the post-run state.json snapshot. Auth is via the CLAUDE_CODE_OAUTH_TOKEN repo secret (same secret as release.yml). One run at a time per repo — concurrent invocations queue rather than race on the same docs-agent branch.
Install from local clone
If you're working from a checkout of this repo (e.g., to test changes before publishing), register the local marketplace and install the plugin:
claude plugin marketplace add /path/to/engineering-docs-agent
claude plugin install engineering-docs-agent@engineering-docs-agent-marketplace
That makes the eight agents resolvable without --plugin-dir workarounds. The marketplace registration reads .claude-plugin/marketplace.json; the plugin manifest is at .claude-plugin/plugin.json.
Lens paths and editable paths
The agent reads from lens paths and writes to editable paths. They overlap, but they are different:
docs.lens_paths defines where docs live for each lens (e.g., core: docs/site-src/). The voice-load, gap-detection, and PR-summarization stages read from these paths.docs.agent_editable_paths defines where the agent may write. The orchestrator's runtime filter rejects any proposed page outside these globs.
Invariant: every lens_paths entry must be covered by at least one agent_editable_paths glob. The config loader enforces this at boot via _validate_lens_paths_are_editable in scripts/state_io.py. A lens with no matching editable glob means the agent reads docs it can never update — usually a mistake.
