Cornerstone es el framework open-source de governance y modernización para ingeniería de software agentic. Provee el ecosistema completo de agentes IA — instrucciones, skills, herramientas, observabilidad y mandato ADR-first — preconfigurado y listo para usar desde el día uno.
Misión: Comprimir el tiempo y costo de modernización de sistemas legacy via Agentic Pipelines — de forma consistente, en todos los equipos de tu organización.
Cornerstone es el punto de entrada operativo hacia una ingeniería agentic madura: la fase donde los agentes dejan de ser asistentes y pasan a operar la plataforma de forma autónoma.
Las organizaciones con grandes portfolios de sistemas legacy enfrentan un desafío común: modernizar miles de componentes sin detener operaciones. Cornerstone estructura ese proceso en pipelines agentic reproducibles:
- Archaeology first — entiende el sistema antes de reescribirlo
- ADR-first governance — cada decisión arquitectónica queda trazada y auditada
- TDD+BDD — los agentes escriben specs verificables, no solo código
- Observabilidad cross-team — telemetría unificada desde el día uno
# Prerequisitos
pip install git+https://github.com/deagentic/cornerstone
gh auth login # requerido para sync automático de skills
# Generar proyecto
cornerstone new| Componente | Ubicación | Propósito |
|---|---|---|
| Instrucciones de agente | AGENTS.md (router), CLAUDE.md, GEMINI.md |
Enrutamiento jerárquico por contexto (ADR-0029) |
| Skills de agentes | .agents/skills/ |
Composed capabilities via sparse-checkout de deagentic/cornerstone-agents |
| Herramientas de discovery | tools/software/discovery/ |
SQUIT client, SQL topology, call tree, decompilers y más |
| ADR gate | tools/check_adr_gate.py |
Bloquea merges en cambios de librería sin ADR |
| CI/CD | .github/workflows/ci.yml |
ADR gate + tests + emisión de telemetría |
| SDK de telemetría | .telemetry/ |
Observabilidad cross-team — fire-and-forget, opt-in |
| Variables de entorno | .env / .env.example |
Todas las vars centralizadas |
| Setup multiplataforma | setup/install.sh, setup/install.bat |
Linux/Mac y Windows |
| Sync automático | cornerstone sync |
Sincroniza solo los skills necesarios para el proyecto |
| Skills TDD+BDD | .agents/skills/software/quality/ |
tech-lead, tdd-developer, qa-validator: el equipo de desarrollo que garantiza calidad desde el inicio (ADR-0039) |
| Variable | Default | Descripción |
|---|---|---|
project_name |
My Project | Nombre legible del proyecto |
project_slug |
my-project | Nombre del repo (kebab-case) |
package_name |
my_package | Nombre del paquete Python (snake_case) |
github_username |
myuser | Usuario u org de GitHub |
description |
... | Descripción de una línea |
author |
Your Name | Nombre del autor |
python_version |
3.11 | Versión mínima de Python para CI |
library_path |
library | Subdirectorio del paquete Python |
adr_path |
docs/adr | Subdirectorio para ADRs |
squit_api_key |
— | API key para SQUIT — búsqueda semántica sobre objetos SQL legacy |
agentic_telemetry_url |
— | URL del Observability Service central |
La arquitectura de Cornerstone v1.x está distribuida en múltiples repositorios dentro de la organización deagentic. El mapa completo (incluyendo diagramas Mermaid detallados) vive en proposed_architecture/.
| Repositorio | Qué contiene |
|---|---|
deagentic/cornerstone ← este repo |
CLI (factory + runtime), starters, quality gates (tools/), cliente de telemetría (.telemetry/), servicio receptor de telemetría (services/observability/), CI/CD workflows, ADRs |
deagentic/cornerstone-agents |
Biblioteca compartida de skills — common/, capabilities/<cap>/, integrations/<a+b>/. Origen del cornerstone sync vía sparse-checkout |
deagentic/crisol-gateway |
Gateway MCP OSS: configuración Pomerium + AgentGateway + catálogo declarativo de backends (catalog/<nombre>-mcp.yaml) |
deagentic/crisol-mcp-github |
Backend MCP de GitHub: fork de github-mcp-server + supergateway (stdio → HTTP) |
deagentic/crisol-context-mcp |
Backend MCP de contexto corporativo |
deagentic/crisol-bigquery-mcp |
Backend MCP de BigQuery (planned) |
keystone/ (submódulo) |
KDB centralizada: WikiPage domain model, search engine BM25+semántico, adaptadores fs/Gemini, surface MCP (kdb_search, kdb_get_project_context, …) |
<org>/<nombre> (repos generados) |
Cada cornerstone new crea su propio repo en la organización del deployer — fuera de la jurisdicción de Cornerstone |
Ver
proposed_architecture/README.mdpara el catálogo completo de diagramas Mermaid y las convenciones de documentación de arquitectura.
| Starter | Propósito |
|---|---|
base |
Discovery y modernización de propósito general (ADR-first, skills, telemetría) |
cli |
Aplicación dual-mode (CLI + MCP), arquitectura hexagonal (ADR-0025) |
mcp |
Servidor MCP puro, puertos y adaptadores, sin CLI |
api |
Microservicio FastAPI + PostgreSQL con migraciones Alembic |
archaeology |
Nuevo — Arqueología de sistemas legacy: reverse-engineer → BDD specs → handoff al equipo TDD |
Todo proyecto generado con Cornerstone está estructurado para ejecutar los 5 pipelines de agentic engineering definidos en deagentic/knowledge-base:
| Pipeline | Skill(s) | Propósito |
|---|---|---|
| Archaeology | software-archeologist, retro-engineer |
Entender el sistema legacy — generar executions graph, inventario de APIs, BDD specs |
| Docs | adr-writer, decision-logger, learning-protocol |
Documentar decisiones, extraer reglas de negocio, persistir conocimiento |
| Architecture | architect, bdd-writer, code-reviewer |
Diseñar la arquitectura target, escribir ADRs, revisar código |
| Re-implementation | tool-writer, database-expert, gitops-expert |
Implementar la solución moderna con trazabilidad completa |
| TDD+BDD | tech-lead, tdd-developer, qa-validator, bdd-writer, code-reviewer |
Story intake → BDD scenarios → Red→Green→Refactor → QA validation |
Los skills se sincronizan bajo demanda desde deagentic/cornerstone-agents mediante el comando cornerstone sync.
| Capacidad | Descripción |
|---|---|
common |
Skills universales (ADR, Architect, BDD, etc.) siempre incluidos |
cli |
Manejo de versiones y estándares POSIX |
archaeology |
SQUIT, COBOL, retro-engineering de legacy |
server |
APIs, Hexagonal architecture, FastMCP |
frontend |
Stitch design loop, shadcn-ui, React |
hardware |
Serial, Bluetooth, NFC, USB-HID |
pipeline |
Kedro builder, dbt, data-lineage |
quality |
tech-lead (story gate), tdd-developer (TDD cycle), qa-validator (pre-merge) |
cd <project_slug>
# 1. Configurar variables de entorno
cp .env.example .env
# editar .env: SQUIT_API_KEY y AGENTIC_TELEMETRY_URL
# 2. Instalar dependencias
pip install -e ".[dev]" # Instalar herramientas base, testing y linting
bash setup/install.sh # Instalar pre-commit hooks (Linux/Mac)
# setup\install.bat # Instalar pre-commit hooks (Windows)
# 3. Abrir el índice de ADRs — escribir ADR-0001 antes de cualquier código
open docs/adr/index.mdEl sync de skills corre automáticamente en el primer new y puede forzarse con cornerstone sync.
Para override de capacidades: cornerstone sync --capabilities archaeology,server
Cualquier cambio en <library_path>/<package_name>/ requiere un nuevo ADR en docs/adr/.
El CI gate (tools/check_adr_gate.py) lo enforcea en cada PR.
Bypass para fixes triviales: [skip-adr] en el commit message.
- Python 3.11+
pip install git+https://github.com/deagentic/cornerstone- GitHub CLI instalado y autenticado (
gh auth login) - Docker (opcional — para Observability Service)