CLAUDE.md — dev repo hook (autoinstalled by lobster-wenshu-bot)

This file is the project's CLAUDE.md hook for the dev role. When Claude Code opens this repo, this is the first context it reads. Author: 文殊菩萨 / lobster-wenshu-bot. Last updated: 2026-04-27.

Identity

This repo is a product / dev repo. Code that ships to users. Bot owners: lobster-worker-bot* (iOS), xurishu_bot / kevins-studio-bot / jarvis_theone_bot / andyjanebot (H5). PR review: 八戒 (lobster-qa-bot) or human gate. Deploy: mini-build-all orchestrator (see also packing-machine-arch-2026-04-27.md in claude-worker-universe .omc/notes/).

Top rules

TDD-first. Before changing behavior, the diff must include a new or updated test that fails on main and passes on this branch. No exceptions for "trivial" fixes — historically the trivial ones are the ones that come back as P0 production bugs (idem-label collapse, label string→int64 422, bold-colon regex, fail-closed iOS routing — all shipped without enough tests).
Fail-closed defaults. When a routing / permission / platform table is unsure, default to the safer answer (no fan-out, no auto-promote, no auto-merge). See _MODULE_PLATFORMS and _PLATFORM_OWNER_BOTS in claude-worker-universe/core/wen_shu_hub.py for the canonical pattern.
Idempotency markers in the body. Any artifact this repo creates (issues, PRs, comments, files) should carry an idempotency key in its body (e.g. ) so re-runs / retries de-dupe. The labels field on Gitea issues is not authoritative — it requires the bot account to be a repo collaborator (most aren't). Cross-ref commit 3a1013b in claude-worker-universe.
Portable links only. Never write a per-machine path (/Users/pp-bot/...) into a commit, issue, or comment. Use the Gitea web URL (<host>/<org>/<repo>/src/branch/<branch>/<path>) with per-segment UTF-8 percent-encoding. See _qa_spec_gitea_url for the canonical helper.
Branch convention (target end state): main is prod, dev is rolling integration, release/* is tagged. If this repo currently uses something else (im-dev, bundle, 4411-1, release, 20260203), read the latest packing-machine-arch-2026-04-27.md for the migration plan and don't unilaterally rename.
Default branch is read at runtime — never hardcode "main" in PR-create / merge calls. auto_pr_botdev got bitten by this; the fix reads RepoState.default_branch dynamically.

Big-co patterns reused in this codebase

Stripe Idempotency-Key → _idempotency_key() (sha16 hash; body marker is the source of truth, not the label).
Linear AI agents / GitHub Copilot for Issues → @-mention _PLATFORM_OWNER_BOTS in body; assignees are best-effort with 422 fallback because most bots aren't repo collaborators.
Datadog rolling-window WARN → distribute.summary JSON + distribute.idem_storm after 3 consecutive ticks at idem_rate > 0.9.
AWS IAM fail-closed default-deny → _MODULE_PLATFORMS opt-in for iOS routing; default H5-only.
GitHub Actions/Vercel preview-smoke contract → headless-smoke CLI command (Playwright + Chromium against built dist/, emits PASS/FAIL
- screenshot + exit code).

Agent tier guidance for this repo

Trivial lookups → Haiku
Standard implementation → Sonnet
Architecture, race conditions, security review → Opus

For multi-step work in this repo, route via the wenshu CLI: python3 .../core/wen_shu_hub.py <subcommand> — gen / distribute / poll / auto-pr / state / daemon / headless-smoke / align-bot-dev / figma.

Run commands

If package.json exists: npm install && npm run build-only (skip type-check until repo's TS errors are clean — see lessons_learned). If pyproject.toml exists: python3 -m pytest core/tests/. If pubspec.yaml exists: this is a Flutter repo — see packing-machine-arch-2026-04-27.md for build hooks (worker-knowledge, bajie merge).

Commit style

<type>(<scope>): <subject in lowercase, no trailing period> Body: Why: + How: + Refs:. End every commit with the Co-Authored-By trailer for the bot that authored it.

What this hook deliberately does NOT do

It does NOT pin a Python / Node / Flutter version (varies per repo).
It does NOT enforce a license / formatter — repos diverge.
It does NOT bypass review — bot-dev → main PRs still need human or 八戒 sign-off (master-design D2 / §6.2).

4.5 KiB Raw Blame History