When this skill is activated, always start your first response with the 🧢 emoji.

Codedocs

Codedocs generates structured, layered documentation for any git repository or code directory - documentation designed to be consumed by AI agents first and human developers second. Instead of flat READMEs that lose context, codedocs produces a docs/ tree with an architecture overview, per-module deep dives, cross-cutting pattern files, and a manifest that tracks what has been documented and when. Once docs exist, the skill answers questions from the docs (not by re-reading source code), and supports incremental updates via targeted scope or git-diff detection.

Activation Banner

At the very start of every codedocs invocation, before any other output, display this ASCII art banner:

 ██████╗ ██████╗ ██████╗ ███████╗██████╗  ██████╗  ██████╗███████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔═══██╗██╔════╝██╔════╝
██║     ██║   ██║██║  ██║█████╗  ██║  ██║██║   ██║██║     ███████╗
██║     ██║   ██║██║  ██║██╔══╝  ██║  ██║██║   ██║██║     ╚════██║
╚██████╗╚██████╔╝██████╔╝███████╗██████╔╝╚██████╔╝╚██████╗███████║
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═════╝  ╚═════╝  ╚═════╝╚══════╝

Follow the banner immediately with the active sub-command and target path, e.g.: codedocs:generate · src/ → docs/

When to use this skill

Trigger this skill when the user:

• Wants to generate documentation for a codebase, repo, or directory
• Asks "what does this project do" or "explain this codebase"
• Needs onboarding docs for new team members joining a project
• Wants AI-agent-readable documentation for a repo
• Asks a question about a codebase that already has codedocs output
• Needs to update existing docs after code changes or a new feature
• Wants to document only a specific module or subdirectory
• Asks to refresh docs based on recent git commits or a diff

Do NOT trigger this skill for:

• Writing standalone technical documents (RFCs, ADRs, runbooks) - use internal-docs
• API reference docs for external consumers - use technical-writing
• README creation for open-source packaging - use open-source-management

Key principles

1. Docs-first answers - Once codedocs output exists, always answer questions from the docs before falling back to source code. The docs are the cached, structured knowledge layer. Only read source code when docs are missing, stale, or insufficient for the specific question.

2. Language-agnostic detection - Detect the tech stack from manifest files (package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, composer.json, pom.xml, build.gradle, Gemfile, mix.exs, etc.) and directory conventions. Never assume a specific language.

3. Modules map to code, patterns cut across - Module docs correspond to distinct code directories or bounded contexts (auth, api, database). Pattern docs capture cross-cutting concerns (error handling, testing strategy, logging conventions) that span multiple modules. This split prevents duplication and matches how developers think about code.

4. Manifest-driven incremental updates - The .codedocs.json manifest tracks every documented module, its source path, and the git SHA at documentation time. Updates use this manifest to know what changed, what to re-scan, and what to skip.

5. Output is configurable, structure is not - The output directory (default docs/) is configurable. The internal structure (OVERVIEW.md, INDEX.md, .codedocs.json, modules/, patterns/) is fixed. Consistency across repos means any agent or developer knows where to look.

6. Coverage is a first-class metric - Documentation that covers 40% of a codebase is often worse than none - it gives a false sense of completeness. Always run coverage verification before presenting the plan. Target 70%+ for mid-size repos. Report coverage percentage in OVERVIEW.md and the manifest. See references/coverage-strategy.md for targets.

7. Go deep, not just wide - For large repos, top-level modules are just the starting point. Any module with 15+ source files must be analyzed for sub-modules. Scan recursively through the full directory tree - a huge repo should generate 30-80 doc files, not 8-12.

Core concepts

Output structure - Codedocs always produces the same directory tree. OVERVIEW.md is the entry point covering architecture, tech stack, project structure tree, and module map. GETTING_STARTED.md is the authoritative local development guide with every runnable command in the repo. INDEX.md is the file-to-module lookup table. The modules/ directory contains one markdown file per major code module (with optional sub-module directories for large modules). The patterns/ directory contains cross-cutting concern docs. The .codedocs.json manifest tracks metadata, coverage stats, and SHAs for incremental updates. See references/output-structure.md for the full spec.

Four sub-commands - The skill exposes four operations: generate for full or scoped documentation creation, ask for docs-first Q&A, update for incremental refresh, and status for coverage reporting. Each has its own workflow and parameters. See the common tasks below and the corresponding reference files for detailed workflows.

Sub-modules - When a module directory has 15+ source files with distinct internal groupings, it is split into sub-modules. The parent module doc becomes an index; sub-module docs live at modules/<parent>/<child>.md. This keeps docs focused and prevents any single file from becoming an unreadably long catch-all.

Coverage verification - Before presenting the generation plan, codedocs computes what percentage of source files are covered by the proposed module set. If below target, it expands the scan to find additional modules. Coverage is tracked in the manifest and reported in OVERVIEW.md. See references/coverage-strategy.md.

Discovery phase - Before writing any docs, the generate command runs a discovery phase: scan the directory tree, identify the tech stack from manifest files, map module boundaries from directory structure and import graphs, and detect cross-cutting patterns from shared utilities and conventions. This phase produces the plan that drives doc generation.

Staleness detection - The update command compares the current git SHA against the SHA recorded in .codedocs.json for each module. Modules with changed files since last documentation are flagged as stale. The --diff flag uses git diff to identify exactly which files changed, enabling surgical updates to only the affected module docs.

Common tasks

1. Generate full codebase documentation

Command: codedocs:generate [path] [--output docs/]

Workflow:

1. Discover - Scan the target path (default: repo root). Identify language/framework from manifest files. Map directory structure to candidate modules. Detect entry points (main files, index files, route definitions, CLI entry points).
2. Plan - Present the user with a proposed doc plan: list of modules to document, patterns detected, estimated scope, and coverage percentage. Confirm before proceeding if the plan is large or ambiguous.
3. Write OVERVIEW.md - Architecture summary, tech stack, annotated project structure tree, entry points, key concepts, and module map with one-line descriptions.
4. Write GETTING_STARTED.md - Full local development guide: prerequisites, installation, environment setup, dev server, test commands, build commands, lint/format, database workflow, common dev tasks, and how to reproduce CI locally. Sourced from package.json scripts, Makefile targets, CI config, and any existing README setup sections.
5. Write module docs - For each module: purpose, public API/exports, internal structure, dependencies (what it imports), dependents (what imports it), and key implementation notes.
6. **Write pattern