Brownfield

Add aidokit to a project that already has source code, docs, a PRD, or a README. The CLI scans, ingests, and integrates — it never overwrites.

The ingestion pipeline

Brownfield init runs a digest sub-stage before any write. Existing inputs land in the agent-artifacts tree where the workflow's planning roles will read them.

flowchart LR classDef in fill:#f0fdf4,stroke:#15803d,color:#14532d; classDef proc fill:#eff6ff,stroke:#2563eb,color:#0f172a; classDef out fill:#fffbeb,stroke:#b45309,color:#78350f; PRD["README, PRD, BRD"]:::in SRC["src/ + lockfiles"]:::in DOCS["existing docs/"]:::in GIT["git history"]:::in D[digest sub-stage
read-only, no LLM]:::proc Detect[stack-detect]:::proc ART[agent-artifacts/
digest-reports/]:::out AD[.aido/
brownfield-inputs.json]:::out CL[CLAUDE.md draft
with source-of-truth chain]:::out PRD --> D SRC --> Detect --> D DOCS --> D GIT --> D D --> ART D --> AD D --> CL

Figure 1. Nothing under src/ or existing docs/ is rewritten. The digest is a separate read-only artifact the planning roles consult.

What "brownfield" means here

A project is brownfield to aidokit when any of these are present:

Existing source code (src/, language manifests, lockfiles).
Existing PRD, BRD, or README content that describes the product.
Existing docs/ with architectural documentation.
An existing git history.

Bootstrap

shell

cd my-existing-project
npx aidokit@alpha init --brownfield

Or non-interactive:

shell

npx aidokit@alpha init --brownfield --yes \
  --adapter claude-code --conformance standard \
  --source-docs docs/inputs/

What happens

The CLI scans the project root and reports detected signals: stack, package manager, source-doc inventory.
You confirm which source docs to ingest as workflow inputs.
The CLI emits the engine directory + agent rules file as normal.
The shared docs/ skeleton is emitted only for files that don't already exist. Your existing files are preserved.
Ingested source docs are linked from the rules file so the agent uses them as context.
The brownfield: true flag is recorded in .aido/adapter.md.

What it does not do

It does not rewrite your existing code.
It does not overwrite your existing README.md, CHANGELOG.md, or any file outside the adapter's declared writesPaths.
It does not move files around. If your docs are in an unusual layout, aidokit works around them.
It does not re-run lint / typecheck / tests — the agent does that during /intake.

Recommended first session

Run aidokit init --brownfield.
Open the AI coding CLI.
Run /intake "ingest the source docs and produce an architecture summary".
Review the produced summary; adjust if needed.
Run /intake "plan the next change" for the actual feature work.

The first intake digests prior context into the workflow. Subsequent intakes plan work against that ingested context.

If you have a PRD or BRD

Drop it under docs/inputs/ (or pass --source-docs <path>) before init. The CLI records it in the source-doc inventory; the first /intake will read it and produce a capability decomposition.

Multi-adapter brownfield

shell

npx aidokit@alpha init --brownfield --adapter claude-code,codex

Same brownfield ingestion logic; both engine directories are written.

Caveats

You may need to adjust the rules file. The emitted CLAUDE.md (or equivalent) reflects best-guess validation commands. Open it and tune to your actual scripts after init.
Existing test failures don't disappear. The agent will encounter them when it tries to validate changes. Fix them or document them as known-broken before serious work.
Existing TODOs and FIXMEs are not auto-tasked. Run /intake with explicit prompts to surface and triage them into Beads.

Migrating from a prior kit version

If your project was set up with the v3 kit (predecessor of aidokit):

shell

npx aidokit migrate v3-to-v4 --backup-dir .aido-backup
# Review .aido-backup-<ts>/ for original files.
# Read scripts/migration-review.md for items needing manual review.