git-native-agent-protocol
Coordinate multiple AI agents using Git as the shared protocol — issues as task queues, branches as agent workspaces, PRs as deliverables, and commit messages as structured agent signals. Use when ask
SKILL.mdcore/skills/git-native-agent-protocol/SKILL.md
GitHubWhen to Use
- Use when: multiple agents need to divide and claim tasks without a separate message broker
- Use when: agent work needs full audit trail baked into version control
- Use when: humans need visibility into what each agent did and why
- Use when: running agents in parallel across Codespaces / worktrees
- Do NOT use for: real-time < 1s agent coordination — use in-process signaling
- Do NOT use for: single agent tasks — overhead not worth it
The Mental Model
Git repo = shared coordination layer (no separate message bus)
Issues = task queue — agents claim issues by assigning themselves
Branches = workspaces — one branch per agent per task
PRs = deliverables — agent opens PR when task complete, requests review
Labels = routing tags — "agent:ready", "agent:in-progress", "agent:blocked"
Comments = status signals — agents post structured JSON progress updates
Human or Orchestrator
└─ Creates issue: "feat: implement payment retry logic"
Labels: "agent:ready", "backend"
Agent A (claims it)
└─ Assigns issue to itself, label → "agent:in-progress"
└─ Creates branch: agent/payment-retry-{issue-number}
└─ Works in worktree: git worktree add ../payment-retry agent/payment-retry-42
└─ Opens PR: links to issue, structured checklist
└─ Posts progress comment: { "status": "blocked", "reason": "need DB schema decision" }
Agent B (reviewer)
└─ Sees "agent:review-needed" label
└─ Reviews PR, approves or requests changes
└─ Merge → issue closes → branch deleted → worktree cleaned
Issue as Task Spec
<!-- Issue body — structured for agent consumption -->
## Task
Implement exponential backoff retry for payment API calls.
## Acceptance Criteria
- [ ] Retry up to 3 times with 1s, 2s, 4s delays
- [ ] Do NOT retry on 4xx errors (client fault)
- [ ] Log each retry attempt with attempt number and delay
- [ ] Unit tests cover: success on retry 2, exhausted retries, no-retry on 400
## Context
- File: `src/services/payment.ts`
- Dependency: `resilience-patterns` skill for circuit breaker integration
- Related: #38 (payment timeout fix)
## Agent Instructions
Branch: `agent/payment-retry-{issue_number}`
Commit prefix: `fix(payment):`
Agent Branch + Worktree Convention
# Orchestrator or agent claims issue
gh issue edit 42 --add-assignee "@me" --add-label "agent:in-progress"
# Create isolated worktree (no checkout conflict with main work)
ISSUE=42
BRANCH="agent/payment-retry-${ISSUE}"
git worktree add "../workspace-${ISSUE}" -b "$BRANCH"
cd "../workspace-${ISSUE}"
# Work, commit with structured prefix
git commit -m "fix(payment): add exponential backoff retry
agent: payment-agent
issue: #${ISSUE}
attempt: 1/3
status: implementation complete, tests pending"
# Open PR linking to issue
gh pr create \
--title "fix(payment): exponential backoff retry (#${ISSUE})" \
--body "Closes #${ISSUE}
## Changes
- Added RetryPolicy class with exponential backoff
- Integrated with circuit breaker (resilience-patterns)
## Checklist
- [x] Retry up to 3 times
- [x] Skip retry on 4xx
- [x] Unit tests pass
agent: payment-agent | branch: ${BRANCH}" \
--label "agent:review-needed"
Agent Status Comment Protocol
// Agents post structured JSON progress to issue/PR comments
// Parseable by orchestrator for status aggregation
const statusUpdate = {
agent: 'payment-agent',
issueRef: 42,
status: 'blocked', // ready | in-progress | blocked | done
progress: '2/4 criteria met',
blockedBy: 'schema decision needed — see comment #3',
timestamp: new Date().toISOString(),
};
await gh.issues.createComment({
body: `<!-- agent-status -->\n\`\`\`json\n${JSON.stringify(statusUpdate, null, 2)}\n\`\`\``,
});
Orchestrator: Claim Next Available Task
#!/usr/bin/env bash
# Claim oldest unassigned agent-ready issue
ISSUE=$(gh issue list \
--label "agent:ready" \
--assignee "" \
--json number,title \
--jq '.[0].number')
if [[ -z "$ISSUE" ]]; then
echo "No tasks available"
exit 0
fi
gh issue edit "$ISSUE" \
--add-assignee "@me" \
--remove-label "agent:ready" \
--add-label "agent:in-progress"
echo "Claimed issue #$ISSUE"
Cleanup After Merge
# Post-merge: clean worktree + archive branch
ISSUE=42
git worktree remove "../workspace-${ISSUE}" --force
git branch -d "agent/payment-retry-${ISSUE}"
gh issue close "$ISSUE" --comment "Completed by agent. PR merged."
Anti-Fake-Pass Rules
Before claiming GNAP coordination is set up, you MUST show:
- Issues have structured acceptance criteria + agent instructions section
- Branch naming follows
agent/{task}-{issue_number}convention - Each agent uses a separate worktree — no shared working directory
- Agents post structured JSON status comments — not free-text
- PRs link to issue with
Closes #N— auto-closes on merge - Orchestrator script can claim next available task idempotently
- Worktrees and branches cleaned up post-merge
Reference: gates/anti-fake-pass-gate.md