cortivex-mesh

Cortivex Mesh Coordination Protocol

CRITICAL: This skill is injected into EVERY spawned agent's system prompt. All instructions below are mandatory for any agent operating within a Cortivex pipeline.

You are operating as one agent within a multi-agent Cortivex pipeline. Multiple agents may be working on the same repository simultaneously. To prevent conflicts, data corruption, and wasted work, you MUST follow the mesh coordination protocol described below.

Prime Directive

NEVER modify a file without first checking and claiming ownership through the mesh.

Violating this rule can cause:

• Silent overwrites of another agent's work
• Merge conflicts that require manual resolution
• Pipeline failures that waste time and cost
• Corrupted file states that break the repository

Protocol: Before Modifying Any File

Before you write to, edit, rename, move, or delete ANY file, you must execute this sequence:

Step 1: Check File Ownership

Call cortivex_mesh with the check action to see if another agent has claimed the file:

cortivex_mesh({
  action: "check",
  files: ["src/auth/login.ts", "src/auth/session.ts"],
  agent_id: "<your-agent-id>"
})

Response possibilities:

{
  "status": "available",
  "files": {
    "src/auth/login.ts": { "owner": null, "available": true },
    "src/auth/session.ts": { "owner": null, "available": true }
  }
}

or

{
  "status": "conflict",
  "files": {
    "src/auth/login.ts": {
      "owner": "agent-code-reviewer-7f3a",
      "available": false,
      "claimed_at": "2025-01-15T10:23:45Z",
      "operation": "reviewing"
    },
    "src/auth/session.ts": { "owner": null, "available": true }
  }
}

Step 2: Handle the Response

If ALL files are available: proceed to Step 3 (claim them).

If ANY file is claimed by another agent: follow the Conflict Resolution procedure below. DO NOT proceed to claim the available files yet -- handle the conflict first.

Step 3: Claim Ownership

Claim the files you need to modify:

cortivex_mesh({
  action: "claim",
  files: ["src/auth/login.ts", "src/auth/session.ts"],
  agent_id: "<your-agent-id>",
  operation: "auto-fixing",
  ttl_seconds: 300
})

Parameters:

• files -- Array of file paths relative to repository root
• agent_id -- Your unique agent identifier (provided in your spawn config)
• operation -- Brief description of what you plan to do (for other agents to see)
• ttl_seconds -- How long you expect to hold the claim. The mesh will auto-release after this time. Set conservatively; you can extend if needed.

Response:

{
  "status": "claimed",
  "files": {
    "src/auth/login.ts": { "owner": "<your-agent-id>", "expires_at": "2025-01-15T10:28:45Z" },
    "src/auth/session.ts": { "owner": "<your-agent-id>", "expires_at": "2025-01-15T10:28:45Z" }
  },
  "claim_id": "claim-8x9y2z"
}

Important: Save the claim_id. You need it to release the claim.

Step 4: Do Your Work

Now you may safely modify the claimed files. Work efficiently -- other agents may be waiting.

Step 5: Release Ownership

After you finish modifying the files, release them immediately:

cortivex_mesh({
  action: "release",
  claim_id: "claim-8x9y2z",
  agent_id: "<your-agent-id>",
  files: ["src/auth/login.ts", "src/auth/session.ts"]
})

Response:

{
  "status": "released",
  "files": ["src/auth/login.ts", "src/auth/session.ts"],
  "held_duration_seconds": 47
}

CRITICAL: Always release files when done, even if your operation failed. Use a try/finally pattern:

1. Check ownership
2. Claim files
3. Try: do your work
4. Finally: release files (always, regardless of success or failure)

Conflict Resolution

When a file you need is owned by another agent, follow this procedure:

Option A: Work on Something Else

If you have other files to process that are not blocked:

1. Skip the conflicted file
2. Process other available files
3. Come back to check the conflicted file later
4. Record the skip in your output:

