cleveragents-core/.opencode/skills/auto-agents-system/references/tracking-system

Tracking System — Automation Tracking Issues

Overview

The CleverAgents system has no shared memory between agents. All coordination happens through Forgejo issues with the Automation Tracking label. There are two distinct issue types:

Type	Purpose	Lifecycle	Title Pattern
Status issue	Current agent state — what it's doing, health, progress	Replaced each cycle (old one closed)	[{PREFIX}] Status: {Type} (Cycle N)
Announcement issue	Persistent signals to other agents	Persists until explicitly closed	[{PREFIX}] Announce: {Message}

Status Tracking Issues

Invariant: One at a Time Per Prefix

Each agent prefix may have at most one open status issue at any time. The automation-tracking-manager enforces this automatically when CREATE_TRACKING_ISSUE is called.

Cycle Number

Cycle numbers are:

• Globally unique per prefix — never reused
• Monotonically increasing — computed by searching ALL issues (open AND closed)
• Used to detect missed cycles — a gap in cycle numbers means the agent crashed

Rolling Average Interval

The Estimated Cycle Interval field is computed by automation-tracking-manager using:

new_interval = round(old_interval × 0.90 + actual_interval × 0.10)

This provides a smoothed estimate of how often the agent actually wakes up. Agents do not compute this themselves — they pass sleep-interval-default to CREATE_TRACKING_ISSUE and the ATM handles the calculation.

CREATE_TRACKING_ISSUE Steps

When called, automation-tracking-manager:

1. Finds all open status issues with label Automation Tracking and title starting with [{prefix}] Status:
2. Closes every one found (posts "Superseded by next cycle" comment, then closes)
3. Searches ALL issues (including closed) to find the highest cycle number for this prefix
4. Calculates next cycle number (highest + 1)
5. Calculates estimated interval (rolling average from previous issue)
6. Creates new issue: [{prefix}] Status: {tracking-type} (Cycle N)
7. Applies Automation Tracking label via forgejo-label-manager
8. Returns the issue number and cycle number to the caller

Mandatory Startup Recovery Protocol

CRITICAL: READ state BEFORE creating a new one.

1. READ_TRACKING_STATE    ← read the old state while it still exists
2. ANALYZE recovered state
3. CREATE_TRACKING_ISSUE  ← this closes the old issue and creates a fresh one
4. RESUME work using recovered data

Why this order matters: CREATE_TRACKING_ISSUE closes all existing status issues. If you call it first, then READ_TRACKING_STATE reads your brand-new empty issue — all previous state is lost.

Discovery Pattern

Any agent that wants to find another agent's current status can:

1. Search for open issues with label Automation Tracking and title containing the prefix and "Status:"
2. The most recent open issue is the current cycle
3. Read its body and comments for detailed state

Announcement Issues

Purpose

Announcements are persistent signals to other agents. Unlike status issues (which are replaced each cycle), announcements persist until the creating agent explicitly closes them. They communicate:

• Conditions that block operation
• Problems requiring attention from other agents
• Important events (capacity degraded, human escalation, quality gates violated)

Format

• Title: [{PREFIX}] Announce: {short message}
• Labels: Automation Tracking + one priority label
• Body: detailed description of the condition
• Lifetime: persists until CLOSE_ANNOUNCEMENT_ISSUE is called

Priority Labels for Announcements

The priority label applied to an announcement determines which agents consume it (see the relevancy matrix in SKILL.md). For label definitions and the full priority hierarchy see cleveragents-contributing and cleverthis-guidelines skills.

Label	When to Use for Autonomous System Announcements
Priority/CI-Blocker	CI pipeline broken; consumed by ALL agents immediately
Priority/Critical	Multiple supervisors down; system unable to make progress
Priority/High	Single supervisor repeatedly failing; degraded capacity
Priority/Medium	Informational: product completion reached, capacity changed
Priority/Low	Minor notices; no immediate action needed

Announcement Lifecycle

1. Create: CREATE_ANNOUNCEMENT_ISSUE with prefix, message, priority, body
2. Review own: REVIEW_OWN_ANNOUNCEMENTS — list all your open announcements
3. Close: CLOSE_ANNOUNCEMENT_ISSUE when condition resolves
4. Frequency: Agents must review and close stale announcements every 3 cycles

Announcement Consumption

Agents read others' announcements via READ_ANNOUNCEMENTS:

• Provide: comma-separated prefixes, minimum priority, repo info
• Returns: filtered list of open announcement issues
• Use agent-prefix-info to get the relevancy matrix for your prefix

Universal baseline: Every agent consumes Priority/CI-Blocker from ALL agents. This cannot be waived.

Processing urgency:

• Critical: process IMMEDIATELY before anything else
• High: process before starting next work cycle
• Medium/Low: opportunistically when convenient

System-Specific Labels

Two labels have special meaning within the autonomous agent system:

Automation Tracking — Universal Discovery Mechanism

This label is applied to every status tracking issue and every announcement issue. It is the discovery mechanism by which agents find each other's activity. Without it, no agent can locate another's tracking state.

Applied to:

• All status tracking issues ([{PREFIX}] Status: ... (Cycle N))
• All announcement issues ([{PREFIX}] Announce: ...)

needs feedback — Human Escalation Signal

This label signals that a work item cannot proceed without human intervention and that all agents must stop dispatching workers for the item until a human removes the label.

Applied when:

• A PR or issue has exhausted all model tier escalations (Opus × 3 same-problem failures)
• An architectural decision requires human approval before implementation
• An agent definition modification proposal is awaiting human review
• A spec change is pending human feedback

Workflow: agent applies label → posts detailed comment explaining what was tried → all supervisors skip this item in their dispatch loops → human resolves the issue and removes the label → supervisors resume normal dispatch.

All Other Label Rules

For complete label rules — forbidden operations (forgejo_create_label etc.), never listing repo-level labels, why only org-level labels are used, how forgejo-label-manager works, label scope descriptions (State/, Priority/, MoSCoW/, Type/), the full priority hierarchy — see:

• cleveragents-contributing skill — enforcement rules and what each label scope means
• cleverthis-guidelines skill — company-wide label and priority hierarchy definitions
• forgejo-api skill — curl patterns for all Forgejo API operations including label endpoints (forgejo-label-manager loads this skill automatically)

automation-tracking-manager Operations Summary

Operation	Purpose
CREATE_TRACKING_ISSUE	Creates new status issue (closes old ones first). Both creating AND updating the status issue.
UPDATE_TRACKING_ISSUE	Adds a comment to the current open status issue.
READ_TRACKING_STATE	Reads the latest status issue (open or closed) and extracts state.
GET_NEXT_CYCLE_NUMBER	Returns what the next cycle number will be (without creating the issue).
CREATE_ANNOUNCEMENT_ISSUE	Creates a persistent announcement with a priority label.
CLOSE_ANNOUNCEMENT_ISSUE	Closes a specific announcement by issue number.
READ_ANNOUNCEMENTS	Returns filtered open announcements by prefix and minimum priority.
REVIEW_OWN_ANNOUNCEMENTS	Lists all open announcements from a specific prefix.
CYCLE_ANNOUNCEMENT_REVIEW	Combined: reads others' announcements AND reviews own.
CLOSE_TRACKING_ISSUE	Closes the current status issue (without creating a new one).