Prepare repositories for task worktrees

alterac.ai requires each task to be implemented in its own linked Git worktree. Linked worktrees are a built-in Git feature: each task gets its own branch and working directory while the retained checkout stays available for alterac.ai. That lets multiple task agents work at once without editing the same checkout.

A linked worktree starts from tracked content at the selected Git commit. Tracked source, lockfiles, checked-in configuration examples, and repository scripts are available. Ignored or machine-local inputs from the retained checkout do not carry over. Common examples include installed dependencies, build output, .env files, local certificates, secrets, editor state, and untracked databases.

Do not copy credentials or other secrets into tracked files to make setup convenient. Prefer your repository's existing secret manager, environment injection, or documented local provisioning path. If an agent cannot obtain a required input safely, it should report the missing prerequisite instead of inventing or copying one.

No special worktree tool is required. If your repository needs ignored dependencies or generated local files, run its normal setup in the new worktree just as you would for another fresh checkout. For example, a repository that normally uses pnpm can run:

pnpm install

Use your repository's existing instructions and package manager; the command is only an illustration.

Git hooks and wrapper scripts can run from different linked working directories. Resolve paths from the hook or invocation context instead of embedding the retained checkout's absolute path.

For example, a hook can ask Git for the current worktree root:

repository_root="$(git rev-parse --show-toplevel)"
"$repository_root/scripts/check-before-commit.sh"

Choose the context appropriate to your hook manager and Git hook. The important boundary is that repository automation must not assume every task runs from one fixed directory.

Two worktrees may run at the same time. Give each one distinct repository-defined ports, service names, databases, caches, containers, or other mutable namespaces when the tools cannot safely share them.

For example, an existing local launcher can derive a safe identifier from the task branch:

workspace_id="$(git branch --show-current | tr '/.' '-')"
./scripts/start-local.sh --name "$workspace_id" --allocate-port

In this illustrative interface, the repository launcher reserves and reports a port for that workspace instead of reusing one fixed host port. Your repository decides how to allocate and release these resources. alterac.ai does not provision, supervise, or clean them up.

Run project-scoped alterac.ai CLI commands from the retained main checkout, where .alterac-ai machine-local state was initialized. Implementation, tests, commits, and delivery happen in the task worktree.

When an alterac.ai command accepts a file created in the worktree, pass its absolute path. For example:

alterac-ai work-run complete 00000000-0000-0000-0000-000000000000 \
  --summary-file /path/to/repository/worktrees/301-example/summary.md \
  --hand-off-file /path/to/repository/worktrees/301-example/hand-off.md

This keeps project selection and local approval state anchored to the initialized checkout without confusing worktree-owned files with retained-checkout files.

alterac.ai does not remove task worktrees or branches. Never have an active work-run agent remove the worktree in which it is running.

Remove a task worktree only after the task is Done, no follow-up work is expected, and the branch is no longer needed under your repository's delivery policy. Repository owners decide whether cleanup is manual or automated and remain responsible for any associated services, databases, caches, and other local resources.

For initialization problems or missing local inputs, use repository setup troubleshooting. To understand command launch approval and coding-agent permissions, read command trust modes.