# Codebase Suite > Structured, phase-based workflow for analyzing, documenting, and preparing unfamiliar codebases. Read-only first, human checkpoints after each phase. Produces durable technical documentation (incl. architecture.md and important-files.md) in _docs/ as well as analysis artifacts in _docs/intake/, and optionally provides the documentation to AI agents via CLAUDE.md/AGENTS.md. Includes a refresh mode that re-verifies existing documentation claim by claim against the current code. - Skill: `mdeuerlein/codebase-suite` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add mdeuerlein/codebase-suite` - Raw SKILL.md: https://api.skillmd.com/api/skills/mdeuerlein/codebase-suite/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: mdeuerlein (https://skillmd.com/u/mdeuerlein) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mdeuerlein/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. | Mode | Alias | Purpose | Phases | |---|---|---|---| | Quick Scan | `quick` | Fast initial assessment of small projects | 0, 1, 2 | | Standard Intake | `standard` | Normal onboarding run | 0–4 | | Deep Audit | `deep` | Critical or poorly documented codebases | 0–6 | | Documentation Mode | `docs` | Create or update technical documentation | 4 | | Repository Preparation | `repo` | Set up working structure, no re-analysis | 5–6 | | Refresh / Re-Check | `refresh` | Re-verify existing documentation against the current code and update it | R, then 4 in update mode (optionally 3, 5–6) | `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.