Monorepo Task Harness

# Monorepo Task Harness

A Claude Code project configuration for running build and test tasks scoped to the packages
affected by a change in a monorepo.

## What it does

When this harness is active, Claude Code acts as a monorepo task orchestrator. It computes
which packages are affected by the current change, builds the dependency graph between them,
and runs only the necessary tasks in the correct order — using cached outputs wherever
possible.

- **Affected detection:** Claude uses `git diff` to identify changed files, maps them to
  packages, and follows the dependency graph to include any downstream packages that must
  be rebuilt or retested.
- **Task graph:** Claude makes the dependency order explicit — if `pkg-b` depends on
  `pkg-a`, it builds `pkg-a` first, regardless of the order packages appear in the workspace.
- **Caching:** Claude checks for existing build outputs (dist/, .turbo/, .nx-cache/) before
  running a task, and skips any package whose inputs have not changed since the last run.
- **Tool focus:** The `settings.json` scopes bash to monorepo toolchains (Turborepo, Nx,
  Lerna, pnpm workspaces) and read-only git.

## Files in this harness

| File | Purpose |
|------|---------|
| `README.md` | This guide — Claude reads it as its working instructions |
| `settings.json` | Claude Code project settings — copy to `.claude/settings.json` |

## Setup

1. Copy `settings.json` to `.claude/settings.json` in your project root.
2. Open your project in Claude Code.
3. Tell Claude which monorepo toolchain you use and where packages live, e.g.:
   "We use Turborepo. Packages are in `packages/` and apps in `apps/`."

Claude will read the workspace manifest and build an internal dependency map for the session.

## Workflow reference

### Finding affected packages
Tell Claude: "Which packages are affected by the changes on this branch?"

Claude will run `git diff` against the base branch, map changed files to package roots,
and traverse the dependency graph to list every package that needs to be rebuilt or retested.

### Running affected tasks
Tell Claude: "Build and test only the affected packages."

Claude will:
1. Compute the affected set.
2. Order tasks by dependency (topological sort).
3. Skip packages with unchanged inputs and valid cached outputs.
4. Run build then test for each remaining package, in order.
5. Report the per-package result and total time saved by cache hits.

### Visualising the task graph
Tell Claude: "Show me the task graph for this change."

Claude outputs a dependency tree showing which packages run in which order, which are
cached, and which are the critical-path bottlenecks.

## Example output

```
Affected packages (4 of 12):
  pkg-utils    ← changed directly
  pkg-api      ← depends on pkg-utils
  pkg-client   ← depends on pkg-api
  app-web      ← depends on pkg-client

Task graph (build → test):
  pkg-utils    build ✓ (cache hit)   test ✓ (cache hit)
  pkg-api      build ✓ (ran 4s)      test ✓ (ran 12s)
  pkg-client   build ✓ (ran 6s)      test ✓ (ran 8s)
  app-web      build ✓ (ran 22s)     test ✓ (ran 15s)

Cache saved: ~68s  Total: 67s
```

## Commands

- `/affected` — Compute and list the packages affected by the current branch's changes,
  including downstream dependents.
- `/task-graph` — Show the dependency graph for the affected packages: order, critical
  path, and which tasks will be cache hits.
- `/cache-status` — Report which packages have valid cached outputs and which need a
  fresh run based on current file hashes.

## Allowed bash commands

The harness permits monorepo toolchain commands and read-only git:

- `Bash(npx turbo*)`, `Bash(turbo*)` — Turborepo task runner
- `Bash(npx nx*)`, `Bash(nx*)` — Nx task runner
- `Bash(pnpm run*)`, `Bash(pnpm --filter*)` — pnpm workspace commands
- `Bash(lerna*)` — Lerna lifecycle commands
- `Bash(npm run*)` — fallback workspace scripts
- `Bash(git diff*)`, `Bash(git status*)`, `Bash(git log*)` — change detection

Destructive commands and remote pushes are blocked.

## Known limitations

- Affected detection relies on `git diff` against the base branch; detached-HEAD states
  may need you to tell Claude the comparison ref explicitly.
- Remote caching (Turborepo Remote Cache, Nx Cloud) is not configured by this harness;
  it handles local caching only.

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(**)",
      "Edit(**)",
      "Bash(npx turbo*)",
      "Bash(turbo*)",
      "Bash(npx nx*)",
      "Bash(nx*)",
      "Bash(pnpm run*)",
      "Bash(pnpm --filter*)",
      "Bash(lerna*)",
      "Bash(npm run*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git log*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(git restore*)",
      "Bash(git clean*)",
      "Bash(rm -rf*)"
    ]
  }
}