Document

Document

Generate a single documentation page from codebase exploration. Agents research the topic, orchestrator synthesizes findings into the doc directly. One file in docs/, diagrams in docs/diagrams/.

• [ ] Step 1: Parse topic + determine output path
• [ ] Step 2: Select 3-5 agents (topic-adaptive)
• [ ] Step 3: Spawn agents in parallel, wait for all
• [ ] Step 4: Synthesize and write doc directly
• [ ] Step 4b: Generate diagrams (if applicable)
• [ ] Step 5: Present and iterate
• [ ] Step 6: Update docs/MAP.md
• [ ] Step 7: Report

You receive a topic prompt, spawn exploration agents to map the codebase around that topic, then synthesize findings into a single documentation page styled after Claude Code's own docs (https://code.claude.com/docs/en/memory). You are the orchestrator — you spawn agents, collect output, present the result, and iterate with the user.

Hard rules:

• Never create a PR (gh pr create is forbidden)
• Never push to remote (git push is forbidden)
• No git operations beyond git status
• Read-only access to source files — no fixes, no edits to source code
• Diagrams must be generated from actual code analysis, never placeholders
• One doc file in docs/ per topic
• Diagrams go in docs/diagrams/ (shared across docs, .drawio source + .png exports)

Avoid:

• Generic descriptions ("the system does stuff") — be specific with paths and line numbers
• Skipping agent selection — always justify why each agent was picked
• Placeholder diagrams — every tree/box/table must reflect real code paths
• Forced template sections — let the topic dictate structure
• Asking scope/audience before the user has seen output — show first, ask after

Input

$ARGUMENTS is the topic prompt describing what to document.

If provided: use as $TOPIC directly.

If not provided: AskUserQuestion:

• "What should I document?"
• Let the user type a topic description

Store the answer as $TOPIC.

Process

Step 1: Parse Topic + Determine Output Path

Derive a URL-safe slug from $TOPIC:

• Take first 5-6 words
• Lowercase, replace spaces with hyphens, strip non-alphanumeric except hyphens
• Max 40 characters

Scan for existing docs:

ls docs/[0-9][0-9][0-9]-*.md 2>/dev/null

Collision check: if any existing doc contains the same slug (e.g., 001-how-hooks-work.md exists and slug is how-hooks-work), AskUserQuestion: "Existing doc 001-how-hooks-work.md covers this topic. Update it or create a new doc?" Options: "Update existing" (reuse path, overwrite) / "Create new" (next number).

If no collision: auto-increment to next number (starting from 001).

Set paths:

$DOC_PATH = docs/{NNN}-{slug}.md

mkdir -p docs docs/diagrams

Check for existing codebase context:

ls .claude/context/*.md 2>/dev/null

If .claude/context/ exists (from /orc:map), read relevant context files before selecting agents. This avoids redundant exploration — agents can focus on topic-specific depth rather than re-discovering structure and architecture.

| Topic involves | Read these context files | |---------------|------------------------| | System design, architecture | ARCHITECTURE.md, STRUCTURE.md, STACK.md | | Execution flows, data lifecycle | FLOWS.md, ARCHITECTURE.md | | Packages, dependencies | CODEMAP.md, STRUCTURE.md | | Boundaries, seams | BOUNDARIES.md, TYPES.md | | Gaps, security, debt | CONCERNS.md, TEST-QUALITY.md | | Design patterns | PATTERNS.md, CONVENTIONS.md | | Frontend, UI | UX-PATTERNS.md |

Step 2: Select 3-5 Agents (Topic-Adaptive)

Pick 3-5 agents from the pool based on what $TOPIC actually needs.

Selection rules:

1. Always include at least 1 Explore agent (codebase grounding is non-negotiable)
2. Pick 2-4 more from the pool based on topic fit
3. For each pick, state in one line why it's relevant

Agent pool:

| Agent (subagent_type) | Best for | |------------------------|----------| | Explore | Any topic — deep codebase search, call chain tracing | | orc:repo-research-analyst | Codebase structure, conventions, onboarding | | orc:codemap-generator | Dependency maps, call chains, module graphs | | orc:code-reviewer | Code quality, patterns, risks | | claude-code-guide | Claude Code features, tools, API, SDK, hooks, settings | | orc:security-reviewer | Auth, injection, OWASP, secrets | | orc:silent-failure-hunter | Error handling, empty catches, swallowed errors | | orc:test-analyzer | Test coverage gaps, behavioral coverage | | orc:pattern-recognition-specialist | Design patterns, anti-patterns, duplication | | orc:git-history-analyzer | Code evolution, why patterns exist | | orc:type-design-analyzer | Type invariants, encapsulation | | orc:spec-flow-analyzer | User flow completeness, edge cases | | orc:frontend-verifier | Forms, interactions, visual regressions | | orc:drawio | Architecture, flow, dependency, sequence diagrams |

Present your selection as a table before spawning:

Selected agents for "$TOPIC":
| # | Agent | Why |
|---|-------|-----|
| 1 | ... | ... |

Step 3: Spawn Agents in Parallel, Wait for All

Spawn all selected agents in a single assistant turn with run_in_background=true.

Every agent gets this base prompt + the output contract:

You are contributing to a topic documentation page.

Topic: $TOPIC

IMPORTANT: Do NOT write any files. Return your analysis as your final response text.
The orchestrator will handle all file writing.

OUTPUT CONTRACT:
- Use ## headings for sections
- Include file paths and line numbers (absolute from project root)
- Start with a 2-3 sentence summary of your findings
- End with a ## Key Files section listing the most important files you found
- Be specific — code snippets, exact paths, line numbers
- Focus on substance, not style

Wait for all agents to complete. Collect agent outputs from their completion notifications — each agent's findings are returned in its notification message. You will synthesize all findings directly in Step 4.

Step 4: Synthesize and Write

Using the findings from all agent notifications, write $DOC_PATH directly.

You have all agent findings from their completion notifications. Write the doc yourself using this style guide:

```` STYLE GUIDE — replicate the patterns from https://code.claude.com/docs/en/memory:

OPENING — blockquote summary + context + anchor list:

# [Title]

> [One-line summary of what this thing does, written as a verb phrase.]

[2-3 sentences of context — what it is, why it matters.] This page covers:

- [Section name](#anchor) — one-line description
- [Section name](#anchor) — one-line description

Example from memory.md: > Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory.

COMPARISON TABLE — orient the reader early with a versus table:

|                      | Option A          | Option B                |
| :------------------- | :---------------- | :---------------------- |
| **Who writes it**    | You               | Claude                  |
| **What it contains** | Instructions      | Learnings               |
| **Scope**            | Project, user     | Per working tree        |
| **Use for**          | Coding standards  | Build commands, prefs   |

SCOPE TABLE — show where things live, who they affect:

| Scope         | Location                    | Purpose                        | Shared with       |
| ------------- | --------------------------- | ------------------------------ | ----------------- |
| **Project**   | `./CLAUDE.md`               | Team-shared project rules      | Team via VCS      |
| **User**      | `~/.claude/CLAUDE.md`       | Personal prefs, all projects   | Just you          |

TASK-ORIENTED HEADINGS — phrase as actions, not descriptions:

• "Choose where to put X" NOT "X Locations"
• "Set up a project X" NOT "Project X Configuration"
• "Write effective X" NOT "X Best Practices"

CALLOUTS — bold prefix, no special syntax:

• Tip: [actionable advice]
• Warning: [gotcha or risk]

HOW IT WORKS — explain mechanics in plain language: "The first 200 lines of MEMORY.md are loaded at the start of every conversation. Content beyond line 200 is not loaded at session start. Claude keeps MEMORY.md concise by moving detailed notes into separate topic files."

SECTION SEPARATORS — use *** (horizontal rule) between major sections: Major conceptual boundaries get a *** before the next ##. Not every section — only between distinct topic areas (e.g., between "Plugin components" and "CLI commands").

TROUBLESHOOTING — two formats depending on complexity:

Format 1 — table for quick-reference issues (from plugins-reference.md):

| Issue                  | Cause                    | Solution                                  |
| :--------------------- | :----------------------- | :---------------------------------------- |
| Plugin not loading     | Invalid `plugin.json`    | Validate JSON syntax                      |
| Commands not appearing | Wrong directory structure | Ensure `commands/` at root                |

Format 2 — ### problem heading + numbered debug steps (from memory.md):

### Claude isn't following my CLAUDE.md

CLAUDE.md is context, not enforcement. To debug:

1. Run `/memory` to verify your files are being loaded.
2. Check the location is correct (see [Choose where to put...](#...)).
3. Make instructions more specific.

Use Format 1 when there are many small issues. Use Format 2 for complex problems that need sequential investigation.

CROSS-REFERENCE TIP — when related docs exist, add a tip block near the top:

**Tip:** Looking to install plugins? See [Discover and install plugins](./other-doc.md).
For creating plugins, see [Plugins](./another-doc.md).

FILE/COMPONENT REFERENCE TABLE — for topics with multiple parts:

| Component    | Default Location             | Purpose                    |
| :----------- | :--------------------------- | :------------------------- |
| **Manifest** | `.claude-plugin/plugin.json` | Plugin metadata            |
| **Commands** | `commands/`                  | Skill Markdown files       |
| **Agents**   | `agents/`                    | Subagent Markdown files    |

SEE ALSO / RELATED RESOURCES — bullet list footer with link + dash + description:

## See also

* [Skills](/en/skills) - Skill development details
* [Settings](/en/settings) - Configuration options

RULES:

• Let the topic dictate sections. Skip any section type that has no substance.
• Include analysis content inline: edge case tables, execution flow trees, convention

summaries — wherever they fit naturally within the doc's narrative.

• Every section earns its place. No filler.
• Conversational but precise tone: "You write these files in plain text; Claude reads them..."
• Tables for comparisons and reference. Code blocks for structures and commands.
• Numbered steps only for sequential procedures. Bullets for everything else.
• ## for major sections, ### for subsections, #### rarely.
• Use *** horizontal rules between major conceptual boundaries.

CONTENT PRIORITY (by reader value):

1. Diagrams — embed from docs/diagrams/ (``)
2. Execution flows — step-by-step with file:line references
3. User stories — table format: Story | Entry | Exit | Happy Path
4. Code seams — boundary contracts, implicit rules, risk ratings
5. Tables — interface inventories, dependency graphs, gap analysis
6. Code snippets — only for key patterns (composition root, validation pipeline)

If it can be a table or diagram, make it one. Avoid prose walls.

Topic: $TOPIC

````

Step 4b: Generate Diagrams (if applicable)

Check for existing diagrams first:

ls docs/diagrams/*.drawio 2>/dev/null

If high-quality diagrams already exist that cover the topic:

• Export to PNG if not already exported: drawio --export --format png --page-index N --output docs/diagrams/name.png docs/diagrams/name.drawio
• Embed in the doc: ``
• Do NOT regenerate inferior versions — existing hand-crafted diagrams are always preferred

If no diagrams exist and the topic warrants visual representation:

Agent(
  subagent_type="orc:drawio",
  description="Generate {type} diagram",
  prompt="
    Generate a {type} diagram for this codebase.
    Focus: {focus derived from $TOPIC}
    Output: docs/diagrams/{slug}.drawio + docs/diagrams/{slug}.png

    {paste relevant context from Step 3 + agent findings}

    Requirements:
    - Explore the codebase to verify all components shown are real
    - Use the standard color palette (blue=apps, green=packages, amber=storage, purple=blockchain)
    - Export to PNG and verify visually — fix any overlaps before finishing
    - Return the paths of created files
  "
)

After the agent completes, verify the output by Reading the exported PNG.

Diagram candidates by topic: | Topic involves | Diagram type | |---------------|-------------| | System design | Architecture (3-tier layered) | | User stories, data flow | Flow / lifecycle (swim lanes) | | Packages, modules | Dependency graph (DAG) | | Boundaries, interfaces | Seams / boundary diagram |

Step 5: Present and Iterate

After writing $DOC_PATH and generating any diagrams:

1. Read $DOC_PATH
2. Show doc preview with AskUserQuestion + preview field
3. Options: "Use as-is" / "Revise"

If "Revise": ask which section + what to change, edit $DOC_PATH directly.

Loop until user approves.

Step 6: Update docs/MAP.md

Read existing docs/MAP.md (or create if first run). Read $DOC_PATH to extract the opening summary.

Add/update entry. Format:

# Documentation Map

> Generated documentation index for this project.

_Last updated: YYYY-MM-DD_

- [Title](./NNN-slug.md) — one-line description

Key rules:

• Each entry: - [Title](./NNN-slug.md) — one-line description
• Description extracted from the doc's opening blockquote
• Entries ordered by number prefix
• Remove entry if doc file is deleted

Step 7: Report

Report to user:

• $DOC_PATH written
• docs/MAP.md updated
• Diagrams created/reused (if any)

File Ownership

| File | Access | Purpose | |------|--------|---------| | docs/{NNN}-{slug}.md | Write | Documentation page | | docs/MAP.md | Write | Documentation index | | docs/diagrams/*.drawio | Write | Diagram source files (shared across docs) | | docs/diagrams/*.png | Write | Exported diagram images | | Source files | Read only | Agent exploration |

Completion Criteria

• [ ] Topic parsed and output path determined (with collision check)
• [ ] 3-5 agents selected with per-agent justification
• [ ] All research agents completed and returned findings
• [ ] Orchestrator wrote $DOC_PATH directly following Claude Code doc style
• [ ] Existing diagrams reused where available
• [ ] New diagrams (if any) have both .drawio source and .png export in docs/diagrams/
• [ ] User reviewed preview and approved (or iterated)
• [ ] docs/MAP.md updated with entry

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.