---
name: auto-agents-system
description: |
  Complete self-reflection skill for the auto-agents autonomous development
  system. Covers every architectural concept, agent role, operational rule,
  and coordination pattern that agents need in order to understand and operate
  within the system correctly.
references:
  - universal-rules
  - agent-registry
  - async-operations
  - tracking-system
  - tier-system
  - credential-flow
  - coordination
  - redundancy
  - operational-parameters
---

# CleverAgents System — Self-Reflection Skill

Use this skill whenever you need to know:

TBD

## ⚡ Quick Reference

```
Session format:    [TAG] display-name          (all AUTO-* sessions)
Worker formula:    N_FULL=N  N_HALF=max(1,N÷2)  N_QUARTER=max(1,N÷4)
Escalation:        GPT5-nano (-3) → o4-mini(-2) → GPT5-mini(-1) → Haiku(0) → Codex(1) → Sonnet(2) → Opus(3) → Human (default: start at 0)
Labels:            NEVER create. Org-level only. Always via forgejo-label-manager.
Tracking:          One status issue at a time per prefix. Announcements persist until closed.
```

## 🧭 Master Decision Trees

### "Being asked to use a script from this skill?"

```
Need to use or understand a script by name?
│
│  ── Forgejo PR / Issue scripts ──────────────────────────────────────────────
├─ `merge_pr`                               → [`merge_pr/`](./references/scripts/merge_pr/)
├─ `rebase_pr`                              → [`rebase_pr/`](./references/scripts/rebase_pr/)
├─ `list_prs_needs_review_not_stale`        → [`list_prs_needs_review_not_stale/`](./references/scripts/list_prs_needs_review_not_stale/)
├─ `list_prs_needs_review_stale_clean`      → [`list_prs_needs_review_stale_clean/`](./references/scripts/list_prs_needs_review_stale_clean/)
├─ `list_prs_needs_review_stale_conflicts`  → [`list_prs_needs_review_stale_conflicts/`](./references/scripts/list_prs_needs_review_stale_conflicts/)
├─ `list_prs_stale_clean`                   → [`list_prs_stale_clean/`](./references/scripts/list_prs_stale_clean/)
├─ `list_prs_stale_conflicts`               → [`list_prs_stale_conflicts/`](./references/scripts/list_prs_stale_conflicts/)
├─ `list_prs_ready_to_merge`                → [`list_prs_ready_to_merge/`](./references/scripts/list_prs_ready_to_merge/)
├─ `list_prs_ci_failing`                    → [`list_prs_ci_failing/`](./references/scripts/list_prs_ci_failing/)
├─ `list_prs_changes_requested`             → [`list_prs_changes_requested/`](./references/scripts/list_prs_changes_requested/)
├─ `list_prs_addressed_changes_ci_passing`  → [`list_prs_addressed_changes_ci_passing/`](./references/scripts/list_prs_addressed_changes_ci_passing/)
├─ `list_prs_no_active_review_ci_passing`   → [`list_prs_no_active_review_ci_passing/`](./references/scripts/list_prs_no_active_review_ci_passing/)
├─ `list_prs_addressed_changes_ci_failing`  → [`list_prs_addressed_changes_ci_failing/`](./references/scripts/list_prs_addressed_changes_ci_failing/)
├─ `list_prs_no_active_review_ci_failing`   → [`list_prs_no_active_review_ci_failing/`](./references/scripts/list_prs_no_active_review_ci_failing/)
├─ `list_prs_missing_ci_checks`             → [`list_prs_missing_ci_checks/`](./references/scripts/list_prs_missing_ci_checks/)
├─ `list_prs`                               → [`list_prs/`](./references/scripts/list_prs/)
├─ `list_issues`                            → [`list_issues/`](./references/scripts/list_issues/)
│
│  ── OpenCode Session scripts (localhost:4096) ───────────────────────────────
├─ `session_api`         (shared module)    → [`session_api/`](./references/scripts/session_api/)
├─ `session_list`                           → [`session_list/`](./references/scripts/session_list/)
├─ `session_start`                          → [`session_start/`](./references/scripts/session_start/)
├─ `session_find_by_tag`                    → [`session_find_by_tag/`](./references/scripts/session_find_by_tag/)
├─ `session_find_by_prefix`                 → [`session_find_by_prefix/`](./references/scripts/session_find_by_prefix/)
├─ `session_messages`                       → [`session_messages/`](./references/scripts/session_messages/)
├─ `session_stop`                           → [`session_stop/`](./references/scripts/session_stop/)
├─ `session_delete`                         → [`session_delete/`](./references/scripts/session_delete/)
├─ `session_health_data`                    → [`session_health_data/`](./references/scripts/session_health_data/)
├─ `session_prompt`                         → [`session_prompt/`](./references/scripts/session_prompt/)
├─ `session_wait_till_idle`    (core)      → [`session_wait_till_idle/`](./references/scripts/session_wait_till_idle/)
├─ `session_wait_till_supervisor_idle`     → [`session_wait_till_supervisor_idle/`](./references/scripts/session_wait_till_supervisor_idle/)
├─ `session_wait_till_worker_idle`         → [`session_wait_till_worker_idle/`](./references/scripts/session_wait_till_worker_idle/)
│
├─ "What's the project's tier escalation table?"
│     → [tier-table/](./references/tier-table/)
│       (single source of truth — used by tier-dispatcher,
│        estimator-implementation, and every worker citing a tier)
│
├─ "What conventions does the project use?"
│     ├─ Bot signature format        → [conventions/bot-identity/](./references/conventions/bot-identity/)
│     ├─ Session/agent tag format    → [conventions/tag-format/](./references/conventions/tag-format/)
│     ├─ Branch-naming rules         → [conventions/branch-naming/](./references/conventions/branch-naming/)
│     └─ Attempt-comment format      → [conventions/attempt-comments/](./references/conventions/attempt-comments/)
│
├─ "What parameters do agents accept?"
│     ├─ Forgejo credentials         → [parameters/forgejo-credentials/](./references/parameters/forgejo-credentials/)
│     ├─ Git identity                → [parameters/git-identity/](./references/parameters/git-identity/)
│     ├─ Work item (issue/PR)        → [parameters/work-item/](./references/parameters/work-item/)
│     ├─ PR data                     → [parameters/pr-data/](./references/parameters/pr-data/)
│     ├─ Review data                 → [parameters/review-data/](./references/parameters/review-data/)
│     └─ Merge data                  → [parameters/merge-data/](./references/parameters/merge-data/)
│
├─ "What pipeline / work groups does each supervisor use?"
│     ├─ implementation-supervisor   → [work-groups/implementation-pipeline/](./references/work-groups/implementation-pipeline/)
│     ├─ pr-merge-supervisor         → [work-groups/pr-merge-pipeline/](./references/work-groups/pr-merge-pipeline/)
│     └─ pr-review-supervisor        → [work-groups/pr-review-pipeline/](./references/work-groups/pr-review-pipeline/)
│
├─ "What prompt should I send to a subagent?"
│     ├─ Bot signature block         → [prompt-templates/bot-signature/](./references/prompt-templates/bot-signature/)
│     ├─ Attempt comment             → [prompt-templates/attempt-comment/](./references/prompt-templates/attempt-comment/)
│     ├─ Calling git-isolator-util   → [prompt-templates/git-isolator-call/](./references/prompt-templates/git-isolator-call/)
│     └─ Calling git-commit-and-push → [prompt-templates/git-commit-and-push-call/](./references/prompt-templates/git-commit-and-push-call/)
│
├─ "How does a specific agent work in this project?"
│     ├─ auto-agents                 → [agents/auto-agents/](./references/agents/auto-agents/)
│     ├─ async-agent-util            → [agents/async-agent-util/](./references/agents/async-agent-util/)
│     ├─ Supervisors                 → [agents/supervisors/](./references/agents/supervisors/)
│     ├─ Workers                     → [agents/workers/](./references/agents/workers/)
│     ├─ task-implementor            → [agents/task-implementor/](./references/agents/task-implementor/)
│     ├─ estimator-implementation    → [agents/estimator-implementation/](./references/agents/estimator-implementation/)
│     ├─ tier-dispatcher             → [agents/tier-dispatcher/](./references/agents/tier-dispatcher/)
│     ├─ Tier selectors              → [agents/tier-selectors/](./references/agents/tier-selectors/)
│     ├─ Git utilities               → [agents/git-utilities/](./references/agents/git-utilities/)
│     ├─ work-group-util             → [agents/work-group-util/](./references/agents/work-group-util/)
│     └─ Session health agents       → [agents/](./references/agents/)
│
├─ "How do I use a Forgejo work-group script (list_issues, list_prs_*, merge_pr, rebase_pr)?"
│     → [scripts/](./references/scripts/)
│       ⚠️  Session management scripts (session_*.ts) are NOT here —
│           they live in supervised-workers/scripts/ instead.
│
├─ "How do I deploy or maintain this system?"
│     → [consumer-guide/](./references/consumer-guide/)
└─ Overview of all scripts                  → [`scripts/`](./references/scripts/)
```

