---
title: "Work across packages and Git worktrees Docs"
source: https://docs.autohand.ai/guides/monorepo-workflows
---

# Work across packages and Git worktrees

A monorepo workflow scopes an Autohand Code task to the packages that own the behavior and the consumers affected by its contract. Use repository instructions and package-specific validation to avoid unrelated edits. A Git worktree provides a separate working directory and branch for a task on the same repository.

## Find the owning package

Start from the reported endpoint, exported function, screen, or failing command. Ask the agent to identify the owning package, its public exports, the test runner, and direct consumers before editing.

```text
Find the package that owns task filtering and its direct consumers.
Read repository instructions and package scripts. Do not edit yet.
Show the exported contract, current tests, and which consumer checks
would detect a compatibility regression.

```

A green package test does not prove all consumers remain compatible. A shared type, schema, or event change may require a consumer build or integration check.

## Define an explicit scope

| Change | Initial scope | Additional evidence |
|---|---|---|
| Internal helper fix | Owning package and focused tests | Existing public behavior remains intact |
| Exported type change | Library plus direct consumers | Consumer type checking and builds |
| API response change | Producer and clients | Request/response compatibility tests |
| Build tooling change | Workspace configuration | Relevant package builds under the new configuration |

Record the validation commands from the repository itself. Workspace managers differ, so do not copy a filtering flag from another package manager without checking the local scripts.

## Separate a task with a worktree

Check the repository state, then start an isolated session using the CLI's supported worktree option:

```bash
git status --short
autohand --worktree task-filter

```

See [worktrees](https://docs.autohand.ai/working-with-autohand-code/worktrees) for naming and lifecycle behavior. Dependencies, local environment files, and services may need separate setup in the new directory. Do not assume uncommitted changes from the original worktree are present.

Give each concurrent task clear file ownership. Two branches changing the same public interface still need integration and conflict resolution, even when their working directories are separate.

## Integrate with evidence

Review the task diff and compare its changes to the current target branch. Resolve overlapping changes using the intended behavior from both branches. Then rerun the checks affected by the combined result. Tests run before conflict resolution do not validate the resolved files.

```text
Review this task's changed files against the package scope.
List changed exports and affected consumers. Run the owner tests and
consumer checks identified in the plan. Report any integration checks
that require services not available locally.

```

## Troubleshooting and checkpoint

If a worktree cannot start, confirm you are inside a Git repository and consult the reported branch/path error. If tests pass only in the original checkout, compare dependencies, ignored files, and service configuration. The task is complete when the reviewed combined change passes its owner and consumer checks. Continue with [reliable automation](https://docs.autohand.ai/guides/reliable-automation) for repeatable validation.

## Frequently asked question

### Are owner-package tests enough for a shared API change?

Owner tests cover the assertions they exercise. For shared contracts, identify direct consumers and run the relevant consumer type checks, builds, or integration tests against the combined change.