Saltar a contenido

Modelo de Interaccion Humano-Agente (Local + Remoto)

Objetivo

Definir una operativa unica para que cada perfil (rol tecnico, negocio y comunicacion) sepa como trabajar entre Notebook local, VSCode, Codex (agente local) y entornos remotos con agentes dockerizados GitOps.

Fuente canónica visual

Para arquitectura por capas, grafo de decisión y mindmap multi-audiencia, usar primero docs/portal/operating-visual-canon.md.

1. Alcance operativo

Este modelo cubre la colaboracion entre:

  1. desarrollo local en dispositivo del colaborador (laptop, workstation o nodo edge),
  2. trabajo asistido por agente local (Codex),
  3. ejecucion remota gobernada por GitHub + GitOps,
  4. operacion multi-dispositivo bajo repositorio privado atlantyqa-labs/atlantyqa-universe.

1.1 Principio rector: Git como motor y origen de verdad

  1. git define estado deseado, cambios aprobados y versionado de evidencia.
  2. dashboards y vistas GUI consumen estado derivado de main, PRs, issues y artefactos CI.
  3. no se considera valido ningun estado operativo que no exista en git + trazabilidad de workflow.
  4. la interfaz para cada audiencia debe mostrar solo datos y acciones coherentes con su rol.

1.2 Sistemas en juego (vista facil)

Sistema Quien lo usa primero Para que sirve Salida obligatoria
Dispositivo local (laptop/desktop) cada colaborador preparar cambios y evidencia inicial branch local + notas tecnicas
VSCode + Codex perfiles tecnicos y mixtos implementar cambios y validaciones commits semanticos
Repositorio personal (fork o repo propio) colaborador individual sandbox y pruebas controladas PR hacia repositorio oficial
Repositorio oficial atlantyqa-universe todo el equipo source of truth y gobernanza issue + PR + checks + decision humana
GitHub GUI / GitHub App lideres, QA, negocio, comunicacion aprobaciones, labels, estado y cierre decision humana explicita
Runners remotos (hosted/self-hosted) DevSecOps/Infra ejecucion reproducible de workflows artefactos y logs auditables
Entornos remotos gestionados (Proxmox/MicroK8s/cloud) Infra + owners de dominio operar servicios y despliegues evidencia operativa trazable

1.3 Regla de oro por tipo de repositorio

  1. repositorio personal: iterar rapido, sin secretos, sin decisiones finales de gobernanza.
  2. repositorio oficial: toda decision valida para negocio/compliance vive en issue/PR del repo oficial.
  3. sincronizacion personal -> oficial: siempre por PR, nunca por copia manual fuera de git.
  4. si un colaborador cambia de dispositivo, el estado se recupera desde git y no desde carpetas locales.

2. Capas de trabajo

graph TD
    A[Notebook Local] --> B[VSCode Workspace]
    B --> C[Codex Agente Local]
    C --> D[Git Commit + PR]
    D --> E[Workflows GitHub]
    E --> F[Agentes Dockerizados GitOps]
    F --> G[Infra multi-dispositivo]
    G --> H[Evidencia + Decision humana]

    style A fill:#f1f5f9,stroke:#182232,stroke-width:2px,color:#182232
    style C fill:#5dc6d1,stroke:#2a8690,stroke-width:2px,color:#182232
    style E fill:#e7ae4c,stroke:#8b6914,stroke-width:2px,color:#182232
    style F fill:#37a880,stroke:#1f6d52,stroke-width:2px,color:#ffffff
    style H fill:#182232,stroke:#0b1626,stroke-width:2px,color:#ffffff

3. Contrato de interaccion humano-agente

  1. humano define objetivo, alcance y riesgo.
  2. agente propone cambios tecnicos, validaciones y evidencias.
  3. humano elige opcion (ClickOps o comentario estructurado en PR/Issue).
  4. agente ejecuta, registra resultados y deja trazabilidad reproducible.
  5. humano aprueba o bloquea con criterio explicito.

Referencia de gobierno:

  • protocolo humano: docs/portal/human-decision-protocol.md
  • gobernanza de repositorio: docs/trust/repository-governance.md
  • hub operativo GitHub: docs/portal/github-collaboration-hub.md

4. Matriz por rol y tipo de actor

Perfil Entrada principal Interaccion esperada Superficie minima de apps Salida minima Decision humana requerida
DevSecOps / Plataforma VSCode + Codex + runbooks iteracion tecnica, hardening, IaC, CI VSCode, terminal, PR checks, dashboard GitOps PR con evidencia tecnica aprobacion tecnica de responsable
Data/AI/Notebook Notebook local + VSCode experimentacion controlada y export a GitOps Notebook, repositorio de datos curados, PR/artefactos notebook versionado + artefacto validado validacion de impacto y trazabilidad
QA / Auditoria PR + artefactos de workflow verificacion de gates, checks y evidencia vista de checks CI, reporte de evidencias, lectura PR checklist de conformidad aceptacion/bloqueo explicito
Colaborador externo Portal onboarding + GitHub Project tarea acotada con guia y soporte portal onboarding, issue board, PR form issue/PR con pasos reproducibles tutor/lead confirma cumplimiento
Empleado Flujo completo local-remoto ejecucion diaria y comunicacion de estado portal, panel operativo, PR/issue, dashboard de estado entrega con metricas y evidencia cierre por owner de dominio
Socio Trust pack + tablero proyecto alineacion de compromiso y capacidad trust pack, vista ejecutiva de roadmap, board de hitos plan o decision compartida aprobacion de direccion/lead
Ventas one-pagers + trust pack + estado PR traduce capacidad tecnica a propuesta cliente one-pagers, trust pack, tablero comercial resumido narrativa comercial trazable validacion con equipo tecnico
Medios / Comunicacion governance pack + release notes difusion sin filtrar datos sensibles release notes aprobadas, pack de comunicacion, estado publico comunicado compatible compliance aprobacion final responsable corporativo

