customer-im-client-dev/AGENTS.md

AGENTS.md — dev role

Open-standard agent contract per agents.md. Companion to CLAUDE.md (Claude-specific) — this file works for any AI coding agent (Cursor, Aider, Codex, OpenHands, etc.).

Dev environment tips

• Default branch convention: main = prod, dev = rolling integration, release/* = release candidates, feat/* = ephemeral feature branches. If this repo currently uses something else (im-dev, bundle, 4411-1, release, 20260203), see dasheng-repos/.omc/notes/packing-machine-arch-2026-04-27.md for the migration plan.
• For Vue 3 + Vite repos: npm run build-only (not npm run build) to bypass legacy tsc errors that block clean builds.
• For Flutter repos: flutter pub get && flutter test before any change.
• For Swift repos: xcodebuild -workspace ... -scheme ... test from the workspace root.

Testing instructions

• TDD-first. Diff that changes behavior MUST add or update a test that fails on the parent commit and passes on this branch.
• Find existing tests by language:
  • tests/, core/tests/, __tests__/ (Python / JS)
  • test/, integration_test/ (Flutter / Dart)
  • *Tests/ (Swift)
• Run with the lightest scope that proves the change: pytest core/tests/test_<module>.py / vitest run <pattern> / flutter test test/<file> / xcodebuild test -only-testing:<TestClass>.
• Pre-existing failures unrelated to your change are NOT in scope to fix unless explicitly requested. Note them in your PR body.

PR instructions

• Title: <type>(<scope>): <subject> lowercase, no trailing period.
• Body: Why: + How: + Refs: + Co-Authored-By: trailer.
• Default branch is read at runtime — never hardcode "main" in PR-create / merge calls. See wen_shu_hub.auto_pr_botdev for the canonical pattern.
• Idempotency: any artifact (issue, PR, comment) the agent creates MUST carry an idempotency key in body so re-runs dedupe. Pattern: <!-- idem:<sha16> -->.

Hard rules (production-incident-driven)

1. Fail-closed defaults when uncertain about routing / permissions / platforms. Default to the safer outcome (no fan-out, no auto-promote, no auto-merge). See _MODULE_PLATFORMS in claude-worker-universe/core/wen_shu_hub.py for the canonical pattern.
2. Portable links only. Never write /Users/... in commits, issues, comments, or test artifacts. Use Gitea web URL with per-segment UTF-8 percent-encoding. Helper: _qa_spec_gitea_url.
3. No inline PAT in remote URL. If you see https://oauth2:<token>@host/... in a remote, that's an existing smell — don't propagate.

References

• Master design: claude-worker-universe/.omc/notes/master-design.md
• Build machine review: dasheng-repos/.omc/notes/packing-machine-arch-2026-04-27.md
• Big-co patterns reused: Stripe Idempotency, Linear AI agents, GitHub Copilot for Issues, Datadog rolling-3-window WARN, AWS IAM fail-closed.