# Examples & use cases

Real, end‑to‑end runs and the [focus](/docs/focus) that drove them. Each shows
the pattern, a focus you can copy, and what it produces. Use these as starting
points — adapt the specifics to your repo.

## Batch‑add catalog content (additive)

**Pattern:** grow a catalog — plugins, fixtures, examples, sample configs — by N
new entries per run, without touching anything that already exists. Pairs well
with a persistent [objective](/docs/objectives) (e.g. "8000 plugins") so the
[scheduler](/docs/scheduling) keeps making progress run after run.

**Focus:**

```
OBJECTIVE: Add exactly 5 NEW plugins to the plugin catalog.

Each plugin is a NEW directory under plugins/<name>/ containing a plugin.json
that follows the EXACT schema of existing plugins — inspect any existing
plugins/*/plugin.json first to match the format precisely.

Pick 5 distinct, real, useful tools NOT already present under plugins/ — verify
each target directory does NOT already exist before creating it. Do NOT modify
or delete any existing entry; keep the change strictly additive. Deliver a
single PR titled "feat: add 5 new plugins".
```

**Produces:** one PR, strictly additive — e.g. five new plugin directories
(`frawk`, `slumber`, `vgrep`, `xplr`, `zenith`), 15 files, 0 deletions, nothing
outside the new folders touched. The [team](/docs/teams-and-models)'s reviewer
checks the diff stays on‑objective before it opens.

**Why it works:** an exact count, an explicit "additive only" constraint, and
"verify it doesn't already exist" keep the agent from drifting or duplicating.

## Add one focused test

**Pattern:** raise coverage one honest test at a time — small, mergeable,
low‑risk. Good as a scheduled background drip.

**Focus:**

```
Add ONE unit test for an untested or under-tested function. Pick the function,
write a single focused test that asserts real behaviour (not a tautology), make
it pass, and commit. Don't refactor the code under test.
```

**Produces:** a tiny PR adding one test file or case. Pair with a
[verify command](/docs/verification-gate) (`go test ./...`, `npm test`) so the
run only ships when the suite is green.

## Safe dependency bump

**Pattern:** keep dependencies current without breakage risk.

**Focus:**

```
Update ONE outdated dependency safely — minor or patch only, NO major versions.
Update the manifest + lockfile, run the build and tests, and commit only if
everything passes.
```

**Produces:** a single‑dependency PR with the lockfile updated and the gate
green. See [Playbooks](/docs/playbooks) for a ready‑made version of this.

## Resolve a specific GitHub issue

**Pattern:** point AM at one issue and let it open a fix PR. With
[Issue solving](/docs/issue-solving) enabled, AM can pick issues on its own; you
can also target one directly.

**Focus:**

```
Fix GitHub issue #123. Read the issue and reproduce the problem, make the
smallest change that resolves it, add a regression test, and reference the issue
in the PR description.
```

**Produces:** a focused fix PR linked to the issue. Set an
[acceptance command](/docs/objectives) when "fixed" is mechanically checkable.

## Documentation pass

**Pattern:** improve docs without changing behaviour — safe to auto‑merge on
higher trust.

**Focus:**

```
Improve documentation quality only — READMEs, module docs, doc comments, typos.
Do NOT change code behaviour. Pick ONE under-documented area and expand it.
```

**Produces:** a docs‑only PR. Because there's no behaviour change, it's a good
candidate for [auto‑merge](/docs/auto-merge) once you trust the repo.

## Tips that apply to all of these

- **Bound the run.** An exact count or a single named target beats "improve X".
- **Constrain the blast radius.** "Strictly additive", "don't modify existing",
  "minor/patch only" keep diffs reviewable.
- **Gate it.** A [verify command](/docs/verification-gate) turns "looks done"
  into "is correct".
- **Make it persistent.** For ongoing work, set an [objective](/docs/objectives)
  and a [schedule](/docs/scheduling) so runs repeat without you re‑triggering.

## Related

- [Focus](/docs/focus) · [Playbooks](/docs/playbooks) · [Objectives](/docs/objectives)
- [Teams & models](/docs/teams-and-models) · [The Verification Gate](/docs/verification-gate)