Skip to content

Practical GitHub.com + GitHub App manual for actors

This guide is the practical collaboration reference for atlantyqa-universe:

  • contributors
  • reviewers/approvers
  • governance leads
  • infra/ops/compliance actors

1) Overview (mindmap)

mindmap
  root((ATLANTYQA GitHub Collaboration))
    Capture
      "Issue template"
      "Initial labels"
      "Project v2 card"
    Execution
      "Branch from main"
      "Small verifiable change"
      "Local validation"
    Integration
      "PR body + evidence"
      "Root cause + rollback"
      "HDP checkbox or HDP-*"
    Decision
      "CODEOWNERS review"
      "Required approvers"
      "CI/HDP gates"
    Closure
      "Merge to main"
      "Status Done"
      "Rolling RC update"

2) Operational layers (mindmap)

mindmap
  root((Operational layers))
    Actors
      "Contributor"
      "Reviewer"
      "Lead/HILT"
      "Infra/Ops"
    Channels
      "GitHub Web"
      "GitHub App mobile"
      "Local terminal (git/gh)"
    Artifacts
      "Issue"
      "Branch"
      "PR"
      "Project v2 item"
      "Workflow run"
    Governance
      "Labels"
      "PR template"
      "HDP gate"
      "CODEOWNERS"

3) Canonical flow (Issue -> PR -> Merge)

  1. create or pick an issue.
  2. set labels (or let auto-label workflows classify).
  3. move card to execution.
  4. create branch from main.
  5. apply a small verifiable change.
  6. open PR using .github/pull_request_template.md.
  7. complete HDP in checkbox mode or HDP-* mobile mode.
  8. request review and approvals.
  9. pass gates and merge.

4) Labels you should use

  • Domain: domain-docs, domain-ui, domain-core, domain-gitops, domain-ops
  • Skill: skill-python, skill-frontend, skill-devsecops, skill-docker, skill-docs, skill-data-ai
  • Compute: compute-low, compute-medium, compute-heavy
  • Level: level-beta, level-stable, level-critical
  • Status override: status-backlog, status-in-progress, status-in-review, status-done, status-blocked

Default status policy:

  • PR -> In Progress
  • new issue -> Backlog

5) PR body essentials

Required practical blocks:

  1. issue reference
  2. root cause
  3. applied change and trade-offs
  4. validation evidence
  5. rollback plan
  6. compliance/security checklist
  7. HDP decision block

Mobile HDP example:

HDP-TYPE: operativa-diaria
HDP-APPROVER: loky
HDP-DECISION: aprobado
HDP-TRACE: #123
HDP-EVIDENCE: https://github.com/atlantyqa-labs/atlantyqa-universe/actions/runs/123456
HDP-RISK: bajo
HDP-NEXT: merge-a-main

6) GitHub App mobile routine

  1. open notification.
  2. check Files changed and Checks.
  3. verify evidence/HDP completeness.
  4. add focused comment batch.
  5. apply decision (Approve, Request changes, Comment).

7) Common failures

  • HDP gate fails: missing section/checkboxes/directives in PR body.
  • Status drift: explicit status-backlog label or old workflow version not yet in main.
  • Human actor shown in automation: fallback PROJECT_TOKEN PAT is being used instead of GitHub App token.

8) Fast workflow error reading (ERRORLOG + actor actions)

When a workflow fails, run the local assistant to get likely root cause and actor-specific remediation:

python3 scripts/workflow_errorlog_assistant.py \
  --run-url "https://github.com/atlantyqa-labs/atlantyqa-universe/actions/runs/<run_id>/job/<job_id>?pr=<pr>" \
  --actor-login "<github_login>"

Generated output:

  • outputs/workflow-triage/workflow-triage-<timestamp>.md
  • outputs/workflow-triage/workflow-triage-<timestamp>.json

It provides:

  1. high-signal ERRORLOG snippets,
  2. root-cause candidates,
  3. concrete actions by actor (PR Author, Reviewer, Ops/Governance),
  4. copy-paste PR comment template.

9) Context handoff for new agent sessions

To transfer compact repository context across sessions/tools (Codex/Claude/local agent):

python3 scripts/build-agent-context-pack.py --profile codex

Full guide:

  • docs/portal/agent-context-handoff-sca.en.md

10) Executable action when opening PR from agent

To sync context automatically on PR open/update:

python3 scripts/agent_pr_context_sync.py \
  --summary "Summary of the change in this PR update" \
  --scope "pr-open-context-sync" \
  --agent-id codex \
  --actor-login Kabehz \
  --comment-pr \
  --commit-ledger

It will:

  1. append compact entry to context ledger,
  2. regenerate context-pack,
  3. post didactic PR comment (if PR is detected),
  4. create segregated ledger commit (with --commit-ledger).

Place the agent on the exact repository context before coding:

Initial bootstrap + per-actor tech timer in one step:

python3 scripts/agent_context_bootstrap_local.py \
  --profile codex \
  --mode bootstrap \
  --actor-login Kabehz \
  --bootstrap-systemd-steward \
  --steward-only-tech-people \
  --steward-enable-now

Incremental update (once bootstrap already exists):

python3 scripts/agent_context_bootstrap_local.py \
  --profile codex \
  --mode update \
  --agent-id codex \
  --actor-login Kabehz \
  --interaction-scope "pr-open-context-sync" \
  --interaction-summary "Compact summary of this increment"

Validate consistency before pushing:

python3 scripts/validate_agent_context_pack.py \
  --pack outputs/agent-context/context-pack-latest.json \
  --ledger knowledge/datasets/agent-context-transfer-log.jsonl \
  --report outputs/agent-context/context-pack-validation-latest.md

context-pack-validation-latest.md should end in PASS.

12) Full literal transfer (100% raw) for collaborators

If you need full historical handoff (no summarization), build raw archive + manifest:

python3 scripts/build-agent-context-raw-archive.py \
  --raw-file docs/internal/release-rc-mvp-synthesis.md \
  --raw-file inputs/deep-research-report.md \
  --raw-dir inputs \
  --glob "*.docx"

Then attach that manifest into the compact pack:

python3 scripts/build-agent-context-pack.py \
  --profile codex \
  --raw-transfer-manifest outputs/agent-context/raw/agent-context-raw-manifest-latest.json

And validate that compact pack requires raw evidence:

python3 scripts/validate_agent_context_pack.py \
  --pack outputs/agent-context/context-pack-latest.json \
  --ledger knowledge/datasets/agent-context-transfer-log.jsonl \
  --require-raw-transfer \
  --report outputs/agent-context/context-pack-validation-latest.md

13) Decentralized local steward (no history loss, no memory leak)

For multi-device/multi-clone teams, use local steward:

python3 scripts/agent_context_steward.py --mode once --profile codex --with-raw-transfer --require-raw-transfer

Benefits:

  1. preserves literal history + compact pack per local environment,
  2. applies safe retention pruning without breaking traceability,
  3. avoids long-running process leaks: run via systemd --user timer.

Ready templates:

  • ops/systemd/user/atq-context-steward.service
  • ops/systemd/user/atq-context-steward.timer
  • ops/systemd/user/README.md

Ultra-fast per-tech-profile guide:

  • docs/portal/tech-people-context-steward-quickstart.en.md

ATQ-CST-001 policy:

  • never use generic atq-context-steward.timer/service,
  • always use actor-scoped units (atq-context-steward-<persona>.*) via scripts/install_context_steward_for_actor.py --migrate-legacy-generic.