Canonical source: docs/claude/agent-fleet.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.
Atlas & the Autonomous Agent Fleet
What this is. The authoritative map of Atlas (Ready Practice's AI) and the autonomous agent fleet that runs the platform's engineering + growth + ops loops. Read this before touching any agent, the build/triage pipeline, the intake router, or the operator/COO loops. Deep-dives for individual arms are linked at the bottom.
1. What "Atlas" is
Atlas is the single AI brand across Ready Practice, wearing several hats:
| Hat | Who sees it | Where it lives |
|---|---|---|
| Copilot (staff) | Clinic staff in basisflow-web | functions_orchestrator.py → functions_ai_agent.py (tools) |
| Clinical assistant | Providers (pre-visit, notes, labs) | same orchestrator, clinical intent set |
| Health Assistant (consumer) | Clients in basishybrid | functions_atlas_consumer.py |
| COO / Operator | George (Ready Practice itself) | functions_atlas_operator.py |
| Slack employee | Staff in Slack | functions_atlas_slack.py |
Atlas is model-tiered via atlas_models.py — ATLAS_FAST (Haiku), ATLAS_BALANCED
(Sonnet), ATLAS_SMART (Opus). Never hardcode model literals — import the constants
(the #232 refactor did this fleet-wide; functions_model_watch.py auto-detects new models).
Adding an Atlas tool — the 5 registration layers (all silent-fail)
- TOOLS schema in
functions_ai_agent.py - TOOL_PERMISSION_MAP in
functions_permissions.py(default-DENY — missing = invisible) - Intent set in
functions_orchestrator.py(UNIVERSAL/CLINICAL/OPS/RESEARCH — missing = orchestrator STRIPS it) - Dispatch branch (the executor)
- Function decorator
secrets=[](missing secret = silent 500)
.github/scripts/lint_registrations.py cross-checks layers 1–4 + secret gaps; it runs in
predeploy and CI (lint-registrations.yml). Run it after any tool change. A second
gate — .github/scripts/lint_prompt_fencing.py (#305) — blocks unfenced untrusted text
(error/user-sourced strings) reaching an LLM prompt; also predeploy + CI. Untrusted text
entering a prompt MUST go through fence_untrusted() (functions) or an explicit
===== UNTRUSTED DATA ===== marker.
2. The autonomous agent fleet
Every agent below runs without a human in the loop on a trigger. The master kill switch
(system/atlas_autonomy_master.paused, via tools/atlas_kill.py --pause) halts the
autonomous loops — each checks autonomy_paused() in atlas_tenancy.py.
Engineering loop (GitHub Actions)
| Agent | File | Trigger | Does |
|---|---|---|---|
| Nightly Orchestrator | .github/scripts/nightly_orchestrator.py | nightly cron | Reads ROADMAP.md → files the top eligible task as agent:triage (via intake router) |
| Triage Agent | .github/scripts/triage_agent.py | issue opened/labeled = agent:triage | Classifies (severity/area/taskType/critical-path/criteria) and gates: promotes to agent:build ONLY if deterministic + non-critical + has criteria; else needs-human-design / needs-acceptance-criteria / needs-human |
| Build Agent | .github/workflows/build-agent.yml (claude-code-action) | issue labeled = agent:build | Explores → implements → commits → pushes → opens a PR into Human Review; on failure posts a scope-handoff; drains the queue to the next issue |
| QA Agent | .github/scripts/qa_agent.py | PR opened | HIPAA checklist review of the diff → PASS/FAIL comment |
| PR Risk Review | .github/scripts/pr_risk_review.py | PR opened | Risk-scores the diff, labels risk level |
| Learning Digest | .github/scripts/agent_learning_digest.py | weekly cron | Clusters build failures (buildfail:* / buildoutcome:success), recommends classifier fixes, files a task when a class recurs |
| Error→Bug | .github/workflows/error-to-bug.yml | repository_dispatch (Sentry/Cloud Monitoring) | Turns prod errors into deduped issues (via intake router) |
Ops / Growth loop (Cloud Functions, scheduled)
| Agent | File | Trigger | Does |
|---|---|---|---|
| Operator / COO | functions_atlas_operator.py | scheduled tick | Company snapshot (platform-Stripe MRR, fleet engagement), checklist candidates, files unblock tasks → intake |
| Market Intel | functions_market_intel.py | scheduled | 21-target competitor/vendor watchlist → Act/Aware digest + vendor-verify tickets |
| Model Watch | functions_model_watch.py | weekly | Polls the Anthropic Models API → alerts on newer/deprecated models |
| Cost Watch | functions_cost_watch.py | daily | Cloud Monitoring request-count surge detection → files a cost issue (caught the #241/#242 mirror loop). NOTE: counts invocations, not $ — real LLM/vendor spend is a #366 gap |
| Error Watch | functions_error_watch.py | hourly | GCP Error Reporting sweep — new/significant error groups (exceptions/5xx/OOM/validation) → intake + Slack |
| Ops Watch | functions_ops_watch.py | hourly | Cloud Scheduler health — a scheduled job silently failing (the 24h heartbeat-outage class) → intake |
| CI Watch | functions_ci_watch.py | hourly | GitHub Actions workflow failures (#294) → intake + Slack, P1 for pipeline workflows; first-run baseline guard |
| Uptime Watch | functions_uptime_watch.py | 15 min | Probes critical HTTP endpoints (#296) — down/5xx/timeout → P1 intake + Slack, RECOVERED on return (retry so cold starts don't false-alarm) |
| Freshness Watch | functions_freshness_watch.py | hourly | Pipeline-liveness (#366) — a scheduled job firing but producing stale/no output (the #241 silent-stall class ops_watch misses) → P1 intake. Registry extensible via system/freshness_watch.checks |
| Config-Drift Watch | functions_configdrift_watch.py | every 6h | Public-exposure drift (#365, SOC2 CC6) — snapshots each Cloud Run service's allUsers/run.invoker state, alerts on any FLIP: private→public (exposure) or public→private (redeploy dropped run.invoker → webhook silently 401/403s). Needs roles/run.viewer on the functions SA |
| Observation Engine | functions_observations.py | heartbeat | Scans clinics for out-of-range labs / attention items → dashboard cards |
| Heartbeat | functions_heartbeat.py | scheduled dispatcher | Runs user-scheduled + Atlas proactive tasks (reminders, reports, scans) |
| Scribe / Call Center | functions_scribe.py, functions_call_center.py | events | Meeting scribe (incl. sales mode → CRM leads); inbound AI voice (prospect mode) |
Continual learning
| Piece | File | Does |
|---|---|---|
| Signal capture | functions_atlas_signals.py | Records confirm-card accept/edit/reject (Phase 1) |
| Analytics | functions_atlas_analytics.py | Per-client cross-client queries powering copilot |
3. The intake router — one front door (#222)
Every bug/gap/feature signal — from you, worktree agents, Sentry, cost-watch, market-intel,
synthetic-QA, staff via per-clinic Atlas, the operator loop — routes through
functions_atlas_intake.py::atlas_intake(signal):
signal → dedup (Haiku vs open issues, SAME-ROOT, high-confidence-only)
→ append occurrence to existing issue OR create new
→ return reporter feedback ("Already tracked as #N" / "Logged as #M")
- HTTP front door:
atlas_intake_endpoint(X-Intake-Token auth). board.sh createalready routes through it — do NOTgh issue createdirectly for bug/feature/gap tasks.- Instrumented in
atlas_signals(dedupConfidence + candidatePool) to measure over/under-merge.
4. The build/triage pipeline (post-#217)
ROADMAP / Sentry / staff / you
│ (intake router: dedup)
▼
issue + agent:triage
│ Triage Agent — SUITABILITY GATE
├─ deterministic + non-critical + has criteria ─→ agent:build
├─ design / cross-repo ───────────────────────→ needs-human-design (never auto-built)
├─ no checkable criteria ─────────────────────→ needs-acceptance-criteria
└─ critical-path / P0 / HIGH / low-confidence ─→ needs-human
▼
Build Agent (agent:build) — In Progress
├─ success → PR → Human Review (you review + merge)
└─ failure → buildfail:<cat> + scope-handoff → Learning Digest
▼
merge → Done (still needs a deploy: merged ≠ live)
Critical-path denylist (fail-closed, in triage_agent.py, reused by self-healing #224):
money movement, auth/permissions, PHI/clinical decisioning, e-prescribing, insurance/RCM,
booking money. Never auto-built. Keyword matching is whole-word (not substring).
Board: Ready Practice Project #7 — Todo → In Progress → Human Review → Ready To Deploy
→ Done. The build agent moves the Status FIELD, not just labels. Auth (#344, 2026-07-14):
all 6 pipeline workflows (build-agent, triage-agent, self-heal-ledger, nightly-orchestrator,
agent-learning-digest, board-in-progress) mint a short-lived GitHub App installation token via
actions/create-github-app-token (secrets APP_ID + APP_PRIVATE_KEY, App basis-build-agent
with org Projects write) — NOT AGENT_PAT (retired). Fixed the ~57% failure rate (rate limits),
the PAT-leak risk, and gave the agent a distinct bot identity.
Build gate (#217): the build-agent job now REFUSES to run if the issue also carries
needs-human / needs-human-design / needs-acceptance-criteria — triage's suitability verdict
is enforced at the build workflow too, not just by label-flipping (closed the tasktype:unknown
failure cluster where agent:build landed on already-rejected issues).
Label rule: agents NEVER self-apply agent:build / agent:triage — only George flips those.
5. Tenancy & the kill switch
atlas_tenancy.py— per-tenant autonomy config (operatorTenant,tier,webSearch). Ready Practice's own operator tenant isaxuk-khwf-prkr. Autonomy is per-tenant — never global.autonomy_paused()— master kill switch with deadman semantics: a single read blip fails OPEN, but 3 consecutive read failures fail CLOSED (assume paused).tools/atlas_kill.py.- Covers the autonomous loops (operator, market-intel, model-watch, observations, learning). Does NOT cover clinic product features (growth sequences, user-scheduled reminders) — those have their own controls.
6. Related deep-dives
docs/claude/atlas-operator-plan.md— COO/Operator master plan + loop-engineering decisionsdocs/claude/atlas-slack-plan.md— Slack employee distribution + phasesdocs/claude/atlas-consumer-handoff.md— consumer Health Assistant resume pointdocs/claude/chat-atlas-spec.md— chat/assistant specdocs/claude/copilot.md— copilot tool matrix + agent architecturedocs/claude/atlas-api-webhooks.md— Atlas REST API + webhooks + MCPdocs/claude/operations.md— CI/CD, monitoring, deploy operations