our-claude-skills/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/references/ownership-matrix.md

Ownership Matrix Reference

This document provides detailed patterns for configuring the ownership matrix in check-ownership.py.

Pattern Syntax

The ownership matrix uses Python regular expressions (regex) to match file paths.

Common Patterns

Pattern	Matches	Example Files
^src/cli\.py$	Exact file	src/cli.py
^src/.*/cli\.py$	Any subdirectory	src/app/cli.py, src/core/cli.py
^src/core/	Directory prefix	src/core/main.py, src/core/utils/helper.py
^tests/	All tests	tests/test_main.py, tests/unit/test_foo.py
^docs/.*\.md$	Markdown in docs	docs/api.md, docs/guides/setup.md
\.py$	All Python files	Any .py file

Regex Cheat Sheet

Symbol	Meaning	Example
^	Start of string	^src/ matches paths starting with src/
$	End of string	\.py$ matches paths ending with .py
.	Any character	a.c matches abc, a1c, etc.
\.	Literal dot	\.py matches .py
*	Zero or more	a* matches ``, a, aa, aaa
+	One or more	a+ matches a, aa, aaa
.*	Any characters	src/.* matches anything starting with src/
[abc]	Character class	[abc] matches a, b, or c
\w	Word character	\w+ matches words
\d	Digit	\d+ matches numbers
(a|b)	Alternation	(foo|bar) matches foo or bar

Project-Specific Examples

Python Project

OWNERSHIP_MATRIX: Dict[str, str] = {
    # Claude - Core application
    r"^src/app/": "claude",
    r"^src/core/": "claude",
    r"^src/.*/cli\.py$": "claude",
    r"^CLAUDE\.md$": "claude",
    r"^AGENTS\.md$": "claude",
    r"^GUARDRAILS\.md$": "claude",

    # Gemini - APIs and documentation
    r"^src/.*/api/": "gemini",
    r"^src/.*/integrations/": "gemini",
    r"^docs/": "gemini",
    r"^GEMINI\.md$": "gemini",

    # Codex - Testing and utilities
    r"^tests/": "codex",
    r"^src/.*/models\.py$": "codex",
    r"^src/.*/utils/": "codex",
    r"^CODEX\.md$": "codex",
}

TypeScript Project

OWNERSHIP_MATRIX: Dict[str, str] = {
    # Claude - Core application
    r"^src/app/": "claude",
    r"^src/core/": "claude",
    r"^src/index\.ts$": "claude",
    r"^CLAUDE\.md$": "claude",

    # Gemini - APIs and documentation
    r"^src/api/": "gemini",
    r"^src/services/": "gemini",
    r"^docs/": "gemini",
    r"^GEMINI\.md$": "gemini",

    # Codex - Testing and utilities
    r"^tests/": "codex",
    r"^__tests__/": "codex",
    r"^src/.*/.*\.test\.ts$": "codex",
    r"^src/types/": "codex",
    r"^src/utils/": "codex",
    r"^CODEX\.md$": "codex",
}

Monorepo Project

OWNERSHIP_MATRIX: Dict[str, str] = {
    # Claude - Core packages
    r"^packages/core/": "claude",
    r"^packages/cli/": "claude",
    r"^CLAUDE\.md$": "claude",

    # Gemini - API packages
    r"^packages/api/": "gemini",
    r"^packages/sdk/": "gemini",
    r"^docs/": "gemini",
    r"^GEMINI\.md$": "gemini",

    # Codex - Testing and shared
    r"^packages/testing/": "codex",
    r"^packages/shared/": "codex",
    r"^packages/.*/tests/": "codex",
    r"^CODEX\.md$": "codex",
}

Shared Files Configuration

Files that require coordination between agents:

SHARED_FILES: Set[str] = {
    # Package configuration
    r"^pyproject\.toml$",
    r"^package\.json$",
    r"^Cargo\.toml$",

    # Build configuration
    r"^Makefile$",
    r"^Dockerfile$",
    r"^docker-compose\.ya?ml$",

    # CI/CD
    r"^\.github/workflows/",
    r"^\.gitlab-ci\.yml$",
    r"^\.circleci/",

    # Project planning
    r"^PROJECT_PLAN\.md$",
    r"^ROADMAP\.md$",
    r"^CHANGELOG\.md$",
}

Unrestricted Files Configuration

Files any agent can modify:

UNRESTRICTED_FILES: Set[str] = {
    # Agent state
    r"^\.agent-state/",

    # Git configuration
    r"^\.gitignore$",
    r"^\.gitattributes$",

    # Editor configuration
    r"^\.vscode/",
    r"^\.idea/",

    # Documentation
    r"^README\.md$",
    r"^CONTRIBUTING\.md$",
    r"^LICENSE$",

    # Pre-commit
    r"^\.pre-commit-config\.yaml$",
}

Custom Agent Example

Adding a custom agent (e.g., "designer"):

# 1. Add to valid agents
VALID_AGENTS = {"claude", "gemini", "codex", "human", "designer"}

# 2. Add ownership patterns
OWNERSHIP_MATRIX: Dict[str, str] = {
    # ... existing patterns ...

    # Designer - UI and styles
    r"^src/components/": "designer",
    r"^src/styles/": "designer",
    r"^src/.*/.*\.css$": "designer",
    r"^src/.*/.*\.scss$": "designer",
    r"^DESIGNER\.md$": "designer",
}

# 3. Update commit message pattern in check_commit_message()
pattern = r"^\[(Claude|Gemini|Codex|Human|Designer|CI)\]\s+\w+(\([^)]+\))?:\s+.+"

Testing Patterns

Test your patterns using Python:

import re

def test_pattern(pattern: str, test_paths: list) -> None:
    """Test a regex pattern against multiple paths."""
    for path in test_paths:
        match = re.match(pattern, path)
        print(f"{path}: {'MATCH' if match else 'NO MATCH'}")

# Example
test_pattern(r"^src/.*/cli\.py$", [
    "src/cli.py",           # NO MATCH (no subdirectory)
    "src/app/cli.py",       # MATCH
    "src/core/cli.py",      # MATCH
    "src/a/b/cli.py",       # MATCH
])

Debugging Tips

1. Pattern not matching?

   • Check for literal dots (use \. not .)
   • Verify start ^ and end $ anchors
   • Test with simple paths first

2. Pattern too broad?

   • Add more specific path components
   • Use $ to anchor end of pattern
   • Add file extension matching

3. Multiple agents matching?

   • First match wins
   • Order patterns from specific to general
   • Use more specific patterns for exceptions

---

Customize the ownership matrix for your specific project structure.