Agent boundary

Agent Boundary

Use this skill before and during parallel coding work. The goal is not to orchestrate agents. The goal is to prevent unclear ownership, same-file edits, and unsafe integration.

Core Workflow

1. Define the batch goal and success criteria.
2. Create or update an ownership manifest before workers start.
3. Assign each worker a disjoint write scope.
4. Reserve integration hotspots as leader_only.
5. Run the bundled checker before spawning workers.
6. Generate worker prompts from the manifest.
7. Validate each returned diff against the worker scope.
8. Let the leader integrate leader-only files after worker work returns.
9. Freeze and re-scope if ownership drift appears.

Bundled Files

• scripts/agent_boundary.py: dependency-free manifest and diff checker.
• templates/ownership.json: starter ownership manifest.
• references/manifest-format.md: manifest fields and rules.
• references/claude-code.md: Claude Code hook and workflow guidance.

Load a reference only when needed.

Create A Manifest

Prefer a small JSON manifest in the target repo, such as:

.agent-boundary/ownership.json

Start from templates/ownership.json, then edit:

• batch: short batch name.
• leader: lead agent/session name.
• leader_only: files or globs workers must not edit.
• owners: worker names with owns globs and validation commands.
• merge_gate: review and test expectations.

If the target repo already has a manifest, update it instead of creating a second competing source of truth.

Check Ownership

From the target repo:

python path/to/agent-boundary/scripts/agent_boundary.py check \
  --manifest .agent-boundary/ownership.json \
  --repo .

Use --repo . when the repo already has tracked files and you want resolved overlap checks against actual paths. Without --repo, the checker still catches invalid fields and exact duplicate patterns.

Generate Worker Prompts

Each worker prompt should include:

• batch name
• owned file globs
• leader-only files
• deliverable
• validation commands
• instruction to stop if a leader-only hook is needed
• instruction to report unexpected changes in owned files

Keep prompts concrete. Do not ask a worker to "help wherever needed" during a parallel batch.

Validate Returned Work

Before accepting a worker's changes:

python path/to/agent-boundary/scripts/agent_boundary.py diff \
  --manifest .agent-boundary/ownership.json \
  --agent dev-api \
  --from-git main \
  --repo .

Use --files instead of --from-git when validating an explicit file list.

Drift Handling

Ownership drift includes:

• a worker edited leader-only files
• a worker edited files owned by another worker
• two workers claim overlapping file scopes
• a returned diff contains unowned files

When drift appears:

1. Stop the affected parallel work.
2. Preserve the dirty diff if salvage is useful.
3. Decide whether to integrate, discard, or re-scope the change.
4. Rewrite the manifest before restarting work.

Do not continue parallel implementation while ownership is ambiguous.

Claude Code

For Claude Code dynamic workflows, agent teams, or subagents, use this skill as the ownership layer. Claude Code can orchestrate agents; this skill supplies the file-scope contract and diff guard. See references/claude-code.md when wiring hooks or writing workflow prompts.