dsp-brownfield

DSP Brownfield Workflow

Use this workflow when integrating DSP into an existing codebase. Bootstrap runs as three flat waves over fixed file batches — no recursion, no graph traversal. Core economy rule: each file is read exactly once, by exactly one subagent; all three waves run on top of that single read.

Phase 0: Initialize and Discover Roots

dsp-cli init

Identify entrypoints and the directory zone (scope) each one covers:

dsp-cli create-object backend/src/main.ts "Backend entry — <brief project overview>" --new-root --scope backend
dsp-cli create-object frontend/src/main.tsx "Frontend entry" --new-root --scope frontend
# single-root project: one root with --scope .

Scopes make TOC assignment automatic: every entity created later lands in all TOCs whose root scope covers its path — no --toc needed in the waves below.

Inventory and Batching

Before reading any file content: list all files with sizes (git ls-files | xargs wc -c; skip vendored code, build output, lock files), group them by TOC, and split each group into batches of roughly equal total volume (not file count). One batch = one subagent; run batches in parallel. Each subagent executes Waves 1–3 over its own files. No subagents available → process batches sequentially, keeping per-file notes from the Wave 1 read — each file is still read only once.

Wave 1: Index All Files

Each subagent reads each file of its batch once — capturing purpose, inner entities, exports, and imports with usage sites — then registers it:

dsp-cli create-object src/auth/jwt.service.ts "JWT token generation and validation"
dsp-cli create-function "src/auth/jwt.service.ts#signToken" "Signs access tokens" --owner <jwt-uid>

Place @dsp <uid> markers before inner-entity declarations. Resume-safe: run dsp-cli find-by-source <path> first and skip files that already have entities. If the code already carries @dsp markers from a previous graph, keep identities with --uid <old-uid>.