Add cfgit-agent coordination plugin

.github/workflows/ci.yml

@@ -24,6 +24,7 @@ jobs:
           python -m pip install -U pip
           python -m pip install -e '.[mongo,postgres,mcp,dev]'
           python -m pip install -e plugins/cfg_impact
+          python -m pip install -e plugins/cfg_agent
       - name: Run tests
         run: python -m pytest -q
 
@@ -38,9 +39,12 @@ jobs:
       - name: Build and check distributions
         run: |
           python -m pip install -U build twine
-          rm -rf dist plugins/cfg_impact/dist
+          rm -rf dist plugins/cfg_impact/dist plugins/cfg_agent/dist
           python -m build
           python -m twine check dist/*
           cd plugins/cfg_impact
           python -m build
           python -m twine check dist/*
+          cd ../cfg_agent
+          python -m build
+          python -m twine check dist/*

README.md

@@ -67,6 +67,7 @@ cfgit is pre-1.0 software. The current implementation includes:
 - MCP server
 - portable Codex or Claude Code skill
 - optional `cfgit-impact` plugin for deterministic impact summaries and opt-in LLM narration
+- optional `cfgit-agent` plugin for multi-agent coordination over shared live database records
 
 The engine is intentionally DB-neutral. Mongo and Postgres are the first two
 adapters to prove the storage seam.
@@ -130,6 +131,34 @@ Optional impact plugin:
 pip install cfgit-impact
 ```
 
+Agent coordination plugin is currently in-repo development, not published to
+PyPI yet:
+
+```bash
+pip install -e plugins/cfg_agent
+```
+
+Enable it per project when you want multi-agent coordination state:
+
+```toml
+[agent]
+enabled = true
+state_backend = "auto" # memory, auto, mongo, or postgres
+state_collection = "cfgit_agent_state"
+events_collection = "cfgit_agent_events"
+default_lease_ttl_seconds = 900
+
+[agent.policies]
+deny_paths = ["/provider_config*"]
+review_paths = ["/rollout*", "/pricing*"]
+require_claims = true
+```
+
+When an agent patch touches `review_paths`, `cfgit-agent` validates the patch,
+creates a cfgit draft branch, opens a cfgit PR, and returns
+`state = "review_requested"` without mutating runtime. The human merge path
+remains the only runtime mutation for those changes.
+
 If you use `pipx`, install cfgit first and inject the optional plugin into the
 same isolated environment:
 
@@ -358,7 +387,9 @@ surfaces live drift and the latest cfgit commits across all configured records,
 so you can see what changed recently without opening records one by one. It can
 run status, diff, impact, commit, branch draft commits, PR open and merge, log,
 show, adopt, restore, tag, init, import, and fsck, and ships dark and light
-themes.
+themes. When `cfgit-agent` is installed and `[agent]` is enabled, the UI also
+shows live agent sessions, claims, intents, conflicts, and events, with safe
+manager actions for stale coordination state.
 
 By default it binds to `127.0.0.1:8765` and tries the next free ports if needed:
 

docs/AGENTS.md

@@ -157,3 +157,61 @@ Supported providers:
 The impact engine calls a provider-agnostic `narrate()` or `complete()` method.
 Provider selection is done by `cfg_impact.providers.factory.ImpactProviderFactory`.
 No vendor provider code lives in `src/cfg/core`.
+
+## Agent coordination plugin
+
+`cfgit-agent` is an optional package for multi-agent coordination over shared
+live database records. It keeps cfgit core lightweight while adding agent-first
+sessions, leases, intents, idempotency, conflicts, and event feeds.
+
+It is currently in-repo development, not published to PyPI yet:
+
+```bash
+pip install -e plugins/cfg_agent
+```
+
+Current implementation slice:
+
+- package scaffold
+- in-memory state adapter
+- Mongo and Postgres state adapters
+- plugin-local `[agent]` config loader
+- resource/path overlap checks
+- sessions
+- field/record/collection leases
+- intents
+- idempotency records
+- structured conflicts
+- deterministic claim/path policies
+- branch/PR routing for review-required paths
+- JSON Patch validation against cfgit HEAD/live state
+- safe patch application through cfgit core
+- MCP wrappers
+
+The current apply path goes through cfgit core's normal commit/apply safety
+checks rather than writing the database directly. Agent state is opt-in; if
+`[agent].enabled = true`, use `state_backend = "auto"` to store sessions, leases,
+intents, conflicts, idempotency, and events beside cfgit history.
+If `[agent.policies].review_paths` matches a patch path, `apply_patch` does not
+mutate runtime; it creates a cfgit branch draft commit, opens a cfgit PR, links
+the PR to the agent session/intent, and returns `review_requested`.
+The localhost UI includes an agent manager view for enabled projects, so humans
+can inspect active sessions, claims, intents, conflicts, and events without
+tailing MCP logs.
+
+Minimal config:
+
+```toml
+[agent]
+enabled = true
+state_backend = "auto"
+state_collection = "cfgit_agent_state"
+events_collection = "cfgit_agent_events"
+
+[agent.policies]
+deny_paths = ["/provider_config*"]
+review_paths = ["/rollout*", "/pricing*"]
+require_claims = true
+```
+
+See [AGENT_COORDINATION_SPEC.md](AGENT_COORDINATION_SPEC.md).