### "Being asked about a health evaluation agent?"

```
Need to understand a health evaluation agent?
│
├─ `session-health-util`        (coordinator)  → [`agents/session-health-util/`](./references/agents/session-health-util/)
├─ `session-health-quick-util`  (Tier 1)       → [`agents/session-health-quick-util/`](./references/agents/session-health-quick-util/)
├─ `session-health-full-util`   (Tier 2)       → [`agents/session-health-full-util/`](./references/agents/session-health-full-util/)
│
└─ Overview of all health agents                    → [`agents/`](./references/agents/)
```

## Scripts Index

See [`scripts/`](./references/scripts/) for the full index with invocation instructions and detailed documentation for each script. Quick reference:

| Script | Reference Docs | Script File | Description |
|--------|---------------|-------------|-------------|
| `list_prs` | [docs](./references/scripts/list_prs/) | [list_prs.ts](./scripts/list_prs.ts) | General-purpose PR lister with all filter options (`--stale`, `--ci-status`, `--min-approvals`, `--has-request-changes`, …); core module imported by the wrappers below |
| `list_prs_ready_to_merge` | [docs](./references/scripts/list_prs_ready_to_merge/) | [list_prs_ready_to_merge.ts](./scripts/list_prs_ready_to_merge.ts) | Open PRs with ≥ 1 approval, not stale, **and CI passing** — ready to merge immediately |
| `list_prs_stale_clean` | [docs](./references/scripts/list_prs_stale_clean/) | [list_prs_stale_clean.ts](./scripts/list_prs_stale_clean.ts) | Open PRs with ≥ 1 approval, stale but no conflicts, any CI status — server-side rebase then merge |
| `list_prs_stale_conflicts` | [docs](./references/scripts/list_prs_stale_conflicts/) | [list_prs_stale_conflicts.ts](./scripts/list_prs_stale_conflicts.ts) | Open PRs with ≥ 1 approval, stale with conflicts, any CI status — local clone, resolve, force-push, then merge |
| `list_prs_needs_review_not_stale` | [docs](./references/scripts/list_prs_needs_review_not_stale/) | [list_prs_needs_review_not_stale.ts](./scripts/list_prs_needs_review_not_stale.ts) | Open PRs with zero approvals, not stale, any CI status — review only needed; merges immediately on approval |
| `list_prs_needs_review_stale_clean` | [docs](./references/scripts/list_prs_needs_review_stale_clean/) | [list_prs_needs_review_stale_clean.ts](./scripts/list_prs_needs_review_stale_clean.ts) | Open PRs with zero approvals, stale but no conflicts, any CI status — review + server-side rebase needed |
| `list_prs_needs_review_stale_conflicts` | [docs](./references/scripts/list_prs_needs_review_stale_conflicts/) | [list_prs_needs_review_stale_conflicts.ts](./scripts/list_prs_needs_review_stale_conflicts.ts) | Open PRs with zero approvals, stale with conflicts, any CI status — review + local conflict resolution needed |
| `list_prs_ci_failing` | [docs](./references/scripts/list_prs_ci_failing/) | [list_prs_ci_failing.ts](./scripts/list_prs_ci_failing.ts) | Open PRs with **failing CI**, any review or staleness status — CI must be fixed before any downstream step |
| `list_prs_changes_requested` | [docs](./references/scripts/list_prs_changes_requested/) | [list_prs_changes_requested.ts](./scripts/list_prs_changes_requested.ts) | Open PRs with **passing CI**, zero approvals, and at least one active `REQUEST_CHANGES` review — author must address reviewer feedback |
| `list_prs_addressed_changes_ci_passing` | [docs](./references/scripts/list_prs_addressed_changes_ci_passing/) | [list_prs_addressed_changes_ci_passing.ts](./scripts/list_prs_addressed_changes_ci_passing.ts) | Open PRs with **passing CI**, zero approvals, active `REQUEST_CHANGES`, and **addressed** feedback — highest-priority re-review |
| `list_prs_no_active_review_ci_passing` | [docs](./references/scripts/list_prs_no_active_review_ci_passing/) | [list_prs_no_active_review_ci_passing.ts](./scripts/list_prs_no_active_review_ci_passing.ts) | Open PRs with **passing CI**, zero approvals, and **no active `REQUEST_CHANGES`** — ready for a fresh first review |
| `list_prs_addressed_changes_ci_failing` | [docs](./references/scripts/list_prs_addressed_changes_ci_failing/) | [list_prs_addressed_changes_ci_failing.ts](./scripts/list_prs_addressed_changes_ci_failing.ts) | Open PRs with **failing CI**, zero approvals, active `REQUEST_CHANGES`, and **addressed** feedback — re-review with CI failure noted |
| `list_prs_no_active_review_ci_failing` | [docs](./references/scripts/list_prs_no_active_review_ci_failing/) | [list_prs_no_active_review_ci_failing.ts](./scripts/list_prs_no_active_review_ci_failing.ts) | Open PRs with **failing CI**, zero approvals, and **no active `REQUEST_CHANGES`** — first review with CI failure noted |
| `list_prs_missing_ci_checks` | [docs](./references/scripts/list_prs_missing_ci_checks/) | [list_prs_missing_ci_checks.ts](./scripts/list_prs_missing_ci_checks.ts) | Open PRs with zero approvals and **no CI checks reported** — lightweight review flagging missing CI |
| `list_issues` | [docs](./references/scripts/list_issues/) | [list_issues.ts](./scripts/list_issues.ts) | Open issues excluding `State/In Progress`, sorted by milestone due date (oldest first) then priority within each milestone tier |
| `merge_pr` | [docs](./references/scripts/merge_pr/) | [merge_pr.ts](./scripts/merge_pr.ts) | Initiates a rebase-style merge with automerge scheduling; handles open issue dependencies |
| `rebase_pr` | [docs](./references/scripts/rebase_pr/) | [rebase_pr.ts](./scripts/rebase_pr.ts) | Triggers a Forgejo server-side rebase on a stale, conflict-free PR — no local clone required |

