Skip to content

Human-Agent Interaction Model (Local + Remote)

Objective

Define one operating model so each profile (technical, business, and communication) can work across local notebooks, VSCode, Codex (local agent), and remote GitOps dockerized agents.

Canonical visual source

For layered architecture, decision graph, and audience mindmap, use docs/portal/operating-visual-canon.en.md first.

1. Operational scope

This model covers collaboration across:

  1. local development on collaborator devices (laptop, workstation, or edge node),
  2. local agent-assisted work (Codex),
  3. remote governed execution through GitHub + GitOps,
  4. multi-device operations under private repo atlantyqa-labs/atlantyqa-universe.

1.1 Guiding principle: Git as engine and source of truth

  1. git defines desired state, approved changes, and evidence versioning.
  2. dashboards and GUI views consume state derived from main, PRs, issues, and CI artifacts.
  3. no operational state is valid without git traceability plus workflow evidence.
  4. each audience must only see data and actions aligned with role scope.

1.2 Systems in play (easy view)

System Primary user Purpose Mandatory output
Local device (laptop/desktop) each collaborator prepare changes and initial evidence local branch + technical notes
VSCode + Codex technical and mixed roles implement changes and validations semantic commits
Personal repository (fork or own repo) individual collaborator sandbox and controlled experiments PR into official repository
Official repository atlantyqa-universe whole team source of truth and governance issue + PR + checks + human decision
GitHub GUI / GitHub App leads, QA, business, communications approvals, labels, status, closure explicit human decision
Remote runners (hosted/self-hosted) DevSecOps/Infra reproducible workflow execution auditable artifacts and logs
Managed remote environments (Proxmox/MicroK8s/cloud) Infra + domain owners run services and deployments traceable operational evidence

1.3 Golden rule by repository type

  1. personal repository: iterate fast, no secrets, no final governance decisions.
  2. official repository: every valid business/compliance decision is recorded in official issues/PRs.
  3. personal -> official sync: always through PR, never manual copy outside git.
  4. if collaborator changes device, state is restored from git, not from local folders.

2. Work layers

graph TD
    A[Local Notebook] --> B[VSCode Workspace]
    B --> C[Codex Local Agent]
    C --> D[Git Commit + PR]
    D --> E[GitHub Workflows]
    E --> F[GitOps Dockerized Agents]
    F --> G[Multi-device Infrastructure]
    G --> H[Evidence + Human Decision]

    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. Human-agent interaction contract

  1. human sets goal, scope, and risk.
  2. agent proposes technical changes, validations, and evidence.
  3. human selects option (ClickOps or structured PR/Issue comment).
  4. agent executes, records outcomes, and leaves reproducible traceability.
  5. human explicitly approves or blocks.

Governance references:

  • human protocol: docs/portal/human-decision-protocol.en.md
  • repository governance: docs/trust/repository-governance.en.md
  • GitHub operational hub: docs/portal/github-collaboration-hub.en.md

4. Matrix by role and actor type

Profile Main entry point Expected interaction Minimum app surface Minimum output Required human decision
DevSecOps / Platform VSCode + Codex + runbooks technical iteration, hardening, IaC, CI VSCode, terminal, PR checks, GitOps dashboard PR with technical evidence technical owner approval
Data/AI/Notebook local notebook + VSCode controlled experimentation and GitOps export Notebook, curated dataset repo, PR/artifacts versioned notebook + validated artifact impact and traceability validation
QA / Audit PR + workflow artifacts verify gates, checks, and evidence CI checks view, evidence report, PR review compliance checklist explicit accept/block
External collaborator onboarding portal + GitHub Project scoped task with guided support onboarding portal, issue board, PR form reproducible issue/PR mentor/lead confirms compliance
Employee full local-remote flow daily execution and status communication portal, operations panel, PR/issue, status dashboard delivery with metrics and evidence domain owner closure
Partner trust pack + project board commitment and capability alignment trust pack, executive roadmap view, milestone board shared plan or decision leadership/lead approval
Sales one-pagers + trust pack + PR status translate technical capability into client proposal one-pagers, trust pack, summarized commercial board traceable commercial narrative validation with technical team
Media / Communications governance pack + release notes communicate without exposing sensitive data approved release notes, communication pack, public status view compliance-safe communication output final corporate owner approval

