codehub-document

Primary artifact generator. Applies the proven four-phase /document pattern to OpenCodeHub’s graph and extends it with first-class group mode.

Writes a tree of cross-linked Markdown under .codehub/docs/ (single-repo) or .codehub/groups/<name>/docs/ (group mode) plus a .docmeta.json sidecar that drives --refresh.

Frontmatter

name: codehub-document
argument-hint: "[output-dir] [--group <name>] [--committed] [--refresh] [--section <name>]"
color: indigo
model: sonnet

Preconditions

mcp__opencodehub__list_repos returns the target. Otherwise: run codehub analyze.
codehub status reports fresh. Otherwise: run codehub analyze.
Group mode only: every member repo must be fresh per mcp__opencodehub__group_status. Stale members abort with named repos.

Four-phase orchestration

Inline, no subagent. Writes two shared-context files on disk:

<docs-root>/.context.md (hard 200-line cap) — repo profile, top communities, top processes, routes, MCP tools, owners summary, staleness envelope. Group mode adds the manifest + contracts matrix + freshness table.
<docs-root>/.prefetch.md — newline-delimited JSON ledger of tool calls with {tool, args, sha256, keys, cached_at, truncated}. Subagents read this instead of re-calling tools.

Prompt dedup via filesystem, not copy-paste.

Four subagents dispatched in a single message:

doc-architecture → architecture/{system-overview,module-map,data-flow}.md
doc-reference → reference/{public-api,cli,mcp-tools}.md
doc-behavior → behavior/{processes,state-machines}.md
doc-analysis → analysis/{risk-hotspots,ownership,dead-code}.md

In group mode, fan-out multiplies by member count (4 × N subagents). Claude Code’s concurrent-Agent ceiling is ~10 per message — groups of 3+ repos batch by role.

Two subagents in parallel:

doc-diagrams → diagrams/{architecture,behavioral,structural}/*.md
doc-cross-repo → cross-repo/{portfolio-map,contracts-matrix,dependency-flow}.md (group mode only)

Skipped silently in single-repo mode.

Deterministic Markdown assembly. No LLM call.

Regex over backtick path:LOC (or repo:path:LOC) citations.
Build co-occurrence index: source_file → [docs_citing_it].
For any two docs sharing ≥ 2 common sources, append ## See also footers.
In group mode: add ## See also (other repos in group) to every cross-repo/*.md.
Write README.md (landing page with determinism disclaimer) + .docmeta.json.

Same inputs, same output. See .docmeta.json schema.

Arguments

Flag	Meaning
`[output-dir]`	Where to write. Default `.codehub/docs/` (gitignored). With `--committed`, default flips to `docs/codehub/`.
`--group <name>`	Enable group mode. Phase 0 calls `group_list` + `group_status` + `group_contracts` + `group_query`. Phase CD dispatches `doc-cross-repo`.
`--committed`	Write to a committed path instead of `.codehub/docs/`. Does not touch `.gitignore`.
`--refresh`	Regenerate only sections whose `sources[]` mtimes are newer than the section’s `mtime`. Phase E always re-runs.
`--section <name>`	Regenerate one named section (e.g., `architecture/system-overview`).

Invocation examples

# Single-repo, default gitignored output
/codehub-document

# Group mode with an explicit output
/codehub-document docs/platform --group platform --committed

# Refresh stale sections only
/codehub-document --refresh

# One-section regenerate
/codehub-document --section architecture/system-overview

Output contract

See ADR 0009 for the full contract.

No YAML frontmatter on outputs.
Every factual claim carries a backtick path:LOC citation (or repo:path:LOC in group mode).
Mermaid diagrams only (no SVG/PNG).
.docmeta.json is the source of truth for --refresh and staleness.