# Workflow guide
Start with the task you want to perform. The lower-level evidence protocol is automatic.
| Security audit | `oy audit` | `ISSUES.md` |
| Code-quality review | `oy review` | `REVIEW.md` |
| Review current work against a ref | `oy review main` | `REVIEW.md` |
| Fix one finding | `oy enhance <finding-id>` | source changes |
The same workflows are available inside OpenCode or Cursor as `/oy-audit`, `/oy-review`, and `/oy-enhance`.
## Choose what to review
### Audit scope and focus
```bash
oy audit # workspace
oy audit src/auth # one existing path
oy audit "authentication boundaries" # focus text
oy audit --out reports/security.md
oy audit --format sarif --out oy.sarif
```
When the audit receives exactly one argument and it names an existing workspace-relative file or directory, that path becomes the collection scope. Other text guides the model without narrowing collection.
### Review scope and focus
```bash
oy review # workspace
oy review main # git diff main
oy review HEAD~3 --focus "error handling"
oy review main --out reports/review.md
```
A positional branch, commit, tag, or ref selects target-diff review. `--focus` adds review guidance and can be repeated.
Review findings are intentionally sparse. The reviewer prefers concrete structural issues—unclear ownership, unnecessary complexity, weak boundaries/types, expensive dependencies, or files needing meaningful decomposition—over generic advice.
## Read a report
Markdown reports contain:
- a verdict or summary;
- detailed evidence-backed findings;
- a machine-readable `oy-findings` JSON block;
- generation and evidence metadata.
Each finding has a stable ID, severity, status, location when available, evidence, and remediation guidance. Common statuses are `new`, `carried-forward`, `fixed?`, and `stale`.
A no-findings report is a successful result, not a failed run. Check the command exit status and generated metadata when distinguishing the two.
Treat findings as candidates until a person confirms the evidence and impact.
## Fix and confirm one finding
```bash
oy enhance audit-0123456789abcdef
oy enhance review-0123456789abcdef
```
`oy enhance` reads `ISSUES.md` or `REVIEW.md`, confirms the cited source, fixes one actionable finding, and runs focused verification. Use `--interactive` when you want OpenCode `mini` to show native permission prompts, questions, and forms:
```bash
oy enhance --interactive review-0123456789abcdef
```
Then rerun the originating command:
```bash
oy audit
oy review main
```
The new report replaces the old generated report, carries forward findings that still apply, and drops stale ones.
## What happens under the hood
Audit and review follow four stages:
1. **Prepare** — collect eligible workspace files or a target diff into ordered chunks under `.oy/runs/<run-id>/`.
2. **Review** — the agent host reads every prepared chunk under your current model and permissions.
3. **Verify** — reject changed inputs, modified evidence, concurrent output changes, or malformed finding data.
4. **Finalize** — write normalized Markdown or SARIF.
> Collection and report normalization are deterministic. Model findings and prose are not.
Advanced automation can call `oy audit|review prepare` and `finalize` directly; most users should not need those commands.
## Coverage and limits
The default limit is 80 evidence chunks. If preparation exceeds it, oy fails instead of silently sampling. Narrow the path first; increase `--max-chunks` only when the broader scope is intentional.
The workspace collector excludes:
- gitignored and hidden paths;
- `.git`, `.oy`, `target`, `node_modules`, `.venv`, and `.tmp`;
- common lockfiles, generated reports, likely secrets, and private-key formats;
- binary, non-UTF-8, empty, unreadable, and larger-than-512-KiB files.
These exclusions reduce accidental disclosure and context waste, but they also limit completeness. In particular, an oy audit is not a complete supply-chain audit because lockfiles are excluded.
Eligible large files and diffs are split into bounded chunks. Prepared source may be sent to the model provider configured in the selected agent host.
## Practical guidance
- Begin with a small scope and inspect the first report.
- Narrow by path before raising `--max-chunks`.
- Use a model with reliable tool use and sufficient context.
- Do not rely on secret-like filenames as a security boundary.
- Keep generated reports private when their findings or paths are sensitive.
- Pin `OY_OPENCODE_MODEL=provider/model#variant` when comparing repeat runs.
See [Examples and CI](examples.md) for representative output and SARIF upload.