CortexBuild — Brownfield Onboarding Architecture (v0.1)¶

Looking to onboard your repo?

See the step-by-step Onboard Your Repo guide for the real, copy-pasteable commands. This page explains how the analyser works under the hood — the design of the multi-pass pipeline.

In plain English

To make AI agents respect an existing codebase, CortexBuild first studies it in several passes — counting what's there, mapping how it fits together, inferring conventions, and mining git history for pain. The output is a set of rules and reports that teach agents your team's unwritten standards.

How it works under the hood¶

Why brownfield is the wedge¶

Greenfield is solved (Lovable / Bolt / Replit / Cursor / V0). Brownfield is not. Every existing codebase has implicit conventions a generic agent will violate — making PRs that "look right" but break the team's tribal knowledge.

CortexBuild's onboarding extracts that tribal knowledge into machine-enforced rules so future agent work obeys it.

The 4-pass analyser¶

Runs once at project setup, then incrementally on every PR merge.

Pass 1 — Structural scan (fast, deterministic)¶

Tools: tokei, cloc, git, tree, find.

Outputs: - Language stats (LOC by language, ranked) - Framework detection (Django, Next.js, Rails, Spring, etc. via file fingerprints) - Module / package count and depth - Test framework + coverage % (if reports exist) - CI config detected (GitHub Actions, GitLab CI, Jenkins, etc.) - Dockerfile / k8s / Terraform presence - Database detected (via dependency files + migrations dir) - License (LICENSE file or SPDX detection)

Time: 60–90 seconds for 100k LOC.

Pass 2 — Graph extraction (your existing `graphify` pattern)¶

Tool: Port of CortexVigil's graphify → cortexbuild_core/analyser/graph.py.

Outputs: - Per-file: function/class definitions - Per-symbol: call graph (who calls whom) - Module dependency graph - Community detection (Louvain) → architectural clusters - God-node detection (highest betweenness centrality) - Cross-community bridges (likely abstraction boundaries)

Time: 2–4 minutes for 100k LOC.

Pass 3 — Convention inference (LLM-driven, expensive)¶

For each architectural cluster identified in Pass 2:

Sample the top 5 god-nodes by community
Feed to Critic-tier model with prompt: "Identify recurring conventions used in these files. Return YAML with: auth_pattern, error_handling, logging_pattern, naming_conventions, test_fixture_pattern, sql_safety, secret_handling."
Collate across clusters into project-level conventions
For each detected convention, emit a draft rule fragment

Example inferred rule:

---
id: rule-inferred-error-handling-pattern
severity: medium
source: brownfield-analyser
confidence: 0.78
applies_to: [builder, pr-reviewer]
---

# Error Handling Convention (inferred from existing code)

This codebase wraps API route handlers in `@with_error_handling` decorator
(found in 87 of 102 routes). New routes MUST follow the same pattern unless
explicitly justified.

## Example uses
- src/api/users.py:42
- src/api/orders.py:18

The rule's Builder gate is a separate shell check:

grep -L "with_error_handling" src/api/*.py
# Any file without the decorator → flag for review

Convention inference is opt-in and propose-only

Pass 3 runs only when you pass --with-rule-synthesis with an LLM provider configured and CORTEXBUILD_LLM=1. It proposes draft rules for review — it never auto-enforces inferred rules. In Phase 0 the graph pass that feeds it is Python-only.

Time: 5–15 minutes for 100k LOC (cost: ~$5–$20 per onboarding using Opus).

Pass 4 — Pain-point mining (git log analysis)¶

Inputs: Last 12 months of git log.

Outputs: - Hotfix clusters — files appearing in commits with hotfix:, fix:, urgent: prefixes, grouped - Revert clusters — files appearing in or surrounding Revert commits - Rollback clusters — files touched within 24h of a tag/release rollback - Coupling pairs — pairs of files that get edited together > N times - Author hotspots — files touched by only 1 author (bus-factor risk) - Age vs change rate — old files with high churn (modernisation candidates) - Death-by-1000-cuts files — files in top 5% of total commits

Outputs become the Technical Debt Heatmap shown to the user.

Time: 3–5 minutes for a 5-year repo.

Output: the `.cortexbuild/` directory written to the repo¶

init run writes artefacts to .cortexbuild/ (lowercase). This is the real Phase 0 layout produced today:

.cortexbuild/
├── ONBOARDING.md              # human-readable onboarding summary — start here
├── manifest.json              # machine manifest of what was generated
├── recurrence-ledger.yaml     # feedback-loop ledger (empty at start; grows)
├── rules/
│   ├── foundational/          # 43 always-on rules
│   └── adaptive/              # only the rules triggered by detected traits
└── analysis/
    ├── structural.json        # Pass 1 (raw)
    ├── STRUCTURAL_REPORT.md   # Pass 1 (human-readable)
    ├── graph.json             # Pass 2 (raw, queryable; Python-only)
    ├── GRAPH_REPORT.md        # Pass 2 (human-readable)
    ├── debt-heatmap.json      # Pass 4 (raw)
    └── DEBT_HEATMAP.md        # Pass 4 (human-readable)

Design target vs. today

Earlier design drafts also envisioned registry.yaml, a rules/inferred/ folder, a modernisation-roadmap.md, and a pre-rendered/ copy of each tool surface inside .cortexbuild/. In Phase 0, rendering writes directly to the tool surfaces at the repo root (.github/, CLAUDE.md, AGENTS.md, .cursor/) via cortexbuild render — not into a nested rendered/ folder. Treat those extra entries as forward-looking design targets, not current output.

Interview gates (Pass 5 — interactive)¶

After Pass 4 completes, UI presents:

Technical debt heatmap with annotations: "35 files appear in hotfix commits >5 times. Modernise these first?"
Confirmation of inferred conventions — "We detected that you wrap all API handlers in @with_error_handling. Make this a rule?"
[Yes — enforce] [No — too strict] [Yes but only for new code]
Goals interview — "What's your primary goal for the next 3 months?"
Modernise tech stack
Increase test coverage
Reduce production incidents
Burn down feature backlog
All of the above
Risk tolerance —
Aggressive: agents merge low-risk PRs autonomously
Balanced: agents open PRs, you review and merge
Conservative: agents open draft PRs, you must approve each step
Connect issue tracker —
GitHub Issues (auto-detected)
Linear (OAuth)
Jira (OAuth)
Skip

User's answers parameterise the rule pack and the approval matrix.

Re-analysis (incremental)¶

On every PR merge into the default branch:

Diff vs previous graph
Update graph.json deltas only
If new files detected, re-run Pass 3 on them
If hotfix/revert/rollback commits detected, append to debt heatmap
If recurring failure class detected (≥2 occurrences in ledger), propose new inferred rule

When inference is wrong¶

Every inferred rule has confidence and source: brownfield-analyser. User can:

Promote (mark confidence: 1.0, source: user-confirmed)
Demote (mark severity: low, treat as advisory only)
Discard (delete; analyser remembers not to suggest again)

Discarded inferences are tracked in .cortexbuild/analysis/discarded-suggestions.yaml so the analyser doesn't churn.

Privacy / scope of analysis¶

Pass 1 is fully local (no LLM)
Pass 2 is fully local (no LLM)
Pass 3 sends only sampled file content to the LLM (never full repo)
Pass 4 sends only commit messages and file paths to the LLM
All LLM calls go through the user's provider key
Analysis outputs are pushed to the user's repo only — CortexBuild retains no copy of source code on its servers

SLA targets¶

Pass	Time (100k LOC)	Cost (Opus)
1. Structural	60–90 s	$0
2. Graph	2–4 min	$0
3. Convention inference	5–15 min	$5–$20
4. Pain-point mining	3–5 min	$1–$3
5. Interview	depends on user	$0
Total to "ready for work"	~30 min	$6–$23