Getting Started · 1.6

Brownfield agent prompt

The prompt that has your coding agent read an existing codebase and write a report you import into IntentDocs, and the report format it follows.

If you already have a codebase, your coding agent can read it for you. Run the prompt below in Claude Code, Cursor or any agent that can read your repository. It writes one markdown report. You review it, then import it: the features it lists become stories on your map, and its product summary answers the first vision question.

This is the same prompt the app shows at the Vision step of a project started with I have an existing codebase, under Have an existing codebase? Skip ahead. It is also in the Prompt library as Map an existing codebase.

The prompt

Nothing leaves your machine when the agent runs it. The prompt calls no IntentDocs API. The only output is a file on disk, which you upload yourself.

You're helping a founder connect this codebase to IntentDocs, a tool that turns a product into a structured, buildable spec. Read this repository and produce ONE markdown document reporting what you find — nothing else.
 
## What you will read
- Source files, package manifests (package.json, requirements.txt, Cargo.toml, etc.), and config files
- Database schema and migration files
- README / existing docs / ADRs
- Git history, only if useful for dating architecture decisions
 
## What you must NOT include
- Secrets, API keys, tokens, or credentials of any kind
- Values from .env / .env.local or any environment file — reference that a variable exists by name only, never its value
- Personal data found in seed data or fixtures
 
## What leaves this machine
Nothing, until the founder chooses to. You are running locally against a local checkout. This prompt does not call any IntentDocs API, upload anything, or transmit anything anywhere. The only output is the markdown file you write to disk. The founder reviews it and uploads it themselves through the IntentDocs brownfield report flow — that upload is the only point at which anything leaves their machine.
 
## Output format
Write the report as a single markdown file. Start with front-matter carrying the schema version, then exactly these sections, in this order, using these exact headings:
 
```
---
schema_version: 1
generated_at: <ISO 8601 timestamp, e.g. 2026-09-03T00:00:00Z>
source_repo: <repo name or local path, whatever identifies it to the founder>
---
```
 
- `## Product summary` — What the product does today, who it's for, and its current state (live, in development, dormant). 1-3 paragraphs.
- `## Tech stack` — Languages, frameworks, datastores, infra/deploy target, and notable third-party services — as a list, not prose.
- `## Architecture decisions` — Notable structural or technical decisions already baked into the codebase, and why they were made where that's discoverable (comments, ADRs, commit messages).
- `## Existing features` — Every user-facing capability the codebase already implements, one per bullet, written as a short capability statement (e.g. "Users can reset their password via emailed link") so it can seed story-map stories.
- `## Data model` — Core entities/tables and how they relate — schema definitions, migrations, or ORM models are the primary source.
- `## Constraints & invariants` — Business rules, technical limits, and things that must not break — auth boundaries, rate limits, data invariants, compliance requirements.
 
Every section must be present and non-empty — an upload with a missing or empty section will be rejected. Do not add a schema_version other than 1; that number is what lets IntentDocs tell your output apart from a report generated by a future, incompatible version of this prompt.
 
Save the file as `intentdocs-brownfield-report.md` in the repository root, then hand it to the founder to review and upload.

The report format

The report is a markdown file: front-matter with a schema_version, then six ## sections with these exact headings.

Current schema version: 1

Section	Contains	Used for
`## Product summary`	What the product does today, who it's for, and its current state.	The answer to Who are your users?
`## Tech stack`	Languages, frameworks, datastores, deploy target and third-party services, as a list.	Kept with the import as context.
`## Architecture decisions`	Structural decisions already in the code, and why, where that's discoverable.	Kept with the import as context.
`## Existing features`	Every user-facing capability, one per bullet.	One story per bullet.
`## Data model`	Core entities and how they relate.	Kept with the import as context.
`## Constraints & invariants`	Business rules, limits and things that must not break.	Kept with the import as context.

The version exists so a format change can deliberately turn away a report from an older copy of the prompt instead of misreading it. If your upload is refused for its schema_version, run the current prompt again.

Import the report

Read intentdocs-brownfield-report.md yourself first. It should never contain secrets or .env values, but check before anything leaves your machine.
On the project's Vision step, open Already have a report?.
Upload the file, or paste its contents, and choose Preview import. The preview writes nothing.
Check the preview: the vision answer it will fill, each story marked New or Update, and anything under Won't be populated.
Choose Confirm import, or Cancel.

Stories land under an activity called Existing functionality (from brownfield report). Importing the same report again updates those stories rather than duplicating them.

A report is refused outright only when its front-matter or schema_version is missing or wrong. A missing or empty section is imported as far as it goes, and the preview names what's missing.

Note: a report can't answer the other four vision questions: the problem, what makes people switch, the first release, and how you'll know it's working. The preview lists them under Vision questions to answer yourself. Answer them on the Vision step.

Let your agent import it

An agent connected over MCP can import the report itself:

set_vision with report fills the vision answer the report can give. It asks for confirm: true before replacing an answer that's already there.
create_stories with report creates one story per Existing features bullet.

Your agent should tell you what it's about to change and wait for a yes first.