4.1 Audience GUI views (minimum and necessary)

  1. technical (DevSecOps/Infra/QA): pipeline status, risks, drift, and evidence.
  2. delivery (employees/collaborators): active backlog, blockers, SLA, and next action.
  3. business (partners/sales): deliverable capacity, communicable risks, and contractual status.
  4. media/communications: approved narrative only, published milestones, and incident FAQ.

UI references:

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

5. Flows by environment

5.1 Local development notebook

  • objective: fast exploration and validation without breaking governed flow.
  • rule: every relevant result must move to PR (not only local state).
  • output: exportable evidence (logs, markdown, json, report).

5.2 VSCode + Codex (local agent)

  • objective: implement code, docs, and workflow changes with short feedback loops.
  • rule: every change includes reason, risk, and validation.
  • output: semantic commit + PR description aligned with template.

5.3 Remote environments with GitOps dockerized agents

  • objective: run reproducible pipelines on hosted/self-hosted runners.
  • rule: no execution without human gate on governance/main-sensitive changes.
  • output: check status, artifacts, evidence, and final decision.

5.4 Personal repositories per collaborator

  • objective: allow local-first exploration without blocking the team.
  • rule:
  • use fork/personal repo for experiments or large refactors.
  • promote changes through PR to the official repository.
  • never store secrets or sensitive data in personal repositories.
  • output: promotable branch + PR with traceability (#issue) in official repo.

6. Quickstart by actor (30-minute adoption)

  1. enter through docs/portal/institutional-onboarding.en.md.
  2. pick a task in https://github.com/orgs/atlantyqa-labs/projects/1.
  3. run minimal local flow (Notebook or VSCode + Codex).
  4. open PR with traceability (#issue or #pr) and evidence.
  5. request explicit role-based human decision.

6.1 Minimal human-machine flow (7 steps)

  1. human opens issue and defines target/risk.
  2. Codex proposes change set and validation plan.
  3. collaborator executes locally (VSCode/terminal/notebook).
  4. push branch and open PR in official repo.
  5. workflows validate (compliance bots + technical checks).
  6. human decides in GUI (Approved, Changes requested, Blocked, Waiting for evidence).
  7. merge/close and register final evidence.

7. Non-negotiable rules

  1. no main changes without gate control and human approval.
  2. no external communication (sales/media) without compliance validation.
  3. no artifacts without source and version traceability.
  4. no multi-device collaboration without visible state in Project/PR.
  5. no operational dashboard outside git-synchronized data.

8. Fast checklists

Technical (Dev/Infra)

  • clear scope in issue/PR
  • evidence attached
  • CI checks green or justified exception
  • human decision registered

Business (Sales/Media/Partners)

  • message aligned with real platform status
  • risks and limits explicitly stated
  • reference to verifiable evidence
  • final approval registered

8.1 Device-based checklist

GitHub App (mobile)

  • review checks and comments.
  • confirm traceability #issue.
  • apply operation/approval labels.
  • register final human decision.

Desktop (GitHub Web)

  • review full diff and artifacts.
  • validate governance gates.
  • leave accept/block comment with evidence.
  • merge only when human protocol is complete.

Local (VSCode + terminal)

  • run minimum local validations.
  • prepare small semantic commits.
  • push only changes traceable to issue/PR scope.

9. Dynamic learning method per collaborator

  1. every relevant interaction (issue, PR, review, human decision) is treated as a learning signal.
  2. the system computes a maturity stage per collaborator: bootstrap, guided, autonomous, mentor.
  3. each stage defines allowed workload and supervision depth.
  4. stage transitions require explicit responsible human confirmation in GUI.

Reference command:

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

Output artifacts:

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

10. Expected outcome

This model reduces onboarding friction, removes ambiguity across teams, and lets each collaborator operate faster with security, traceability, and a shared language between technical and non-technical profiles.