AGENTS.md · diff

git:20260930.1d16e9d to git:20260930.05b9808

44 added, 30 removed. Audit A to A.

# AGENTS.md - aigb-skills-usda

## Quick Start

- `git status --short --branch`

- `node -e "require('./package.json')"`

- `npm install` (or `make install`)

- - `npm test` (or `make test`)

+ - `npm run validate:skills`

+ - `npm run test:validate`

+ - `npm test` (or `make test`) for the maintainer smoke path

- `npx skills --help`

- `npx skills install --target ~/.agents/skills` (or `make install-skills`)

- ## Installing Skills (Users & Agents)

+ ## Find Things

+ - `bin/` -- executable shim for the `skills` CLI.

+ - `src/cli.js` -- public CLI command dispatch.

+ - `scripts/install.js` -- installs the packaged `skills/` tree.

+ - `scripts/sync-skills.js` -- maintainer-only materialization from upstream checkouts.

+ - `scripts/validate-skills.js` -- packaged-skill structural and selected behavioral validator.

+ - `scripts/validate-skills-test.js` -- validator regression tests.

+ - `scripts/smoke.js` -- broader maintainer smoke suite.

+ - `skills/` -- curated, materialized skill folders; source of truth for users and CI.

+ - `catalog/skills.lock.json` -- catalog entries and upstream provenance.

+ - `.github/workflows/ci.yml` -- Node matrix CI for packaged validation.

+ - `planning/` -- execution plans, wave states, task tracking, and prompt templates.

+ ## Workflows

+ ### Installing Skills (Users & Agents)

- **Primary off-ramp**: Pre-materialized skills live in `skills/`.

- - To install skills into your agent directory on any machine, run:

- - `npx skills install --target ~/.agents/skills` (or `~/.claude/skills`, `~/.pi/agent/skills`)

- - Or run `make install-skills`

- - **Do not run `skills sync` or `make sync` to install skills.** `sync` is a maintainer-only command that rebuilds `skills/` from upstream source checkouts.

+ - Install packaged skills with `npx skills install --target ~/.agents/skills` (or `~/.claude/skills`, `~/.pi/agent/skills`).

+ - Or run `make install-skills`.

+ - **Do not run `skills sync` or `make sync` to install skills.** Sync is maintainer-only and rebuilds `skills/` from upstream source checkouts.

- ## Maintainer Workflows

- - `npx skills sync --mode copy` (or `make sync`): Re-materializes `skills/` from external source repositories listed in `catalog/skills.lock.json`. Requires local source repo checkouts.

- - `npm run catalog:mine` (or `make catalog`): Regenerates catalog lockfile.

+ ### Maintainer Sync and Catalog

+ - `npx skills sync --mode copy` (or `make sync`) re-materializes `skills/` from repositories listed in `catalog/skills.lock.json`; local source checkouts are required.

+ - `npm run catalog:mine` (or `make catalog`) regenerates the catalog lockfile.

- ## Repo shape

- - `bin/` -- executable shims that expose CLI entry points.

- - `src/` -- CLI implementation layer (`install` and `sync` commands).

- - `skills/` -- curated and materialized skill folders (packaged source of truth for installations).

- - `catalog/` -- authoritative lockfile for upstream source repos.

- - `scripts/` -- installer (`install.js`), maintainer sync (`sync-skills.js`), history mining, and smoke check utilities.

- - `planning/` -- execution plans, wave states, task tracking, and prompt templates (untracked locally).

- - `Makefile` -- standard developer workflow targets (`make help`, `make install`, `make install-skills`, `make test`, `make sync`).

- - `README.md` -- public-facing overview and install guidance.

- - `LICENSE` -- MIT License at the repo root.

+ ### Validation

+ - CI runs `npm ci`, CLI help, and `npm run validate:skills -- --report .scratch/skills-report.json`.

+ - Packaged validation never clones, syncs, or accesses upstream/private repositories.

+ - `npm test` and `make test` retain upstream-dependent maintainer smoke coverage and may require sibling source checkouts.

+ - `npm run test:validate` tests validator success, structural failure, behavioral failure, and JSON reporting.

- ## Working conventions

+ ## Infrastructure

+ - Node.js `>=18` is required.

+ - `package.json` exposes the `skills` bin through `bin/skills.js`.

+ - `.scratch/` holds disposable validation reports and smoke artifacts; run `make clean` to remove it.

+ - If package metadata changes, run `node -e "require('./package.json')"` before validation.

+ - `Makefile` provides install, smoke, sync, catalog, and cleanup targets.

+ ## Working Conventions

- Keep the public package minimal, reliable, and functional.

- - `package.json` must parse cleanly and expose the `skills` bin.

- - The `skills install` command installs pre-bundled skills directly from `./skills` without external network or sibling repo requirements.

- - The `skills sync` command is strictly for maintainers with local checkouts of upstream source repositories.

+ - The `skills install` command installs pre-bundled skills directly from `./skills` without external network or sibling-repository requirements.

+ - The `skills sync` command is strictly for maintainers with local upstream checkouts.

- Multi-wave development and planning artifacts live under `planning/` following the `wave-orchestration` skill guidelines.

- Prefer small, verifiable changes that are easy to review and maintain.

- ## Validation

- - Favor the targeted smoke path: `npm install` followed by `npx skills --help` and `npm test`.

- - If a change affects package metadata, re-run `node -e "require('./package.json')"` before the smoke test.

## References

- - `catalog/skills.lock.json` -- authoritative lockfile for curated skills

- - `planning/` -- orchestration state, task DAGs, and execution plans

- - Reference repo: `D:\workspace\aigb-skills`

+ - `README.md` -- public install, CI, and maintainer-sync guidance.

+ - `catalog/skills.lock.json` -- authoritative lockfile for curated skills.

+ - `skills/*/SKILL.md` -- individual skill instructions and metadata.

+ - `planning/` -- orchestration state, task DAGs, execution plans, and prompt templates.

+ - Reference repo: `https://github.com/AndrewBrown-USDA/aigb-skills.git` (private maintainer repository).