# Monorepo Harness Notes

Use this reference when the repository contains multiple apps, packages, crates, or services.

## What to map clearly

- workspace root vs package roots
- shared libraries vs deployable apps
- root-level commands vs package-level commands
- ownership or responsibility boundaries between packages
- which decisions are global vs package-local

## Common risks

- root-level commands may not validate a specific package well
- agents may edit shared packages when a package-local change is safer
- build, lint, and test commands may vary by package manager, workspace tool, or package type
- one package may require a spec, ADR, or risk note even when the rest of the repo does not
- status can become ambiguous when several packages move in parallel

## Good harness patterns

- include a short workspace map
- show how to run commands for one package or crate
- define allowed scope for a task
- prefer targeted validation for the touched package first
- record cross-package rules in a durable place
- use specs or status docs for multi-package migrations or coordinated refactors

## Artifact guidance

In monorepos, keep the top-level working guide short. Push detail into focused supporting artifacts when needed:

- project map for workspace layout and boundaries
- task contracts for per-package scope
- ADRs for cross-cutting decisions
- status docs for migrations spanning several packages

Do not duplicate every package's README into the harness.