deepfield

Deepfield

An AI-driven knowledge base builder for understanding brownfield projects.

Overview

Deepfield is a monorepo containing:

• CLI Tool: Standalone command-line tool for universal knowledge base management
• Claude Code Plugin: AI-assisted integration wrapping the CLI with specialized skills

Together, they help you understand brownfield projects through structured exploration. Feed it sources (code, docs, wikis, tickets) and it will:

• Learn iteratively: AI reads, connects dots, identifies gaps → you provide more sources or feedback → repeat until knowledge is sufficient
• Decompose domains: Auto-detects project domains and focuses learning per domain
• Trust hierarchically: Prioritizes running code > git history > tickets > tests > comments > docs
• Scan incrementally: Only reads changed/new files across runs
• Document gaps honestly: Always documents what it doesn't know (unknowns.md)
• Freeze snapshots: Version knowledge at any point, continue learning after
• Use robust scripts: Critical operations use tested scripts, not AI generation

Use Cases

Scenario	Primary Sources	Focus
Legacy codebase takeover	Git repo, old wiki, tribal knowledge	Architecture, data flow, deployment
New team onboarding	Internal docs, repo, meeting notes	Glossary, conventions, business logic
Vendor system integration	API docs, SDK, sample code	API surface, auth, error handling
Compliance audit	Policy docs, codebase, configs	Data flow, access controls, PII
Monolith decomposition	Monorepo, DB schemas, configs	Domain boundaries, coupling, state

Installation

Prerequisites

• Node.js 18+ and npm
• Claude Code 2.1.69+ (required for plugin installation via marketplace)
• Git (optional, for git repository features)

CLI Only (Universal Usage)

For Published Package (Coming Soon):

Install the CLI globally:

npm install -g deepfield

Or install locally in a project:

npm install --save-dev deepfield

For Local Development/Testing:

# Clone the repository
git clone https://github.com/TomazWang/deepfield.git
cd deepfield

# Install dependencies
npm install

# Build the CLI
npm run build

# Link CLI globally
cd cli && npm link

# Verify installation
deepfield --version

# If 'command not found', add npm global bin to PATH:
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Now you can use deepfield or df commands anywhere.

With Claude Code Plugin (via Marketplace)

Requires Claude Code 2.1.69+. Update with claude update if needed.

Add the marketplace and install the plugin:

/plugin marketplace add TomazWang/deepfield
/plugin install deepfield@deepfield

That's it. The plugin is now available in Claude Code with all df-* commands.

To get future updates:

/plugin marketplace update deepfield

With Claude Code Plugin (manual)

1. Install CLI (see above)

2. Link plugin to Claude Code:

# Clone or navigate to deepfield repo
cd deepfield

# Build the project
npm install
npm run build

# Link plugin to Claude Code
ln -s $(pwd)/plugin ~/.claude/plugins/deepfield

3. Verify plugin is linked:

ls -la ~/.claude/plugins/deepfield
# Should show a symlink to your plugin directory

4. Restart Claude Code to load the plugin

Quick Start

Using the CLI

# Initialize knowledge base structure
deepfield init

# Configure your project interactively
deepfield start

# Check current status
deepfield status

Using Claude Code Commands

/df-init    - Initialize deepfield/ directory
/df-start   - Start interactive project setup
/df-status  - Display current state

Commands

deepfield init (or df init)

Initialize the deepfield/ directory structure:

• source/ - Source materials and baselines
• wip/ - Work in progress (active runs)
• drafts/ - Draft documents and notes
• output/ - Final knowledge base artifacts

Options:

• -f, --force - Overwrite existing files
• -y, --yes - Skip confirmation prompts

deepfield start (or df start)

Run interactive setup to configure your project:

• Asks about project type (legacy, onboarding, documentation, etc.)
• Collects project goals and focus areas
• Creates project.config.json
• Pre-fills brief.md template

deepfield status (or df status)

Display current project state:

• Workflow state (EMPTY, INITIALIZED, CONFIGURED, READY, etc.)
• Project information (name, goal, focus areas)
• Last modified timestamp
• Suggested next action

Options:

• -v, --verbose - Show detailed information

Architecture

Four-Space Design

source/     → Raw inputs (baseline + per-run)
wip/        → AI's private workspace (notes, maps, plans)
drafts/     → Living documents that evolve each run
output/     → Frozen versioned snapshots