# 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

```text
[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.
