---
name: Antigravity Coordination
description: |
  Parallel worktree execution system using Antigravity MCP tools.
  Coordinate work across charming-dirac, elegant-black, and epic-agnesi
  worktrees with file-locked shared state, event logging, and Gemini delegation.

  WHEN TO USE:
  - "Run parallel agents across worktrees"
  - "Coordinate multi-worktree work"
  - "Antigravity plan/execute"
  - "Sync state between worktrees"
  - "Dispatch work to charming-dirac / elegant-black / epic-agnesi"
  - "Push/pull worktree context"
  - Need to fan out tasks across 3 isolated branches simultaneously
  - Need to check what each worktree is currently doing

  CAPABILITIES:
  - antigravity_plan: Create Gemini-backed workflow plans
  - antigravity_execute: Execute a saved plan
  - sync_push / sync_pull: Cross-agent shared state sync
  - sync_status: Health check on sync infrastructure
  - gemini_query: Direct Gemini delegation
  - memory_store / memory_query: Persist insights to memory bridge

allowed-tools:
  - Read
  - Bash
  - mcp__genesis-full__antigravity_plan
  - mcp__genesis-full__antigravity_execute
  - mcp__genesis-full__sync_push
  - mcp__genesis-full__sync_pull
  - mcp__genesis-full__sync_status
  - mcp__genesis-full__gemini_query
---

# Antigravity Coordination

## What Is Antigravity?

Antigravity is Genesis's parallel worktree execution system. It lets one orchestrating Claude session coordinate work across multiple isolated git worktrees, each running its own agent, while maintaining a shared state bus for context exchange.

The name comes from its purpose: lifting the gravitational constraint of sequential single-agent work. Three worktrees, three agents, one goal — done in parallel.

```
                    ORCHESTRATOR (charming-dirac)
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   charming-dirac    elegant-black     epic-agnesi
   (current/main)   (research/UI)     (infra/build)
          │                │                │
   [Claude agent]   [Claude agent]   [Claude agent]
          │                │                │
          └────────────────┼────────────────┘
                           ▼
                  Shared State Bus
              /mnt/e/genesis-system/data/
                    antigravity-sync/
                           │
                    ┌──────┴──────┐
                    ▼             ▼
               state.json    events.jsonl
```

## Worktree Inventory

| Worktree | Path | Branch | Role |
|----------|------|--------|------|
| charming-dirac | `E:\genesis-system\.claude\worktrees\charming-dirac` | `claude/charming-dirac` | Orchestrator, primary agent, current session |
| elegant-black | `E:\genesis-system\.claude\worktrees\elegant-black` | `claude/elegant-black` | Research, UI work, strategy documents |
| epic-agnesi | `E:\genesis-system\.claude\worktrees\epic-agnesi` | `claude/epic-agnesi` | Infrastructure, build pipelines, backend |

Main repo lives at `E:\genesis-system` on branch `master`.

## Sync Infrastructure

The shared state bus lives at:
```
E:\genesis-system\data\antigravity-sync\
├── state.json          ← Shared key-value state (file-locked)
├── events.jsonl        ← Append-only event log (file-locked)
├── plans\              ← Saved workflow plans (plan_<id>.json)
├── executions\         ← Execution results (plan_<id>_<ts>.json)
├── context\            ← Arbitrary context blobs
└── browser_requests\   ← Delegated browser tasks
```

File locking (portalocker) prevents concurrent write corruption. All reads/writes are safe for multi-agent parallel access.

## MCP Tool Reference

All tools are in the `genesis-full` MCP server. The tool implementation lives at:
`E:\genesis-system\genesis_v2\mcp\antigravity_tools.py`

### antigravity_plan

Creates a Gemini-backed workflow plan for a goal. Persists to `plans/` and marks the active plan in state.

