pastoralist git:20260830.3a7f15aA

Immutable. This exact content is served forever at /api/v1/blob/46d53d0c774cab3a.

---
name: pastoralist
description: >
  Use when setting up, running, or maintaining Pastoralist override tracking,
  security checks, install hooks, GitHub Actions, or dependency override docs.
---

# Pastoralist

Start with `npx pastoralist onboard` when setting up a repo.
Use `npx pastoralist doctor` for read-only project health.
Run `pnpm run setup:local-dev -- --dry-run` before setup writes.
Use `npx pastoralist init` to create config.
Config can live under `package.json#pastoralist` or as top-level settings in `.pastoralistrc`, `.pastoralistrc.json`, `pastoralist.json`, or `pastoralist.config.*`.
Use `npx pastoralist` to update the override appendix.
Use `npx pastoralist --setup-hook` to keep the appendix current after installs.
Use `npx pastoralist --checkSecurity` for advisory checks.
Use `npx pastoralist --remove-unused` only after reviewing dry-run output.

## User-Owned Best-Case Overrides

When best-case selection conflicts with an override the user controls, show the
active version and the appendix ledger `addedDate`, then ask whether the package
should be user-owned. Do not infer ownership from the date. Persist approved
package names in `pastoralist.bestCase.userOwnedOverrides`; the active override
supplies the required version.

```json
{
  "overrides": {
    "alpha": "2.5.0"
  },
  "pastoralist": {
    "bestCase": {
      "enabled": true,
      "userOwnedOverrides": ["alpha"]
    },
    "appendix": {
      "alpha@2.5.0": {
        "ledger": {
          "addedDate": "2026-08-09T00:00:00.000Z"
        }
      }
    }
  }
}
```

User-owned versions win. Re-run the security check so the complete portfolio is
evaluated with those versions as hard constraints.

## Agent Setup

Prefer the packaged setup script for agent config and skills:

```bash
pnpm run setup:local-dev -- --agent codex --skills all --hooks git,postinstall
```

If only the skill is needed:

```bash
npx pastoralist --init agent-skill
```

## Agent Loop

1. Run `npx pastoralist doctor`.
2. Run `pnpm run setup:local-dev -- --dry-run`.
3. Apply the smallest needed setup command.
4. Run `npx pastoralist --dry-run`.
5. Report changed files and remaining manual steps.

For CI, add `yowainwright/pastoralist@v1` to a pull request workflow.
Keep secrets in environment variables, not config files.