GigiKit Guides

File Ownership & Conflict Resolution

The single most common source of bugs in multi-agent teams is two agents editing the same file simultaneously. GigiKit prevents this through explicit glob-pattern ownership declared in every task description, backed by git worktrees for hard isolation.

Declaring Ownership

Every task description must include a File ownership: line that lists the glob patterns the agent is permitted to edit.

Task: Implement JWT authentication middleware.
File ownership: src/api/auth-middleware.ts, src/api/token-validator.ts, src/types/auth-types.ts

Do not edit any file outside these paths.
Work context: /path/to/project
Reports: /path/to/project/plans/reports/

Patterns follow standard glob syntax:

PatternMatches
src/api/*All files directly in src/api/
src/api/**All files in src/api/ and all subdirectories
src/api/*.tsOnly TypeScript files directly in src/api/
tests/unit/auth*All test files starting with auth in tests/unit/

Tester Agent Ownership

The tester is a special case: it reads any implementation file but owns only test files.

File ownership: tests/unit/auth*, tests/integration/auth*

Read-only access: src/api/auth-middleware.ts, src/api/token-validator.ts

Git Worktree Strategy

Git worktrees give each agent a fully isolated working directory on its own branch, eliminating the possibility of filesystem-level conflicts even if ownership rules are accidentally violated.

# Lead creates a worktree for each agent before the team starts
git worktree add ../project-feature-api   feature/api-layer
git worktree add ../project-feature-ui    feature/ui-layer
git worktree add ../project-feature-tests feature/tests

# Each agent works exclusively in its own worktree directory
# Agent 1: cd ../project-feature-api
# Agent 2: cd ../project-feature-ui
# Agent 3: cd ../project-feature-tests

Worktree cleanup

After the team’s work is merged, clean up worktrees:

git worktree remove ../project-feature-api
git worktree remove ../project-feature-ui
git worktree remove ../project-feature-tests
git worktree prune

Detecting Conflicts

An ownership conflict occurs when:

  • Two task descriptions include overlapping glob patterns
  • An agent needs to edit a file listed in another agent’s ownership
  • A shared utility file is required by multiple agents

Conflict detection checklist (lead’s responsibility)

Before starting a team session, the lead should:

  • List all File ownership: globs across all tasks
  • Run a glob overlap check — any file matched by two different tasks is a conflict
  • Resolve overlaps by splitting the file, moving logic, or assigning a single owner

Conflict Resolution Escalation

SituationResolution
Agent discovers it needs an unowned fileStop, message lead with file path and reason
Lead identifies two tasks share a fileRestructure tasks or absorb shared file into lead’s work
Conflict discovered mid-implementationAffected agent stops; lead decides which agent continues
Reviewers disagree on a contested changeLead synthesizes, documents disagreement, makes final call

Shared Files Strategy

Some files are genuinely shared — package.json, tsconfig.json, shared type definitions. Handle them with one of these patterns:

Pattern 1: Lead owns shared files. The lead edits shared files at the start of the session before agents begin, or at the end after agents complete.

Pattern 2: Designated single owner. Assign shared files to one specific agent and have other agents request changes via message rather than direct edit.

Pattern 3: Pre-agreed edits. Before the session, document exactly what each agent needs in the shared file. The lead or a single designated agent applies all changes at once.