```python
# Usage
result = mcp__genesis-full__antigravity_plan(
    goal="Build the Telnyx webhook integration",
    context_json='{"priority": "high", "worktree": "epic-agnesi"}'
)
# Returns: {"plan_id": "...", "goal": "...", "steps": [...], "status": "planned"}
```

The plan_id is used by antigravity_execute. Always store the plan_id from the result.

### antigravity_execute

Executes a previously created plan. The plan must exist in the plans/ directory.

```python
result = mcp__genesis-full__antigravity_execute(
    plan_id="<plan_id from antigravity_plan>"
)
# Returns: {"plan_id": "...", "result": {...}, "status": "completed"}
```

### sync_push

Pushes context into the shared state bus. Used by any worktree agent to broadcast state to all others.

```python
result = mcp__genesis-full__sync_push(
    context_json='{"task": "webhook-integration", "status": "in_progress", "worktree": "epic-agnesi", "eta": "30min"}'
)
# Returns: {"success": true, "sync_count": 42}
```

Keys are merged into `state["claude_context"]`. Existing keys are overwritten.

### sync_pull

Pulls the entire shared state plus the last 20 events. Call this at session start or before making decisions.

```python
result = mcp__genesis-full__sync_pull()
# Returns: {"state": {...}, "recent_events": [...]}
```

The `state["claude_context"]` key contains everything pushed by all agents.

### sync_status

Health check on sync infrastructure. Call this to verify the system is operational.

```python
result = mcp__genesis-full__sync_status()
# Returns: {"sync_count": 42, "active_plan": "...", "event_count": 156, ...}
```

### gemini_query

Direct Gemini delegation for analysis, planning, or generation without full workflow overhead.

```python
result = mcp__genesis-full__gemini_query(
    prompt="Analyze the webhook retry logic and suggest improvements",
    task_type="analysis",  # general | analysis | planning | code_review
    temperature=0.7
)
```

## Worktree Assignment Policy

### What Goes Where

**charming-dirac** (you are here — orchestrator):
- Coordination, synthesis, handoffs
- Orchestrating the other worktrees
- Final integration and merge decisions
- Responses to Kinan / session management

**elegant-black** (research and UI):
- Strategy documents, competitive research
- Frontend, UI components, HTML/CSS
- Prompt engineering, system prompt work
- Knowledge Graph updates, axiom writing
- ReceptionistAI branding/copy

**epic-agnesi** (infrastructure and backend):
- Python backend, API integrations
- Webhook handlers, Telnyx/Stripe config
- Database schema, PostgreSQL work
- Deployment scripts, CI/CD
- Performance optimization

### Decision Rule

When assigning a task to a worktree, use this test:
1. Does it require browser interaction? → Use Playwright MCP from current worktree (do not fan out)
2. Is it research or UI? → elegant-black
3. Is it backend or infra? → epic-agnesi
4. Is it orchestration or synthesis? → charming-dirac (stay here)
5. Is it genuinely parallel? → fan out all three

## Standard Protocol: Session Start

Every time you start work in ANY worktree:

```python
# Step 1: Pull current state
state = mcp__genesis-full__sync_pull()
# Read state["state"]["claude_context"] for current task assignments

# Step 2: Announce your presence
mcp__genesis-full__sync_push(context_json=json.dumps({
    "worktree": "charming-dirac",
    "status": "active",
    "task": "describe what you're about to do",
    "started_at": "ISO timestamp"
}))
```

## Standard Protocol: Before Handoff or Session End

```python
# Step 1: Push your final state
mcp__genesis-full__sync_push(context_json=json.dumps({
    "worktree": "charming-dirac",
    "status": "complete",
    "completed": ["list of what was done"],
    "blockers": [],
    "next_for": "elegant-black"  # who picks up next
}))

# Step 2: Git commit your work on the worktree branch
# cd to your worktree, commit, then the next agent can git pull or merge
```

## One-Command Parallel Launch

To fan out work across all three worktrees simultaneously, create a plan and then open separate Claude Code sessions (one per worktree). The sync bus handles coordination.

