# GNS-2 Agent Protocol

Rules for all agents participating in the Gitea-Nervous-System v2.0 distributed workflow.

## Core Principle

Gitea is the shared brain. Every agent reads state from Gitea on entry and writes state back on exit. No agent holds exclusive state in RAM.

## Entry Protocol

Every agent MUST execute on entry:

1. **Read Issue**: `GET /repos/{owner}/{repo}/issues/{number}`
2. **Parse Checkpoint**: Extract YAML block from issue body
3. **Check Budget**: Verify `checkpoint.budget.remaining > estimated_cost`
4. **Check Depth**: Verify `checkpoint.depth < max_depth` from cascade label
5. **Read Timeline**: `GET /issues/{number}/timeline` for recent events
6. **Read Comments**: `GET /issues/{number}/comments` for agent messages

## Execution Protocol

During work:

1. **Atomic Tasks**: One clear deliverable per invocation
2. **Token Budget**: Stop and report if approaching limit
3. **Subagent Calls** (Tier 2+ only): Check budget and depth before spawning
4. **State Changes**: Update labels, assignee, milestone via API

## Exit Protocol

Every agent MUST execute before terminating:

1. **Write Result Comment**: Structured markdown with machine-readable footer
2. **Update Checkpoint**: Patch issue body with new checkpoint YAML
3. **Update Labels**: Reflect new phase, quality, budget state
4. **Set Assignee**: Hand off to next agent or self
5. **Log Cascade**: If subagents were spawned, include cascade table

## Comment Format

```markdown
## 🔄 {agent-name} | phase:{phase} | depth:{depth}

**Event Type**: {subagent_result|state_change|budget_update|security_alert|checkpoint}
**Parent**: {parent_invocation_id}
**Invocation**: {invocation_id}
**Budget**: {before} → {consumed} → {remaining}

### Action Taken
{description}

### Result
```json
{result_json}
```

### Next Decision
**Recommended next**: @{agent-name}
**Rationale**: {why}
**Estimated tokens**: {number}
**Budget remaining**: {number}

### Cascade Log (if any)
| Agent | Task | Result | Tokens | Verdict |
|-------|------|--------|--------|---------|
| {agent} | {task} | {result} | {tokens} | ✅/❌ |

### State Changes
- Labels add: {list}
- Labels remove: {list}
- Assignee: {name}
- Milestone: {id}

---
<!-- GNS_EVENT: {machine_readable_json} -->
```

## Machine-Readable Footer

```html
<!-- GNS_EVENT: {
  "type": "subagent_result|state_change|budget_update|security_alert|checkpoint",
  "agent": "agent-name",
  "invocation_id": "cap-042-003",
  "parent_id": "orch-042-001",
  "depth": 1,
  "budget": {"before": 5000, "consumed": 1200, "remaining": 3800},
  "state_changes": {
    "labels_add": ["phase::drafting-spec"],
    "labels_remove": ["phase::gathering-evidence"],
    "assignee": "agent-architect",
    "milestone": null,
    "is_locked": false
  },
  "cascade_log": [
    {"agent": "history-miner", "task": "git search", "tokens": 1200, "verdict": "pass"}
  ],
  "next_agent": "agent-architect",
  "estimated_next_tokens": 3000,
  "timestamp": "2026-05-08T20:00:00Z"
} -->
```

## Checkpoint Schema v2

```yaml
checkpoint:
  version: 2
  issue: {number}
  phase: {phase_name}
  depth: {current_depth}
  last_agent: {agent_name}
  last_invocation: {invocation_id}
  budget:
    total: {allocated}
    consumed: {used}
    remaining: {left}
  state:
    labels: [{list}]
    assignee: {agent_name}
    milestone: {milestone_id}
  history:
    - {agent: name, invocation: id, action: description}
  next_agent: {agent_name}
  next_estimated_tokens: {number}
  created_at: {ISO8601}
```

## Budget Governance

- Agent MUST check `checkpoint.budget.remaining` before any subagent call
- Subagent call rejected if `estimated_cost > remaining * 0.5`
- Budget exhaustion → add label `budget::exhausted`, pause, request human approval
- Agent MUST update `consumed` and `remaining` in checkpoint after completion

## Depth Governance

- `cascade::depth-0`: Leaf agents, no subagent calls
- `cascade::depth-1`: One level of subagent calls
- `cascade::depth-2`: Two levels of subagent calls
- `cascade::depth-n`: Unlimited (orchestrator only)
- Depth exceeded → add label `cascade::depth-exceeded`, lock issue

## Security Rules

- Agent MUST NOT modify `.kilo/` files without `permission::evolve-system`
- Agent MUST NOT call subagents not in `allowed_subagents` list
- Agent MUST NOT exceed `max_cascade_depth`
- Violation → add label `permission::violation`, `is_locked = true`

## Recovery

If agent crashes or orchestrator restarts:

1. Read issue body → parse checkpoint
2. Read timeline → reconstruct events since last checkpoint
3. Read comments → parse GNS_EVENT footers
4. Resume from `next_agent` in checkpoint
5. No state lost — everything is in Gitea

## Prohibited Actions

- DO NOT hold state in RAM without writing to Gitea
- DO NOT skip comment footer
- DO NOT skip checkpoint update
- DO NOT exceed budget or depth limits
- DO NOT modify checkpoint version
- DO NOT hardcode APAW in API calls