Code Project Brain (CPB)

Un segundo cerebro a nivel de proyecto que crece en sincronía con un repositorio de código. Una Guía de Desarrollo (contexto de primera clase) se sitúa sobre CodeGraph (hechos) y Project KB (conocimiento digerido), compilados en contexto específico de tarea para Claude Code — con un bucle gobernado de Cambio → Propuesta que mantiene el conocimiento correcto sin permitir nunca que una IA lo reescriba silenciosamente.

CPB implementa el diseño v3.0: la Guía de Desarrollo es el primer ciudadano — el modelo mental del proyecto que un Agente carga primero. Un Compilador de Contexto ensambla un ContextPlan en el orden fijo Guía → KB → CodeGraph; un centro de conceptos enlaza los tres dominios por canonical_id; una capa de Anclas de Código mantiene la Guía honesta frente al código.

Development Guide (context / first-class)
        │  describes / governs (via Concept hub)
        ▼
CodeGraph (facts)  ·  Project KB (digested knowledge)
        └──────────────► Context Compiler ► Claude Code
Change → Impact → (Guide stale?) → Guide Proposal → Validate → Approve → Apply

¿Nuevo aquí? Lee docs/OVERVIEW.md — un recorrido de entrada única por la arquitectura, implementación, decisiones de diseño y hoja de ruta. La historia de v2.0 vive en UpdateGuide2.0.md.

Las tres capas (v3.0, update3.0 §1)

El orden de carga fijo es Guía → KB → CodeGraph, nunca el inverso (§3):

• Guía de Desarrollo = Contexto — qué es el proyecto, por qué está diseñado de esta manera y las reglas a seguir. El modelo mental que un Agente carga primero. Se encuentra en guide/ como un esqueleto 00-overview → 06-decisions (§14).

• CodeGraph = Hechos — código analizado por tree-sitter en un grafo SQLite de símbolos y aristas de llamada/referencia (WAL + FTS5). El Adaptador de Verdad Fundamental que verifica las Anclas de Código de la Guía (§9). QUÉ ES.

• Project KB = Conocimiento — requisitos / errores / decisiones (ADRs) / fuentes externas / lecciones digeridos. La capa detallada e histórica a la que se llega solo después de la Guía. QUÉ SE APRENDIÓ.

El centro de conceptos (§21/§22) enlaza secciones de la Guía, documentos de KB y símbolos de CodeGraph por canonical_id, de modo que un cambio de código pueda rastrear symbol → concept → guide section y marcar la Guía como obsoleta.

El bucle gobernado (§11/§13/§24)

Un cambio de código o KB nunca edita silenciosamente la Guía. En su lugar:

Change → Impact → Concept impact → Guide stale? → Guide Proposal (draft)
      → Validate → Approve → Apply

El motor propone; un humano (o Claude, como revisor) valida y aprueba antes de aplicar. El conocimiento de KB puede ser promovido a la Guía a través de la misma propuesta gobernada (§13 Knowledge Promotion). cpb sync redacta propuestas pendientes; cpb proposals <id> --approve|… las resuelve.

Qué hace

• Guía de Desarrollo — indexa Markdown de guide/ (frontmatter de esqueleto + Anclas de Código), verifica anclas contra CodeGraph, marca las obsoletas.

• CodeGraph — sincronización incremental por archivo de símbolos + aristas.

• Project KB — indexa Markdown de project-kb/ con frontmatter tipado; digiere en kb_digests; deduplicación/fusión de digests duplicados (§13).

• Compilador de Contexto — cpb context "<tarea>" → un ContextPlan (Guía → KB → Código, Nivel de Divulgación Progresiva 0-6, presupuesto de tokens) (§18).

• Motor de Impacto — radio de explosión + restricciones/decisiones afectadas y conceptos / secciones de Guía afectados (§22).

• Centro de conceptos — canonical_id que enlaza Guía / KB / CodeGraph (§21).

• Habilidades de Claude Code — ocho flujos de trabajo: /project-init, /project-context, /project-feature, /project-impact, /project-update-docs, /project-review, /project-knowledge, /project-sync.

Tecnología

Node/TypeScript, node:sqlite (integrado, WAL+FTS5, Node ≥ 22), web-tree-sitter (gramáticas WASM para C/C++/TS/JS/Python/Rust/Go/Java). Sin compilaciones nativas, sin base de datos vectorial (por diseño, §19). Motor v3.0.0 / protocolo 2.

Inicio rápido