### Step 1: Create the master plan (from charming-dirac)

```python
plan = mcp__genesis-full__antigravity_plan(
    goal="Ship the full ReceptionistAI Telnyx integration: webhook handler (epic-agnesi) + demo UI update (elegant-black) + GHL workflow config (charming-dirac)",
    context_json='{"deadline": "2026-02-23", "priority": "GOLD"}'
)
plan_id = json.loads(plan)["plan_id"]
```

### Step 2: Push task assignments to sync bus

```python
mcp__genesis-full__sync_push(context_json=json.dumps({
    "active_plan": plan_id,
    "charming-dirac": "Configure GHL workflow via Playwright MCP",
    "elegant-black": "Update demo UI - new color scheme and copy",
    "epic-agnesi": "Build Telnyx webhook handler in Python",
    "coordination_channel": "sync_bus",
    "merge_order": ["epic-agnesi", "elegant-black", "charming-dirac"]
}))
```

### Step 3: Each worktree agent starts with sync_pull

Each agent in its own session does:
```python
state = mcp__genesis-full__sync_pull()
my_task = state["state"]["claude_context"]["<my-worktree-name>"]
# Execute my_task
```

### Step 4: Agents signal completion

```python
mcp__genesis-full__sync_push(context_json=json.dumps({
    "epic-agnesi_status": "DONE",
    "epic-agnesi_output": "webhook_handler.py committed on claude/epic-agnesi"
}))
```

### Step 5: Orchestrator merges in order

```bash
# From main repo (master branch)
git merge claude/epic-agnesi    # infra first
git merge claude/elegant-black  # UI second
# charming-dirac is handled last (orchestrator merges its own work)
```

## Conflict Avoidance Rules

These rules prevent parallel agents from stomping on each other:

1. **File ownership**: Each worktree owns specific file domains (see Assignment Policy above). Never write to another worktree's domain files without syncing first.

2. **No direct file sharing**: Worktrees do NOT share files directly. Context passes only through `sync_push/pull`. File outputs stay in the worktree branch until merge.

3. **Lock via sync_push**: Before touching a shared resource (e.g., a config file that will merge), push a "locking" key:
   ```python
   sync_push('{"lock:telnyx_config": "epic-agnesi", "lock:expires": "ISO+30min"}')
   ```
   Other agents pull state and check the lock before touching that resource.

4. **Merge order matters**: Always merge infra (epic-agnesi) before UI (elegant-black) before orchestrator (charming-dirac). This respects dependency order.

5. **One active plan at a time**: The `state["active_plan"]` field is the source of truth. Do not start a new plan until the current one is completed or cancelled.

## Checking Worktree Status

To assess what each worktree is currently working on:

```python
# Pull full state
state = mcp__genesis-full__sync_pull()
context = state["state"]["claude_context"]

# Check per-worktree status
for wt in ["charming-dirac", "elegant-black", "epic-agnesi"]:
    status_key = f"{wt}_status"
    task_key = wt
    print(f"{wt}: {context.get(status_key, 'unknown')} — {context.get(task_key, 'no task assigned')}")

# Check recent events (last 20)
for event in state["recent_events"][-5:]:
    print(f"[{event['timestamp']}] {event['source']}: {event['type']}")
```

To also check git state of a worktree:
```bash
# What branch and last commit is each worktree on?
git -C "E:\genesis-system" worktree list

# What changed in elegant-black since master?
git -C "E:\genesis-system" log master..claude/elegant-black --oneline

# What files did epic-agnesi change?
git -C "E:\genesis-system" diff master...claude/epic-agnesi --name-only
```

## Merging Completed Worktree Work

### Standard Merge Flow

