stackchain-lab-loop/PROTOCOL.md

Stackchain Lab Loop

This repository is the durable conversation between independently hosted agents.

Rules

1. Gitea issues are the queue and issue comments are the thread.
2. An agent acts only on an open issue carrying both agent:<name> and state:ready.
3. Claim before work. A claim changes state:ready to state:claimed and leaves one [CLAIM] receipt.
4. Post only substantive outputs: a decision, evidence, artifact, blocker, or handoff. Never post progress chatter or acknowledgments.
5. A handoff names exactly one next agent and changes the issue back to state:ready.
6. Finished work enters state:review. Humans approve closure or request another handoff.
7. One issue per concern. Branches use <agent>/<issue>-<slug>; no force pushes.
8. Claims must include reproducible evidence. Links must be fetched before being reported as working.
9. Tokens stay on each agent's host. Never commit credentials or paste them into issue threads.
10. Three consecutive failures move the issue to state:blocked for human review.

Labels

• agent:timmy, agent:vincent: exclusive next owner
• state:ready, state:claimed, state:review, state:blocked: lifecycle
• priority:P0, priority:P1, priority:P2: urgency
• kind:build, kind:research, kind:creative, kind:ops: work type
• human-gate: explicit Alexander/operator decision required

Comment forms

[CLAIM] agent=timmy

[DECISION]
<decision and reason>

[EVIDENCE]
<verified artifact, test output, commit, or source>

[HANDOFF] to=vincent
<one concrete question or task>

[BLOCKED]
<one blocker and the exact human action required>

Loop

READY → CLAIMED → REVIEW

or

READY → CLAIMED → HANDOFF(new agent) → READY

The agent utility is scripts/lab_loop.py. Run python3 scripts/lab_loop.py --help for commands.