# ice-data-dm/cerebro-gremial-andi architecture

> Architecture diagram of the GitHub repository ice-data-dm/cerebro-gremial-andi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ice-data-dm/cerebro-gremial-andi
- Repository: https://github.com/ice-data-dm/cerebro-gremial-andi

## Overview

#### Purpose and Operating Model
Cerebro Comercial UNIANDI is a file-backed commercial knowledge system for UNIANDI KAMs and AI assistants. It preserves client context, commercial decisions, promotions, incidents, and commitments so future actions reuse organizational learning. The primary entry point is `README.md`; operational storage conventions begin at `vault/README.md`, while agent procedures begin at `skills/README.md`.

#### Knowledge Vault Boundary
`vault/` is the authoritative persistent-memory layer, organized by client, business unit, and team member. It is intended to be read before commercial decisions and updated immediately after activity. There is no application runtime or executable service in this repository; the consumer is an assistant/CRM integration operating over Markdown files.
Paths: `vault/README.md`, `vault/clientes/`, `vault/unidades/`.

#### Client-Centric Record Aggregate
Each client directory is the central aggregate for account knowledge: a canonical profile, contacts, pending work, and optional operational histories. The profile naming convention (`00-ficha.md`) establishes a stable account entry record.
Paths: `vault/clientes/red-la-vecindad/00-ficha.md`, `vault/clientes/superandes/contactos.md`, `vault/clientes/ahorramas/00-ficha.md`.

#### Activity, Incident, and Promotion Streams
Client histories are partitioned into append-oriented streams: `bitacora` for visits/activity, `incidentes` for commercial or operational failures, and `promociones` for campaign learning. Timestamped filenames encode chronology plus business context, enabling recent-activity retrieval and later pattern analysis.
Paths: `vault/clientes/red-la-vecindad/bitacora/`, `vault/clientes/superandes/incidentes/`, `vault/clientes/red-la-vecindad/promociones/`.

#### Business-Unit Knowledge Dimension
The five UNIANDI business units form a cross-client classification layer. Records identify their unit so an assistant can combine account-specific evidence with portfolio/category knowledge and propagate lessons across customers.
Paths: `vault/unidades/alimentos.md`, `vault/unidades/aseo.md`, `vault/unidades/cuidado-personal.md`.

#### AI Workflow Skills
`skills/` packages repeatable assistant workflows as independently discoverable `SKILL.md` instructions. These govern the critical control flow: consult institutional knowledge first, act with context, then register outcomes; specialized skills handle onboarding, promotions, incidents, contradiction governance, daily cadence, and executive preparation.
Paths: `skills/consultar-antes-de-decidir/SKILL.md`, `skills/registrar-incidente-completo/SKILL.md`, `skills/aprendizaje-de-promociones/SKILL.md`.

#### External Integration and Runtime
The stated operational runtime is each KAM’s assistant connected to the external “Cerebro Gremial ANDI” CRM connector. The repository itself supplies durable Markdown knowledge and procedural prompts, not a web service, database, or deployment stack. The assistant/connector is responsible for discovery, retrieval, applying skills, and writing structured records back into `vault/`.
Paths: `README.md`, `skills/montar-la-colmena/SKILL.md`, `vault/equipo/david.md`.

Main entry points: [`skills/README.md`](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/README.md) (Skills index), [`skills/consultar-antes-de-decidir/SKILL.md`](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/consultar-antes-de-decidir/SKILL.md) (Consult before deciding), [`vault/README.md`](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/README.md) (Vault conventions), [`skills/registrar-incidente-completo/SKILL.md`](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/registrar-incidente-completo/SKILL.md) (Register complete incident)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vault["Knowledge Vault"]
  node_vault_guide["Vault conventions<br/>documentation<br/>[README.md]"]
  node_client_records["Client record directories<br/>knowledge aggregate"]
  node_red_profile["Red La Vecindad profile<br/>client profile<br/>[00-ficha.md]"]
  node_ahorramas_profile["AhorraMas profile<br/>client profile<br/>[00-ficha.md]"]
  node_superandes_contacts["SuperAndes contacts<br/>contact records<br/>[contactos.md]"]
  node_activity_log["Activity stream<br/>append-only history"]
  node_incident_log["Incident stream<br/>append-only history"]
  node_promotion_log["Promotion stream<br/>append-only history"]
  node_business_units["Business-unit knowledge<br/>cross-client classification"]
  node_foods_unit["Foods unit<br/>business unit<br/>[alimentos.md]"]
  node_cleaning_unit["Cleaning unit<br/>business unit<br/>[aseo.md]"]
  node_personal_care_unit["Personal care unit<br/>business unit"]
  node_team_member["KAM record<br/>team knowledge<br/>[david.md]"]
