our-claude-skills/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/templates/guardrails-md.md

GUARDRAILS.md - Ownership & Enforcement Rules

This document defines the ownership matrix, lock system, and enforcement mechanisms for multi-agent collaboration in this repository.

Collaboration Rules: See AGENTS.md for handoff protocols and code standards.

---

1. Ownership Matrix

1.1 Ownership Categories

Category	Description	Override
Primary	Agent has exclusive authority	Claude can override
Shared	Multiple agents can modify, requires coordination	Claude approves changes
Unrestricted	Any agent can modify	No restrictions

1.2 Claude Code - Primary Ownership

Claude Code is the lead agent with primary ownership of:

Pattern	Description
CLAUDE.md	Lead agent directive
AGENTS.md	Shared collaboration rules
GUARDRAILS.md	This file
src/*/cli.py	CLI entry points
src/*/core/	Core logic modules
src/*/main.py	Main entry points

1.3 Gemini - Primary Ownership

Gemini has primary ownership of:

Pattern	Description
GEMINI.md	Gemini directive
src/*/integrations/google/	Google API integrations
src/*/integrations/gsc.py	Google Search Console
src/*/integrations/ga*.py	Google Analytics
docs/	Documentation (markdown)

1.4 Codex - Primary Ownership

Codex has primary ownership of:

Pattern	Description
CODEX.md	Codex directive
src/*/models.py	Pydantic/data models
src/*/utils/	Utility functions
tests/	All test files

1.5 Shared Files

These files require coordination (Claude approves):

Pattern	Coordination Rule
pyproject.toml	Dependency changes require discussion
config/*.yaml	Configuration changes affect all agents
.github/workflows/	CI/CD changes impact everyone
PROJECT_PLAN.md	Roadmap changes need consensus

1.6 Unrestricted Files

Any agent can modify these files:

Pattern	Notes
.agent-state/	Task and lock management
.gitignore	Git configuration
README.md	Project readme
.pre-commit-config.yaml	Pre-commit hooks

---

2. Lock System

2.1 Lock Types

Type	Description	Use Case
exclusive	Single agent can modify	Long-running refactors
shared	Multiple can read, one writes	Concurrent development
override	Claude override for conflicts	Emergency fixes

2.2 Lock File Format

Location: .agent-state/locks.yaml

version: "1.0"
updated_at: "2025-01-29T12:00:00Z"

locks:
  - path: "src/module/"
    agent: "claude"
    lock_type: "exclusive"
    task_id: "TASK-001"
    reason: "Refactoring core module"
    created_at: "2025-01-29T10:00:00Z"
    expires_at: "2025-01-29T14:00:00Z"

  - path: "docs/api/"
    agent: "gemini"
    lock_type: "shared"
    task_id: "TASK-002"
    reason: "Updating API documentation"
    created_at: "2025-01-29T11:00:00Z"
    expires_at: "2025-01-29T15:00:00Z"

2.3 Lock Operations

Acquire Lock:

1. Check if path is already locked
2. If locked by another agent, wait or request release
3. Add lock entry to locks.yaml
4. Set expiration time (default: 4 hours)

Release Lock:

1. Remove lock entry from locks.yaml
2. Update updated_at timestamp
3. Notify other agents if requested

Lock Expiration:

• Locks automatically expire at expires_at time
• Expired locks can be claimed by any agent
• Run python tools/check-ownership.py --list-expired to see expired locks

---

3. Task Claiming Protocol

3.1 Task File Format

Location: .agent-state/tasks.yaml

version: "1.0"
updated_at: "2025-01-29T12:00:00Z"

tasks:
  - id: "TASK-001"
    description: "Implement new feature"
    agent: "claude"
    status: "in_progress"
    priority: "high"
    files:
      - "src/feature.py"
      - "tests/test_feature.py"
    created_at: "2025-01-29T09:00:00Z"
    claimed_at: "2025-01-29T09:30:00Z"
    expires_at: "2025-01-29T13:30:00Z"

  - id: "TASK-002"
    description: "Write API documentation"
    agent: "gemini"
    status: "pending"
    priority: "medium"
    files:
      - "docs/api.md"
    created_at: "2025-01-29T10:00:00Z"

3.2 Task Status Flow

pending → in_progress → completed
              ↓
          abandoned (if expired)
              ↓
          blocked (if dependency)

3.3 Claiming Process

1. Check availability: Verify task is pending
2. Set identity: Ensure SEO_AGENT_AUTHOR is set
3. Claim task: Update tasks.yaml with your agent name
4. Acquire locks: Lock files you'll modify
5. Begin work: Start implementation
6. Complete task: Mark as completed, release locks

3.4 Task Expiration

• Default timeout: 4 hours from claimed_at
• Expired tasks revert to pending
• Other agents can reclaim expired tasks

---

4. Environment Configuration

4.1 Required Environment Variable

# Set in shell profile or .envrc
export SEO_AGENT_AUTHOR=<agent_name>

# Valid values:
# - claude
# - gemini
# - codex
# - human

4.2 Verification

# Check current agent identity
echo $SEO_AGENT_AUTHOR

# Verify setup
python tools/check-ownership.py --verify-setup

---

5. Conflict Resolution

5.1 Resolution Hierarchy

Conflict Type	Resolution
Ownership dispute	Claude decides
Lock conflict	First to lock wins; Claude can override
Task overlap	Split tasks or assign to single agent
Merge conflict	Claude resolves

5.2 Escalation Process

1. Identify conflict: Agent detects violation
2. Document issue: Add to escalation log
3. Notify Claude: Include conflict details
4. Claude decides: Makes binding decision
5. Update rules: Modify GUARDRAILS.md if pattern emerges

5.3 Claude Override

Claude can override any lock or ownership rule:

# In locks.yaml
- path: "src/critical/"
  agent: "claude"
  lock_type: "override"
  task_id: "EMERGENCY-001"
  reason: "Critical bug fix"
  override_agent: "gemini"  # Agent whose lock was overridden

---

6. Verification Tools

6.1 check-ownership.py Commands

# Verify files before commit
python tools/check-ownership.py path/to/file.py

# Check commit message format
python tools/check-ownership.py --check-commit-msg

# Verify setup
python tools/check-ownership.py --verify-setup

# List expired locks/tasks
python tools/check-ownership.py --list-expired

# Validate state files
python tools/check-ownership.py --validate-state

# Strict mode (warnings as errors)
python tools/check-ownership.py --strict path/to/file.py

6.2 Pre-commit Integration

The following hooks run automatically:

Hook	Stage	Purpose
check-ownership	commit	Verify file ownership
check-commit-message	commit-msg	Validate message format

---

7. CI/CD Integration

7.1 GitHub Actions

Ownership checks run on PRs:

# .github/workflows/ownership-check.yml
- Check changed files against ownership matrix
- Post violations as PR comments
- Block merge on violations

7.2 PR Labels

Label	Meaning
ownership-verified	All files verified
ownership-override	Claude approved override
ownership-violation	Needs resolution

---

8. Quick Reference

Commands

# Set identity
export SEO_AGENT_AUTHOR=claude

# Check ownership
python tools/check-ownership.py src/file.py

# List expired
python tools/check-ownership.py --list-expired

# Validate state
python tools/check-ownership.py --validate-state

Commit Format

[Agent] type(scope): description

[Claude] feat(core): implement new feature
[Gemini] docs(api): update API documentation
[Codex] test(models): add model tests

File Locations

File	Purpose
.agent-state/tasks.yaml	Task registry
.agent-state/locks.yaml	Lock registry
tools/check-ownership.py	Verification script

---

This document defines the enforcement rules for multi-agent collaboration. Claude Code is the authoritative source for conflict resolution.

Last updated: [DATE]