Onboarding

First-run checklist for local use, agent setup, and CI

Use onboarding when you are adding Pastoralist to a repo for the first time or when you want a repeatable setup path for contributors and agents.

Start Read-Only

Check the current project without writing files:

npx pastoralist doctor

npx pastoralist doctor

Print the full checklist from the CLI:

npx pastoralist onboard

npx pastoralist onboard

Add Project Setup

Install Pastoralist and create the initial config:

npm install pastoralist --save-dev
npx pastoralist init

npm install pastoralist --save-dev
npx pastoralist init

Update the appendix once the config is in place:

npx pastoralist

npx pastoralist

Keep it current after dependency installs:

npx pastoralist --setup-hook

npx pastoralist --setup-hook

Add Agent Setup

Install only the bundled Pastoralist skill:

npx pastoralist --init agent-skill

npx pastoralist --init agent-skill

Preview local dev setup before writing files:

npx -p pastoralist pastoralist-setup-local-dev --dry-run

npx -p pastoralist pastoralist-setup-local-dev --dry-run

Set up agent config, bundled skills, and local hooks:

npx -p pastoralist pastoralist-setup-local-dev --skills all --hooks git,postinstall

npx -p pastoralist pastoralist-setup-local-dev --skills all --hooks git,postinstall

The local dev setup script auto-detects Codex or Claude when possible. You can pin the target explicitly:

npx -p pastoralist pastoralist-setup-local-dev --agent codex
npx -p pastoralist pastoralist-setup-local-dev --agent claude

npx -p pastoralist pastoralist-setup-local-dev --agent codex
npx -p pastoralist pastoralist-setup-local-dev --agent claude

Copy/Paste Prompts

Use this prompt when you want an agent to do the setup:

Set up Pastoralist in this repository.
Start with `npx pastoralist doctor` and inspect the current package manager setup.
Run `npx -p pastoralist pastoralist-setup-local-dev --dry-run` before writing files.
Configure the Pastoralist skill, local agent config, GitHub Action, and postinstall hook only when appropriate.
Keep changes scoped to setup files, docs, and tests.

Set up Pastoralist in this repository.
Start with `npx pastoralist doctor` and inspect the current package manager setup.
Run `npx -p pastoralist pastoralist-setup-local-dev --dry-run` before writing files.
Configure the Pastoralist skill, local agent config, GitHub Action, and postinstall hook only when appropriate.
Keep changes scoped to setup files, docs, and tests.

Use this prompt when you want an agent to review an existing setup:

Review this repository's Pastoralist setup.
Run `npx pastoralist --dry-run` and summarize stale overrides, security checks, and missing setup.
Do not remove overrides unless `npx pastoralist --remove-unused --dry-run` shows they are unused.
If setup is missing, propose the smallest script, skill, hook, or GitHub Action change.

Review this repository's Pastoralist setup.
Run `npx pastoralist --dry-run` and summarize stale overrides, security checks, and missing setup.
Do not remove overrides unless `npx pastoralist --remove-unused --dry-run` shows they are unused.
If setup is missing, propose the smallest script, skill, hook, or GitHub Action change.

Agent Setup Loop

Use this loop when an agent owns the setup:

Run npx pastoralist doctor.
Run npx -p pastoralist pastoralist-setup-local-dev --dry-run.
Apply the smallest needed setup command.
Run npx pastoralist --dry-run.
Report changed files and remaining manual steps.

Add CI

Create .github/workflows/pastoralist.yml:

name: Override Check
on: [pull_request]

jobs:
  pastoralist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: yowainwright/pastoralist@v1
        with:
          mode: check
          check-security: false

name: Override Check
on: [pull_request]

jobs:
  pastoralist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: yowainwright/pastoralist@v1
        with:
          mode: check
          check-security: false

Verify

Use these commands before merging setup changes:

npx pastoralist --dry-run
npx pastoralist --summary
npx pastoralist --checkSecurity

npx pastoralist --dry-run
npx pastoralist --summary
npx pastoralist --checkSecurity