end

subgraph group_skills["Assistant Skills"]
  node_skills_guide["Skills index<br/>documentation<br/>[README.md]"]
  node_consult_skill["Consult before deciding<br/>assistant workflow<br/>[SKILL.md]"]
  node_incident_skill["Register complete incident<br/>assistant workflow<br/>[SKILL.md]"]
  node_promotion_skill["Promotion learning<br/>assistant workflow<br/>[SKILL.md]"]
  node_onboarding_skill["Mount the hive<br/>assistant workflow<br/>[SKILL.md]"]
end

subgraph group_external["Operational Runtime"]
  node_assistant_crm{{"KAM assistant + CRM connector<br/>external consumer"}}
end

node_readme["Repository entry point<br/>documentation<br/>[README.md]"]

node_readme -->|"introduces"| node_vault_guide
node_readme -->|"points to"| node_skills_guide
node_vault_guide -->|"governs"| node_client_records
node_vault_guide -->|"governs"| node_business_units
node_client_records -->|"contains"| node_red_profile
node_client_records -->|"contains"| node_ahorramas_profile
node_client_records -->|"contains"| node_superandes_contacts
node_client_records -->|"records"| node_activity_log
node_client_records -->|"records"| node_incident_log
node_client_records -->|"records"| node_promotion_log
node_business_units -->|"includes"| node_foods_unit
node_business_units -->|"includes"| node_cleaning_unit
node_business_units -->|"includes"| node_personal_care_unit
node_skills_guide -->|"indexes"| node_consult_skill
node_skills_guide -->|"indexes"| node_incident_skill
node_skills_guide -->|"indexes"| node_promotion_skill
node_skills_guide -->|"indexes"| node_onboarding_skill
node_assistant_crm -->|"applies"| node_consult_skill
node_consult_skill -->|"retrieves context from"| node_client_records
node_consult_skill -->|"combines with"| node_business_units
node_assistant_crm -->|"uses to register"| node_incident_skill
node_incident_skill -->|"writes"| node_incident_log
node_assistant_crm -->|"uses to learn"| node_promotion_skill
node_promotion_skill -->|"writes"| node_promotion_log
node_assistant_crm -->|"updates after activity"| node_activity_log
node_assistant_crm -->|"supports"| node_team_member
node_onboarding_skill -->|"configures workflow for"| node_assistant_crm

