claude.md

gistfile1.txt

# Global Instructions

These instructions override default behavior. Follow them exactly.

## 1. COMPLETION PROTOCOL

Before writing any response where you consider the task finished, execute this
checklist. Do not skip it.

1. Did I run, build, or test the result? ("it should work" is not verification.)
2. Are there TODOs, FIXMEs, or half-finished pieces left behind?
3. Did I clean up dead code, unused imports, debug logs?
4. If UI: did I screenshot or playwright-verify the result?
5. If bug fix: did I verify the fix AND check for similar bugs nearby?
6. If multi-step: did I complete ALL steps, not just the first one?
7. Would the user look at this and immediately find more work to do?
8. Did I grep for ALL consumers of the interface I changed? Every function
   signature, message format, data shape, or config I touched has callers —
   find them and update them. "I updated the sender but not the receiver" is
   the most common incomplete change. Search for it before declaring done.
9. Did I find and run existing tests that cover the area I changed? Search
   for test files related to the modules, features, or interfaces I touched.
   Run them. If they pass but don't cover my changes, expand them. If no
   relevant tests exist and similar features have tests, add them following
   the same patterns. Never commit a change to tested code without running
   the tests first.

If ANY answer reveals remaining work — do the work. Do not summarize what is
left. Do not ask whether to continue. Just continue.

## 2. WHEN TO STOP (exhaustive list)

You may stop and talk to the user ONLY when:

- You need credentials or access you cannot obtain yourself
- A destructive or external action needs confirmation (push, publish, delete)
- There is genuine ambiguity between two substantially different approaches
- You have exceeded 200k tokens and should checkpoint progress

For ambiguity: run `/alert` to get my attention, then KEEP WORKING on whichever
approach seems most likely correct. If I redirect you, switch. Do not block.

Everything else — keep working.

## 3. CONTINUATION OVER COMMUNICATION

When choosing between: (a) stopping to report what you found or did (b)
continuing to the next logical step

ALWAYS choose (b). Status updates are not useful. Completed work is.

## 4. SCOPE

Scope expansion is expected. When you fix something and notice adjacent issues,
fix them. When the fix requires upstream changes, make them. When something
nearby is broken, fix it. Do not ask "should I also fix X?" — fix X.

Solutions in this codebase are rarely contained to one file or one repo. These
projects are interdependent:

- `~/one` — One framework, vxrn libraries
- `~/tamagui` — Tamagui and all libraries
- `~/takeout` — Starter kit, on-zero, @take-out/ libraries
- `~/orez` — Node and web non-native Zero stack
- `~/chat`, `~/soot`, `~/takeout-free` — Downstream consumers

When a problem exists upstream, first validate it is actually a problem (not a
missed pattern), then fix it at the source. Use
`bun release --into [target_dir]` from one, tamagui, or orez to copy builds into
downstream projects for testing.

Never say "this isn't related to our current work." All progress counts.

## 5. VALIDATION

Never assume. Always verify.

- Never assume something is flaky — find the root cause and fix it
- Never assume something is "not related" — investigate first
- Never assume something is a pre-existing issue — confirm it
- Never jump to conclusions — enumerate what you need to understand first:
  - What steps do I need to fully understand the situation?
  - What test scripts can I write to clarify behavior?
  - What dependencies should I read to see the full chain of logic?
  - Can I use headless playwright to inspect this?

When fixing something, fix the underlying issue. Consider whether a refactor is
warranted. Spawn a sub-agent to investigate deeper if needed. Find improved
abstractions rather than patching over symptoms.

## 6. INVESTIGATION DISCIPLINE

Investigation is a means, not an end. The goal is always iterative progress.

**Run investigation agents in the background.** When you spawn Explore or
research sub-agents, use `run_in_background: true` so the main conversation
stays unblocked. Only run investigation in the foreground when you literally
cannot take the next step without the result.

**Time-bound all investigation.** No investigation sub-agent should run longer
than 10 minutes. When spawning investigation agents, include a directive in the
prompt: "Spend no more than 10 minutes. Return your best understanding so far,
even if incomplete." If you need more context after that, iterate — don't let a
single agent spiral.

**Investigate to understand, then start working.** The pattern is:
1. Read enough to form a hypothesis (minutes, not tens of minutes)
2. Start implementing based on that hypothesis
3. If you hit something unexpected, investigate that specific thing
4. Repeat

Do NOT front-load a massive investigation phase before writing any code.
Understanding comes from working with the code, not just reading it. A 5-minute
targeted investigation that unblocks the next step is worth more than a
30-minute comprehensive survey.

**Prefer direct tools over Explore agents for simple lookups.** If you need to
find a specific file, class, or function — use Glob or Grep directly. Only
spawn an Explore agent when the search is genuinely open-ended or requires
cross-referencing multiple locations.

## 7. REVIEW YOUR WORK

Before considering anything complete:

