pokoclaw: Instructions file for Codex

AGENTS

Guidance for coding agents working in this repository.

Project Shape

• TypeScript / Node.js / pnpm project
• Personal AI assistant focused on long-running, observable task execution
• Feishu/Lark is currently the only supported channel
• The codebase is early-stage and should be changed incrementally

Core Rules

• Make the best change that solves the task.
• Preserve existing user work.
• Prioritize code quality, maintainability, extensibility, and product quality above short-term shortcuts.
• Do not reject a refactor just because it is speculative; use judgment and make the change when it improves the result materially.
• If behavior changes, add or update tests.
• If user-facing setup or usage changes, update the relevant repository docs in the same change when practical.
• Keep explanations concrete and tied to actual code paths.

File And Git Safety

• Never use destructive git commands such as git reset --hard or git checkout -- unless explicitly requested and approved.
• Do not amend commits unless the user explicitly asks.
• Never revert changes you did not make.
• If you notice unrelated unexpected modifications, stop and ask how to proceed if they conflict with the task.
• Prefer apply_patch for manual file edits.
• Do not use Python for file editing when a shell command or apply_patch is sufficient.
• Prefer ASCII when editing files unless the file already uses non-ASCII and there is a clear reason to match it.

Dependency Commands

• When running pnpm add, pnpm install, or similar dependency-changing commands:
  • if the command hits a permissions or sandbox problem, request escalated permissions directly
  • do not first try to work around it with --store-dir or other local store rewrites
  • reason: this repository has repeatedly hit false-detour issues from trying to patch pnpm store behavior instead of just requesting the needed permission

Commands

• pnpm install - install dependencies
• pnpm build - TypeScript check (tsc --noEmit)
• pnpm typecheck - same as pnpm build
• pnpm lint - Biome checks
• pnpm format - Biome write/fix
• pnpm test - Vitest suite
• pnpm test:integration - integration tests
• pnpm preflight - build + format + lint + test
• pnpm start - run the app once
• pnpm dev - run the app with watch mode
• pnpm meditation:backtest -- --tick-at <iso> [--lookback-days N | --start-at <iso> --end-at <iso>] [--label name] - run the normal meditation pipeline against a sandbox copy of the live DB/workspace for replay/backtest without mutating live meditation state
• pnpm meditation:episode-study -- --tick-at <iso> [--lookback-days N | --start-at <iso> --end-at <iso>] [--session-id <id>]... [--top-sessions N] [--label name] - compare multiple candidate friction-episode extraction strategies against real historical session data and write reports under .tmp/meditation-episode-study/