### OpenCode Session Scripts

These scripts wrap the OpenCode Server API at `localhost:4096`. They are used exclusively by the `async-agent-util` agent — no other agent may call them directly or interact with localhost:4096.

| Script | Reference Docs | Script File | Description |
|--------|---------------|-------------|-------------|
| `session_api` (module) | [docs](./references/scripts/session_api/) | [session_api.ts](./scripts/session_api.ts) | Shared types and API client functions imported by all other session scripts |
| `session_list` | [docs](./references/scripts/session_list/) | [session_list.ts](./scripts/session_list.ts) | List all sessions with their current busy/idle status and last-activity timestamps |
| `session_start` | [docs](./references/scripts/session_start/) | [session_start.ts](./scripts/session_start.ts) | Start an async agent in a new session (or report/restart an existing one by tag) |
| `session_find_by_tag` | [docs](./references/scripts/session_find_by_tag/) | [session_find_by_tag.ts](./scripts/session_find_by_tag.ts) | Find sessions whose title tag exactly matches the given string |
| `session_find_by_prefix` | [docs](./references/scripts/session_find_by_prefix/) | [session_find_by_prefix.ts](./scripts/session_find_by_prefix.ts) | Find sessions whose tag starts with a given prefix; optional supervisor exclusion |
| `session_messages` | [docs](./references/scripts/session_messages/) | [session_messages.ts](./scripts/session_messages.ts) | Retrieve and format messages from a session; supports limit and raw output |
| `session_stop` | [docs](./references/scripts/session_stop/) | [session_stop.ts](./scripts/session_stop.ts) | Stop (and delete) sessions by ID or by tag-prefix pattern |
| `session_delete` | [docs](./references/scripts/session_delete/) | [session_delete.ts](./scripts/session_delete.ts) | Delete a session directly by ID; guards against busy-session deletion |
| `session_health_data` | [docs](./references/scripts/session_health_data/) | [session_health_data.ts](./scripts/session_health_data.ts) | Collect raw health signals (status + recent messages) for all sessions; the caller classifies health states |
| `session_prompt` | [docs](./references/scripts/session_prompt/) | [session_prompt.ts](./scripts/session_prompt.ts) | Send a prompt to an **existing** session (fire-and-forget); the canonical "send continue" script |
| `session_wait_till_idle` | [docs](./references/scripts/session_wait_till_idle/) | [session_wait_till_idle.ts](./scripts/session_wait_till_idle.ts) | Core blocking script — polls sessions and blocks while busy count >= threshold; supports supervisor and worker modes |
| `session_wait_till_supervisor_idle` | [docs](./references/scripts/session_wait_till_supervisor_idle/) | [session_wait_till_supervisor_idle.ts](./scripts/session_wait_till_supervisor_idle.ts) | Wrapper — blocks until busy supervisor count (tags ending in `-SUP`) drops below expected count |
| `session_wait_till_worker_idle` | [docs](./references/scripts/session_wait_till_worker_idle/) | [session_wait_till_worker_idle.ts](./scripts/session_wait_till_worker_idle.ts) | Wrapper — blocks until busy worker count in a specific pool drops below pool size |