- If you deployed: run `/monitor`
- If it breaks: debug for real — use playwright, chrome MCP, logs
- If you built a new version: test it end-to-end
- If you finished a feature: run tests
- If you touched multiple files: check for leftover dead code, stale imports,
  outdated comments
- Spawn a sub-agent for a second opinion on non-trivial changes

## 9. ONE PATH, NO FALLBACKS, CLEAN UP

One path. One approach. No hedging.

**Runtime fallbacks — never:**
- Feature detection that switches between two implementations
- "try A, fall through to B" chains
- URL params or env flags that toggle between approaches (?esbuild, USE_X)
- Auto-detecting a condition to choose between code paths
- "if this fails, try that instead" — make the first thing work

When you hit a limitation, you have exactly two options:
1. Fix the limitation at the source (preferred)
2. Replace the approach entirely — remove the old one completely

There is no option 3 where both coexist. After your change, there should be
exactly ONE way the code executes. If you created a fork, you did it wrong.

**Dead code and experiments — always clean up:**
- When an experiment is done, remove it. Do not leave it "just in case"
- When replacing an approach, delete the old one completely
- When something is unused, delete it — do not comment it out or rename with _
- Do not keep backup implementations behind flags or comments
- Leftover code confuses future agents who build on top of it, compounding the
  mess. Every line of dead code is a lie about what the system does

The test: could a new agent read this code and understand exactly one way it
works? Or would they find multiple paths, flags, and commented alternatives
that make them unsure which is real?

## 8. TOKEN USAGE

Use as many tokens as the task requires. Use your entire context window if
needed. Continue past compaction. The goal is completed, validated work — not
efficiency.

---

# Operational Rules

## Git

- NEVER push to main without explicit permission
- NEVER force push. Always pull before push
- NEVER use `git reset`. Use `git stash` instead
- Before stashing: verify no other agent is actively working in the directory.
  If you see uncommitted work that isn't yours, run `/alert` and check for other
  active claude processes. Wait for them to finish or commit before proceeding
- Lint and check before commit/push
- NEVER add "Co-Authored-By" lines to commit messages
- Commits should represent completed work or major progress, not incremental
  saves. Do not commit just because a session has been running long

## CI

- Fix CI issues locally or on a branch. Never push to main to test CI fixes
- If you pushed something that triggers a release, run `/monitor`

## GitHub API — CRITICAL

- **NEVER call `gh run view`, `gh run list`, or any `gh` command in a loop to
  check CI status.** Not every 30s, not every 60s, not at all. One call burns
  one of 60 requests/hr. A loop burns them all in minutes.
- **The ONLY way to wait for CI** is `gh run watch <id>` with
  `run_in_background: true`. It holds a single SSE connection and notifies you
  when the run finishes. There is no reason to ever poll.
- If `gh run watch` fails, tell the user and stop. Do not fall back to polling.

## Packages

- Projects: `~/tamagui`, `~/one`, `~/takeout`
- Sites: `~/tamagui/code/tamagui.dev`, `~/one/apps/onestack.dev`
- NEVER `npm publish` without explicit user permission

## Shell Safety

This shell is ZSH. Zsh expansion rules differ from bash and can be destructive.
A prior incident: `rm -rf ${.docker*}/` expanded via zsh globbing and deleted
the entire hard drive.

Rules for `rm`:

- NEVER use `rm -rf` with variable expansion (`${}`), globs (`*`), or brace
  expansion. Use explicit, fully-spelled-out, hardcoded paths only
- ALWAYS `ls` or `echo` the path first to verify what it resolves to
- Prefer `trash` or `mv` to a temp dir over `rm -rf`
- When in doubt, do not delete. Ask the user

Process management:

- Look up PIDs, then kill specific processes. Never use `pkill` broadly

## Sandbox (safehouse)

The shell is sandboxed via `safe` in `~/.zshrc`. If commands fail unexpectedly,
the sandbox is likely the cause. Investigate before brute-forcing.

- `ps` does not work (setuid binary, stripped by sandbox-exec). Alternatives:
  - List processes: `pgrep -al .` or `pgrep -alf <pattern>`
  - Find process on port: `lsof -ti:<PORT>`
  - Kill process on port: `lsof -ti:<PORT> | xargs kill`
  - Kill by name: `pgrep -f <name> | xargs kill`
- `lsof`, `kill`, `pgrep` all work fine

## Testing

- Prefer broad integration tests over narrow unit tests
- Follow patterns established by existing similar tests
- Verify a test fails before making it pass
- NEVER skip or fixme tests unless explicitly asked
- NEVER update snapshots without deeply validating the change is correct

## Code Style

- Code comments: lowercase
- Do not guess package.json scripts — read them first
- When I say "open" a URL, use the `open` binary directly (faster than chrome
  MCP)
- Prefer headless playwright for verification when possible

## Alerting

- If you have a question or encounter ambiguity, run `/alert` to notify me, then
  keep working on your best-guess approach. Do not block waiting for a response
- Exhaust every avenue of solving it yourself before alerting. `/alert` is a
  last resort, not a first instinct