Coordination Model

botminter teams use a pull-based coordination model. There is no central dispatcher. Each member independently scans the board for work matching its role, processes it, and hands off to the next member by updating the issue's status label.

Pull-based work discovery

Each member scans GitHub issues on the team repo for status labels matching its role. When a member finds work, it processes the highest-priority issue, updates the status label to hand off to the next role, and rescans.

The specific roles, labels, and priorities are defined by the profile. The generator provides the mechanism; the profile defines the vocabulary.

Status label convention

Status labels follow the pattern status/<role>:<phase>:

• <role> — the team member role responsible
• <phase> — the current phase within that role's workflow

Transition rule: Only the role named in the status label may transition it. Profiles may designate a role with override authority.

Board scanning

Each member has a board scanner hat that runs at the start of every loop cycle:

1. Sync the workspace (pull .botminter/ and project repos)
2. Clear the scratchpad and tasks (prevent context pollution between issues)
3. Query GitHub issues for status labels matching the member's role
4. Dispatch to the appropriate work hat based on the highest-priority match
5. If no work is found, publish LOOP_COMPLETE (idle)

Board scanning uses the gh skill, which wraps the gh CLI. The team repo is auto-detected from .botminter/'s Git remote.

Handoff mechanism

Work transitions between members through status label updates:

1. The current member removes the old status label and adds the new one via gh issue edit
2. The current member adds an attribution comment documenting the transition
3. The next member detects the change on its next board scan cycle

No direct communication occurs between members. The board (GitHub issues) is the sole coordination mechanism.

sequenceDiagram
    participant HA as human-assistant
    participant Board as GitHub Issues
    participant Arch as architect

    HA->>Board: Scan for status/po:*
    Board-->>HA: #42 at status/po:triage
    HA->>Board: Triage → status/po:backlog
    HA->>Board: Activate → status/arch:design

    Arch->>Board: Scan for status/arch:*
    Board-->>Arch: #42 at status/arch:design
    Arch->>Board: Produce design doc
    Arch->>Board: → status/po:design-review

    HA->>Board: Scan for status/po:*
    Board-->>HA: #42 at status/po:design-review
    HA->>Board: Human approves → status/arch:plan

Priority dispatch

When multiple issues match a member's role, the board scanner processes them by priority. Priority orderings are defined per role in the profile's member skeletons.

One issue is processed per scan cycle. After processing, the board rescans.

Rejection loops

At review gates, a reviewer can reject work and send it back to the producing role. The rejection mechanism is profile-defined — profiles specify which status transitions represent rejections and where they route back to.

Rejection routing relies on the hatless Ralph orchestrator. When a rejection event goes unmatched (no hat subscribes), Ralph examines the context, determines which work hat the reviewer rejected, and routes directly back to that hat.

Comment format

All comments use emoji-attributed format to identify which role wrote them:

### <emoji> <role> — <ISO-8601-UTC-timestamp>

Comment text here.

The emoji and role name are read from each member's .botminter.yml file. Since all agents share one GH_TOKEN, the role attribution in the comment body is the primary way to identify which agent wrote it.

Human-in-the-loop (HIL)

Profiles can designate a member as the human's interface to the team. This member relays human decisions and feedback to the board. No other team member communicates directly with the human — all human interaction goes through the designated member.

HIL channels

Two HIL models are supported, depending on the profile:

The GitHub comment model eliminates timeout-related issues — if the human hasn't responded, the agent moves on to other work and re-checks on the next scan. The Telegram model blocks the loop and may time out.

Operating modes

Members support an operating mode toggle in their PROMPT.md. This acts as a configurable safety dial:

• Training mode — all decisions require human confirmation
• Supervised mode — only review gates require human input; routine transitions auto-advance
• Autonomous mode — agents act independently

Related topics

• Architecture — two-layer runtime model
• Process Conventions — full scrum label scheme, issue format, comment format
• Member Roles — scrum role definitions and hat models