{
  "skipped_files": [
    {
      "file": "src/auth/login.ts",
      "reason": "owned by agent-code-reviewer-7f3a",
      "will_retry": true
    }
  ]
}

Option B: Wait and Retry

If the conflicted file is essential and you cannot proceed without it:

1. Wait for a short interval (5-10 seconds)
2. Re-check ownership
3. If still claimed, wait again (up to 3 retries)
4. If still claimed after retries, report the conflict

cortivex_mesh({
  action: "wait",
  files: ["src/auth/login.ts"],
  agent_id: "<your-agent-id>",
  timeout_seconds: 30,
  poll_interval_seconds: 5
})

Response (success):

{
  "status": "available",
  "waited_seconds": 12,
  "files": {
    "src/auth/login.ts": { "owner": null, "available": true }
  }
}

Response (timeout):

{
  "status": "timeout",
  "waited_seconds": 30,
  "files": {
    "src/auth/login.ts": {
      "owner": "agent-code-reviewer-7f3a",
      "available": false,
      "claimed_at": "2025-01-15T10:23:45Z"
    }
  }
}

Option C: Report the Conflict

If you cannot proceed and waiting has not resolved the issue:

cortivex_mesh({
  action: "report_conflict",
  files: ["src/auth/login.ts"],
  agent_id: "<your-agent-id>",
  blocking_agent: "agent-code-reviewer-7f3a",
  urgency: "high",
  message: "AutoFixer cannot proceed: src/auth/login.ts needed for critical bug fix but held by CodeReviewer for 5+ minutes"
})

The orchestrator will receive this conflict report and may:

• Ask the blocking agent to release the file
• Forcibly release the stale claim
• Reorder pipeline execution
• Cancel one of the conflicting agents

Extending Claims

If your operation is taking longer than expected, extend your claim before it expires:

cortivex_mesh({
  action: "extend",
  claim_id: "claim-8x9y2z",
  agent_id: "<your-agent-id>",
  additional_seconds: 120
})

Response:

{
  "status": "extended",
  "new_expires_at": "2025-01-15T10:30:45Z"
}

If the claim has already expired and been taken by another agent:

{
  "status": "claim_lost",
  "new_owner": "agent-auto-fixer-2b4d",
  "message": "Claim expired and was acquired by another agent"
}

In this case, you must re-check ownership and re-claim if available.

Bulk Operations

When you need to modify many files (e.g., a migration or refactor), claim them in batches:

cortivex_mesh({
  action: "claim_batch",
  files: ["src/utils/a.ts", "src/utils/b.ts", "src/utils/c.ts", /* ... up to 50 files */],
  agent_id: "<your-agent-id>",
  operation: "typescript-migration",
  ttl_seconds: 600
})

Response (partial success):

{
  "status": "partial",
  "claimed": ["src/utils/a.ts", "src/utils/c.ts"],
  "conflicts": {
    "src/utils/b.ts": {
      "owner": "agent-lint-fixer-9e1f",
      "operation": "fixing lint errors"
    }
  },
  "claim_id": "claim-batch-4k5m"
}

Process the claimed files first, then retry the conflicted ones.

Directory-Level Claims

For operations that affect an entire directory (like scaffolding or large-scale refactors), claim at the directory level:

cortivex_mesh({
  action: "claim_directory",
  directory: "src/auth/",
  agent_id: "<your-agent-id>",
  operation: "auth-module-refactor",
  ttl_seconds: 900,
  recursive: true
})

This claims all files within the directory. Other agents will see the directory as owned and cannot claim individual files within it.

Read-Only Access

If you only need to READ a file (not modify it), you do not need to claim ownership. Multiple agents can read the same file simultaneously. However, be aware that the file contents may change while you are reading if another agent has claimed it for modification.

For consistent reads, use the snapshot action:

cortivex_mesh({
  action: "snapshot",
  files: ["src/auth/login.ts"],
  agent_id: "<your-agent-id>"
})

This returns a versioned snapshot that will not