Skip to main content
skill CX Codex

bmad-document-project — Claude Code skill: what it does

The bmad-document-project Claude Code skill scans an existing codebase in read-only mode to generate project-documentation.md. It maps runtime dependencies and entry points before downstream planning.

MIT 104 installs ★ 493 updated 2026-06-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-document-project -a claude-code
Open on GitHub

What bmad-document-project does

The skill reads through a brownfield codebase using directory globs and regex searches, compiling an architectural reference document. It executes six distinct passes: mapping directory layout, reading package manifests, identifying application entry points, delineating module boundaries, identifying code conventions, and logging external integrations such as databases or message queues.

Operation is split into three intents: initial creation, targeted updates for changed subsystems, and completeness validation. Missing components receive an explicit <!-- not detected --> marker so that details are never fabricated.

Source files remain untouched throughout the process. The skill restricts execution strictly to file reading and progress tracking, never running test suites or build scripts, and only writes to bmad-output/project-documentation.md.

What it helps with

  • extract architecture and dependency maps from an existing codebase
  • catalog external APIs, databases, and background queues
  • create a factual baseline document prior to drafting a PRD
  • validate that project documentation covers all critical application layers

Example prompts for the agent

  • Document this codebase before we plan the new architecture
  • Update the project documentation for the altered authentication flow
  • Validate bmad-output/project-documentation.md for missing sections

How to install bmad-document-project

1Skills CLI (Vercel)

npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-document-project -a claude-code

2Manually: put the files in place

~/.claude/skills/bmad-document-project/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bmad-document-project/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bmad-document-project

How to install bmad-document-project in Claude Code?

Run npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-document-project -a claude-code in your terminal.

What does bmad-document-project do?

It analyzes project structure, dependencies, and external services to compile a current-state snapshot into bmad-output/project-documentation.md.

Does bmad-document-project modify application code?

No. It operates in read-only mode across your source tree and only writes to the specified markdown output file.

Source text

SKILL.md · MIT
---
name: bmad-document-project
description: |
  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.
allowed-tools: Read, Glob, Grep, Write, TodoWrite
---

# 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**

```
Glob: **/* (depth ≤ 3, exclude node_modules, .git, dist, build, __pycache__, .venv)
Glob: *.md, *.txt, *.rst at root and docs/
```

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**

```
Grep: "main\|entrypoint\|app\.listen\|createServer\|handler\|router\|routes"
Grep: "export default\|module\.exports\|@app\.route\|@Controller\|@RestController"
```

