Saltar a contenido

Get Started Multiplataforma con ATQ

Objetivo

Dar una entrada rápida para usar atq desde distintos dispositivos sin obligar a entender todo el repositorio desde el minuto uno.

Esta guía está orientada a:

  • Kabehz
  • L0KY
  • AJCG131281
  • nuevos colaboradores
  • operadores que necesitan usar el sistema antes de contribuir al repo

Regla simple

Si quieres usar ATLANTYQA:

  1. entra por atq
  2. sigue una ruta corta por rol o dispositivo
  3. valida por FSM
  4. deja evidencia

Si quieres desarrollar ATLANTYQA, entonces ve a GET-STARTED.md.

Qué experiencia intenta dar atq

atq no pretende que memorices scripts internos ni que adivines saltos ocultos.

La experiencia buscada es esta:

  • una intención humana clara antes del comando
  • una entrada corta que funcione igual en varias plataformas
  • una progresión visible por estados
  • una acción útil por bloque
  • feedback rápido
  • evidencia local antes de depender de remoto
  • continuidad entre móvil, desktop/laptop y CLI sin perder contexto

Importante

  • la shell puede ser nativa
  • el runtime Python del repo debe ejecutarse desde .venv
  • si cierras la terminal, vuelve a activar .venv
  • la experiencia multiplataforma no significa que todos los dispositivos hagan todo igual
  • desktop/laptop es la ruta completa; smartphone y tablet suelen actuar como ruta de consulta, validación y handoff

Por qué local-first importa

Usar atq en modo local-first no es solo una preferencia técnica.

También sirve para:

  • preservar autoría y propiedad intelectual del colaborador
  • dejar evidencia reproducible en repo y outputs/
  • evitar que decisiones o prompts útiles se pierdan en chats efímeros
  • mantener control humano sobre lo que se ejecuta, se comparte y se promueve

Ruta rápida de 10 minutos

Paso 1. Clona el repo

bash git clone https://github.com/atlantyqa-labs/atlantyqa-universe.git cd atlantyqa-universe

Paso 2. Activa el entorno Python si vas a usar tooling del repo

bash python3 -m venv .venv source .venv/bin/activate python3 -m pip install --upgrade pip python3 -m pip install -r requirements.txt

Paso 3. Entra por atq

Ejemplos canónicos:

bash bash scripts/atq device sso describe --audience onboarding bash scripts/atq human onboarding --mode plan --domain ops --use-case bootstrap-artifacts bash scripts/atq ops reconcile --audience onboarding --dry-run

Paso 4. Valida tu nodo

Ejemplos:

bash bash scripts/atq collab doctor --collaborator-id l0ky bash scripts/atq collab doctor --collaborator-id ajcg131281

Matriz real por dispositivo

Dispositivo o plataforma Qué se espera de verdad Entrada ATQ recomendada Nivel
Linux desktop/laptop experiencia completa de operación local-first collab, ops, human, device recommended
macOS experiencia casi completa con shell + bash + .venv human, ops, device, doctor supported
Windows con WSL experiencia completa si el trabajo real vive en WSL collab, ops, human, device supported-via-wsl
Windows sin WSL lectura y validación parcial; evitar asumir paridad total portal + GitHub + shell compatible limited
Android / Termux bootstrap ligero, lectura operativa y consultas rápidas device, human onboarding, ops reconcile --dry-run lightweight
Smartphone con GitHub App revisión, evidencia, decisiones y handoff portal + issue/PR + CTA móviles review-companion
Tablet lectura guiada, revisión UX/UI y handoff portal + GitHub + CLI remoto si aplica companion

Qué cambia según el dispositivo

Desktop o laptop

Es la ruta canónica cuando necesitas:

  • clonar el repo
  • activar .venv
  • ejecutar collab doctor
  • correr validaciones
  • tocar archivos
  • preparar evidencia fuerte antes de PR

Experiencia esperada:

  1. abres triad-control-plane
  2. formulas objetivo en una frase
  3. ejecutas doctor
  4. eliges una acción corta en atq
  5. registras evidencia en outputs/, PR o bitácora

Smartphone

No es la mejor superficie para cambiar mucho código, pero sí para:

  • leer la PR
  • revisar CTA y narrativa del portal
  • validar que la experiencia no exige zoom o contexto oculto
  • abrir issues/PR desde GitHub App
  • dejar una nota corta de evidencia o decisión humana

Experiencia esperada:

  1. abrir portal o PR
  2. entender en pocos segundos qué toca hacer
  3. confirmar si el siguiente paso real debe pasar a laptop/desktop
  4. dejar handoff breve si no ejecutas CLI local

Tablet

Debe sentirse como una superficie intermedia:

  • mejor lectura que móvil
  • menos potencia operativa que laptop
  • útil para revisión guiada, demos, onboarding o validación UX/UI

Si en la sesión no hay tablet real, marca no-aplica y no inventes cumplimiento.

Android / Termux

