code-wiki

# Code Wiki Skill Generate a full wiki for any codebase — overview, architecture, per-module deep-dives, Mermaid class and sequence diagrams. Inspired by Google CodeWiki, but works on local repos, private repos, and any language. Uses only existing Hermes tools (`terminal`, `read_file`, `search_files`, `write_file`); no Docker, no external services, no extra dependencies. This skill produces **reference documentation** (what/how). It does not produce strategic narrative (why — that's a different skill). ## When to Use - User says "document this codebase", "generate a wiki", "make architecture diagrams" - Onboarding to an unfamiliar repo and wants a structured reference - User points at a GitHub URL and asks for documentation - Need a stable artifact (markdown + Mermaid) that renders on GitHub Do NOT use this for: - Single-file or single-function documentation — just answer directly - API reference for one specific endpoint — use `read_file` and answer inline - Strategic "why does this exist" narrative — different skill, different purpose - Codebases the user is actively developing in this session — just answer questions as they come ## Prerequisites - No env vars required. - `git` on PATH for repo SHA tracking and remote clones. - Optional: `pygount` for language-breakdown stats (see the `codebase-inspection` skill). ## How to Run Invoke through the `terminal` tool from the target repo's root, then use `read_file` / `search_files` / `write_file` to produce the wiki. Default output location is `~/.hermes/wikis/<repo-name>/`. Only write into the repo (`docs/wiki/`) when the user explicitly requests it. ## Quick Reference | Step | Action | |---|---| | 1 | Resolve target — local cwd, given path, or `git clone --depth 50 <url>` to a temp dir | | 2 | Scan structure — `ls`, `find -maxdepth 3`, manifest files, README | | 3 | Pick 8–10 modules to document | | 4 | Write `README.md` (overview + module map) | | 5 | Write `architecture.md` with Mermaid flowchart | | 6 | Write per-module docs in `modules/` | | 7 | Write `diagrams/class-diagram.md` (Mermaid classDiagram) | | 8 | Write `diagrams/sequences.md` (Mermaid sequenceDiagram, 2–4 workflows) | | 9 | Write `getting-started.md` | | 10 | Write `api.md` if applicable, else skip | | 11 | Write `.codewiki-state.json` | | 12 | Report paths to user | ## Procedure ### 1. Resolve the target For a GitHub URL: ```bash WIKI_TMP=$(mktemp -d) git clone --depth 50 <url> "$WIKI_TMP/repo" cd "$WIKI_TMP/repo" REPO_SHA=$(git rev-parse HEAD) REPO_NAME=$(basename <url> .git) ``` For a local path (or cwd if none given): ```bash cd <path> REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted") REPO_NAME=$(basename "$PWD") ``` Then set the output dir: ```bash OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME" mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams" ``` ### 2. Scan repo structure Use the `terminal` tool for the shell work, `read_file` for manifests: ```bash # Shallow tree first ls -la # Deeper tree, noise filtered find . -type d \ -not -path '*/\.*' \ -not -path '*/node_modules*' \ -not -path '*/venv*' \ -not -path '*/__pycache__*' \ -not -path '*/dist*' \ -not -path '*/build*' \ -not -path '*/target*' \ -maxdepth 3 | sort # Language breakdown (skip if pygount unavailable) pygount --format=summary \ --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \ . 2>/dev/null || true ``` Then `read_file` the relevant manifests (`package.json`, `pyproject.toml`, `setup.py`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`) and the project README. Use `search_files target='files'` to find them rather than guessing names. ### 3. Pick modules to document Cap initial pass at **8–10 modules**. Heuristics by language: - Python: top-level packages (dirs with `__init__.py`), plus subsystem dirs - JS/TS: `src/<subdir>`, top-level workspace dirs - Rust: each crate in a workspace, or top-level `src/<module>` dirs - Go: each top-level package directory - Mixed/unfamiliar: top-level directories that contain source code (not config, not tests) For very large repos, prioritize by: 1. Imported-from count (a module imported by many is core) 2. LOC (bigger modules usually warrant their own doc) 3. Mentions in README / top-level docs State the module list to the user before generating per-module docs on big repos — gives them a chance to redirect. ### 4. Write `README.md` `read_file` the actual project README plus the top 2–3 entry-point files. Then `write_file`: ````markdown # <Project Name> <One paragraph: what it is and what it's for. Self-contained — don't assume the reader has the source README.> ## Key Concepts - **<Concept 1>** — <one line> - **<Concept 2>** — <one line> ## Entry Points - [`path/to/main.py`](<link>) — <what runs when you start it> - [`path/to/cli.py`](<link>) — <CLI surface> ## High-Level Architecture <2-3 sentences. Detail goes in architecture.md.> See [architecture.md](architecture.md). ## Module Map | Module | Purpose | |---|---| | [`<module>`](modules/<module>.md) | <one-line purpose> | ## Getting Started See [getting-started.md](getting-started.md). ```` For link targets in local mode use relative paths. For cloned repos use `https://github.com/<owner>/<repo>/blob/<sha>/<path>` so links survive future commits. ### 5. Write `architecture.md` ````markdown # Architecture <2-3 paragraphs: shape of the system. What talks to what. Where data enters, where it exits, where state lives.> ## Components - **<Component>** — <1-2 sentences>. See [`modules/<module>.md`](modules/<module>.md). ## System Diagram ```mermaid flowchart TD User([User]) --> Entry[Entry Point] Entry --> Core[Core Engine] Core --> StorageA[(Database)] Core --> ExternalAPI{{External API}} ``` ## Data Flow 1. **<Step>** — [`<file>`](<link>) 2. **<Step>** — [`<file>`](<link>) ## Key Design Decisions - <Anything load-bearing the reader should know> ```` **Mermaid shape semantics:** - `[]` = component - `[()]` = database / storage - `{{}}` = external service - `(())` = entry point or terminal - `-->` = sync call, `-.->` = async/event Cap at ~20 nodes per diagram. Split into sub-diagrams if larger. ### 6. Write per-module docs in `modules/` For each selected module, inspect its layout with `ls`, identify 3–5 most important files (by size, by being named `core.py` / `main.py` / `__init__.py`, by being imported a lot), then `read_file` those files (use `offset` / `limit` to read only what you need; prefer `search_files` for specific symbols). ````markdown # Module: `<module>` <1-2 sentence purpose.> ## Responsibilities - <bullet> - <bullet> ## Key Files - [`<module>/<file>`](<link>) — <what it does> ## Public API <Functions/classes/constants other code uses. Group related items. Show signatures, not full implementations.> ## Internal Structure <How the module is organized internally. State management.> ## Dependencies - **Used by:** <other modules> - **Uses:** <other modules + external libs> ## Notable Patterns / Gotchas - <Anything non-obvious> ```` ### 7. Write `diagrams/class-diagram.md` Pick the 5–10 most important classes/types. `read_file` them, then write: ````markdown # Class Diagram ## Core Types ```mermaid classDiagram class Agent { +string name +list~Tool~ tools +chat(message) string } class Tool { <<interface>> +name string +execute(args) any } Agent --> Tool : uses Tool <|-- TerminalTool Tool <|-- WebTool ``` ## Notes <Anything the diagram can't express — lifecycle, threading, etc.> ```` For languages without classes (Go, C, Rust): use the diagram for struct relationships, or skip class-diagram.md and explain it in prose in architecture.md. Don't force-fit. ### 8. Write `diagrams/sequences.md` Pick 2–4 of the most important workflows. Trace each call path through the code (read entry point, follow function calls), then: ````markdown # Sequence Diagrams ## Workflow: <Name> <1 sentence describing what this does and when it runs.> ```mermaid sequenceDiagram participant User participant CLI participant Agent participant LLM User->>CLI: types message CLI->>Agent: chat(message) Agent->>LLM: API call LLM-->>Agent: response + tool_calls Agent->>Agent: execute tools Agent-->>CLI: final response ``` ### Walkthrough 1. **User input** — [`cli.py:HermesCLI.run_session`](<link>) 2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](<link>) ```` Don't invent participants. Every box must correspond to a real component the reader can find in the code. ### 9. Write `getting-started.md` ````markdown # Getting Started ## Prerequisites <From manifest files + README. Be specific — versions if pinned.> ## Installation ```bash <exact commands> ``` ## First Run ```bash <minimum command to see the system do something useful> ``` ## Common Workflows ### <Workflow 1> <commands> ## Configuration - `<config-file>` — <what it controls> - Env var `<VAR>` — <what it controls> ## Where to Go Next - Architecture: [architecture.md](architecture.md) - Module reference: [README.md#module-map](README.md#module-map) ```` ### 10. Write `api.md` (skip if not applicable) Only write this if the project is a library or API server. If it is: - Find the public API surface (`__init__.py` exports, OpenAPI specs, route handlers, exported types) - Document each public entry with signature, parameters, return type, one-line description - Group by category ### 11. Write the state file ```bash cat > "$OUTPUT_DIR/.codewiki-state.json" <<EOF { "repo_name": "$REPO_NAME", "source_path": "$PWD", "source_sha": "$REPO_SHA", "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", "generator": "hermes-agent code-wiki skill v0.1.0", "modules_documented": [] } EOF ``` ### 12. Report to user State exactly what was generated and where: ``` Generated wiki at ~/.hermes/wikis/<repo-name>/: README.md project overview, module map architecture.md system architecture + flowchart getting-started.md setup, first run, workflows modules/<N files> per-module deep-dives diagrams/architecture.md Mermaid flowchart diagrams/class-diagram.md Mermaid class diagram diagrams/sequences.md Mermaid sequence diagrams ``` If you cloned to a temp dir, remind the user it can be removed (`rm -rf "$WIKI_TMP"`) after they've reviewed the wiki. ## Scope Control Generating a full wiki for a 500K-LOC monorepo is wildly token-expensive. Default to bounded scope: - Initial scan: max depth 3 directories - Per-module docs: cap at 10 modules unless user expands scope - Per-file reads: prefer `search_files` for symbols + `read_file` with `offset`/`limit` over full reads - Skip vendored code (`vendor/`, `third_party/`, generated code, `_pb2.py`, `.min.js`) If the user says "do the whole thing exhaustively", believe them — but ballpark the cost first: "this repo has ~340 source files, comprehensive coverage will be expensive — confirm?" ## Re-Run / Update If `.codewiki-state.json` already exists at the target path: - Read it for previous SHA and module list - If source SHA matches: ask user if they want to regenerate or skip - If SHA differs: offer to regenerate only modules with changed files (`git diff --name-only <old-sha> HEAD`) Full incremental-regeneration is a future enhancement — for now, regenerating the whole thing is acceptable.