Arquitectura General — Cornerstone

Cornerstone es el scaffold de infraestructura agentic de DeAcero. Este documento describe sus componentes, cómo encajan entre sí, y cómo se integran con la Plataforma de Datos y Analítica del grupo.

Para la visión futura y el roadmap ver future.md.

Posición en el ecosistema DeAcero

graph TB
    subgraph deacero["Plataforma de Datos y Analítica — DeAcero"]
        direction TB
        subgraph legacy["Sistemas Legacy"]
            SQL["250+ instancias SQL Server\n2005-2019"]
            APPS["65 sistemas\n~13M líneas C#/VB.NET"]
            BB["645 repos Bitbucket\n47 proyectos"]
        end

        subgraph modern["Plataforma Moderna (GCP)"]
            BQ["BigQuery\nDWH central"]
            DBT["dbt\nSilver/Gold"]
            ALDB["AlloyDB ODS\n769 tablas"]
            COMP["Cloud Composer 2\nOrquestación"]
        end

        subgraph agents["Capa Agentic (F3 target)"]
            CS["⬡ Cornerstone\nScaffold + Skills + Telemetría"]
            SQUIT_SVC["SQUIT MCP\n5.7M objetos SQL"]
            OBS["Observability Service\nFastAPI + PostgreSQL"]
        end
    end

    legacy -->|Archaeology Pipeline| CS
    CS -->|modernización guiada| modern
    CS -->|telemetría de agentes| OBS
    CS -->|búsqueda semántica| SQUIT_SVC

Diagrama de componentes

graph TB
    subgraph template["deagentic/cornerstone"]
        CJ["cookiecutter.json\n11 variables"]
        HOOK["post_gen_project.py\nhook post-generación"]
    end

    subgraph project["Proyecto generado (por equipo)"]
        INSTR["Instrucciones multi-plataforma\nAGENTS.md · CLAUDE.md · GEMINI.md · .cursorrules"]
        SKILLS[".agents/skills/\n21 skills · 7 dominios"]
        TOOLS["tools/\nADR gate · discovery · emit_ci"]
        TEL[".telemetry/\nSDK fire-and-forget"]
        CI[".github/workflows/ci.yml\nADR gate → tests → telemetría"]
        ENV[".env\nSQUIT_API_KEY · AGENTIC_TELEMETRY_URL"]
    end

    subgraph services["Servicios centrales"]
        OBS["Observability Service\nFastAPI + PostgreSQL\n192.99.38.188:8000"]
        SQUIT["SQUIT MCP\nsquit-mcp.deacero.us\n5.7M objetos SQL legacy"]
        ATL["Atlassian MCP\nJira + Confluence\n117 espacios"]
    end

    subgraph sync["Sincronización automática"]
        SYNCH["sync_agents.sh\nUserPromptSubmit hook · 24h throttle\nRequiere: gh auth login"]
    end

    CJ --> HOOK
    HOOK -->|genera| project
    SYNCH -->|gh CLI pull · rsync| SKILLS
    SYNCH -.->|fuente| template

    TEL -->|AGENTIC_TELEMETRY_URL set| OBS
    CI  -->|ci.run event| OBS
    TOOLS -->|SQUIT_API_KEY| SQUIT

    CLI["cornerstone CLI\nreport · status · deploy · sync · graph"]
    OBS -->|GET /v1/summary| CLI

Los 4 Core Pipelines

Cornerstone está estructurado alrededor de los 4 pipelines de agentic engineering de DeAcero:

graph LR
    L["Sistema\nLegacy"] --> A
    A["1. ARCHAEOLOGY\nEntender el sistema\nsoftware-archeologist\nretro-engineer\nSQUIT MCP"] --> D
    D["2. DOCS\nDocumentar decisiones\nadr-writer\ndecision-logger\nlearning-protocol"] --> AR
    AR["3. ARCHITECTURE\nDiseñar solución target\narchitect\nbdd-writer\ncode-reviewer"] --> R
    R["4. RE-IMPLEMENTATION\nImplementar modernización\ntool-writer\ndatabase-expert\ngitops-expert"] --> M
    M["Sistema\nModerno\n(GCP)"]

Pipeline	Skill(s) activos	Herramientas	Artefactos de salida
Archaeology	software-archeologist, retro-engineer	squit_client, sql_topology, call_tree, decompiler_manager	executions-graph.dot, FINDINGS.md, BDD stubs
Docs	adr-writer, decision-logger, learning-protocol	sql_logic_parser, decision_extractor	ADRs, docs/knowledge/, learning_log.md
Architecture	architect, bdd-writer, code-reviewer	-	ADRs, .feature files, review reports
Re-implementation	tool-writer, database-expert, gitops-expert	kedro_lineage_builder, api_mapper	código, tests, pipelines dbt/Kedro

