member-console/AGENTS.md

Project instructions (canonical)

This file is the single source of truth for harness-agnostic instructions. CLAUDE.md, GEMINI.md, and QWEN.md at the repo root are symlinks to this file.

Test stack — parallel worktree contract

Before running docker compose up in test/, run ./bootstrap-stack.sh from test/. It generates a per-worktree test/.env with collision-free host ports so multiple worktrees can run isolated stacks concurrently. See test/AGENTS.md for the full contract (idempotency, Stripe webhook constraint, teardown).

Browser tooling — chrome-devtools MCP

All harnesses are configured to attach the chrome-devtools MCP to a Chrome instance running on 127.0.0.1:9222. If the MCP fails to attach, launch one and retry; do not ask the user to launch Chrome. Any Chromium build works (google-chrome, chromium, chromium-browser), started with remote debugging on that port and an isolated profile so it never touches the contributor's own browser state:

google-chrome --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-dev-profile \
  --no-first-run --no-default-browser-check --disable-sync \
  --password-store=basic --disable-save-password-bubble &

That command is the contract; a contributor may keep it in a personal wrapper script, but nothing in this repository depends on one.

context-mode — MANDATORY routing rules

You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.

BLOCKED commands — do NOT attempt these

curl / wget — BLOCKED

Any Bash command containing curl or wget is intercepted and replaced with an error message. Do NOT retry. Instead use:

• ctx_fetch_and_index(url, source) to fetch and index web pages
• ctx_execute(language: "javascript", code: "const r = await fetch(...)") to run HTTP calls in sandbox

Inline HTTP — BLOCKED

Any Bash command containing fetch('http, requests.get(, requests.post(, http.get(, or http.request( is intercepted and replaced with an error message. Do NOT retry with Bash. Instead use:

• ctx_execute(language, code) to run HTTP calls in sandbox — only stdout enters context

WebFetch — BLOCKED

WebFetch calls are denied entirely. The URL is extracted and you are told to use ctx_fetch_and_index instead. Instead use:

• ctx_fetch_and_index(url, source) then ctx_search(queries) to query the indexed content

REDIRECTED tools — use sandbox equivalents

Bash (>20 lines output)

Bash is ONLY for: git, mkdir, rm, mv, cd, ls, npm install, pip install, and other short-output commands. For everything else, use:

• ctx_batch_execute(commands, queries) — run multiple commands + search in ONE call
• ctx_execute(language: "shell", code: "...") — run in sandbox, only stdout enters context

Read (for analysis)

If you are reading a file to Edit it → Read is correct (Edit needs content in context). If you are reading to analyze, explore, or summarize → use ctx_execute_file(path, language, code) instead. Only your printed summary enters context. The raw file content stays in the sandbox.

Grep (large results)

Grep results can flood context. Use ctx_execute(language: "shell", code: "grep ...") to run searches in sandbox. Only your printed summary enters context.

Tool selection hierarchy

1. GATHER: ctx_batch_execute(commands, queries) — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
2. FOLLOW-UP: ctx_search(queries: ["q1", "q2", ...]) — Query indexed content. Pass ALL questions as array in ONE call.
3. PROCESSING: ctx_execute(language, code) | ctx_execute_file(path, language, code) — Sandbox execution. Only stdout enters context.
4. WEB: ctx_fetch_and_index(url, source) then ctx_search(queries) — Fetch, chunk, index, query. Raw HTML never enters context.
5. INDEX: ctx_index(content, source) — Store content in FTS5 knowledge base for later search.

Subagent routing

When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt. Bash-type subagents are upgraded to general-purpose so they have access to MCP tools. You do NOT need to manually instruct subagents about context-mode.

Output constraints

• Keep responses under 500 words.
• Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
• When indexing content, use descriptive source labels so others can ctx_search(source: "label") later.

ctx commands

Command	Action
ctx stats	Call the ctx_stats MCP tool and display the full output verbatim
ctx doctor	Call the ctx_doctor MCP tool, run the returned shell command, display as checklist
ctx upgrade	Call the ctx_upgrade MCP tool, run the returned shell command, display as checklist