ADapptive
Menu
How it worksFeaturesPricingAboutInstructionsDocsSecurityDownloadSign inGet started

Developer guide

You run a product. ADapptive gives you a community of testers who find bugs, propose changes, and vote — and a loop that hands vote-approved, safety-cleared items to your own coding agent. This guide is the golden path from an empty account to your first deployed community change. Budget: about fifteen minutes.

0. Concepts in one minute

Term Meaning
Workspace Your tenant. Owns keys, campaigns, zones, testers, deployments.
Campaign A testing initiative on a URL (or URL patterns) with a goal, a schedule, a visibility (private / invited / public), and a pipeline configuration.
Zone A region of your UI (CSS selector) where testers can leave a specific kind of feedback: comment, suggestion, bug, vote, rating, poll, or an inline yes/no (VOTE_ONLY).
Audience Who can act on a zone: anyone (ANONYMOUS), signed-in testers (ACCOUNT), or your trusted pool (TRUSTED_POOL). Use ACCOUNT or TRUSTED_POOL for anything that drives implementation.
Threshold and quorum A zone's weighted score target plus the minimum number of distinct trusted voters. Both must be met before an item is "ready".
Safety status Every submission is redacted and screened. Only CLEARED items reach your agent; FLAGGED items wait in Moderation.
Implementation loop Your agent (Claude Code, Cursor, Codex, any MCP client) pulls ready items through the ADapptive MCP server, changes your code locally, and reports progress.

1. Create your workspace

  1. Go to https://app.adapptive.space → Sign in. Accounts live in Authentik; sign-up happens there.
  2. First sign-in lands on Onboarding. It creates your workspace and shows your secret key once. Store it in a password manager. You will rarely need it: day-to-day work uses the dashboard, the MCP-scoped key, and short-lived tokens.
  3. The Overview page shows a checklist that tracks the rest of this guide.

2. Create a campaign

Campaigns → New campaign. Give it a name, the product URL patterns testers will visit, a goal ("Find checkout blockers before launch"), optional dates, and a visibility:

  • Private — only your own invited testers.
  • Invited — your pool plus anyone you send the link.
  • Public — listed in the community Tester Hub for House Pool members at or above the tier you choose.

The Pipeline tab sets the loop rules: vote threshold, minimum trusted voters, automation level (HUMAN_IN_LOOP — your agent asks before acting; AUTOMATIC — your agent may start immediately), and the paths in your repo your agent may touch (advisory; enforced by your agent's own tooling).

3. Place your first zone

Pick one of three ways; they write to the same zone table.

Way When How
Extension, developer mode (recommended) Any live site, no code Dashboard → Campaign → Zones → Connect extension. A 6-digit pairing code appears. In the extension side panel choose Developer → enter the code. Right-click any element → Add feedback zone.
SDK You ship a web app and want zones for embedded users Install @adapptive/sdk or @adapptive/react, init with your publishable key, wrap regions in FeedbackZone. See sdk/README.md.
Studio You want a visual configurator locally pnpm --filter @adapptive/studio dev; it uses the secret key and is never deployed.

Zone settings that matter: type, threshold, minimum trusted voters, audience, and (for TRUSTED_POOL) which tiers may submit and vote.

4. Invite testers

Testers → Tiers: create tiers with weights and permissions (for example Core weight 3, Community weight 1). Invite links are usage-capped, expiring, revocable. Share them, or make the campaign Public so the House Pool can discover it.

Testers can also reach you through the community: see the community playbook.

5. Connect your agent

Agent & MCP in the dashboard:

  1. Create an MCP key (adp_mk_*). It can read feedback, zones and campaigns and write status, deployments and analyses. It cannot delete zones, manage people, or touch rewards. Rotate it any time.
  2. Copy the ready-made config for your client:
    • Local (stdio) — node tools/mcp-server/dist/index.js with ADAPPTIVE_API_URL and ADAPPTIVE_SECRET_KEY (an adp_mk_* key is accepted here too).
    • Remote (Streamable HTTP) — https://mcp.adapptive.space/mcp with Authorization: Bearer adp_mk_…, or sign in through Authentik when your client supports OAuth.
  3. The Activity panel shows every tool call that produced a deployment record or a log line, so you can see what your agent is doing.

The tools your agent gets:

Tool Purpose
get_ready_feedback CLEARED items whose zone threshold and quorum are met — the entry point
get_feedback, list_feedback, list_zones, get_campaign_context Context, including the CSS selector that locates the UI
submit_feedback_analysis Store the agent's summary, category, duplicate link and task plan
start_implementation Create the deployment record; flips the item to GENERATING_CODE
report_deployment_progress, add_deployment_log, update_deployment_stages Progress, PR URL, checklist
rollback_deployment, update_feedback_status, list_deployments Control and history

Tester text arrives inside <untrusted_tester_content> envelopes with PII already redacted. Your agent is instructed to treat it as data, never as instructions, and to confirm with you before acting on anything that reads like a command.

6. Watch the loop close

  • Feedback inbox — filter by campaign, zone, status, safety status; batch triage; open an item to see votes, screenshot, analysis and deployment.
  • Moderation — items the safety pipeline flagged. Approve, edit-and-approve, or block. Every decision is audited.
  • Deployments — one record per implemented item with stages, logs, PR link and rollback metadata.
  • When your agent reports DEPLOYED, the contributing testers are notified and asked to re-verify. Three "still broken" reports reopen the item; a confirmation credits their reputation and, if the campaign has a budget, their rewards.

7. Team, notifications, analytics

  • Team & permissions — invite colleagues as OWNER / ADMIN / EDITOR / VIEWER; override per campaign.
  • Notifications — in-product inbox and per-user preferences.
  • Analytics — tenant-scoped summary and CSV export.

Troubleshooting

Symptom Check
Testers see no zones on the live site The extension needs a per-origin permission grant on that site; the zone's audience may exclude them; the campaign may be paused.
get_ready_feedback returns nothing although votes are high Quorum not met (need distinct trusted voters) or the item is FLAGGED — see Moderation.
Agent cannot connect Key kind: adp_pk_ is never accepted by the MCP server. Check ADAPPTIVE_API_URL is https://api.adapptive.space.
Lost the secret key Settings → rotate keys. The MCP key is separate and can be rotated independently.

Reference

  • REST API: https://api.adapptive.space/docs (OpenAPI at /openapi.json)
  • SDK: sdk/README.md, sdk/packages/core/README.md, sdk/packages/react/README.md
  • Extension: tools/browser-extension/README.md
  • MCP server: tools/mcp-server/README.md