Repository navigation
Building with AI Agents
Most of OpenBridge's code and documentation is written by AI coding agents, and we say so openly. This page explains how that works, the rules agents follow, and how to give an agent a good task. It is for anyone contributing with an AI tool, and for anyone who wants to know how the project keeps that work trustworthy.
The decision behind this setup is ADR-0002.
AGENTS.md is the one operating contract for every agent and
every person. It holds the non-negotiable rules, the commands, the standard workflow, and what
needs human approval. If two documents disagree, AGENTS.md wins, then the requirements in
.kiro/specs/openbridge/requirements.md,
then everything else.
Tool-specific files only point back to it:
-
CLAUDE.mdfor Claude Code; -
.github/copilot-instructions.mdfor GitHub Copilot.
Each file in .kiro/steering covers one topic. Front matter
tells tools that support it when to load the file. Any agent can read them as plain Markdown.
| Loaded | Files |
|---|---|
| Always |
product.md, tech.md, structure.md, engineering-standards.md, testing.md, git-and-review.md
|
| Engine, shared, data, scripts | eligibility-rules.md |
| Stores, save, forms, MCP, infra, workflows | privacy-security.md |
| Web app, end-to-end tests, PDFs | ui-i18n-accessibility.md |
| Only when asked |
grill-spec.md (an expert-panel review of a spec) |
The exact file patterns are in each file's front matter, and the "Topic standards" table in
AGENTS.md section 6 says which to read for which change.
Every agent follows the same loop (AGENTS.md section 4):
- Orient: restate the task and read the existing code.
- Check the spec: find the requirement the change serves.
- Plan small: one concern, no drive-by refactors.
- Test first for engine, adapter, crypto, or store logic.
- Implement to the engineering standards.
- Verify with
npm run verify(andnpm run e2efor UI changes). Never weaken a test to pass. - Document: README,
docs/, steering, wiki, andCHANGELOG.md. - Report what changed, what was verified, and anything uncertain, marked
ASSUMPTION:.
Agents must never invent rule values, mark an adapter verified, or send personal data off the
device. They propose, and wait for an explicit yes, before:
- changing a rule value, a threshold, or the outcome ladder;
- changing the privacy model, encryption, or save-file format;
- adding a runtime dependency or a major version upgrade;
- changing infrastructure, CI workflows, or deployment;
- editing the Terms of Use, disclaimers, referral policy, or license;
- deleting files, data, test cases, or tests;
- publishing, deploying, or pushing anything.
A human maintainer reviews every pull request before it merges, whoever wrote it.
Any commit an AI agent wrote or substantially drafted ends with a trailer naming the agent:
fix(engine): treat income at the limit as passing
Assisted-by: <agent or model name>
The pull request template also asks you to disclose AI help and confirm a human read every line.
A good task is small, specific, and checkable. Include:
- The goal in one or two sentences, and the requirement or issue it serves.
- Where to work: the package or files, and the files it must not touch.
- Sources for any rule value, as links. Without a source, tell the agent to leave the value alone and report the gap.
- How to check it: the commands to run and what "done" looks like.
-
A reminder to read
AGENTS.mdand the matching steering file first.
For example: "In data/states/oh/adapter.json, update wic.incomeLimitPct to match this USDA FNS
page (link, published date). Add a test case just under and just over the new limit. Leave the
adapter draft. Run npm run validate:adapters and npm run test:fixtures, then report."
Never paste real people's information into an AI tool or into the repository.
OpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers