Codebase Suite

Codebase Suite

Gives an agent a solid understanding of an unfamiliar codebase — structured, traceable, without uncontrolled changes — and produces maintainable project documentation from it.

Goal

Instead of diving into a foreign codebase in an unstructured way, this skill runs through a clearly paced process:

• Capture the project context
• Inventory the technical foundation
• Understand features and structure
• Assess risks and technical debt
• Create documentation
• Prepare the repository structure
• Plan and prioritize the implementation
• Later: re-verify the documentation against the evolved code and update it

The result:

• _docs/ — durable technical documentation suitable for both humans and agents (architecture.md, important-files.md, setup.md, database.md, deployment.md, api.md, workflows.md, known-issues.md). Plus _docs/TODO.md as the central, curated overview of open tasks that points to the detailed sources (e.g. known-issues.md, _docs/intake/).
• _docs/intake/ — versionable analysis and process artifacts (context, inventory, risk, roadmap, implementation plan). These go stale faster than _docs/, so they are deliberately kept separate.
• Optional CLAUDE.md + AGENTS.md — when the documentation should be provided to AI agents. AGENTS.md carries the docs index, CLAUDE.md only points to it.
• _docs/intake/run-log.md — one line per suite run (date, mode, commit) so later runs know what state the documentation was last verified against.

Input

• Call without argument: work in the current directory.
• Call with a path: /codebase-suite /path/to/project
• Call with a mode: /codebase-suite --mode quick (or standard, deep, docs, repo, refresh)
• Call with agent provisioning: --agents (create/extend CLAUDE.md/AGENTS.md) or --no-agents (don't).
• --mode refresh --deep additionally re-runs the full Phase 3 risk analysis instead of only re-checking the status of existing findings.
• If no mode is given, determine it from the user context or ask briefly. If _docs/ already exists and the user asks to check, review, or update the documentation, refresh is the right mode.
• If agent provisioning is not set via flag, ask once before Phase 4 finishes: "Should the documentation also be provided to AI agents (create/extend CLAUDE.md + AGENTS.md)?" Default: no.

Prerequisites

• Before starting, load this skill's reference files:
  • references/phase-instructions.md — detailed steps for all phases (incl. Phase R)
  • references/artifact-templates.md — templates for the _docs/intake/ analysis artifacts
  • references/doc-templates.md — detailed templates for _docs/architecture.md, _docs/important-files.md, and the CLAUDE.md/AGENTS.md hint blocks
  • references/prioritization.md — rating scheme for findings
  • references/project-profiles.md — profile-specific analysis hints
• No changes to the source code before Phase 5. Phases 0–4 and Phase R write exclusively to _docs/ and _docs/intake/ (and optionally CLAUDE.md/AGENTS.md), never to the source code.
• Do not blindly overwrite existing _docs/, _docs/intake/, CLAUDE.md, or AGENTS.md files — read first, then extend or replace selectively.
• At the end of every run (any mode), append an entry to _docs/intake/run-log.md — see references/artifact-templates.md.
• Read sensitive content (secrets, .env, credentials) only; never output it or carry it into artifacts.

Documentation Language

• Durable _docs/ documentation: English by default (technical standard, good for AI agents). If the user explicitly wants a different language, follow that — but stay consistent throughout a single file.
• Non-English identifiers from the project (file, class, function, table names, domain terms) stay unchanged but are explained in the documentation language.
• Analysis artifacts in _docs/intake/ follow the conversation/user language.

Modes

Choose the mode based on the user context. When in doubt, ask.

refresh requires a previous run — at least _docs/ or _docs/intake/ must exist. If nothing is there, say so and offer standard instead.

Steps

Run the phases of the chosen mode in sequence. After each phase, observe the defined checkpoint.

Details on each phase are in references/phase-instructions.md.

Phase 0 — Capture the project context

Clarify the framing conditions: purpose, production status, known bugs, existing documentation, access, permission to make changes.

Output: _docs/intake/00-project-context.md

Checkpoint: Is the project context sufficiently clarified? Wait for confirmation before continuing.

Phase 1 — Initial technical inventory

Capture language, framework, dependencies, build structure, entry points, tests, CI/CD. No assessment — just a factual stocktaking.

Output: _docs/intake/01-technical-inventory.md

Checkpoint: Was the technical foundation identified correctly?

Phase 2 — Understanding features and structure

Describe what the application does: main modules, user roles, workflows, data models, interfaces, patterns.

Output:

• _docs/intake/02-system-overview.md
• _docs/intake/03-functional-overview.md

Checkpoint: Is the functional understanding plausible?

Phase 3 — Risk and quality analysis

Assess the codebase technically: bugs, security vulnerabilities, technical debt, missing tests, architecture problems. Use the rating scheme from references/prioritization.md.

Output:

• _docs/intake/04-risk-analysis.md
• _docs/intake/05-security-notes.md
• _docs/intake/06-optimization-opportunities.md

Checkpoint: Which risks are relevant for this project?

Phase 4 — Technical documentation

Create or update usable technical documentation from the analysis results. Write only what can be substantiated from the code. Flag uncertainties explicitly.

For _docs/architecture.md and _docs/important-files.md, use the detailed templates from references/doc-templates.md. Scope boundary: these two files describe the technical structure — no agent rules, coding conventions, setup/deploy/security instructions. Such topics belong in their own files (setup.md, deployment.md …) or in AGENTS.md.

Output (depending on project type):

• _docs/architecture.md
• _docs/important-files.md
• _docs/setup.md
• _docs/database.md
• _docs/deployment.md
• _docs/api.md
• _docs/workflows.md
• _docs/known-issues.md
• _docs/TODO.md

_docs/TODO.md is the central, curated overview of open tasks and tasks earmarked for later: concise entries with a status checkbox and a pointer to the respective detailed source (known-issues.md, _docs/intake/06, …/09, …/10). Create it here in Phase 4, extend it in the later phases (roadmap, implementation plan). Template: references/doc-templates.md.

AI-agent provisioning (optional, at the end of Phase 4): If desired (flag --agents or confirmed query), create a docs index for agents — see references/doc-templates.md:

• AGENTS.md: contains the index to the _docs/ files inside an idempotent marker block.
• CLAUDE.md: only briefly points to AGENTS.md (no duplicated table of contents).
• If one of the files already exists: insert the marker block if missing, otherwise replace its content — leave the rest of the file untouched.

Checkpoint: Should the documentation be accepted or adjusted? Should it be provided to AI agents?

Phase 5 — Prepare the repository and working structure

Only after analysis and ideally after a baseline commit.

Possible tasks: extend .gitignore, create a changelog, create dev and prod branches, set up a GitHub remote, do the initial push of both branches, prepare issue templates.

Output:

• _docs/intake/07-repository-preparation.md
• _docs/intake/08-issue-plan.md
• _docs/intake/09-roadmap.md

Checkpoint: May the repository structure be changed? Explicit approval required.

Phase 6 — Implementation planning

Derive prioritized work packages from the findings: quick wins, security measures, refactoring proposals, effort estimates.

Output: _docs/intake/10-implementation-plan.md

Checkpoint: Which tasks should actually be implemented?

Phase R — Re-verification (mode refresh)

Runs on a project the suite has already documented. Goal: establish whether the existing documentation still matches the code — and update it where it does not.

Core principle: verify substance, not timestamps. Never conclude that a document is current because its file, or the files it describes, have not changed. Every factual claim in the documentation is re-derived from the current code. Modification dates, git log, and the diff since the last run are used only to prioritize the order of work and to cross-check for blind spots — they are never a reason to skip verifying a claim.

Phase R has two directions, and both are mandatory:

1. Doc → code: every claim in the documentation is checked against the code (still true / drifted / gone / wrong / unverifiable).
2. Code → doc: everything relevant in the code that the documentation does not mention (new modules, dependencies, endpoints, tables, env vars, jobs, integrations). This direction is what timestamp-based checks structurally cannot find.

To do that, Phase R re-derives an independent baseline first (Phase 1 + Phase 2 pass from the code, before adopting any claim from the old documents) and only then compares. In refresh combined with a deep run, Phase 3 is re-run as well; otherwise existing findings and TODO items are re-checked for their current status (fixed / still present / regressed / no longer applicable).

Output:

• _docs/intake/11-refresh-report.md — drift report: per-claim verification, coverage gaps, finding status, verdict per document
• _docs/intake/run-log.md — extended with this run

Checkpoint: Present the drift summary and the verdict per document. Nothing is rewritten before approval.

After approval, re-enter Phase 4 in update mode: surgical edits to the affected documents (keep human additions, keep the rest of the file untouched), reconcile _docs/TODO.md, and refresh the marker block in AGENTS.md/CLAUDE.md if those files exist.

Limits

This skill does not replace a manual review. Be especially careful with:

• Production systems and database migrations
• Payment processes and personal data
• Authentication and permission systems
• Dependency updates without test coverage
• Automated deployments

Always have security-relevant findings reviewed by a human before changes are implemented.

Output

At the end of each completed phase, report:

1. Which mode and which phase was completed.
2. Which files were created or updated.
3. The most important findings in 3–5 points.
4. The next recommended step or the checkpoint question posed.

For a full run: an overall summary with all created artifacts and a prioritized list of the recommended next steps.

For a refresh run, additionally: how many claims were verified, how many were confirmed vs. drifted/gone/wrong, which coverage gaps were found, and — if verification had to be sampled instead of exhaustive — exactly what was left out.