Agent skill · writing content · aj-geddes
bmad-document-project
BROWNFIELD planning input. Scans an existing codebase READ-ONLY and writes project-documentation.md — ground truth for stack, structure, key flows, conventions, and integration points — so downstream BMAD planning skills start from reality. Does NOT modify code; produces only the doc artifact. Use when the user says: "document this codebase", "document the project", "document my app", "scan the existing code", "brownfield planning", "we have existing code, start planning", "map what's already built", "document current state", "capture the current architecture", "understand the existing system before planning", "write project-documentation.md", or before a PRD or architecture doc when the user already has code written. Three intents: Create (initial scan), Update (re-scan changed areas), Validate (check completeness). Plans only — reads code but never writes it, runs no tests, no linters, no build tools, no application code.
Why this skill is useful
Generates a detailed project documentation file from existing code, providing insights into stack, structure, and conventions that the AI wouldn't reliably infer on its own.
What it needs
About 4k tokens when loaded. Last updated 2026-06-20. 471 stars on the source repository.
What this skill does
BMAD Document Project BROWNFIELD entry point. When a project already has code, planning skills need ground truth — not guesses about the stack or conventions. This skill performs a systematic, READ-ONLY codebase scan and emits project-documentation.md, the authoritative current-state snapshot that every downstream BMAD planning skill loads. No code is written, modified, or executed. Allowed tools are Read, Glob, Grep, Write (for the output document only), and TodoWrite (to track scan progress). --- Output bmad-output/project-documentation.md (or the user-configured output folder — honor it) Load bmad-output/project-context.md if it exists; merge any constraints already recorded there rather than rediscovering them from scratch. --- Three Intents Ask which intent applies if ambiguous; never silently regenerate an existing document. Create — initial scan Use TodoWrite to track the six scan passes below. Complete every pass before writing the final document. Pass 1 — Repository skeleton Capture: directory tree shape, presence of monorepo markers (packages/, apps/, libs/), top-level config files, documentation roots. Pass 2 — Stack and toolchain Read whichever of these exist (don't fail on missing files): File What to extract ------ ---------------- package.json / package-lock.json runtime + dev deps, scripts pyproject.toml / requirements.txt / Pipfile Python stack go.mod Go module + dependencies Cargo.toml Rust crate pom.xml / build.gradle JVM stack Gemfile Ruby stack composer.json PHP stack .csproj / .sln .NET stack Dockerfile / docker-compose.yml container strategy .github/workflows/.yml / .gitlab-ci.yml / Jenkinsfile CI/CD chain .tf / .bicep / .yaml (in infra/) IaC / cloud provider Record: primary language, frameworks, major libraries, runtime version pins, test frameworks (note them — do NOT run them), build tool, package manager. Pass 3 — Entry points and key flows Read the top-level entry files surfaced (max 5–8 files; skim, don't exhaustively read). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aj-geddes/bmad-document-project