Docs · Coding agents
How coding agents use FeatureParity
Claude Code, Codex, Cursor and any other agent that can run a shell command work with FeatureParity through the fp CLI. The agent reads the requirements before it writes code, drafts new or changed requirements for a person to approve, tags its tests, and reports what it did. Only your CI can mark a requirement as passing.
Set up once per repository
A person mints an agent key on the Agents & API keys page of their account. The key acts for that person: it reaches every project they are a member of, and it can never approve its own work. Then, in the repository:
gem install featureparity # installs the fp CLI
export FP_API_KEY=fp_your_key_here
fp init --project your-project # writes .featureparity.yml, a CI gate and agent instructionsfp init adds instructions to the repository's agent docs (such as AGENTS.md or CLAUDE.md), so every session starts by checking the requirements. See the install guide for other ways to install the CLI.
The loop an agent follows on every task
- Read the requirements first.
fp listshows the active requirements,fp list --status draftshows proposals waiting for review, andfp list --gapsshows requirements with no evidence yet.fp show <slug>prints one requirement's acceptance criteria and its evidence on each platform. - Propose what is missing; don't invent it in code. If nothing covers the work, the agent runs
fp propose, which always creates a draft. If a requirement is wrong or out of date, it runsfp propose-change. The change is applied, the requirement drops back to draft, and a person approves or rejects it. Rejecting restores the old wording exactly. - Tag the test that proves it. A comment directly above the test binds it to the requirement:
Add# fp:reset_password it 'emails a reset link to a registered address' do@web,@iosand so on to say which platforms a test covers, for example// fp:reset_password@android. - Report, then check.
fp report --junit junit.xml --surface webrecords the tagged tests aspresent(tagged, but not yet run in CI).fp checkexits non-zero when the project falls below the parity level the team chose, and lists next steps.
Why an agent can't mark its own work as passing
Agents can report present or stub. Only fp ci-report, run by your CI with its own key, writes passing or failing. A pull request's run shows as pr_passing until it merges. So a green cell means the tagged test ran in CI on the default branch, not that an agent said it was done.
On a pull request, fp check --junit junit.xml --pr judges the branch against the default branch. It fails on regressions the branch introduces, including a deleted or renamed test whose fp: marker vanished, and doesn't blame the branch for gaps it inherited.
What this doesn't do
- FeatureParity doesn't run your tests. Your CI does; FeatureParity records the results.
- A passing cell proves only what the tagged test checks. Weak tests make weak evidence.
- Agents can't approve requirements or changes. Someone on the team has to read and decide.
- Markers are matched by slug. A test with a mistyped slug is reported as an orphan, not as coverage.