Activation Guide

This repo is now set up with the team definitions and a GitHub-native control-tower scaffold. You do not need to run anything locally.

What Is Already In Repo

• agent definitions under agents/

• ownership map in agents/registry.yml

• control-tower workflow in .github/workflows/autonomous-shipping.yml

• GitHub-hosted dispatcher in .github/workflows/autonomous-dispatch.yml

• scoped intake template in .github/ISSUE_TEMPLATE/agent-task.yml

• updated CI and PR template for truthful validation

Smallest Real Deployment

1. Protect main in GitHub.

2. Enable auto-merge for PRs.

3. Create labels from docs/autonomy/OPERATING_MODEL.md.

4. Add repo variables for the hosted runner executor.

5. Add GITHUB_MODELS_TOKEN as a GitHub Actions secret for the default hosted executor, or set AUTONOMY_EXECUTOR_SETUP_CMD if your coding tool needs installation on the GitHub runner.

6. Optionally set AUTONOMY_AGENT_CMD_TEMPLATE in repo or org variables to override the default coding command.

7. Optionally set AUTONOMY_OPEN_PR=true if the executor should auto-commit, push, and open a draft PR when changes exist.

8. Let .github/workflows/autonomous-dispatch.yml claim autonomy:ready issues, generate a work order, and invoke the executor on ubuntu-latest.

Hosted Runner Shape

• GitHub-hosted ubuntu-latest

• ephemeral checkout each run

• GitHub CLI authenticated with GITHUB_TOKEN

• Python 3.11 and Node 20 available in workflow

Executor Variables

• AUTONOMY_EXECUTOR_SETUP_CMD: optional install/bootstrap shell command for the hosted runner

• AUTONOMY_AGENT_CMD_TEMPLATE: command template invoked after branch prep

• AUTONOMY_OPEN_PR: true or false

• AUTONOMY_BASE_BRANCH: optional, defaults to main

• AUTONOMY_BRIEF_DIR: optional, defaults to .autonomy/briefs

• AUTONOMY_MODEL: optional, defaults to gpt-4.1-mini

• AUTONOMY_MAX_PATCH_BYTES: optional, defaults to 50000

• AUTONOMY_MAX_CHANGED_FILES: optional, defaults to 6

• AUTONOMY_REVIEWER_MAP: optional JSON object mapping reviewer-agent ids to GitHub logins

• AUTONOMY_STALE_CLAIM_MINUTES: optional, defaults to 120

Required Secret

• GITHUB_MODELS_TOKEN: preferred for the default hosted executor in scripts/autonomy/hosted_llm_executor.py

Optional Secret

• OPENAI_API_KEY: alternate provider for the same hosted executor if you do not use GitHub Models

Example:

AUTONOMY_EXECUTOR_SETUP_CMD=pip install openai
AUTONOMY_AGENT_CMD_TEMPLATE=python scripts/autonomy/github_hosted_agent.py --agent {agent} --brief {brief} --work-order {work_order}
AUTONOMY_OPEN_PR=true

If AUTONOMY_AGENT_CMD_TEMPLATE is unset but GITHUB_MODELS_TOKEN or OPENAI_API_KEY is present, the workflow falls back to:

python scripts/autonomy/hosted_llm_executor.py --agent {agent} --brief {brief} --work-order {work_order}

If a generated patch exceeds the configured size or file-count guardrails, the executor stops and writes .autonomy/guardrail-failure.json for debugging.

If AUTONOMY_REVIEWER_MAP is set, the executor also assigns the mapped GitHub login to the PR and leaves a reviewer-routing comment.

If an issue stays labeled autonomy:claimed past AUTONOMY_STALE_CLAIM_MINUTES and no open PR exists for the claimed branch, the dispatch workflow automatically releases the claim and comments on the issue.

Dispatch Logic

Use scripts/autonomy/select_agent.py to map labels to a specialist and release lane. Use scripts/autonomy/build_work_order.py to pick the highest-priority unclaimed issue and create an executor-ready work order. Use scripts/autonomy/execute_work_order.py to create the branch, write the brief, optionally comment on the issue, invoke the hosted coding command, and optionally open a draft PR.

Example:

python scripts/autonomy/select_agent.py \
  --issue 123 \
  --labels autonomy:ready autonomy:safe area:cli-sdk risk:low size:s

python scripts/autonomy/build_work_order.py \
  --queue autonomy-queue.json \
  --output autonomy-work-order.json

python scripts/autonomy/execute_work_order.py autonomy-work-order.json

Recommended First Automation

• let the orchestrator open or update a queue summary every 15 minutes

• let only 2 to 4 agents author code at first

• require reviewer assignment before merge

• auto-merge only safe-auto-merge lane changes

Do Not Enable Yet

• unattended infra applies

• unattended auth-breaking changes

• unattended production migrations

• unattended runtime protocol rewrites

Expansion Path

1. Stabilize CI truthfulness.

2. Let safe lanes auto-merge.

3. Add staging deployment gates.

4. Add a second reviewer agent for backend and runtime changes.

5. Expand the active pool to all 10 agents.