Componentes en detalle

Template (deagentic/cornerstone)

Fuente de verdad del ecosistema. Un equipo corre cookiecutter gh:deagentic/cornerstone una sola vez.

cookiecutter.json — 11 variables: nombre del proyecto, rutas, Python version, SQUIT API key, telemetry URL
hooks/post_gen_project.py — post-generación: parchea placeholders en _copy_without_render, emite evento project.generated

Instrucciones de agente (multi-plataforma)

Cada archivo delega a AGENTS.md como fuente única de verdad:

Archivo	Plataforma	Costo en tokens
`CLAUDE.md`	Claude Code CLI	Lean — importa AGENTS.md
`AGENTS.md`	Todos los agentes	Fuente de verdad completa
`GEMINI.md`	Gemini CLI	Lean — importa AGENTS.md
`.cursorrules`	Cursor IDE	Lean — importa AGENTS.md

Skills (`.agents/skills/`) — 21 skills en 7 dominios

.agents/skills/
├── core/               learning-protocol · tool-writer
├── software/
│   ├── architecture/   architect · adr-writer · decision-logger
│   ├── discovery/      software-archeologist · retro-engineer · unknown-domain-protocol
│   └── quality/        bdd-writer · code-reviewer
├── infrastructure/     database-expert · gitops-expert
├── security/           security-expert
├── design/stitch/      stitch-design · enhance-prompt · design-md
│                       stitch-loop · react-components · shadcn-ui · remotion
└── hardware/           embedded · hardware-analyst · smart-card
                        serial · usb-hid · bluetooth · nfc-rfid

Cada skill tiene: - Frontmatter YAML (name, description) — usado por el LLM para trigger automático - Protocolo de ejecución — pasos concretos, output format, circuit breakers - Evals (evals/evals.json) — casos de prueba para validar el skill

Tools (`tools/`)

tools/
├── check_adr_gate.py       ← ADR gate (CI enforcement)
├── emit_ci_event.py        ← emite ci.run al Observability Service
├── sync_agents.sh          ← sincroniza skills desde deagentic/cornerstone
└── software/discovery/     ← 17 herramientas de análisis legacy
    ├── squit_client.py     ← cliente SQUIT MCP (búsqueda semántica SQL)
    ├── sql_topology.py     ← grafo de dependencias entre SPs
    ├── call_tree.py        ← árbol de llamadas desde entry points
    ├── sql_logic_parser.py ← extrae lógica de negocio de stored procedures
    ├── structure_mapper.py ← mapa de módulos y dependencias Python
    ├── api_mapper.py       ← inventario de llamadas a APIs externas
    ├── decompiler_manager.py ← gestiona ILSpy/CFR para .NET y Java
    └── ...

SDK de Telemetría (`.telemetry/`)

# fire-and-forget — nunca bloquea, nunca lanza excepciones
# no-op completo si AGENTIC_TELEMETRY_URL no está configurado
from .telemetry import send_event, skill_span, tool_span, track_knowledge_created

Módulo	Propósito
`client.py`	`send_event()`, `is_telemetry_enabled()`
`decorators.py`	`@skill_span`, `@tool_span` — instrumentación con una línea
`schema.py`	Definiciones de los 6 tipos de evento
`cost_rates.py`	Tabla de precios Claude + Gemini → USD estimado
`otel.py`	Bridge OpenTelemetry/OpenLLMetry (opcional)

CI/CD Pipeline

graph LR
    PR["Push / PR"] --> ADR{"ADR gate\ncheck_adr_gate.py"}
    ADR -->|"library/*.py\nsin ADR nuevo"| BLOCK["❌ merge\nbloqueado"]
    ADR -->|"pasa\no [skip-adr]"| TEST["Tests + Lint\npytest · ruff · mypy"]
    TEST --> EMIT["emit_ci_event.py\nci.run → Observability"]
    EMIT --> DONE["✅"]

Observability Service

Microservicio central para visibilidad cross-team del uso de agentes IA en DeAcero.

Deployment: 192.99.38.188:8000 (Docker Compose — mismo servidor que code-server)

6 tipos de evento y su semántica:

Evento	Cuándo	Datos clave
`project.generated`	`cookiecutter gh:deagentic/cornerstone`	project_slug, python_version
`skill.invoked`	Agente activa un skill	skill_name, model, tokens, costo_usd
`tool.executed`	Se ejecuta una tool	tool_name, tool_path, duration_ms
`ci.run`	Finaliza un run de CI	adr_gate_passed, tests_passed, ref
`knowledge.created`	Se crea ADR, skill, o doc	kind, path
`knowledge.used`	Se lee un artifact de conocimiento	kind, path

