| type | rules | |||
|---|---|---|---|---|
| topics |
|
|||
| status | living |
Package-specific rules are referenced via INDEX.md.
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.
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.
- Manual testing (primary): CI uploads a build → team reviews in the browser. This is tapflow's main use case.
- AI Agent via MCP (experimental): An LLM agent controls the simulator automatically using
@tapflowio/mcp-server. This is a separate, opt-in feature — it does not affect the manual testing path.
When designing features or writing docs, default to the manual testing perspective. The AI Agent path is additive, not a replacement.
- 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 — Manual First, Flow Capture as the moat, AI as an additive harness — see VISION.md.
- 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.
- 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. - 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.
- TypeScript throughout. No
any. Node.js ≥ 22. Everything else is in each package'spackage.json.
Write GitHub PR and issue titles/bodies in English, and write new code comments in English too. (Conversation and docs follow the existing KO/EN rules.) Code comments default to English so contributors of any language can read and extend them — existing Korean comments stay until the line they sit on is changed.
When starting a new task that requires code changes (not when continuing work on an existing branch):
git checkout main && git pull origin main— start from the latest main.git checkout -b <branch-name>— work on a new branch, never directly on main.
Work logs go in .work/. Conventions: .work/CLAUDE.md.
- Plan — define requirements + test cases first (
type: plan). - Work — write tests first, implement until they pass.
- Review — edge cases + real data validation → adversarial review (below) → PR (
type: review). - Compound — extract repeating patterns into test + code + prompt bundles (
type: compound).
Custom commands: /work-plan {topic} · /deep-research {problem} · /qa {target} · /doc-sync · /compound · /promote-decision {topic} · /release {major|minor|patch}.
The authoring session inherits its own assumptions, so before creating a PR the diff must be refuted by an independent context that has NOT seen the working conversation. Docs-only PRs may skip the review itself, but still write the record (with the skip reason) — the gate always requires it.
- Record: findings + dispositions (fixed, or skipped with a reason) go in
.work/reviews/<branch>.md(slashes →__), including the full 40-character HEAD hash (git rev-parse HEAD— an abbreviated hash will not pass the gate). Mention the review in the PR body. - Enforcement: the PreToolUse hook
.claude/hooks/adversarial-review-gate.shblocks PR creation unless that record exists and references the current HEAD — any commit after the review invalidates the record until it is refreshed against the new diff. - A change spanning two or more packages, or both platforms, needs a second, earlier review — of the design, before the code. One adversarial pass over the plan, in addition to the pre-PR one.
Read contributing/adversarial-review.md before launching a reviewer. It covers how to design the channels, how to run the cross-cutting design pass, and how to keep the cost in minutes rather than hours — the same review can take 4 minutes or 106 depending only on what its prompt makes it execute.
- OCP: New platforms and features are added without modifying existing code — platforms register via
AgentRegistry.register()only; relay and dashboard code stay unchanged. - ISP:
DeviceAgentonly contains methods every platform can implement. Platform-specific behavior goes in separate interfaces. - DIP: Dependencies via constructor injection. Depend on interfaces, not implementations.
- Comments only when the WHY is non-obvious. Write new comments in English; leave existing Korean comments unless you're already editing that line.
- When changing an interface, update
agent-corefirst, then align implementations.
Cross-package imports resolve through exports to dist/, so without it a test in one package
exercises whatever was last built of another. #459 shipped a regression behind a green 1889-test
run for exactly that reason: ios-agent stands up a real RelayServer, and the relay it stood up
was the previous one. It surfaced only when the pre-commit tsc -b refreshed the build.
ssr.resolve, not resolve — vitest runs in node and takes the SSR resolution path. Measured:
resolve.conditions, NODE_OPTIONS=--conditions=source and server.deps.inline all still loaded
dist. And source is prepended to vite's defaults rather than replacing them; a replacement
list applies to every dependency, and dropping node from it sent jsdom to the wrong entry of
decimal.js.
Adding a package that imports a sibling in its tests means adding the config too.
scripts/__tests__/testsReadSource.test.mjs finds those packages by inspection and fails if one is
missing it — and separately plants a marker in a built artifact to prove the resolution actually
lands on source, because a config can be present and not work.
Not solved by pointing the manifests at source with publishConfig, which needs no per-tool
config at all and was tried first. pnpm deploy does not apply publishConfig
(pnpm#6693, open), so the Docker image would ship
node_modules full of .ts and die on boot — and packages/cli/bin/tapflow.js is plain node too.
Covering every consumer uniformly means covering the ones that cannot read TypeScript. Opting in
per tool is the point, not the cost.
Tests run through pnpm --filter <pkg> test, never npx vitest — not even from inside the package directory, and not for a single file. npm rewrites the root package.json on its way through and collapses pnpm.overrides to pnpm: {}, leaving pnpm-lock.yaml rewritten beside it, and it reports none of that. Reviewing #474 cost exactly this: one npx vitest on one test file, and the entire override block was gone with only git status to say so. git checkout HEAD -- package.json pnpm-lock.yaml puts both back — check git diff on them first if you were editing either on purpose, since that discards everything uncommitted in both.
After running tests (especially repeated or looped runs), always check for zombie vitest processes and kill them:
ps aux | grep vitest | grep -v grep
pkill -f "vitest"Zombie worker processes accumulate silently from pnpm test loops and consume memory. Kill them before starting new test runs.
Same rule, different processes. Anything you start with pnpm dev you stop before the session ends:
pnpm dev:down # stops relay / agents / vite for THIS checkoutpnpm dev refuses to start when :4000 or :3001 is already held, and names the pid — because the failure it produces otherwise mentions neither. A relay left running once survived a day and cost a debugging session: it failed with EADDRINUSE, concurrently SIGTERMed the dashboard and both agents, and the visible symptom was four processes dying for no stated reason.
concurrently -k cleans up on a normal exit, not when the terminal goes away or the machine sleeps.
A PR that changes published source needs a changeset. The CI changeset job fails without one, and it is a required status check on the protect-main ruleset, so that failure blocks the merge. Note that the job is skipped for bot PRs, and a skipped required check counts as passing — the gate is deliberately not applied to them. Opt out only by writing the reason in the PR body, on its own line:
<!-- no-changeset: comment-only follow-up to #123 -->
A dashboard change names @tapflowio/relay, never @tapflowio/dashboard. The dashboard is ignored in .changeset/config.json because it is private — but it is built into the relay's public/ and ships inside that package, so that is where its release note belongs. Naming both in one changeset is rejected outright by changeset version, and nothing catches it until release day: the CI gate only checks that a changeset exists.
pnpm changeset:check runs the same check locally, against committed work. A changeset written for an EARLIER PR must say so — Backfills: #413 on its own line — or the audit keeps reporting that merge for the rest of the cycle. That gate cannot see anything already on main, so /release audits the merges too (pnpm changeset:audit) — four merged PRs once got as far as release preparation with no changelog entry between them, and only the audit would have caught it.
Reach for pnpm.overrides last. The usual situation is not that the declared range forbids the
patch — it is that the lockfile does not re-evaluate ranges. The patch nearly always lands
inside the same major, the declaring range is a caret, and pnpm update <pkg> takes it with no
permanent entry to maintain. An override is a workaround for a stale lockfile, and it outlives the
problem: measured on 2026-08-06, all fourteen entries in the block were inert — removing the whole
thing and resolving cold produced a byte-identical tree.
pnpm overrides:audit judges each entry: still needed, correct, and whether it reaches a published
package's production tree. Run it before adding an entry, and when one is added, plan to remove it.
Derive an override key from the GHSA advisory, never from the Dependabot alert. An alert reports
only the affected range matching the version you happen to have installed. fast-uri patched three
lines within fourteen minutes of each other; the alert showed one, and #471 shipped a key that left
the current major line unguarded. The same mistake in #469 inherited a lower bound from an earlier
advisory. Read the whole affected set:
gh api graphql -f query='{securityVulnerabilities(ecosystem:NPM, package:"NAME", first:100){
pageInfo{hasNextPage endCursor}
nodes{advisory{ghsaId severity} vulnerableVersionRange firstPatchedVersion{identifier}}}}'Page it. axios has 73 advisories and undici 67, and a page that stops short reads exactly like
"no such advisory" — the direction that hides a floor you needed. Repeat with after:"<endCursor>"
until hasNextPage is false. pnpm overrides:audit does this for you.
Scope the key to the major line its replacement targets — pnpm matches by range intersection,
not containment, so a bare <X reaches every major below it and would force a cross-major jump on
a consumer that declared one. Cap the replacement for the same reason.
- Do not write code that sends app data or streams to external services.
- Do not proactively add features not on the roadmap.