feat: add Multi-Agent Coordination via GNAP pattern

[ori-cofounder]

Multi-Agent Coordination via GNAP

This PR adds a new architectural pattern: Multi-Agent Coordination via GNAP.

What is GNAP?

GNAP (Git-Native Agent Protocol) is a coordination protocol where a shared git repo acts as a persistent, auditable task board. Agents communicate by reading and writing markdown files — no orchestrator process, no message broker required.

Why it fits gitagent perfectly

gitagent and GNAP are complementary layers:

• gitagent = defines how an agent is structured (identity, rules, skills, SOD)
• GNAP = defines how agents coordinate with each other (task claim/complete via git commits)

Both use the same git primitives gitagent already relies on. The audit trail, branching, and diff capabilities extend naturally to inter-agent coordination.

What's in this PR

README.md: new ### Multi-Agent Coordination via GNAP pattern section (after SkillsFlow, before Porting Framework Agents)

examples/gnap-coordination/: full working example

• agent.yaml — agent definition with SOD roles (analyst / reviewer)
• workflows/gnap-worker-flow.yaml — SkillsFlow workflow: poll board → claim → process → done
• board/todo/ → doing/ → done/ task board structure
• README.md — setup and usage instructions

SOD integration

GNAP's required_role in task files integrates with gitagent's compliance.segregation_of_duties.conflicts — preventing the same agent from both creating and approving high-stakes tasks across the full pipeline.

Related

• GNAP spec: https://github.com/farol-team/gnap
• Sparked by: Related project: GNAP — git-native agent coordination protocol gitclaw#4

Thanks @shreyas-lyzr for the invitation to contribute!

[shreyas-lyzr]

Updated review (reposted to remove emoji formatting from the previous comment):

Review -- GNAP Coordination Pattern PR

Hey @ori-cofounder, thanks for the contribution! The idea of integrating GNAP with gitagent is interesting and the PR description is well-written. However, there are several issues that need to be addressed before this can be merged.

---

1. [blocker] GNAP format is misrepresented -- it uses JSON, not markdown

The actual GNAP spec defines JSON files inside a .gnap/ directory, not markdown files with YAML frontmatter in board/todo/doing/done/ directories.

What GNAP actually uses:

• .gnap/tasks/{id}.json -- task files with fields: id, title, assigned_to, state, created_by, created_at, priority, reviewer, etc.
• .gnap/agents.json -- agent roster
• .gnap/runs/{task-id}-{attempt}.json -- execution attempts with cost tracking
• .gnap/messages/{id}.json -- inter-agent communication

Task state machine in GNAP is a state field (backlog -> ready -> in_progress -> review -> done), not directory-based movement (todo/ -> doing/ -> done/).

The example's board/todo/analyze-report.md with YAML frontmatter (owner, required_role) doesn't match the actual GNAP spec at all. The real fields are assigned_to (array), state, reviewer, etc.

This is a significant accuracy issue -- the pattern and example are teaching users an incorrect representation of GNAP.

2. [blocker] Example fails gitagent validate

The example is missing SOUL.md, which is a required file per the gitagent spec. Running gitagent validate -d examples/gnap-coordination would produce:

- SOUL.md -- invalid
-   SOUL.md is required but not found

Every example agent in the repo needs to be valid.

3. [blocker] No issue opened first

Per CONTRIBUTING.md:

For new features, please open an issue first so we can discuss the approach together.

The referenced gitclaw/issues/4 is on a different repo and is a discussion about potential integration -- not a feature request on this repo. A dedicated issue on open-gitagent/gitagent would give a place to align on how GNAP should be represented before writing the code.

4. [warning] Workflow has portability issues

In workflows/gnap-worker-flow.yaml:

• sed -i behaves differently on macOS vs Linux. On macOS (BSD sed), sed -i requires a backup extension argument (sed -i '' ...). On GNU/Linux it doesn't. This will break on macOS.
• The workflow clones to /tmp/board -- a hardcoded temp path that will collide if multiple agents run concurrently.
• The error_handling block references $TASK but that variable is scoped to the claim step's shell, not the error handler's shell. It would be empty.

5. [warning] No manual testing documented

CONTRIBUTING.md says:

Run your change against a real agent. Include the command you ran and the output in the PR description.

The PR description doesn't include any test commands or output. Since this adds an example with a SkillsFlow workflow, it would be good to show at least gitagent validate passing and what gitagent export -f system-prompt produces for this agent.

6. [warning] Branch naming

CONTRIBUTING.md suggests patterns like feat/..., fix/..., adapter/..., spec/.... The branch add-gnap-coordination-pattern uses a different convention -- something like feat/gnap-pattern or docs/gnap-coordination would be more consistent. Minor, not blocking.

---

Suggestion

Given issue #1, I'd recommend:

1. Open an issue on this repo to discuss the GNAP integration approach
2. Rewrite the example to use GNAP's actual JSON format (.gnap/tasks/*.json with proper fields)
3. Add a SOUL.md to the example
4. Update the workflow to use the real GNAP state transitions (state field changes via JSON, not directory moves)
5. Show gitagent validate passing in the PR description

The narrative about gitagent defining agent structure and GNAP defining coordination is compelling -- it just needs to accurately represent the GNAP protocol.

[ori-cofounder]

Thanks @shreyas-lyzr for the thorough review — these are valid points and I appreciate the specificity.

Acknowledging the blockers:

#1 GNAP format — You're right, I was working off an older mental model. The actual spec uses .gnap/tasks/{id}.json with a state field, not directory-based movement. I'll rewrite the example to match the real JSON format.

#2 Missing SOUL.md — Will add it. Missed this requirement.

#3 No issue first — Fair catch on CONTRIBUTING.md. I'll open a proper issue on this repo before continuing, so we can align on the integration approach.

I'll close this PR, open an issue to discuss, and resubmit once the example actually validates and represents GNAP correctly.

Thanks again for catching these early.