generate-codebase-summary - SKILL.md Agent Skill

name: generate-codebase-summary description: "Generate or update codebase-summary.md (README-style overview: tech stack, repo layout, packages, entry points, LOC by language). Init renders from ProjectModel; update applies a Delta filtered for summary scope (RPO/TCH/PKG/MOD); sync scans the repo for file tree + manifests + LOC and proposes Add/Deprecate." category: documentation keywords: [codebase, summary, tech-stack, loc, repo-overview] argument-hint: "init|update|sync|apply-sync [options]" metadata: author: morkit version: "1.0.0"

Generate Codebase Summary Skill

Sub-skill that owns docs/codebase-summary.md. Single-language output (JP / EN / VN).

Environment (plugin context)

CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:?must be set by Claude Code}"
VENV="${HOME}/.claude/plugins/data/docs-hero/.venv"
PY="${VENV}/bin/python3"
SUM_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/generate-codebase-summary/scripts"
ORCH_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/docs-hero-orchestrator/scripts"
PROJECT_DOCS_DIR="${PWD}/docs"
PROJECT_META="${PWD}/.docs-hero-meta.json"

Modes

Mode	Purpose
`init`	Render `docs/codebase-summary.md` from a ProjectModel JSON
`update`	Apply Delta filtered for summary scope (RPO / TCH / PKG / MOD)
`sync`	Scan repo (file tree + manifests + LOC), write proposal — DOES NOT touch docs
`apply-sync`	Read proposal (with user-checked boxes) → convert to Delta

Init Workflow

"$PY" "$SUM_SCRIPTS/render_codebase_summary.py" \
  --project-model "$PROJECT_MODEL" \
  --language EN \
  --output "$PROJECT_DOCS_DIR/codebase-summary.md"

Section IDs (stable for diff engine):

RPO-001        # Singleton repo overview (§1)
TCH-{id}       # Per tech-stack item (inline in §2)
PKG-{id}       # Per package/workspace (inline in §4)
MOD-{id}       # Per entry-point module (inline in §5)

Sync Workflow (2-step)

Step 1: propose

"$PY" "$SUM_SCRIPTS/codebase_summary_sync_propose.py" \
  --codebase-paths "." \
  --existing-doc "$PROJECT_DOCS_DIR/codebase-summary.md" \
  --output "${PWD}/.tmp/codebase-summary-sync-proposal.md"

Detects:

File tree (depth-3, ignores node_modules/.venv/dist/build/etc.)
Pure-Python LOC counter by extension (no cloc dependency — flagged as approximate)
Package manifests: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, composer.json
Tech-stack inference from manifest contents (declared deps + framework presence)
Entry points: main.py, index.{js,ts}, cmd/*, bin/*, pyproject [project.scripts], package.json bin/main

Step 2: apply-sync

"$PY" "$SUM_SCRIPTS/codebase_summary_sync_apply.py" \
  --proposal "${PWD}/.tmp/codebase-summary-sync-proposal.md" \
  --output "${PWD}/.tmp/codebase-summary-delta.json"

File Ownership

This skill owns:

docs/codebase-summary.md

It does not modify:

Source files / manifests (read-only scan)

References

templates/codebase-summary-template.md