4.1 Vistas GUI por audiencia (minimas y necesarias)

  1. tecnica (DevSecOps/Infra/QA): estado de pipelines, riesgos, drift y evidencias.
  2. delivery (empleados/colaboradores): backlog activo, bloqueos, SLA y siguiente accion.
  3. negocio (socios/ventas): capacidad entregable, riesgos comunicables y estado contractual.
  4. medios/comunicacion: solo narrativa aprobada, hitos publicados y FAQ de incidentes.

Referencia UI:

  • docs/user-interface/overview.md
  • docs/user-interface/dashboard.md
  • docs/user-interface/gitops.md

5. Flujos por entorno

5.1 Notebook de desarrollo local

  • objetivo: explorar y validar rapido sin romper flujo gobernado.
  • norma: todo resultado relevante pasa a PR (no queda solo en local).
  • salida: evidencia exportable (logs, markdown, json, reporte).

5.2 VSCode + Codex (agente local)

  • objetivo: implementar cambios en codigo, docs y workflows con iteracion corta.
  • norma: cada cambio incluye contexto de por que, riesgo y validacion.
  • salida: commit semantico + descripcion de PR alineada al template.

5.3 Entornos remotos con agentes dockerizados GitOps

  • objetivo: ejecutar pipelines reproducibles en runners (hosted/self-hosted).
  • norma: no ejecutar sin gate humano en cambios de gobierno o main.
  • salida: estado de checks, artefactos, evidencias y decision final.

5.4 Repositorios personales por colaborador

  • objetivo: permitir exploracion local-first sin bloquear al equipo.
  • norma:
  • usar fork/repo personal para pruebas o refactor grande.
  • promover cambios por PR al repositorio oficial.
  • nunca guardar secretos o datos sensibles en repos personales.
  • salida: rama promovible + PR con trazabilidad (#issue) en el repo oficial.

6. Quickstart por actor (adopcion en 30 minutos)

  1. entrar por docs/portal/institutional-onboarding.md.
  2. tomar una tarea en https://github.com/orgs/atlantyqa-labs/projects/1.
  3. ejecutar flujo minimo local (Notebook o VSCode + Codex).
  4. abrir PR con trazabilidad (#issue o #pr) y evidencia.
  5. solicitar decision humana explicita segun rol.

6.1 Flujo humano-maquina minimo (7 pasos)

  1. humano abre issue y define objetivo/riesgo.
  2. Codex propone cambio y plan de validacion.
  3. colaborador ejecuta en local (VSCode/terminal/notebook).
  4. push a rama y apertura de PR en repo oficial.
  5. workflows validan (bots de cumplimiento + checks tecnicos).
  6. humano decide en GUI (Aprobado, Cambios requeridos, Bloqueado, En espera de evidencia).
  7. merge/cierre y registro de evidencia final.

7. Reglas no negociables

  1. no hay cambios a main sin control de gate y aprobacion humana.
  2. no hay comunicacion externa (ventas/medios) sin validacion de compliance.
  3. no hay artefactos sin trazabilidad de origen y version.
  4. no hay colaboracion multi-dispositivo sin estado visible en Project/PR.
  5. no hay dashboard operativo fuera de datos sincronizados desde git.

8. Checklists rapidas

Tecnica (Dev/Infra)

  • scope claro en issue/PR
  • evidencia adjunta
  • checks CI en verde o excepcion justificada
  • decision humana registrada

Negocio (Ventas/Medios/Socios)

  • mensaje alineado a estado real de plataforma
  • riesgos y limites explicitos
  • referencia a evidencia verificable
  • aprobacion final registrada

8.1 Checklist por dispositivo

GitHub App (movil)

  • revisar checks y comentarios.
  • confirmar trazabilidad #issue.
  • aplicar labels de operacion/aprobacion.
  • registrar decision humana final.

Desktop (GitHub Web)

  • revisar diff completo y artefactos.
  • validar gates de gobernanza.
  • dejar comentario de aceptacion/bloqueo con evidencia.
  • mergear solo cuando el protocolo humano este completo.

Local (VSCode + terminal)

  • ejecutar validaciones locales minimas.
  • preparar commits semanticos pequenos.
  • subir solo cambios trazables al objetivo del issue/PR.

9. Metodo dinamico de aprendizaje por colaborador

  1. cada interacción relevante (issue, PR, review, decision humana) se trata como señal de aprendizaje.
  2. el sistema calcula una etapa de madurez por colaborador: bootstrap, guided, autonomous, mentor.
  3. cada etapa define tipo de carga permitida y nivel de supervisión.
  4. cualquier cambio de etapa se confirma por humano responsable en GUI.

Comando de referencia:

python3 scripts/generate-collaborator-dynamic-learning-report.py

Artefactos de salida:

  1. outputs/insights/collaborator-dynamic-learning-report.tsv
  2. outputs/insights/collaborator-dynamic-learning-report.md

10. Resultado esperado

Este modelo reduce friccion de onboarding, evita ambiguedad entre equipos y permite que cada colaborador opere rapido con seguridad, trazabilidad y lenguaje comun entre perfiles tecnicos y no tecnicos.