Sirve para una experiencia ligera de CLI cuando buscas:

  • recordar comandos
  • hacer consultas rápidas
  • validar narrativa y semántica del wrapper
  • preparar handoff hacia un nodo más completo

No debe presentarse como sustituto automático del entorno completo de contributor.

Rutas cortas por persona

Kabehz

Objetivo típico: coordinación local, contrato de tríada y decisión de ruta.

bash bash scripts/atq human ops --mode plan --domain governance --use-case triad-sync

Qué debería sentir:

  • la intención está clara antes de ejecutar
  • la salida ayuda a decidir, no a improvisar
  • la continuidad entre agentes queda visible

L0KY

Objetivo típico: revisión, riesgo y prioridad de merge.

bash bash scripts/atq ops reconcile --audience onboarding --dry-run

Qué debería sentir:

  • el comando reduce ruido
  • se entiende el riesgo sin abrir diez rutas a la vez
  • el siguiente paso de revisión queda claro

AJCG131281

Objetivo típico: primer avance real sin fricción innecesaria.

bash bash scripts/atq collab doctor --collaborator-id ajcg131281

Qué debería sentir:

  • el primer paso es evidente
  • el bloqueo, si existe, queda explicado
  • el sistema invita a seguir por FSM y no por intuición

Secuencias de uso recomendadas

A. Laptop/desktop first

bash source .venv/bin/activate bash scripts/atq collab doctor --collaborator-id ajcg131281 bash scripts/atq ops reconcile --audience onboarding --dry-run

Úsala cuando vas a ejecutar, validar y dejar evidencia fuerte.

B. Smartphone first

  1. abrir docs/index.md o portal/triad-control-plane/
  2. abrir issue/PR relevante
  3. decidir si basta una revisión o hace falta pasar a laptop
  4. dejar una nota breve con hallazgo, bloqueo o decisión

Úsala cuando prima velocidad de lectura y decisión humana.

C. Cross-device handoff

  1. móvil para leer y detectar fricción
  2. laptop para ejecutar doctor, validar y editar
  3. móvil otra vez para comprobar CTA y PR final

Esta es la experiencia multiplataforma más realista del stack actual.

FSM mínima para operar

graph TD
    S0[S0_ENTRY] --> S1[S1_CONTEXT]
    S1 --> S2[S2_DOCTOR]
    S2 --> S3[S3_ROUTE]
    S3 --> S4[S4_ACTION]
    S4 --> S5[S5_EVIDENCE]
    S5 --> S6[S6_DECISION]
    S2 --> F1[F1_BLOCKED]
    S4 --> F2[F2_UNCLEAR]
    S5 --> F3[F3_EVIDENCE_GAP]

Interpretación

  • S0_ENTRY: entrar por una ruta visible
  • S1_CONTEXT: decir qué intentas hacer
  • S2_DOCTOR: validar entorno o colaborador
  • S3_ROUTE: elegir el comando o portal correcto
  • S4_ACTION: ejecutar una acción pequeña
  • S5_EVIDENCE: registrar resultado
  • S6_DECISION: clasificar si sigues, corriges o bloqueas

Qué significa una buena UX multiplataforma en ATQ

La experiencia es buena cuando:

  • el mismo lenguaje operativo sirve en móvil, laptop y CLI
  • el usuario sabe rápido si está en modo lectura, validación o ejecución
  • el portal y los comandos apuntan al mismo contrato
  • un bloqueo se entiende como bloqueo real, no como fallo personal
  • el handoff entre dispositivos no rompe el contexto

La experiencia es mala cuando:

  • el móvil obliga a adivinar el siguiente paso
  • el desktop exige contexto oculto
  • el CLI devuelve mensajes opacos
  • la PR no deja claro objetivo, evidencia y decisión pendiente

Evidencia mínima esperada

Después de usar atq en cualquier dispositivo, intenta dejar al menos una de estas trazas:

  • comentario en PR o issue
  • entrada en docs/internal/bitacora/
  • artefacto en outputs/**
  • resumen corto con hecho, hipótesis y siguiente paso

Learning by doing

No intentes aprender todo a la vez.

Haz este patrón:

  1. un comando
  2. una expectativa
  3. una comprobación
  4. una nota corta de resultado

Ese es el núcleo de vibe coding gobernado: exploración rápida, pero con validación y memoria compartida.

Errores comunes a evitar

  • usar el Python global para validaciones del repo en vez de .venv
  • asumir que móvil debe sustituir a laptop en tareas de contributor
  • abrir runbooks internos profundos antes de dominar atq
  • ejecutar cambios reales sin pasar por plan o sin evidencia
  • tratar una lectura rápida en smartphone como validación completa de UX/UI

Siguiente capa

Cuando ya domines la entrada corta:

  • arquitectura: docs/atq/operating-system-architecture.md
  • portal operativo: docs/portal/triad-control-plane.md
  • validación UX/UI: docs/portal/triad-ui-ux-validation-windows.md
  • contributor setup: GET-STARTED.md