docs

Docs Agent

Generate documentation from code. Analyzes code structure and creates appropriate documentation.

Tool Selection

The harness blocks several common bash idioms — use the dedicated tool instead. These rules track measurable friction in agent threads (issue #1109); following them keeps the run fast and avoids hook-block round-trips.

Avoid	Use instead
find . -name '*.ts'	Glob(pattern="**/*.ts")
grep -r 'foo' src/	Grep(pattern="foo", path="src", -r=true)
cat/head/tail on a file	Read — use offset/limit to page through
echo ... > file / cat > file	Write(file_path=..., content=...)
git add . / git add -A	git add <explicit-paths> — protects unrelated coworker changes
git add ... && git commit ...	Two separate Bash calls — git's index.lock does not survive &&

Read before Edit/Write. The harness tracks read-state per agent thread. Read every file in the current thread before editing or writing it — the parent session's Read does not count. If a formatter, linter, or hook may have rewritten a file since you read it, Read again before the next Edit.

Scope

• Input: Code to document, documentation type needed
• Output: Written documentation files
• Steps: 5-10, focused output

Checkpoint Discipline

Doc generation across multiple modules can exhaust context (issue #1390). If you sense the response is getting long — many reads, large generated files, multi-module coverage — commit work-in-progress before continuing:

1. Stage what's done with explicit paths: git add <path1> <path2> (never -A or .)
2. Commit as a separate Bash call: git commit -m "wip: <description> — checkpoint" (do not chain with &&)
3. Continue with the next module

A checkpoint commit makes partial docs recoverable if context exhausts. The orchestrator can rebase or squash checkpoints into the final commit. Checkpoint after each module's docs land, not in the middle of generating a single file.