# Document

> Generate a single documentation page from codebase exploration

- **Type:** Skill
- **Install:** `agentstack add skill-qgolem-orc-document`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [qGolem](https://agentstack.voostack.com/s/qgolem)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [qGolem](https://github.com/qGolem)
- **Source:** https://github.com/qGolem/orc/tree/main/skills/document

## Install

```sh
agentstack add skill-qgolem-orc-document
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
```bash
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
```

```bash
mkdir -p docs docs/diagrams
```

**Check for existing codebase context:**
```bash
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:

```markdown
# [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:

```markdown
|                      | 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:

```markdown
| 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):
```markdown
| 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):
```markdown
### 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:
```markdown
**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:
```markdown
| 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:

```markdown
## 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:**
```bash
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:

```markdown
# 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](https://github.com/qGolem)
- **Source:** [qGolem/orc](https://github.com/qGolem/orc)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-qgolem-orc-document
- Seller: https://agentstack.voostack.com/s/qgolem
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.