# Metagit Agent Coordination

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-metagit-ai-metagit-cli-metagit-agent-coordination`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [metagit-ai](https://agentstack.voostack.com/s/metagit-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [metagit-ai](https://github.com/metagit-ai)
- **Source:** https://github.com/metagit-ai/metagit-cli/tree/main/skills/metagit-agent-coordination
- **Website:** https://metagit-ai.github.io/metagit-cli/

## Install

```sh
agentstack add skill-metagit-ai-metagit-cli-metagit-agent-coordination
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Metagit Agent Coordination Layer (ACL)

Use when **more than one agent** may edit the same repository, or when an
orchestrator must give each agent an exclusive checkout.

Full reference: [docs/reference/agent-coordination.md](../../../../docs/reference/agent-coordination.md)

Task graphs (`metagit task …`) can store ACL command hints on nodes via
`metagit task bind-acl` without running git — see
[docs/reference/task-graph.md](../../../../docs/reference/task-graph.md).

Merge orchestration (`metagit merge …`) records conflicts with ACL command
hints only; it does not allocate branches or worktrees automatically.

The agent scheduler (`metagit schedule next`) scores ready task nodes and
returns dispatch hints without launching models or mutating git — see
[docs/reference/agent-scheduler.md](../../../../docs/reference/agent-scheduler.md).

For a composed operator snapshot and next-work envelope across ACL + task
graph + optional 0009–0012, use skill **`metagit-aos`**
(`metagit aos|coord status|doctor|next`) — see
[docs/reference/aos.md](../../../../docs/reference/aos.md).

## When to use

- Dispatching parallel subagents on the same repo
- `handoff.acl_commands` appears in `metagit agent dispatch-plan`
- Preventing two agents from sharing a working directory
- Declaring intended file paths before coding (advisory claims)
- Cleaning up expired leases / orphan worktrees

## Do not confuse with handoff leases

| Concept | Command | Owns |
|---------|---------|------|
| **Handoff claim TTL** | `metagit context handoff claim --ttl` | Task-queue row |
| **ACL branch lease** | `metagit lease acquire` | `agent/*` branch |

## Happy path

```bash
export METAGIT_AGENT_MODE=true

# 1. Allocate an exclusive agent branch
metagit branch allocate \
  --repository project/repo \
  --agent-id agent-1 \
  --task-id 412 \
  --description auth \
  --json

# 2. Lease it (default TTL 30m; renew while working)
metagit lease acquire \
  --repository project/repo \
  --agent-id agent-1 \
  --task-id 412 \
  --allocate \
  --ttl 30m \
  --json

# 3. Create an isolated worktree (requires active lease)
metagit worktree create \
  --repository project/repo \
  --agent-id agent-1 \
  --task-id 412 \
  --branch agent/412-auth \
  --json

# 4. Optional: advisory file claims before editing
metagit claim declare \
  --repository project/repo \
  --agent-id agent-1 \
  --pattern 'src/auth/*' \
  --json

# 5. Show execution manifest written on create
metagit worktree manifest agent-1
```

Or allocate + lease in one step with `--allocate` on `lease acquire`.

## Paths

- **Metadata:** `.metagit/{branches,leases,worktrees,claims,agents,events}/` under the manifest/session root
- **Checkouts:** `/////`
  - Default `worktrees_path`: `.worktrees`
  - Appconfig: `workspace.worktrees_path`
  - Env: `METAGIT_WORKSPACE_WORKTREES_PATH`
- Path basenames (e.g. `worktrees`, `.worktrees`, `campaigns`, `_campaigns`) are **reserved** and cannot be workspace project names

## MCP tools (ACTIVE gate)

| Area | Tools |
|------|-------|
| Branch | `metagit_branch_allocate`, `metagit_branch_list`, `metagit_branch_release` |
| Lease | `metagit_lease_acquire`, `metagit_lease_renew`, `metagit_lease_release`, `metagit_lease_list` |
| Worktree | `metagit_worktree_create`, `metagit_worktree_destroy`, `metagit_worktree_status`, `metagit_worktree_list` |
| Claim | `metagit_claim_declare`, `metagit_claim_check`, `metagit_claim_list`, `metagit_claim_release` |

Events appear in `metagit context events` / `metagit_events` with `source=acl`.

## Conflict handling

- **Branch already allocated** — choose a different `task-id` / description, or wait for release
- **Lease held by another agent** — wait, renew is owner-only; do not force unless authorized
- **Claim overlap** — advisory; response includes `owner` + overlapping patterns; subdivide, wait, or override with `--strict` off (default allows declare with conflict event)
- **Worktree already exists for agent+repo** — destroy/gc first; one active worktree per `(agent_id, repository)`

## Cleanup

```bash
metagit lease renew --lease-id  --agent-id agent-1 --ttl 1h
metagit lease release --lease-id  --agent-id agent-1 --release-branch
metagit worktree destroy --worktree-id  --force
metagit worktree gc
metagit branch cleanup
```

## Anti-patterns

- Two agents editing the same sync-root checkout
- Using handoff `--ttl` instead of `metagit lease` for branch ownership
- Naming a workspace project `worktrees` or `campaigns`
- Skipping lease acquire before `worktree create`
- Leaving expired leases / orphan worktrees without `gc`

## Related skills

- `metagit-control-center` — orchestrator dispatch; run this skill when isolating subagents
- `metagit-multi-repo` — cross-repo delivery; use ACL per repo before parallel edits
- `metagit-sharing-state` — shared objectives/handoffs across machines (orthogonal to git isolation)
- `metagit-cli` — short ACL command cheat sheet

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [metagit-ai](https://github.com/metagit-ai)
- **Source:** [metagit-ai/metagit-cli](https://github.com/metagit-ai/metagit-cli)
- **License:** MIT
- **Homepage:** https://metagit-ai.github.io/metagit-cli/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-metagit-ai-metagit-cli-metagit-agent-coordination
- Seller: https://agentstack.voostack.com/s/metagit-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.