Schema: Tabla única events con payload JSONB (ADR-0002). Vista materializada mv_summary para dashboards.

Multi-tenant: Una instancia central. Cada proyecto se identifica por su project_slug único.

CLI:

cornerstone report summary  --url $AGENTIC_TELEMETRY_URL
cornerstone report cost     --url $AGENTIC_TELEMETRY_URL --group-by model
cornerstone report events   --url $AGENTIC_TELEMETRY_URL --event-type skill.invoked

SQUIT MCP

Búsqueda semántica sobre 5.7 millones de objetos SQL legacy de DeAcero (stored procedures, vistas, funciones, tablas de 250+ instancias SQL Server).

Atributo	Valor
URL	`https://squit-mcp.deacero.us/mcp`
Auth	`SQUIT_API_KEY` (header `X-API-Key`)
Tools	`squit_search`, `squit_get_code`, `squit_dependencies`
Cliente	`tools/software/discovery/squit_client.py`
Infraestructura	Docker en `192.99.38.188`, GCP credentials

SQUIT es el habilitador del Archaeology Pipeline: permite encontrar stored procedures por significado de negocio ("cálculo de precio mínimo", "ajuste de inventario") sin conocer el nombre del objeto.

Sync de Skills

sequenceDiagram
    participant C as Claude Code
    participant H as UserPromptSubmit hook
    participant S as sync_agents.sh
    participant G as deagentic/cornerstone

    C->>H: primer prompt de la sesión
    H->>S: bash tools/sync_agents.sh 2>/dev/null || true
    S->>S: leer .agents/.last_sync timestamp
    alt menos de 24h
        S-->>C: exit 0 silencioso
    else más de 24h o primer run
        S->>G: gh repo clone --depth=1
        G-->>S: skills actualizados
        S->>S: rsync → .agents/skills/
        S->>S: escribir timestamp
    end

Prerequisito: gh auth login — acceso a repos privados de deagentic. Force sync: bash tools/sync_agents.sh --force

Variables de entorno

Todas centralizadas en .env. El archivo se genera pre-llenado con los valores del cookiecutter.

Variable	Requerida	Descripción
`SQUIT_API_KEY`	Para SQUIT	API key de búsqueda semántica SQL legacy
`AGENTIC_TELEMETRY_URL`	Para observabilidad	URL del Observability Service (`http://192.99.38.188:8000`)
`AGENTIC_TELEMETRY_DEBUG`	Opcional	`1` para logs de telemetría en stderr
`OTEL_EXPORTER_OTLP_ENDPOINT`	Opcional	Override del endpoint OTLP (si se usa el bridge OTel)

Flujos de datos

flowchart LR
    DEV["Developer\n+ AI Agent"] -->|cookiecutter| GEN["Proyecto\ngenerado"]
    DEV -->|activa skill| SK["skill.invoked"]
    DEV -->|corre tool| TL["tool.executed"]
    DEV -->|crea ADR| KN["knowledge.created"]
    DEV -->|push/PR| CI["ci.run"]
    DEV -->|busca SPs| SQ["SQUIT MCP\n5.7M objetos"]

    SK & TL & KN & CI -->|fire-and-forget\nsi URL set| OBS[("Observability\nService\n192.99.38.188")]

    OBS -->|cornerstone report| DASH["CLI + Dashboard\ncosto por modelo\ntop skills\nCI pass rate"]

Soporte multi-plataforma

Plataforma	Archivo	Estado
Claude Code	`CLAUDE.md` → `AGENTS.md`	✅ Primario
Gemini CLI	`GEMINI.md` → `AGENTS.md`	✅ Soportado
Cursor	`.cursorrules` → `AGENTS.md`	✅ Soportado
Cualquier agente	`AGENTS.md`	✅ Agnóstico

MCPs disponibles en DeAcero

MCP	Estado	Propósito en proyectos Cornerstone
SQUIT	✅ Producción	Archaeology de SQL legacy
Atlassian (Jira + Confluence)	✅ Producción	Contexto de decisiones, tickets, 117 espacios
AlloyDB (postgres-mcp)	✅ Producción (WPC/CPFR)	Consulta ODS en tiempo real
BigQuery	🔧 Por configurar	Acceso a DWH desde agentes
dbt	🔧 Por configurar	Lineaje y operación de transformaciones
SQL Server	🔧 Por configurar	Complemento a SQUIT para análisis directo
Airflow / Cloud Composer 2	🔧 Por configurar	Orquestación de pipelines
Dataplex	🔧 Por configurar	Governance y catálogo de datos
gcloud	🔧 Por configurar	Operaciones GCP desde agentes