```bash
# 1. Verify the worktree's tests pass before merge
#    (the worktree agent should have run tests and pushed results to sync bus)

# 2. Check what will merge
git -C "E:\genesis-system" diff master...claude/epic-agnesi --stat

# 3. Merge with a clear message
git -C "E:\genesis-system" merge claude/epic-agnesi --no-ff -m "feat: merge epic-agnesi webhook handler"

# 4. Verify no conflicts
# If conflicts: resolve in master, NOT in the worktree branch

# 5. Signal to sync bus that merge is complete
sync_push('{"epic-agnesi_merged": true, "merge_commit": "<sha>"}')
```

### Cleanup After All Merges

```bash
# Remove the worktree (the directory stays, git tracking is removed)
git -C "E:\genesis-system" worktree remove "E:\genesis-system\.claude\worktrees\epic-agnesi"

# Or prune stale worktree references
git -C "E:\genesis-system" worktree prune

# Delete the branch if work is merged
git -C "E:\genesis-system" branch -d claude/epic-agnesi
```

## Re-provisioning Worktrees

If elegant-black or epic-agnesi git metadata has gone stale (e.g., `fatal: not a git repository` error):

```bash
# Remove stale registration
git -C "E:\genesis-system" worktree prune

# Re-add the worktree (reuses existing directory)
git -C "E:\genesis-system" worktree add "E:\genesis-system\.claude\worktrees\elegant-black" -b claude/elegant-black

# Verify
git -C "E:\genesis-system" worktree list
```

Note: The directories at `E:\genesis-system\.claude\worktrees\` persist. Only the git tracking record (in `.git/worktrees/`) may go stale and need re-registration.

## Antigravity + Gemini Swarm

Antigravity tools do NOT replace the Genesis Execution Layer — they complement it. The relationship:

| Tool | Use For |
|------|---------|
| `antigravity_plan` | Multi-step goal decomposition via Gemini |
| `antigravity_execute` | Run a saved plan |
| `genesis_execution_layer.py` | Gemini swarm for heavy batch work |
| `sync_push/pull` | State sharing across agent sessions |
| `gemini_query` | Quick one-off Gemini delegation |

For heavy batch work (10+ parallel tasks), always route through `core/genesis_execution_layer.py`. Use Antigravity for coordination scaffolding and state management.

## Quick Reference

```python
# Health check
sync_status()

# See what everyone is doing
sync_pull()["state"]["claude_context"]

# Announce yourself
sync_push('{"worktree": "charming-dirac", "status": "active", "task": "..."}')

# Create a multi-worktree plan
plan_id = json.loads(antigravity_plan(goal="...", context_json="{}"))["plan_id"]

# Execute a plan
antigravity_execute(plan_id=plan_id)

# Quick Gemini delegation
gemini_query(prompt="...", task_type="analysis")

# Signal you're done
sync_push('{"charming-dirac_status": "DONE", "completed": ["task1", "task2"]}')
```

## Common Failure Modes

| Failure | Symptom | Fix |
|---------|---------|-----|
| Stale worktree | `fatal: not a git repository` | Run `git worktree prune` then re-add |
| Missing GEMINI_API_KEY | `{"error": "GEMINI_API_KEY not set"}` | Check `config/secrets.env` |
| AntigravityWorkflow not available | `{"error": "AntigravityWorkflow not available"}` | Check `core/antigravity_workflow.py` imports |
| Plan not found | `{"error": "Plan not found: <id>"}` | The plan_id was wrong or plans/ was cleared |
| File lock timeout | portalocker exception | Another agent holds the lock; retry after 5s |
| Merge conflict | `CONFLICT (content)` | Resolve in master branch, not in worktree |

## References

- Tool implementation: `E:\genesis-system\genesis_v2\mcp\antigravity_tools.py`
- Sync state directory: `E:\genesis-system\data\antigravity-sync\`
- Related skill: `git-worktrees-parallel` (generic worktree patterns)
- Related skill: `multi-agent-orchestration` (agent coordination patterns)
- Related skill: `agent-sandboxes` (E: drive isolation rules)
