Brownfield: Adopting the Toolkit¶

This guide is for teams with existing projects developed using traditional methods who want to adopt the toolkit's spec-driven workflow. If you're starting a brand-new project, see Greenfield: Your First Project instead.

Prerequisites¶

Toolkit installed — see Installation for your platform
An existing project — with code, requirements docs, or both

Automated Detection (Recommended)¶

Running /0-init in an existing codebase automatically detects brownfield projects and routes to the appropriate workflow based on codebase size. This is the simplest path — just run the init command and follow the prompts.

Small/medium codebases (<500 source files): Document-First — analyzes the codebase, generates CLAUDE.md and architecture docs, then routes to /vt-c-pd-2-prd
Large codebases (>500 source files): PRD-First — asks which module you're targeting, performs focused analysis, then routes to /vt-c-pd-2-prd
Skip analysis: /0-init --skip-analysis for developers who already know the codebase

The manual approaches below are available for advanced users who need more control over the onboarding process.

Choose Your Approach (Manual)¶

There are three manual approaches to adopting the toolkit for existing work. Pick the one that fits your situation.

Approach	Best when	Complexity
A: Separate Workflow Repo	Large codebase, multiple teams, want clean separation	Low
B: Adopt In-Place	Small-to-medium project, single team, single repo	Medium
C: OneDrive Folder	Non-technical stakeholders, design-phase only, no Git comfort	Low

Approach A: Separate Workflow Repo (recommended)¶

Create a dedicated repo for workflow management and specs. Your existing code repo stays untouched until you're ready to start development with the toolkit.

Step 1: Create the workflow repo¶

mkdir my-project-workflow && cd my-project-workflow && git init
claude

Inside Claude Code:

/vt-c-scaffold design my-project

This creates the project structure with CLAUDE.md, PRODUCT-VISION.md, PRD.md, and organized directories for specs, docs, and inbox.

Step 2: Import existing context¶

Gather your existing requirements, design docs, architecture notes, meeting minutes, and any other relevant materials. Copy them into the workflow repo:

cp /path/to/existing-docs/*.md 00-inbox/
cp /path/to/existing-docs/*.pdf 00-inbox/

What to include

Requirements documents, user stories, or feature lists
Architecture diagrams or technical specs
Stakeholder emails or meeting notes with key decisions
Screenshots or mockups of the existing application
README or wiki content from the code repo

Step 3: Create a PRD from existing materials¶

In Claude Code, point the PRD skill at your imported context:

/vt-c-pd-2-prd

Tell Claude about the documents in 00-inbox/ and ask it to synthesize a PRD. The skill will create a structured Product Requirements Document that captures what your project already does and what's planned.

Step 4: Generate specs from the PRD¶

Once the PRD is ready, break it into implementation-sized feature specs:

/vt-c-specs-from-prd

Or create specs directly from specific requirements:

/vt-c-spec-from-requirements "Add webhook support for order notifications"

Step 5: Start the development workflow¶

With specs in place, you can now use the full development workflow. When you're ready to implement a spec in your code repo:

Open your code repo in Claude Code
Run /vt-c-repo-init --adopt to add lightweight governance (see What changes in your code repo below)
Run /vt-c-activate to see your spec dashboard and pick a spec to implement
Follow the standard phases: /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-5-finalize

When to use this approach¶

Your code repo is large or has many contributors — you don't want to add workflow files there
Multiple teams work on the same codebase but with different specs
You want to keep product/design artifacts cleanly separated from code
You're evaluating the toolkit before committing to full adoption

Approach B: Adopt In-Place¶

Add the toolkit workflow directly to your existing code repo. Best for smaller projects or when you want everything in one place.

Step 1: Initialize governance¶

Navigate to your project and start Claude Code:

cd my-existing-project
claude

Run the adoption scan:

/vt-c-repo-init --adopt

This scans your existing artifacts (code in src//apps/, any existing specs, git history) and sets up governance with a traceability cutoff — pre-existing commits are exempt from the toolkit's quality gates.

Step 2: Create a PRD¶

If you don't have a formal PRD yet:

/vt-c-pd-2-prd

Point Claude at your existing README, wiki, or any requirements docs. It will synthesize a structured PRD.

Step 3: Generate specs and start building¶

/vt-c-spec-from-requirements "Describe the feature or area you want to work on next"

Then activate and follow the standard workflow:

/vt-c-activate

When to use this approach¶

Small-to-medium project with a single team
You want specs and code in the same repo
You're comfortable with the toolkit adding a few config files to your repo

Approach C: OneDrive Folder¶

Use a shared OneDrive folder instead of a Git repo. The product design workflow natively supports OneDrive project structures.

Step 1: Create the folder structure¶

Create a project folder in your team's OneDrive:

OneDrive/VisiTrans - Dokumente/1-VisiTrans-intern/
└── My-Project/
    ├── 00-inbox/
    ├── 01-docs/
    ├── 03-PRD/
    ├── 04-prototyp/
    └── 05-specs/

Step 2: Work with Claude Code¶

Open the folder in your terminal or VS Code and start Claude Code. The product design skills (/vt-c-pd-0-start through /vt-c-pd-6-handoff) detect OneDrive folder structures and work with mv instead of git mv.

cd ~/Library/CloudStorage/OneDrive-VisiTransGmbH/VisiTrans\ -\ Dokumente/1-VisiTrans-intern/My-Project
claude

Limitations¶

Feature	OneDrive	Git repo
PRD creation (`/vt-c-pd-2-prd`)	Yes	Yes
Spec generation (`/vt-c-spec-from-requirements`)	Yes	Yes
Product design phases (pd-0 through pd-6)	Yes	Yes
Code review (`/vt-c-4-review`)	No	Yes
Branch-based parallel work	No	Yes
Version history	OneDrive built-in only	Full git history
Quality gates and hooks	No	Yes

Transition to Git when ready

Many teams start with OneDrive for the design phases (research, PRD, prototyping) and transition to a Git repo when development begins. Move your PRD and specs from OneDrive into a new Git repo, then follow Approach A from Step 4.

What Changes in Your Code Repo¶

Running /vt-c-repo-init --adopt adds these files to your existing repo:

File	Purpose
`.repo-manifest.yaml`	Partition definitions (deployable, context, sandbox)
`.gitattributes`	LFS tracking rules for binary files

It does not move, rename, or restructure any existing files. Pre-existing commits are exempt from the toolkit's quality gates via a traceability cutoff date.

Importing Existing Context¶

There is no single-click "import everything" skill. The recommended workflow:

Collect — gather all existing docs (requirements, design, architecture, wiki) into 00-inbox/
Synthesize — run /vt-c-pd-2-prd and reference the inbox contents as input material
Decompose — run /vt-c-spec-from-requirements for each identified feature area
Activate — run /vt-c-activate to see your spec dashboard and start building

Choosing Between Approaches¶

graph TD
    Q1["Do you use Git?"]
    Q1 -->|No| C["Approach C: OneDrive Folder"]
    Q1 -->|Yes| Q2["Keep specs separate from code?"]
    Q2 -->|Yes| A["Approach A: Separate Workflow Repo"]
    Q2 -->|No| B["Approach B: Adopt In-Place"]
    A --> DEV["Development: /vt-c-activate → /vt-c-2-plan → ... → /vt-c-5-finalize"]
    B --> DEV
    C -->|"When ready for development"| A

What's Next¶

Team Onboarding — get your team set up with the toolkit
Two Workflows — understand the full workflow architecture
Development Workflow — deep-dive into the 7 development phases