Code Index Governance
Status: active.
This document explains how agents should search and index AlphaSwarm during the repository split. The goal is to keep edits inside the right future project boundary before source code is physically separated.
Search Order
- Read the nearest
AGENTS.mdfor the folder being edited. - Read
alphaswarm_docs/repository-split.mdto identify the owning domain. - Search within the owning domain first.
- Only broaden to
alphaswarm/or repo root when the boundary document says the implementation still lives there. - Record new reusable patterns in
alphaswarm_snippets/or.cursor/skills/instead of scattering notes across unrelated docs.
Domain Index
| Domain | Start here | Notes |
|---|---|---|
| Control plane | alphaswarm_controller/AGENTS.md | /manage/*, providers, workload lifecycle |
| Platform core | alphaswarm_core/AGENTS.md | Shared contracts only |
| Client | alphaswarm_client/AGENTS.md, alphaswarm_client/AGENTS.md | Active source remains in alphaswarm_client/ |
| Snippets | alphaswarm_snippets/AGENTS.md | Reference-only curated knowledge |
| Bots | alphaswarm_bots/AGENTS.md | Runtime remains in alphaswarm/bots/ for now |
| Runtime monolith | AGENTS.md | Agents, RL, data, backtests, persistence, tasks |
Indexing Rules
- Codebase MCP indexes must respect workspace allow-lists and secret
deny-lists from
alphaswarm/codebase/mcp/policy.py. - Generated indexes should not include
.env, private keys, kubeconfigs, token files, model weights, or local warehouse data. - Agent-readable docs should link to paths, not line numbers, unless the output is a transient review.
- Keep split-boundary indexes short enough that agents can read them before editing.
Boundary Checks
Use these searches before a boundary-sensitive change:
rg --type py "^from alphaswarm(\.|$)|^import alphaswarm(\.|$)" alphaswarm_controller/src
rg "alphaswarm_snippets|extractions|inspiration" alphaswarm alphaswarm_controller alphaswarm_core
rg "control.local/api|management/backend|management/frontend" docs README.md
The first command must return no matches. The second and third commands may return documented migration references, but should not reveal runtime imports or active instructions that route new work to deprecated surfaces.