tapflow: Instructions file for Claude Code

tapflow — AGENTS.md (Common Rules)

Package-specific rules are referenced via INDEX.md.

---

WHAT

tapflow is an open-source self-hosted library that lets the entire team — PO, PM, designers, backend engineers, and QA — test iOS/Android apps directly from a browser. It uses the Mac you already own — no external cloud dependency.

Core value

Remove friction. Anyone on the team can open a browser and test the app on a real simulator, without Xcode, without device setup, without accounts on external services.

Three ways to use tapflow

tapflow Core is the layer everything shares: devices, sessions, UI trees, builds, run records, and resource management. It is a concept, not a package. A team can start from any of the three:

• Manual QA: CI uploads a build → the team tests in the browser. The most mature path.
• AI agents via MCP (experimental): an LLM agent drives a device through @tapflowio/mcp-server.
• Automation (experimental): the flow runner replays YAML flows deterministically, mainly in CI.

Don't design for a single entry point. Every change keeps the hard line in VISION.md: replay calls no model, tapflow saves agent or model output as a flow only after a deterministic replay passes, and Manual QA and the flow runner never depend on an agent or any model.

WHY

• Appetize / BrowserStack are expensive and send app data outside your network.
• Reuses infrastructure (Mac) the team already owns.
• Fully open-source and customizable.

For the product direction and philosophy behind these — start anywhere, replay without a model, Flow Capture as the moat — see VISION.md.

---

Core Principles

• Evidence-based: verify a root cause with code, logs, or tests before fixing — no guess-driven changes.
• Minimal changes: stay within the requested scope; follow the file's existing conventions. Scope is decided by what a reviewer has to hold in their head, not by which file a line sits in.
• Verifiable goal: know how success will be measured before starting (a reproducing test, same tests passing after a refactor, etc.).
• Stop before risky actions — get user confirmation before any hard-to-reverse operation (git push --force, git reset --hard, sending messages to external systems, DB drops, etc.). Specifically:
  • Only create commits or PRs when the user explicitly requests it.
  • Do not merge PRs. Always leave merging to the user — even with --admin. Create the PR and stop. Enforced by the PreToolUse hook .claude/hooks/pr-merge-guard.sh, which blocks gh pr merge and gh pr review in command position. It does not cover the gh api and git plumbing equivalents: same threat model, a cooperative agent rather than an adversary.
  • A push to docs-production is a production deploy of tapflow.dev. Confirm before every one. The only manual push is a docs hotfix: a commit already on main, cherry-picked, with its diff checked for pages about unreleased features — procedure in CONTRIBUTING, "Docs follow releases".
  • Avoid breaking changes. If unavoidable, report to the user and get approval before proceeding. Breaking change scope: public API / interface signature changes, DB schema changes, WebSocket message protocol changes, CLI command / flag changes.