How the Ouroboros Brownfield Explorer Scans 15 Config File Types Across 12+ Ecosystems

The Ouroboros Brownfield Explorer detects existing projects by scanning for 15+ configuration file types across 12+ language ecosystems using a curated catalog in _CONFIG_FILES, then aggregates tech stack data and key type definitions into a Markdown prompt for AI-assisted interviews.

The Brownfield Explorer is a core component of the Q00/ouroboros repository designed to automatically discover context from existing codebases. Unlike greenfield project generators, this engine identifies "brownfield" projects—those with existing source files and build artifacts—by recognizing ecosystem-specific configuration patterns and extracting architectural context for downstream AI interviews.

The Config File Catalogue (_CONFIG_FILES)

At the heart of the scanning process lies a comprehensive dictionary that maps well-known build and dependency files to their corresponding technology stacks.

Mapping 15+ File Types to Tech Stacks

In src/ouroboros/bigbang/explore.py, the _CONFIG_FILES dictionary (lines 28-45) serves as the single source of truth for ecosystem detection. This curated list covers 15+ file types spanning Go (go.mod), Rust (Cargo.toml), JavaScript/TypeScript (package.json), Python (requirements.txt, pyproject.toml), Java/Kotlin (pom.xml, build.gradle), Ruby (Gemfile), Elixir (mix.exs), PHP (composer.json), and C/C++ (CMakeLists.txt, Makefile) ecosystems.

Each entry pairs a filename with a human-readable technology label, enabling the explorer to immediately identify the primary language when it encounters a recognized manifest in the project root.

Brownfield Detection and Tech Stack Inference

Once the catalog is loaded, the explorer executes a two-phase detection process to confirm brownfield status and extract detailed context.

Detecting Existing Projects with detect_brownfield

The detect_brownfield function (lines 80-94 in explore.py) iterates over the keys of _CONFIG_FILES and checks for file existence within the supplied directory using Path.exists(). The presence of at least one recognized configuration file signals a brownfield project, triggering the full exploration pipeline rather than treating the directory as a blank slate.

Inferring Technology Stacks

After confirming brownfield status, scan_directory performs a secondary pass through _CONFIG_FILES to build a comprehensive tech stack profile. For each matching file found, the function records the associated language label (e.g., go.mod maps to "Go", package.json maps to "JavaScript/TypeScript"). This yields a concise "Tech Stack" string that appears in the final interview prompt, informing the AI about the project's architectural foundation.

Deep Code Analysis with Type Patterns

Beyond manifest detection, the explorer performs content analysis to identify key architectural components within the source code.

Source File Discovery (_TYPE_PATTERNS)

Following tech stack identification, the explorer loads glob patterns specific to each language (lines 47-62 in explore.py). The _TYPE_PATTERNS dictionary maps ecosystem labels to file extensions—such as *.go for Go, *.py for Python, and *.rs for Rust—enabling the system to locate relevant source files without parsing directory trees blindly.

Extracting Key Type Definitions (_TYPE_DEF_PATTERNS)

For architectural context, the explorer utilizes _TYPE_DEF_PATTERNS (lines 64-107 in explore.py), which contains regular-expression patterns tailored to each language's syntax. These patterns capture struct, class, interface, enum, and constant definitions. The system runs a fast content search via Read, Glob, and Grep operations on discovered files, collecting "key types" that represent the project's core data models and abstractions.

Aggregating Results for AI Context

All collected data converges in format_explore_results (lines 998-1021 in explore.py). This function aggregates the tech stack, discovered dependencies, and extracted key types into a structured Markdown block. The resulting snippet is injected into the system prompt during the interview phase (src/ouroboros/bigbang/interview.py, lines 214-225), enabling the AI to ask informed questions about existing architecture rather than proposing redundant scaffolding.

Implementation Example

The following example demonstrates how to invoke the Brownfield Explorer on an existing project:

from pathlib import Path
from ouroboros.bigbang.explore import detect_brownfield, scan_directory, format_explore_results

project_root = Path("/my/existing/app")

# 1️⃣ Detect brownfield status

if detect_brownfield(project_root):
    # 2️⃣ Run full exploration

    results = scan_directory(project_root)          # returns List[CodebaseExploreResult]

    prompt_section = format_explore_results(results)
    print(prompt_section)                          # inject into interview prompt

else:
    print("No known config files – treating as greenfield.")

Running the above on a directory containing package.json and a src/*.ts folder produces a prompt snippet such as:

### [PRIMARY] /my/existing/app

Tech: JavaScript/TypeScript
Deps: react, lodash, axios
Key Types:
- class App
- interface Config

Summary

• The Brownfield Explorer uses a curated _CONFIG_FILES dictionary in src/ouroboros/bigbang/explore.py to recognize 15+ configuration file types across 12+ ecosystems including Go, Rust, Python, and Java.
• detect_brownfield (lines 80-94) confirms existing projects by checking for the presence of known manifest files.
• scan_directory infers technology stacks by mapping discovered config files to language labels, while _TYPE_PATTERNS and _TYPE_DEF_PATTERNS (lines 47-107) enable deep source code analysis.
• format_explore_results (lines 998-1021) aggregates findings into Markdown blocks injected into AI interview prompts via the orchestrator adapter.

Frequently Asked Questions

How does the Brownfield Explorer handle polyglot repositories containing multiple config files?

The explorer treats the presence of any recognized config file as a brownfield signal, and scan_directory aggregates all detected technologies into a combined tech stack string. A project containing both go.mod and package.json would report "Go, JavaScript/TypeScript" in the final prompt, allowing the AI to understand cross-language dependencies.

What specific file types does the _CONFIG_FILES dictionary recognize?

According to the source code in explore.py (lines 28-45), the dictionary recognizes ecosystem manifests including go.mod, Cargo.toml, package.json, requirements.txt, pyproject.toml, pom.xml, build.gradle, Gemfile, mix.exs, composer.json, CMakeLists.txt, and Makefile, covering the majority of modern language ecosystems.

How does the explorer extract type definitions without full parsing?

Rather than implementing language-specific parsers, the explorer uses _TYPE_DEF_PATTERNS—a collection of regular expressions (lines 64-107 in explore.py)—to perform fast text searches for struct, class, interface, and enum declarations. This lightweight approach avoids heavy AST parsing while still capturing key architectural signatures.

Where does the brownfield context appear in the AI interview process?

The formatted results from format_explore_results are injected into system prompts by the orchestrator adapter (src/ouroboros/orchestrator/adapter.py, lines 98-112). This occurs when state.is_brownfield evaluates to true in interview.py (lines 214-225), ensuring the AI receives codebase context before generating interview questions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}