# agent-workflow-primitives docs

This crate owns local-first agent workflow primitive binaries. Keep crate-specific specs, runbooks, and reports here; keep workspace-wide
completion, release, and new-crate rules in the root `docs/` tree.

## Binary overview

- `agent-run`: project command execution through normalized direct or direnv
  environment decisions.
- `docs-impact`: Git change classification for docs impact review.
- `canary-check`: redacted local canary command records.
- `review-evidence`: review finding and validation evidence records.
- `review-specialists`: deterministic specialist finding validation, merge,
  render, bundle, and Git diff scope classification.
- `browser-session`: browser-session goal, step, and artifact records.
- `model-cross-check`: cross-model observation records without provider calls.
- `repo-retro`: repo-local implementation retrospectives from local Git,
  HEURISTIC_SYSTEM records, and explicit JSONL inputs.
- `skill-usage`: skill invocation, linked evidence, validation, outcome, and
  failure handling records.
- `test-first-evidence`: failing-test, waiver, and final-validation evidence
  records.

## `agent-run` examples

```bash
agent-run exec --cwd . -- cargo test
agent-run exec --cwd . --direnv require -- npm test
agent-run doctor --cwd . --format json
agent-run env --cwd . --format json
```

`agent-run` keeps successful `exec` output unwrapped and exposes environment
decisions through `doctor` and `env` status surfaces. `.envrc` execution uses
`direnv exec`; bare `.env` execution uses `direnv dotenv json` when `direnv`
does not report the file as a loadable RC. It never runs `direnv allow`.

## `repo-retro` examples

```bash
repo-retro report --repo . --days 7 --mode team --format json
repo-retro report --repo . --mode maintainer --format markdown
repo-retro report --repo . --from 2026-05-11 --to 2026-05-17 \
  --history-dir "$HOME/retro-history" --write
```

## Specs

- None yet. Add documents under `docs/specs/` and register them here.

## Runbooks

- Workspace runbook: `docs/runbooks/review-specialists-primitive.md`.

## Reports

- None yet. Add documents under `docs/reports/` and register them here.

## Links

- Back to crate README: [`../README.md`](../README.md)