# inside a code repository
cpb init        # create .project-brain/ + guide/ + project-kb/
cpb index       # build codegraph + knowledge + guide + concepts + git
cpb status      # summary: engine/protocol/guide sections/stale anchors
cpb context FrameQueue        # ContextPlan (Guide → KB → CodeGraph)
cpb concept camera/capture-pipeline   # the Concept hub: 3-domain graph
cpb guide list               # the Guide skeleton (Level 0)
cpb guide validate           # Guide well-formedness (§17 validator)
cpb impact FrameQueue         # blast radius + affected concepts/guide
cpb kb dedup                  # find duplicate KB digests (§13); --apply to merge
cpb sync                      # detect changes → draft Guide/Update proposals
cpb proposals                 # list / validate / approve / apply proposals

Auto-hospedaje

CPB indexa su propio código fuente y los guide/ + project-kb/ incluidos:

git init && cpb init && cpb index && cpb status

MCP (la interfaz de IA)

CPB expone herramientas MCP con espacios de nombres — la única interfaz de IA:

• code.* — code.search code.symbol code.callers code.callees code.dependencies code.impact

• docs.* — docs.get docs.search docs.related docs.constraints docs.validate docs.apply

• kb.* — kb.search kb.requirement kb.bug kb.decision kb.reference kb.ingest kb.promote kb.digest kb.promote-guide kb.dedup

• guide.* — guide.index guide.section guide.stale guide.validate

• concept.* — concept.graph concept.forSymbol

• project.* — project.context project.impact project.changes project.sync project.proposals project.status

Consulta USAGE.md para la configuración de instalación y la referencia completa de herramientas.

Como plugin de Claude Code

CPB se distribuye como un plugin de Claude Code (cpb-claude-plugin/) que es la capa adaptadora sobre el Motor. El Motor (este repositorio, CLI cpb/cpb-mcp) sigue siendo un runtime independiente; el plugin se vincula mediante el protocolo MCP, no mediante un import de npm — para que el Motor pueda evolucionar de forma independiente. Consulta docs/plans/archi.md para la justificación y cpb-claude-plugin/README.md para los pasos completos de instalación.

# 1. Engine on PATH (once)
npm install -g @cpb/engine        # or: npm link  (from this repo)

# 2. In Claude Code
/plugin marketplace add /path/to/CPB
/plugin install cpb@cpb

Luego /cpb:status, /cpb:context, /cpb:sync, … — o simplemente describe la tarea y las habilidades se activan automáticamente.

El proyecto de demostración

demo-src/camera/ es un pequeño pipeline de cámara en C++ (CameraDevice → FrameQueue → VideoEncoder) con un conjunto completo de documentos v3.0 — guide/ (visión general + arquitectura + una restricción + un ADR) y project-kb/ (ADR, requisito, error, lección, notas externas de V4L2/FFmpeg, evidencia de pruebas). Es dogfood: CPB indexa, explora, verifica desviaciones y ejecuta el bucle cambio→propuesta sobre él.

Estructura

src/
  core/        types (domain model: Guide/Concept/ContextPlan + structured objects)
  db/          sqlite adapter + schema.sql + migrate.ts (versioned migrations)
  engine/
    codegraph/  tree-sitter extractor, grammars, parser, orchestrator, queries
    guide/      Development Guide: indexer, anchor, query, validator (§17)
    concept/    Concept hub: index + query (§21)
    knowledge/  KB: frontmatter, indexer, recall, freshness, entities, external, ingestion, promotion, dedup
    docs/       structured reads: constraints, decisions (Guide-seeded)
    git/        commit index + ADR mining + gitDiff
    impact/     blast radius + affected knowledge/concepts/guide (§22)
    context/    Context Compiler (§18) + builder (v2, cpb explain) + explain/explore
    sync/       semantic-diff, changeset, proposal, pipeline (change→proposal loop)
  mcp/         namespaced MCP tools (code.*/docs.*/kb.*/guide.*/concept.*/project.*) + stdio server
bin/cpb.ts      CLI
guide/          CPB's own Development Guide (self-hosted, v3.0 skeleton)
cpb-claude-plugin/  the Claude Code adapter (skills + commands + MCP declaration)

Límites de diseño (per §19/§23/§25)

No construido: reescritura automática de todos los documentos, generación automática de todo el conocimiento, búsqueda vectorial/por embeddings (§19 — local-first, SQLite+FTS5), un IDE completo o un grafo de conocimiento empresarial. El motor nunca incorpora un LLM (§29) — Claude piensa a través de MCP; el motor mantiene los hechos y la máquina de estados. El conocimiento permanece bajo control humano (§11/§14); la Guía es un activo gobernado — cada edición pasa por una Propuesta. El código es la fuente de verdad más alta (§9).

Licencia

MIT.