---
name: aj-geddes/bmad-document-project
source: https://app.decimal.ai/s/aj-geddes-bmad-document-project@1/SKILL.md
source_sha256: 7564c0f0b1a2
---

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