click node_readme "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/README.md"
click node_vault_guide "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/README.md"
click node_red_profile "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/clientes/red-la-vecindad/00-ficha.md"
click node_ahorramas_profile "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/clientes/ahorramas/00-ficha.md"
click node_superandes_contacts "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/clientes/superandes/contactos.md"
click node_foods_unit "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/unidades/alimentos.md"
click node_cleaning_unit "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/unidades/aseo.md"
click node_personal_care_unit "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/unidades/cuidado-personal.md"
click node_skills_guide "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/README.md"
click node_consult_skill "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/consultar-antes-de-decidir/SKILL.md"
click node_incident_skill "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/registrar-incidente-completo/SKILL.md"
click node_promotion_skill "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/aprendizaje-de-promociones/SKILL.md"
click node_onboarding_skill "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/montar-la-colmena/SKILL.md"
click node_team_member "https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/equipo/david.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vault_guide,node_client_records,node_red_profile,node_ahorramas_profile,node_superandes_contacts,node_activity_log,node_incident_log,node_promotion_log,node_business_units,node_foods_unit,node_cleaning_unit,node_personal_care_unit,node_team_member toneBlue
class node_skills_guide,node_consult_skill,node_incident_skill,node_promotion_skill,node_onboarding_skill toneAmber
class node_assistant_crm toneMint
class node_readme toneNeutral
```

## Components

### Knowledge Vault

Authoritative Markdown persistent memory.

- [Vault conventions](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/README.md): documentation · Defines operational storage conventions. · `vault/README.md`
- **Client record directories**: knowledge aggregate · Central account context organized by client.
- [Red La Vecindad profile](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/clientes/red-la-vecindad/00-ficha.md): client profile · Canonical account entry record. · `vault/clientes/red-la-vecindad/00-ficha.md`
- [AhorraMas profile](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/clientes/ahorramas/00-ficha.md): client profile · Canonical account entry record. · `vault/clientes/ahorramas/00-ficha.md`
- [SuperAndes contacts](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/clientes/superandes/contactos.md): contact records · `vault/clientes/superandes/contactos.md`
- **Activity stream**: append-only history · Timestamped visits and commercial activity.
- **Incident stream**: append-only history · Commercial and operational failures.
- **Promotion stream**: append-only history · Campaign outcomes and learning.
- **Business-unit knowledge**: cross-client classification · Connects account evidence to portfolio knowledge.
- [Foods unit](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/unidades/alimentos.md): business unit · `vault/unidades/alimentos.md`
- [Cleaning unit](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/unidades/aseo.md): business unit · `vault/unidades/aseo.md`
- [Personal care unit](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/unidades/cuidado-personal.md): business unit · `vault/unidades/cuidado-personal.md`
- [KAM record](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/vault/equipo/david.md): team knowledge · `vault/equipo/david.md`

### Assistant Skills

Procedural workflows for assistants.

- [Skills index](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/README.md): documentation · Entry point for agent procedures. · `skills/README.md`
- [Consult before deciding](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/consultar-antes-de-decidir/SKILL.md): assistant workflow · Requires institutional knowledge retrieval before action. · `skills/consultar-antes-de-decidir/SKILL.md`
- [Register complete incident](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/registrar-incidente-completo/SKILL.md): assistant workflow · Guides structured incident capture. · `skills/registrar-incidente-completo/SKILL.md`
- [Promotion learning](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/aprendizaje-de-promociones/SKILL.md): assistant workflow · Captures and reuses campaign learning. · `skills/aprendizaje-de-promociones/SKILL.md`
- [Mount the hive](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/skills/montar-la-colmena/SKILL.md): assistant workflow · Sets up the assistant operating workflow. · `skills/montar-la-colmena/SKILL.md`

### Operational Runtime

External assistant and CRM integration.

- **KAM assistant + CRM connector**: external consumer · Discovers, retrieves, applies skills, and writes Markdown records.

### Other components

- [Repository entry point](https://github.com/ice-data-dm/cerebro-gremial-andi/blob/main/README.md): documentation · Explains the operating model and boundaries. · `README.md`

## Connections

- Repository entry point → Vault conventions: introduces
- Repository entry point → Skills index: points to
- Vault conventions → Client record directories: governs
- Vault conventions → Business-unit knowledge: governs
- Client record directories → Red La Vecindad profile: contains
- Client record directories → AhorraMas profile: contains
- Client record directories → SuperAndes contacts: contains
- Client record directories → Activity stream: records
- Client record directories → Incident stream: records
- Client record directories → Promotion stream: records
- Business-unit knowledge → Foods unit: includes
- Business-unit knowledge → Cleaning unit: includes
- Business-unit knowledge → Personal care unit: includes
- Skills index → Consult before deciding: indexes
- Skills index → Register complete incident: indexes
- Skills index → Promotion learning: indexes
- Skills index → Mount the hive: indexes
- KAM assistant + CRM connector → Consult before deciding: applies
- Consult before deciding → Client record directories: retrieves context from
- Consult before deciding → Business-unit knowledge: combines with
- KAM assistant + CRM connector → Register complete incident: uses to register
- Register complete incident → Incident stream: writes
- KAM assistant + CRM connector → Promotion learning: uses to learn
- Promotion learning → Promotion stream: writes
- KAM assistant + CRM connector → Activity stream: updates after activity
- KAM assistant + CRM connector → KAM record: supports
- Mount the hive → KAM assistant + CRM connector: configures workflow for