## 📂 Reference Index

| Reference | Covers |
|-----------|--------|
| [`universal-rules/`](./references/universal-rules/) | The five non-negotiable rules every agent must follow: exhaustive pagination protocol, label management via forgejo-label-manager (forbidden operations, why PUT not POST), bot signature format and placement, credential flow hierarchy (workers never read env vars), localhost:4096 restriction (async-agent-util only) |
| [`tracking-system/`](./references/tracking-system/) | Automation tracking issues (status vs announcement types), CREATE/READ/UPDATE/CLOSE operations, startup recovery protocol (READ before CREATE), system-specific labels (Automation Tracking, needs feedback) |
| [`tracking-system/announcement-matrix/`](./references/tracking-system/announcement-matrix/) | Full per-agent announcement relevancy table: every supervisor prefix with its complete source-and-minimum-priority matrix; universal CI-Blocker baseline |
| [`tier-system/`](./references/tier-system/) | Four model tiers and their models, how tier selector agents work (model inheritance), progressive escalation rules, human escalation steps, default model assignments for all agents |
| [`scripts/`](./references/scripts/) | All pipeline helper scripts: `list_prs` core + 6 merge-bucket wrappers + 5 review-pipeline wrappers + 2 cross-cutting PR wrappers + `list_issues` issue lister + `merge_pr` and `rebase_pr` action scripts. Load the directory for an overview; load an individual subdirectory for a full man-page reference |
| [`agents/`](./references/agents/) | Internal health evaluation agents: `session-health-util` (coordinator), `session-health-quick-util` (Tier 1 fast classifier), `session-health-full-util` (Tier 2 deep analyst) |

## Health Evaluation Agents

These agents are hidden internal infrastructure used by `async-agent-util`'s health operation. Each session in a health check gets its own `session-health-util` instance.

| Agent | Reference Docs | Agent File | Description |
|-------|---------------|------------|-------------|
| `session-health-util` | [docs](./references/agents/session-health-util/) | [session-health-util.md](../../../agents/session-health-util.md) | Two-tier coordinator: runs quick check, escalates to full evaluation when needed |
| `session-health-quick-util` | [docs](./references/agents/session-health-quick-util/) | [session-health-quick-util.md](../../../agents/session-health-quick-util.md) | Tier 1: classifies from last 3 messages; commits only when extremely confident, otherwise escalates |
| `session-health-full-util` | [docs](./references/agents/session-health-full-util/) | [session-health-full-util.md](../../../agents/session-health-full-util.md) | Tier 2: fetches 10 messages, evaluates timing + tools + content with full system context |
