APAW/.kilo/rules/gns-agent-protocol.md

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

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

**Event Types**: {subagent_result|state_change|budget_update|security_alert|checkpoint|task_claim|task_claim_release}
**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}

---

## 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

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: [{active_labels_only}]
    assignee: {agent_name}
  history_tail:                # ONLY last 3 entries
    - {agent: name, action: brief_action, timestamp: ISO}
  next_agent: {agent_name}
  next_estimated_tokens: {number}
  created_at: {ISO8601}
  current_task:                  # Max 3 files, 1 skill, 1 rule
    title: "{short_title}"
    deliverable: "{one_sentence}"
    files: ["{path1}", "{path2}"]
    skill: "{skill_name}"
    rule: "{rule_name}"
  agent_chain:                   # Last 5 entries only
    - {agent, action, timestamp, result: pass|fail|blocked}

CRITICAL: When checkpoint consumed > 80% of total, orchestrator MUST prune checkpoint before spawning next agent. See context-window-budget.md and gns-checkpoint-pruning.md for full pruning protocol.

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

Context Budget Governance

• Agent MUST calculate context_estimate < available_context * 0.3 before loading any files
• Agent receives ONLY: pruned checkpoint + last 3 comments + ≤3 files + 1 skill + 1 rule
• NEVER load full comment history, build logs, or unrelated rules/skills
• All old state lives in Gitea comments — fetch on demand with limit=3 pagination
• Log every load to .kilo/logs/context-budget.jsonl

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