Skip to main content
Different parts of a codebase need different things checked. A payments module wants the 3DS challenge exercised; an auth module wants session-fixation verified; the frontend wants an accessibility pass. Verification context lets your team author that guidance once, in the repo, and have IronBee surface only the parts relevant to what changed, injecting them straight into the agent’s context the moment it starts verifying. It’s advisory: the guidance reaches the agent as a first-class reminder alongside the standard verification flow, but it never blocks completion on its own.

​
Author guidance in .ironbee/VERIFICATION.md

Drop a Markdown file at .ironbee/VERIFICATION.md inside any directory whose changes need special attention: 
my-app/
├── .ironbee/
│   └── VERIFICATION.md          # repo-wide defaults
├── payment/
│   ├── .ironbee/
│   │   └── VERIFICATION.md       # payment-area guidance
│   └── stripe/
│       └── charge.ts
└── frontend/
    └── .ironbee/
        └── VERIFICATION.md       # frontend-area guidance
The file is plain prose. Write whatever you’d tell a teammate before they verify a change in that area: 
# Payment verification

- Exercise the 3DS challenge flow end-to-end, not just the happy path.
- Confirm a declined card surfaces the retry UI, not a 500.
- Check that the idempotency key prevents a double charge on retry.
The file name is the fixed convention .ironbee/VERIFICATION.md; it isn’t configurable. The .ironbee/ folder is the same namespace that holds the project’s config.json at the repo root, so area guidance lives alongside it consistently. These files are meant to be committed and reviewed in PRs; only sessions/ and config.local.json are gitignored.

​
How guidance is matched to a change

When a verification cycle begins, IronBee looks at what changed this cycle, then for each changed file walks up from its directory to the project root, collecting every .ironbee/VERIFICATION.md it finds along the way: 
Changed:  payment/stripe/charge.ts
Collects: payment/stripe/.ironbee/VERIFICATION.md   (if present)
          payment/.ironbee/VERIFICATION.md          (if present)
          .ironbee/VERIFICATION.md                  (repo-wide default, if present)
  • Nearest-parent hierarchy: a change picks up its own area’s guidance plus everything above it. Directories without a file are simply skipped.
  • Merged general → specific: the repo-wide default reads first, area-specific guidance after it.
  • Deduplicated: if ten files under payment/ changed, payment/.ironbee/VERIFICATION.md is included once.
  • Always includes the changed-path list: even when no .ironbee/VERIFICATION.md matches, IronBee still injects the list of paths that changed this cycle (capped at 100, with a +N more for the rest). This gives the delegated verifier a head start on what to exercise instead of discovering it from scratch. Authored guidance, when present, is appended on top.

​
An always-on instruction (verification.context.message)

The .ironbee/VERIFICATION.md files are path-scoped — they only reach the verifier when a change touches their directory. For a standing instruction that should accompany every verification cycle regardless of what changed, set verification.context.message: 
ironbee config set verification.context.message "Confirm the health endpoint returns 200 before passing."
This is injected into every cycle unconditionally — even a manual /ironbee-verify with no code changes, where the changed-path list and path-scoped docs would otherwise be empty. It’s rendered first, ahead of any matched VERIFICATION.md guidance, and is never truncated (it reserves its own bytes so the maxBytes cap still bounds the path-scoped docs). Two value forms:
  • Inline text the message itself.
  • A file reference file:<path>, read at verification time. The path is relative to the project dir; a leading ~ expands to your home directory; a missing or unreadable file is silently skipped.
ironbee config set verification.context.message "file:.ironbee/verify-checklist.md"
Like the rest of the context keys, it’s layered across global / project / local (the highest layer that sets it wins) and read live, so a change takes effect on the next session.

​
What counts as “changed”

By default the changed set comes from git: your uncommitted work (working tree: staged, unstaged, and untracked files) plus the last commit. In a non-git project, IronBee falls back to its own file_change events for the current cycle.
  • ignoredVerifyPatterns filter the set — test files are excluded by default, and anything you add filters out build/docs churn too, so it doesn’t pull in guidance.
  • IronBee’s own .ironbee/ tree is always excluded.
  • commitDepth controls how many recent commits join the working tree: 1 (default) covers in-flight work plus the latest commit, 0 is uncommitted-only, and you can raise it for teams that commit per logical step.

​
When it’s injected

The guidance is injected on the first verification tool call of each cycle (exactly when the agent starts verifying) and once per cycle (re-verifying after a fix gets a fresh read of what changed). It arrives through each client’s native context channel, so the agent treats it as a binding reminder, not incidental output.
ModeInjects?
Assist (default)Yes, manual /ironbee-verify cycles get the guidance too
EnforceYes
Monitoring-onlyNo, monitoring installs no verification hooks
It is advisory in this release: the agent must follow the guidance as part of its verification, but the content itself never gates completion. (Machine-checkable per-area rules are planned separately.)

​
Configuration

The feature is on by default. Tune it under the verification.context key. See Configuration → Verification context for the full table. The common knobs: 
ironbee config set verification.context.enable false      # turn it off entirely
ironbee config set verification.context.commitDepth 0     # uncommitted work only
ironbee config set verification.context.source actions    # skip git, use IronBee's own file_change events
These keys are read live at verification time, so a change takes effect on the next session without re-rendering client artifacts.
.ironbee/VERIFICATION.md is repo content at the same trust level as CLAUDE.md or AGENTS.md; the agent follows whatever it says. Review changes to these files in PRs as you would any other instruction your agent reads.

​
What’s next?

Verification

Choose which platforms get verified and switch between enforce, assist, and monitoring.

Configuration

The full verification.context key reference.