agent-docs-maintainer

name	agent-docs-maintainer
description	Audit, clean, and rewrite CLAUDE.md / AGENTS.md / agent instruction templates so they stay compact, current, and routing-oriented instead of becoming dumped CLI manuals. Use whenever the user asks to update CLAUDE.md or AGENTS.md, clean bloated agent docs, align agent prompts with current project structure, create project agent guide templates, or fix stale xtrm/beads/specialists/GitNexus guidance.
disable-model-invocation	true

Agent Docs Maintainer

Keep agent-facing project docs small, accurate, and useful at session start. CLAUDE.md, AGENTS.md, and .xtrm/config/instructions/*.md are routing documents, not manuals.

Core principle

A good agent guide answers:

1. What project am I in?
2. What rules must I not violate?
3. Which skill or CLI help should I load for deeper workflow details?
4. Which files and services matter for this repo?
5. What is current and non-obvious?

It should not include full command manuals, long historical notes, code tutorials, or copied documentation that belongs in a skill, README, service runbook, or CLI --help.

Workflow

1. Audit before editing

Run the bundled audit script from the repo root or against explicit repos:

python3 .xtrm/skills/default/agent-docs-maintainer/scripts/audit_agent_docs.py . --format md
python3 .xtrm/skills/default/agent-docs-maintainer/scripts/audit_agent_docs.py <repo-a> <repo-b> --format json

If the skill is not installed in the target repo, run the script from its source path and pass repo paths explicitly.

The audit highlights:

• repo-identity presence before managed workflow boilerplate
• split size budget: repo-identity prose vs routing/managed boilerplate
• line/character counts
• code fence and table density
• likely CLI manual dumps, excluding concise operational-entry sections
• managed xtrm/GitNexus/beads blocks
• stale project-name hints, including per-repo .xtrm/agent-docs.toml extensions
• service registry presence
• rewrite recommendations

2. Check repo identity first

Before trimming anything, ask whether a fresh agent can learn what the repo is from the first 20-30 lines.

Good agent docs start with a short project summary or a substantive Stack Overview / Repo Identity section before managed xtrm:start, GitNexus, or beads blocks. If the file opens with generic managed workflow boilerplate, add repo identity instead of reporting it as clean.

Use references/stack-overview-template.md when the repo needs more than a 2-5 line summary. A 100-150 line current stack overview can be correct when it explains role, services, public surface, sibling stacks, entry points, data flow, and what belongs elsewhere.

3. Classify content

Keep only session-critical guidance in agent docs.

Keep in agent docs	Move or replace with pointer
5-line project summary	release history, old roadmap sections
non-negotiable rules	full bd, xt, sp, gitnexus command references
runtime-local task planning policy	long CLI tables and copied help text
skill routing table	copied project wiki/tutorial content
compact project map	code examples, SQL snippets, migration tutorials
active gotchas, max 10	stale warnings, completed fixes, archaeology
canonical service-skills routing for docs/project/service context	full service registry dumps

4. Keep a tiny essential command surface

Do not remove every command. Keep the commands an agent needs to safely start, inspect, claim, delegate, validate, and close work without loading another manual.

Good essentials include:

• Whether runtime-local task planning is required before proceeding on non-trivial/multi-step work, and the rule that it must be used alongside normal beads operations while beads remains authoritative.
• bd ready, bd list --status=in_progress, bd show <id>, bd update <id> --claim, memory ack + bd close.
• sp --help, sp list, sp ps, sp feed <job-id>, sp result <job-id> when specialists are part of the repo workflow.
• Mandatory GitNexus tool calls such as gitnexus_impact(...) before symbol edits and gitnexus_detect_changes(...) before commit.
• Project validation commands such as build, targeted tests, registry/policy generation.

5. Prefer pointers over manuals

Use pointers like these instead of copying full command references:

For beads commands, run `bd --help` or `bd <cmd> --help`.
For xtrm workflow details, load `/using-xtrm`.
For specialist orchestration, load the latest available `/using-specialists-*` skill, preferring `/using-specialists` when present.
For GitNexus debugging/refactor/impact workflows, load the matching `/gitnexus-*` skill.

6. Separate runtime-specific docs

CLAUDE.md may include Claude Code specifics:

• GitNexus MCP requirements
• Claude hook behavior
• Claude-only skill invocation notes
• canonical service-skills routing for project/service context

AGENTS.md should stay runtime-neutral or Pi-friendly:

• xtrm workflow summary
• Pi/process extension notes when relevant
• no Claude-only tool assumptions
• pointers to skills/CLI help for details

7. Preserve managed blocks carefully

Before rewriting, identify managed blocks:

<!-- xtrm:start --> ... <!-- xtrm:end -->
<!-- gitnexus:start --> ... <!-- gitnexus:end -->
<!-- BEGIN BEADS INTEGRATION --> ...

If a block is generated by xtrm, do not treat edits to generated CLAUDE.md / AGENTS.md blocks as durable. Update the canonical xtrm instruction templates for the current installation/package, then run xt update --apply to regenerate project copies. The exact template source location depends on installation mode, so avoid hard-coding machine-specific paths in user-facing docs. The GitNexus block is regenerated separately by GitNexus hooks, so do not treat local edits to that block as durable.

8. Rewrite to the compact template

Use the templates in references/:

• references/claude-template.md for Claude Code
• references/agents-template.md for generic/Pi agent docs
• references/audit-rules.md for scoring and rewrite rules

Target size:

• preferred: 150-300 lines
• soft maximum: 500 lines
• any doc above 500 lines should be treated as bloated unless there is a project-specific reason

9. Validate after editing

Run the audit again and check:

• no duplicated managed blocks
• no long command reference tables
• no stale project names
• no code fence count explosion
• skill references point to installed skills or clearly say “latest available”
• CLAUDE.md and AGENTS.md are intentionally different when both exist

Rewrite checklist

Before finishing, verify:

• The first 30 lines explain the project and critical rules.
• If the runtime supports local task planning, the doc requires it before proceeding on non-trivial/multi-step work and says how to use it alongside normal beads operations without replacing beads.
• Full command references are replaced by a tiny essential command surface plus --help or skill pointers.
• Specialist guidance points to latest /using-specialists-*, preferring v3.
• Service skills are mentioned if .claude/service-registry.json or service skills exist.
• Project map has only key directories/files.
• Gotchas are current and limited to the top 5-10.
• Historical material moved to README, docs, reports, or changelog.
• File is under the agreed line budget or has a documented exception.

Common transformations

Beads dump → compact routing

## Issue tracking
Run `bd prime` at session start, claim with `bd update <id> --claim` before edits, and close with a memory ack before committing. Use `bd --help` for full command syntax and `/using-xtrm` for workflow details.

Specialists dump → skill pointer

## Specialists
For substantial implementation, review, debugging, test generation, or orchestration, load the latest available `/using-specialists-*` skill. Prefer `/using-specialists` when present. Check `sp --help` and `sp list` / `specialists list` before choosing a role.

Service wiki → service-skill routing

## Services
This repo has service-specific operational knowledge. Use `/scope "<task>"` or load `/using-service-skills` for service/documentation/project context before touching service code. Keep detailed runbooks in the canonical service-skills skill set or docs, not in this always-loaded guide.