Skip to content

Multi-platform Get Started with ATQ

Goal

Provide a fast entry point to use atq across devices without forcing people to understand the whole repository from minute one.

This guide is aimed at:

  • Kabehz
  • L0KY
  • AJCG131281
  • new collaborators
  • operators who need to use the system before contributing to the repo

Simple rule

If you want to use ATLANTYQA:

  1. enter through atq
  2. follow a short route by role or device
  3. validate through FSM
  4. leave evidence

If you want to build ATLANTYQA, then go to GET-STARTED.md.

What kind of experience atq tries to provide

atq is not meant to force people to memorize internal scripts or guess hidden jumps.

The intended experience is:

  • a clear human intention before the command
  • one short entry layer that works across platforms
  • visible state progression
  • one useful action per block
  • fast feedback
  • local evidence before relying on remote systems
  • continuity across mobile, desktop/laptop, and CLI without losing context

Important

  • the shell can be native
  • the repo Python runtime should come from .venv
  • if you close the terminal, activate .venv again
  • multi-platform does not mean every device should do everything equally
  • desktop/laptop is the full route; smartphone and tablet usually act as reading, validation, and handoff surfaces

Why local-first matters

Using atq in local-first mode is not just a technical preference.

It also helps:

  • preserve collaborator authorship and intellectual property
  • leave reproducible evidence in the repo and outputs/
  • avoid losing useful decisions or prompts inside ephemeral chats
  • keep human control over what gets executed, shared, and promoted

10-minute quick route

Step 1. Clone the repo

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

Step 2. Activate the Python environment if you will use repo tooling

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

Step 3. Enter through atq

Canonical examples:

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

Step 4. Validate your node

Examples:

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

Real device matrix

Device or platform What is realistically expected Recommended ATQ entry Level
Linux desktop/laptop full local-first operation experience collab, ops, human, device recommended
macOS near-full experience with shell + bash + .venv human, ops, device, doctor supported
Windows with WSL full experience if the real work happens inside WSL collab, ops, human, device supported-via-wsl
Windows without WSL partial reading and validation; do not assume full parity portal + GitHub + compatible shell limited
Android / Termux light bootstrap, operational reading, and quick queries device, human onboarding, ops reconcile --dry-run lightweight
Smartphone with GitHub App review, evidence, decisions, and handoff portal + issue/PR + mobile CTAs review-companion
Tablet guided reading, UI/UX review, and handoff portal + GitHub + remote CLI if needed companion

What changes by device

Desktop or laptop

This is the canonical route when you need to:

  • clone the repo
  • activate .venv
  • run collab doctor
  • run validations
  • edit files
  • prepare strong evidence before a PR

Expected experience:

  1. open triad-control-plane
  2. state the goal in one sentence
  3. run doctor
  4. choose one short atq action
  5. record evidence in outputs/, PR, or logbook

Smartphone

It is not the best surface for changing a lot of code, but it is good for:

  • reading the PR
  • reviewing portal CTAs and narrative
  • validating that the experience does not require zoom or hidden context
  • opening issues/PRs from GitHub App
  • leaving a short evidence or decision note

Expected experience:

  1. open the portal or PR
  2. understand the next step in a few seconds
  3. confirm whether the real next step must move to laptop/desktop
  4. leave a short handoff if you do not run local CLI

Tablet

It should feel like an intermediate surface:

  • better reading than mobile
  • less operational power than laptop
  • useful for guided review, demos, onboarding, or UI/UX validation

If no real tablet is used in the session, mark not-applicable and do not invent compliance.

Android / Termux

It supports a light CLI experience when you want to:

  • recall commands
  • run quick queries
  • validate wrapper narrative and semantics
  • prepare a handoff to a stronger node

It should not be presented as an automatic substitute for the full contributor environment.

Short routes by person

Kabehz

Typical goal: local coordination, triad contract, and route decision.

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

What it should feel like:

  • intent is clear before execution
  • output helps decision-making rather than improvisation
  • continuity between agents stays visible

L0KY

Typical goal: review, risk, and merge priority.

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

What it should feel like:

  • the command reduces noise
  • risk is understandable without opening ten paths at once
  • the next review step is clear

AJCG131281

Typical goal: first real progress without unnecessary friction.

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

What it should feel like:

  • the first step is obvious
  • a block, if present, is explained
  • the system invites the user to follow FSM instead of intuition

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

Use it when you will execute, validate, and leave strong evidence.

B. Smartphone first

  1. open docs/index.md or portal/triad-control-plane/
  2. open the relevant issue/PR
  3. decide whether a review is enough or work must continue on laptop
  4. leave a short note with finding, block, or decision

Use it when reading speed and human decision-making matter most.

C. Cross-device handoff

  1. mobile to read and detect friction
  2. laptop to run doctor, validate, and edit
  3. mobile again to verify CTA behavior and final PR state

This is the most realistic multi-platform experience for the current stack.

Minimal FSM to operate

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]

Interpretation

  • S0_ENTRY: enter through a visible route
  • S1_CONTEXT: state what you are trying to do
  • S2_DOCTOR: validate the environment or collaborator
  • S3_ROUTE: choose the correct command or portal
  • S4_ACTION: execute one small action
  • S5_EVIDENCE: record the result
  • S6_DECISION: decide whether to continue, fix, or block

What good multi-platform UX means in ATQ

The experience is good when:

  • the same operational language works across mobile, laptop, and CLI
  • the user quickly knows whether they are in reading, validation, or execution mode
  • portal and commands point to the same contract
  • a block is presented as a real block, not as a personal failure
  • the handoff between devices keeps context intact

The experience is poor when:

  • mobile users have to guess the next step
  • desktop users need hidden context
  • CLI messages are opaque
  • the PR does not make goal, evidence, and pending decision explicit

Minimum evidence expected

After using atq on any device, try to leave at least one of these traces:

  • a PR or issue comment
  • an entry in docs/internal/bitacora/
  • an artifact in outputs/**
  • a short summary with fact, hypothesis, and next step

Learning by doing

Do not try to learn everything at once.

Follow this pattern:

  1. one command
  2. one expectation
  3. one check
  4. one short result note

That is the core of governed vibe coding: fast exploration, but with validation and shared memory.

Common mistakes to avoid

  • using global Python instead of .venv for repo validations
  • assuming mobile should replace laptop for contributor work
  • opening deep internal runbooks before mastering atq
  • executing real changes without plan or without evidence
  • treating a quick smartphone reading pass as full UI/UX validation

Next layer

Once you master the short entry layer:

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