fimoklei/pm-ai-playbook/codedocs

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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).

1. 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.

1. Write OVERVIEW.md - Architecture summary, tech stack, annotated project structure

tree, entry points, key concepts, and module map with one-line descriptions.

1. 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.

1. Write module docs - For each module: purpose, public API/exports, internal structure,

dependencies (what it imports), dependents (what imports it), and key implementation notes.

1. Write pattern docs - For each cross-cutting pattern: description, where it appears,

conventions to follow, and examples from the codebase.

1. Write manifest - Create .codedocs.json with module list, source paths, git SHA,

generation timestamp, coverage stats, and config. See references/output-structure.md.

See references/generate-workflow.md for the complete discovery heuristics, module boundary detection logic, and OVERVIEW.md template.

2. Ask a question about the codebase

Command: codedocs:ask "<question>"

Workflow:

1. Check for docs - Look for .codedocs.json in the output directory. If missing,

suggest running codedocs:generate first.

1. Route the question - Determine which doc file(s) are relevant. Architecture questions

go to OVERVIEW.md. Module-specific questions go to the relevant module doc. Cross-cutting questions go to pattern docs.

1. Read docs first - Load the relevant doc file(s) and attempt to answer from them.
2. Fall back to source - If the docs don't contain enough detail, read the relevant

source files. Flag in the response: "Note: this answer required reading source code - consider running codedocs:update to capture this in the docs."

1. Cite sources - Always cite which doc file or source file the answer came from.

See references/ask-workflow.md for the question routing logic and fallback strategy.

3. Update docs incrementally (targeted scope)

Command: codedocs:update --scope path/to/module

Workflow:

1. Read manifest - Load .codedocs.json to find the existing module mapping.
2. Re-scan the scoped path - Run the discovery phase only on the specified path.
3. Diff against existing docs - Compare the new discovery against the current module

doc. Identify new exports, removed functions, changed dependencies.

1. Update the module doc - Rewrite only the sections that changed.
2. Update OVERVIEW.md - If the module's one-line description or dependency graph changed,

update the module map in OVERVIEW.md.

1. Update manifest - Bump the git SHA and timestamp for the updated module.

4. Update docs from git diff

Command: codedocs:update --diff [base..head]

Workflow:

1. Get changed files - Run git diff --name-only base..head (default: last documented

SHA from manifest to HEAD).

1. Map files to modules - Using the manifest's source path mappings, determine which

documented modules contain changed files.

1. Re-generate affected modules - For each affected module, re-run the module doc

generation workflow.

1. Detect new modules - If changed files are in directories not yet documented, flag

them as new module candidates and prompt the user.

1. Update manifest - Bump SHAs for all updated modules.

See references/update-workflow.md for the diff detection logic and new module handling.

5. Generate docs for a specific subdirectory

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

Same workflow as full generation but scoped to a subdirectory. The output defaults to a docs/ folder inside the specified path. Useful for monorepos where each package needs its own documentation.

6. Check documentation coverage

Command: codedocs:status

Workflow:

1. Read manifest - Load .codedocs.json. If missing, suggest running codedocs:generate.
2. Compute coverage - Count total source files in the repo vs files covered by documented

modules.

1. Detect staleness - For each module, compare the manifest SHA against the latest git

commit SHA on that module's source path.

1. Find gaps - List directories in the repo not covered by any module doc.
2. Report - Print a structured status report: coverage percentage, stale modules, gap

directories, and recommendations.

See references/coverage-strategy.md for coverage targets, the status report format, and strategies for improving coverage on large repos.