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 instructions

fp 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

  1. Read the requirements first. fp list shows the active requirements, fp list --status draft shows proposals waiting for review, and fp list --gaps shows requirements with no evidence yet. fp show <slug> prints one requirement's acceptance criteria and its evidence on each platform.
  2. 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 runs fp 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.
  3. Tag the test that proves it. A comment directly above the test binds it to the requirement:
    # fp:reset_password
    it 'emails a reset link to a registered address' do
    Add @web, @ios and so on to say which platforms a test covers, for example // fp:reset_password@android.
  4. Report, then check. fp report --junit junit.xml --surface web records the tagged tests as present (tagged, but not yet run in CI). fp check exits 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.