Read the top-level entry files surfaced (max 5–8 files; skim, don't exhaustively read).

Capture: how the app starts, primary routing layer, authentication/middleware chain
(names only), background workers or queues detected.

**Pass 4 — Module / domain structure**

Read directory names and `index.*` / `__init__.*` files one level down from `src/`,
`app/`, `lib/`, or the equivalent.

```
Glob: src/**/index.{ts,js,py,go,rb}
Glob: app/**/__init__.py
```

Capture: module names and inferred responsibility, layer boundaries (controllers /
services / repositories / models / utils), shared utilities.

**Pass 5 — Conventions and patterns**

Sample 3–5 representative files per layer (prefer recently modified if discernible
from file names / path depth):

```
Grep: "class \|interface \|type \|enum " — naming style
Grep: "async \|await \|Promise\|goroutine\|concurrent" — concurrency pattern
Grep: "import \|require\|from " — module resolution style
Grep: "console\.log\|logger\.\|log\." — logging approach
Grep: "\.env\|process\.env\|os\.environ\|config\." — config/secrets pattern
```

Capture: naming conventions (casing style for files, classes, functions), error
handling style, logging approach, config/secrets management, test file location
convention (name only — no execution).

**Pass 6 — Integration points**

```
Grep: "http[s]\?://\|fetch(\|axios\.\|requests\.\|http\.Get\|RestTemplate"
Grep: "database\|db\.\|pool\.\|prisma\.\|mongoose\.\|sqlx\.\|gorm\."
Grep: "redis\|kafka\|rabbitmq\|sqs\|pubsub\|queue\|event"
Grep: "s3\.\|storage\.\|blob\.\|bucket"
```

Capture: external HTTP APIs called (domains/service names, not secrets), database
type and ORM/driver, message queues or event buses, object storage, third-party
services (payment, email, auth providers — names only).

**Write the document**

Fill `${CLAUDE_PLUGIN_ROOT}/skills/bmad-document-project/templates/project-documentation.template.md`
→ `bmad-output/project-documentation.md`.

Use the Write tool. Leave sections with a `<!-- not detected -->` comment rather
than inventing content. Accuracy over completeness.

---

### Update — re-scan changed areas

1. Read existing `project-documentation.md`.
2. Ask the user which areas changed (new module? new dependency? refactor?).
3. Re-run only the relevant passes above for those areas.
4. Edit the document surgically with precise rewrites of changed sections.
5. Append a dated update note at the bottom of the document.

Do NOT regenerate the full document from scratch if only part has changed.

---

### Validate — check completeness

Read the existing `project-documentation.md` and verify:

- [ ] All six scan areas have content (not blank or "not detected" for everything)
- [ ] Stack section names the primary language, framework, and major deps
- [ ] Entry points section names at least one bootstrap/start file
- [ ] Module structure lists recognizable domain names
- [ ] Conventions covers naming style and error handling
- [ ] Integration points lists external dependencies (or explicitly states "none")
- [ ] No fabricated file paths (cross-check one or two with Glob)

Report a pass/fail checklist. Offer to fill gaps rather than silently editing.

---

## Scope Boundary

This skill is READ-ONLY except for its single output document. It:

- Does NOT modify any source file.
- Does NOT run tests, build scripts, linters, or coverage tools.
- Does NOT generate application code, migration files, or fixtures.
- Does NOT implement features or review diffs.

If a scan reveals something worth fixing, record it as a planning note in the
document — do not fix it.

---

## Handoff

Once `project-documentation.md` is written, it becomes the brownfield input for:

- **bmad-init** — seed `project-context.md` with the detected stack and constraints.
- **bmad-prd** — ground truth for existing capabilities and integration constraints.
- **bmad-architecture** — baseline architecture to evolve rather than design from scratch.
- **bmad-tech-spec** (Quick Flow) — concrete starting point for a focused spec.

State the recommended next step when the document is ready.

---

## Persona Note

This analysis role aligns with Mary (Business Analyst) in the BMAD Method — start
with what exists before prescribing what should change. The document is her
field notes: precise, sourced, free of conjecture.

---

> ---
> Part of the **BMAD Planning & Orchestrator** plugin — a Claude Code harness for the **BMAD Method** by the **BMAD Code Organization** (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of `bmad-document-project`. All methodology credit belongs to the BMAD Code Organization.

© aj-geddes · MIT · aj-geddes/claude-code-bmad-skills

Similar skills

All skills for Writing and docs →

From the same set11

The whole set →
bmad-brainstorm bmad-brainstorm runs structured ideation sessions using SCAMPER, SWOT, and 5 Whys. Delivers an organized markdown report ready for project planning. CX Codex +1 130installs bmad-tech-spec bmad-tech-spec generates a focused tech spec for small-scope work instead of a full PRD and architecture pair. Use it when requirements are clear, scope fits 1-15 stories, and you need one planning artifact before writing stories. CX Codex +1 114installs bmad-spec The bmad-spec Claude Code skill turns rough notes, a PRD, or a transcript into a compact SPEC.md with five sections. It activates when a project needs a clear problem statement and scope. CX Codex +1 108installs bmad-readiness-check The bmad-readiness-check Claude Code skill checks whether planning documents agree before implementation starts. Ask for it to validate requirements, architecture, and epics for build readiness. CX Codex +1 107installs bmad-sprint-planning The bmad-sprint-planning Claude Code skill sorts stories by dependency and prepares a development handoff plan. Ask it to arrange stories, map parallel waves, or create sprint-status.yaml. CX Codex +1 104installs bmad-investigate The bmad-investigate Claude Code skill investigates bugs and turns findings into a case file. Invoke it to trace a reported failure, update an open investigation, or check a draft before handoff. CX Codex +1 102installs bmad-builder bmad-builder — a skill for Claude Code scaffolds and validates custom planning skills in the BMAD plugin. Generates folder trees and keeps instructions strictly inside planning boundaries. CX Codex +1 102installs bmad-init bmad-init — a skill for Claude Code sets up a BMAD planning workspace. Runs when starting a project to pick an adaptive track and scaffold planning files. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open