Skip to content

Onboard Your Repo

In plain English

This is the hands-on guide. You'll point CortexBuild at your repository, it will write an analysis into a .cortexbuild/ folder, you'll review the rules it proposes, and then render them into your AI tools. Every command below is real and copy-pasteable.

Pre-alpha

cortexbuild-core is 0.0.1 (Phase 0). If you haven't installed the CLI yet, do the dev install first.

What you'll do

  1. Run the onboarding pipeline
  2. Tour what you got
  3. Review & curate the rules
  4. Render the rules into your tools
  5. Start the feedback loop (ledger)
  6. Optional: project-context wizard & rule synthesis
  7. How to undo

Step 1 — Run the onboarding pipeline

Point init run at the repo you want to onboard. The <TARGET> can be a local path or a git URL.

# Local path — analyse a repo already on your machine
cortexbuild init run ./path/to/your-repo

# Git URL — clone and analyse a remote repo
cortexbuild init run https://github.com/your-org/your-repo.git

Useful flags:

Flag What it does
-o, --output-subdir Where artefacts are written (default .cortexbuild).
--output Output location for URL mode.
--depth Limit git-history depth mined for pain-points (faster on huge repos).
--skip-graph Skip Pass-2 graph extraction for a much faster first run.
--auto-commit Commit the generated .cortexbuild/ artefacts for you.
--with-memory Persist analysis into a memory backend.
--with-rule-synthesis Opt in to LLM convention inference (see step 6).

First run? Go fast.

For your very first pass, add --skip-graph to skip the dependency-graph step. You still get the structural scan, debt heatmap, and the foundational rule pack — enough to see the shape of the tool quickly.

Expected time & cost

The deterministic passes are local and free. The optional LLM convention inference is the only paid step. Rough targets for ~100k LOC:

Pass Time Cost
Structural scan 60–90 s $0
Graph extraction (Python via ast; JS/TS/Go via [graph]) 2–4 min $0
Pain-point mining 3–5 min $0
Convention inference (opt-in LLM) 5–15 min ~$5–$20

Without --with-rule-synthesis, onboarding is free and fully local.

Step 2 — Tour what you got

init run writes everything into .cortexbuild/ (lowercase) in your repo. Here's what each artefact tells you:

Path What it tells you
.cortexbuild/ONBOARDING.md Start here. Human-readable summary of the whole onboarding.
.cortexbuild/manifest.json Machine manifest of what was generated.
.cortexbuild/recurrence-ledger.yaml The feedback-loop ledger (empty at start; grows over time).
.cortexbuild/rules/foundational/ The 50 always-on foundational rules.
.cortexbuild/rules/adaptive/ Extra rules auto-enabled only when the analyser detected a matching trait.
.cortexbuild/analysis/structural.json Pass-1 structural scan (raw).
.cortexbuild/analysis/STRUCTURAL_REPORT.md Pass-1 structural scan (readable).
.cortexbuild/analysis/graph.json Pass-2 dependency graph (raw, queryable).
.cortexbuild/analysis/GRAPH_REPORT.md Pass-2 dependency graph (readable).
.cortexbuild/analysis/debt-heatmap.json Pass-4 technical-debt heatmap (raw).
.cortexbuild/analysis/DEBT_HEATMAP.md Pass-4 technical-debt heatmap (readable).

Read the three Markdown reports first — ONBOARDING.md, analysis/GRAPH_REPORT.md, and analysis/DEBT_HEATMAP.md. They are written for humans and orient you fast.

Note

analysis/graph.json / GRAPH_REPORT.md are produced by Pass-2 graph extraction (Python via the standard-library ast; JavaScript, TypeScript, and Go via the [graph] extra). If you used --skip-graph, those two files won't be present — that's expected.

Step 3 — Review & curate the rules

The foundational rules are a starting pack, not a verdict. Open .cortexbuild/rules/foundational/ and skim them. Each rule is a small Markdown file you can read in plain English.

  • Keep the rules that match how your team actually works.
  • Remove (delete the file) any rule that doesn't fit your codebase.
  • Check .cortexbuild/rules/adaptive/ too — those were auto-enabled because the analyser detected a matching trait (e.g. multi-tenant columns, real-time routes). Confirm each one is genuinely relevant.

You are the authority here: the rule pack is yours to edit before it reaches any AI tool.

Step 4 — Render the rules into your tools

Once you're happy with the rule set, render it out to every AI tool surface:

cortexbuild render

This writes the rule pack + agents to each tool's native format:

Tool Files written
GitHub Copilot .github/copilot-instructions.md + .github/agents/*.agent.md
Claude Code CLAUDE.md + .claude/agents/*.md
Codex AGENTS.md
Cursor .cursor/rules/*.mdc

Useful flags:

Flag What it does
-r, --repo-root Render against a different repo root.
--check CI drift gate — exits 1 if rendered files are stale (no writes).
--no-prune Don't delete rendered files that no longer have a source.
--separate-files Emit separate per-rule files where supported.

Wire --check into CI

Add cortexbuild render --check to your CI so a pull request fails if someone edits a rendered file by hand instead of the source rule pack.

Step 5 — Start the feedback loop (ledger)

The recurrence ledger is how CortexBuild learns: you record a class of defect once, and the pipeline watches for it thereafter. Initialise it:

cortexbuild ledger init

Then add an entry whenever a recurring problem shows up:

cortexbuild ledger add \
  --id flaky-auth-redirect \
  --title "Auth redirect loops after token refresh" \
  --class auth \
  --severity high \
  --status open

Other ledger subcommands: list, show, close, set-status, sweep.

Step 6 — Optional: project-context wizard & rule synthesis

For a richer setup, run the interactive wizard. It walks Harvest → Score → Interview → Mission → Render → Lifecycle and captures project context:

cortexbuild onboard

For CI / unattended use, drive it from a profile:

cortexbuild onboard --non-interactive --profile ./onboard-profile.yaml

You can also generate a role-specific getting-started doc:

cortexbuild onboard getting-started --role lead

Rule synthesis is opt-in and propose-only

Convention inference (init run --with-rule-synthesis) is not automatic. It requires an LLM provider configured and CORTEXBUILD_LLM=1, and it only proposes draft rules for you to accept or reject — it never enforces inferred rules silently. The graph pass that feeds it analyses Python with the standard-library ast (no extra); JavaScript, TypeScript, and Go need the [graph] extra.

Step 7 — How to undo

CortexBuild is reversible. Preview exactly what would be removed first:

cortexbuild eject --dry-run

When you're sure, eject for real (keep backups, skip the prompt):

cortexbuild eject --keep-backups --yes

eject reversibly removes CortexBuild artefacts from the repo.

Where to go next