// SPDX-License-Identifier: CC-BY-SA-4.0
// K9 Coordination Protocol - README
= K9 Coordination Protocol
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:revdate: 2026-04-03
:description: Universal AI agent coordination via K9 structured data files
:toc:

== Overview

The K9 Coordination Protocol defines a standard way to express project invariants,
architectural decisions, and coordination state in K9 Kennel-level files, then
generate native instruction files for every major AI coding tool.

=== The Problem

When multiple AI agents (Claude, Copilot, Cursor, Gemini, Codex, etc.) work on
the same codebase — sequentially or concurrently — they lack shared context about:

* What is intentional vs accidental
* What architectural decisions are deliberate
* What another agent is currently working on
* What should never be created, deleted, or reorganised

This leads to well-meaning destruction: agents "fixing" features, creating parallel
systems, or deleting deliberate architecture because they lack context.

=== The Solution

A single `coordination.k9` file per project, written in K9 Kennel format (pure data,
no execution), which:

1. **Declares invariants** — rules that must never be violated
2. **Protects patterns** — files and directories that are deliberate
3. **Records architecture** — decisions that look odd but are intentional
4. **Prevents creation** — things that must not be introduced
5. **Coordinates work** — (Phase 2) who is working on what

A generator tool reads this K9 file and emits native instruction files for every
supported AI tool.

== Supported Targets

[cols="1,2,1"]
|===
| AI Tool | Output File | Location

| Claude Code | `CLAUDE.md` | `.claude/`
| GitHub Copilot | `copilot-instructions.md` | `.github/`
| OpenAI Codex | `AGENTS.md` | root
| Cursor | `.cursorrules` | root
| Windsurf | `.windsurfrules` | root
| Gemini CLI | `GEMINI.md` | root
| Cline | `.clinerules` | root
| JetBrains Junie | `guidelines.md` | `.junie/`
| Amazon Q | `coordination.md` | `.q/rules/`
|===

== Usage

[source,bash]
----
# Generate all AI config files from a coordination.k9
deno run --allow-read --allow-write \
  standards/k9-coordination-protocol/generator/generate.js \
  ./coordination.k9

# Generate for specific targets only
deno run --allow-read --allow-write \
  standards/k9-coordination-protocol/generator/generate.js \
  ./coordination.k9 --targets claude,cursor,copilot
----

== Phases

=== Phase 1: Defensive (Current)

Single K9 file declares what is and isn't negotiable. Every AI reads the same
ground truth. Prevents accidental destruction.

=== Phase 2: Coordination

K9 file tracks which agents are working on which areas. A new agent can read
the coordination state and avoid stepping on active work.

=== Phase 3: Orchestration

Agents report completion. Other agents can pick up follow-on work, tidy seams
between parallel efforts, and flag integration points.

== See Also

* link:spec/COORDINATION-K9-SPEC.adoc[Formal Specification]
* link:examples/[Example Files]
* link:generator/[Generator Tool]
* link:../k9-svc/SPEC.adoc[K9 Format Specification]
* link:../0-ai-gatekeeper-protocol/[AI Gatekeeper Protocol]
