ADapptive
Menu
How it worksFeaturesPricingAboutInstructionsDocsSecurityDownloadSign inExplore campaigns

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 after a security check), the auto-deploy git branch Coolify watches (deployBranch; the agent commits there when AUTOMATIC), 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_*), select only the needed scopes, and optionally restrict it to one Project and expiration. A separate Project-restricted runner:attest key belongs only in GitHub Actions.
  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 main tool flow is:

Tool Purpose
whoami, check_connection, get_workspace_brief Confirm identity and find missing Project/environment setup
Project, Campaign and Zone tools Configure GitHub metadata, beta/production branches and URLs, push/PR policy, paths, execution mode and per-zone thresholds
get_campaign_readiness, materialize_batches Freeze ready individual work or a coherent required-zone campaign batch
claim_implementation, evaluate_implementation_security, start_batch_implementation Lease, policy-check and transactionally start work
request_runner_verification, submit_verification_attestation Bind signed GitHub evidence to the exact commit and actual diff
request_production_promotion Continue automatically or return the exact human approval requirement
reject_feedback, reopen_feedback, deployment reads Validated decisions and retained 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