Skip to main content

Worktree Assignment

Source: .agents/references/implementation/worktree-assignment.md

Content​

Worktree Assignment

Use this when assigning implementation tasks for .agents/skills/implement-feature/SKILL.md.

Tool Preference​

Prefer available platform tools:

  1. Codex subagent/worktree/thread tools when available.
  2. Native worktree tools exposed by the current environment.
  3. Manual git worktree fallback.

If the current workspace is already an isolated worktree, the master agent may keep final integration in that worktree for coordination only and create sibling worktrees for task workers. The master agent must not own feature-code write scopes.

Branch Naming​

Use clear branch names based on the source of work:

feat/<feature-name>/<task-id>
adhoc/<feature-name>/<task-id>
hotfix/<feature-name>/<task-id>

Use feat/ when the work comes from a PRD or a proper large feature brief. Use adhoc/ when no PRD was provided, such as a small task or one-off request. Use hotfix/ when it is related to product issue and it is a direct bug fix.

Examples:

  • feat/checkout-discounts/t1-ui
  • feat/community-profile/t2-service
  • feat/auth-routing/t3-tests
  • adhoc/auth-routing/t4-change
  • hotfix/apple-pay-fix/t5

If the user provides a branch naming convention, use it.

Worktree Naming​

Use predictable worktree paths:

<repo-worktree-root>/<feature-name>-<task-id>

Record the absolute worktree path in the master checklist.

Environment Files​

Every time an agent creates a new worktree for this repo, copy the source checkout's local environment files into the new worktree before running app commands. Copy only files matching .env and .env.*; do not copy unrelated dotfiles, and never commit the copied environment files.

Use the checkout where the worktree command was started as the source of truth for local env files:

rsync -av --include='.env' --include='.env.*' --exclude='*' ./ <absolute-worktree-path>/

After copying, verify the expected files exist in the new worktree. If no .env files exist in the source checkout, record that the env copy was skipped and pull or create env files only when the task needs them.

Ownership Rules​

Each task assignment must include:

  • Non-master owner/subagent name or ID
  • Worktree path
  • Branch name
  • Env files copied, skipped, or not needed
  • Allowed files/modules
  • Disallowed files/modules when relevant
  • Dependencies on other task IDs
  • Context references to load
  • Tests/checks to run
  • Conflict responsibility: task-scoped, ordered dependency, integration-only, or master-agent escalation

Workers must be told:

You are not alone in the codebase. Other workers may be changing adjacent files. Do not revert changes you did not make. Resolve conflicts only inside your assigned write scope. If a conflict touches another task's write scope, a shared file not assigned to you, or an integration decision, stop and report it.

Conflict Avoidance​

  • Do not assign parallel tasks that write the same file.
  • If shared files are unavoidable, create an ordered dependency.
  • If two tasks need the same broad component, merge them into one task.
  • Keep integration-only decisions with the master agent, but assign any repo-editing integration changes to a dedicated integration worker.
  • Each task owner is responsible for resolving conflicts caused by their own edits inside their assigned write scope.
  • A task owner must not resolve a conflict by deleting, reverting, or weakening another task's approved behavior.
  • If a conflict involves another task's write scope, the dependent task owner must report it and wait for master-agent direction instead of guessing.
  • If a conflict appears during final integration, the master agent assigns the resolution to the task owner whose behavior owns the conflicted logic, or to a dedicated integration worker when multiple approved behaviors must be combined.
  • Conflict resolution is not complete until the owner reruns the task's relevant checks and reports the files/conflicts resolved.

Conflict Responsibility Values​

Use one of these values in the master checklist:

  • task-scoped: worker resolves conflicts only in the assigned write scope.
  • ordered dependency: worker waits for the dependency task, updates from it, and resolves conflicts in the dependent write scope only.
  • integration-only: worker does not resolve conflicts; the master agent owns the decision, and any repo-editing resolution is assigned to a dedicated integration worker.
  • master-agent escalation: worker stops and reports any conflict because ownership is ambiguous or risky.

Manual Git Worktree Fallback​

When no platform worktree tool is available:

git worktree add <absolute-worktree-path> -b <branch-name>
rsync -av --include='.env' --include='.env.*' --exclude='*' ./ <absolute-worktree-path>/

If RTK is available, rtk git worktree add ... is also acceptable for compressed command output, but RTK is optional and must not be required for manual worktree creation. The env-file copy rule still applies after an RTK or platform-managed worktree is created.

Before creating project-local worktrees, verify the directory is ignored. Global or Codex-managed worktree directories do not need repo .gitignore edits.

Assignment Output​

Before implementation starts, the master agent must print or record:

## Worktree Assignments

- Task ID:
  - Owner:
  - Branch:
  - Worktree:
  - Env files:
  - Write scope:
  - Dependencies:
  - Conflict responsibility: