Documentation & Modernization

Two complementary workflows for a repository the user already has checked out locally, bundled as one skill:

• Documentation mode — produce one definitive, cited architecture document from the code on disk. Ideal for onboarding, system-design maps, or as the evidence base for a modernization effort.
• Modernization mode — turn that architecture into a phased, safety-laddered plan to upgrade, migrate, or rewrite a legacy system.

Mode selection

• If the user wants to understand, document, map, research, or onboard onto a codebase, run Documentation mode.
• If the user wants to modernize, migrate, upgrade, or rewrite a system, run Modernization mode. Modernization mode is self-sufficient: if no architecture document exists yet, it runs the Documentation mode workflow first (in the same pass), then continues straight through to the plan.

When in doubt, produce the architecture document first — it is the audited evidence base both modes rely on.

Documentation mode

Generate one definitive, cited architecture document for a repository the user already has checked out locally. The goal is a writeup someone could hand to a new engineer as their onboarding reference — broad enough to cover the whole system, deep enough on the hard parts to be useful, and trustworthy because every claim traces back to a file on disk.

Why local-first

Reading from the local checkout (not the GitHub API or the web) is the deliberate default. It is faster, free, avoids rate limits, and — most importantly — it describes the exact code in front of you rather than whatever main happens to look like remotely. The one tradeoff is that remote-only facts (star counts, full CI run history, sibling repos) aren't visible. That's fine: state those as out-of-scope or mark them [UNVERIFIED] rather than guessing.

Local-first is not local-never-remote: a web/API lookup is a deliberate last-resort fallback, reserved for a fact that genuinely cannot be determined from disk and that materially matters to the document. When you do reach for it, flag the result clearly (e.g. [UNVERIFIED] / sourced-remotely) so the reader knows it didn't come from the checkout, and never let it become the easy path that displaces reading the code on disk.

Workflow

1. Establish identity first. Run git remote -v, git branch --show-current, and git log -1 so the document is anchored to a specific remote, branch, and commit. A reader must be able to tell which snapshot this describes. Remote URLs can contain embedded credentials (e.g. https://<token>@github.com/...) — redact any credentials/tokens from the URL before recording it in the document.
2. Detect, don't assume. Read the real manifests (go.mod, package.json, Cargo.toml, pyproject.toml, pom.xml, etc.), the Makefile/task runner, CI config, and any repo-specific agent or contributor docs (AGENTS.md, CONTRIBUTING, README, docs/). These are the source of truth for the tech stack and commands — prefer them over your prior knowledge of the framework.
3. Map breadth, then drill into depth. First build the whole-repo map (the three lenses below), then pick the 2-3 hardest subsystems and go deep on them.
4. Verify as you go. Open the files you cite. If you reference a line number, you should have actually read that line. Unsupported claims are worse than omissions here — the whole value of this document is that it can be trusted.

Output structure

Produce a single Markdown file with the sections below, in this order. Adapt the headings to the actual project (a CLI tool has no "frontend" lens — fold that slot into whatever matters for that repo), but keep the three-lens shape and the verification discipline.

Part 1 — Whole-repo technical deep-dive

• What the repository is (one paragraph, cited to README).
• Tech-stack detection table: layer | technology | evidence (file+line).
• Entry points (backend, frontend, CLI — whatever applies).
• Commands & Verification Inventory — a table of the canonical project commands (command | purpose | evidence), verified against the task runner / manifests / CI config, not guessed. Cover build, run/serve, test (and how to run a single test), lint, format, and — where they exist — typecheck, end-to-end/smoke, contract, and any other gate commands, plus the CI

…