tree_monstor

Dev-agent / checker-agent collaboration loop driven by downstream project docs/STATE.md. Dev agent implements and records work items; an independent checker agent verifies each item with real lint/typecheck/test/build evidence and writes findings back; loop continues until all items are VERIFIED or escalation limits are hit.

Synchronizes review feedback, QA findings, user corrections, and code-review suggestions into durable project docs before Build, merge, or ship.

Intake workflow for existing projects before continuing development. Analyze current source state, derive a truthful docs baseline, identify QA/regression gaps, and create a safe continuation plan.

防止修復過的 bug 重新出現(regression)。 規則:每個修過的 bug 必須留下「regression test」+「root cause note」+「為何會發生」分析, 確保日後 refactor / 改需求時唔會重新踩坑。 David 在 2026-06-06 kanban task 明確指出「舊的 bug 又出現」嘅困擾。

定時壓縮長時間任務的 context，避免 token 爆炸。寫入 context-summary.md 保留決策和當前狀態，丢棄細節。

Task Orchestration Subagent — Coordinates all subagents, manages task board, handles parallel/sequential execution, tracks dependencies and failures. The conductor of the development orchestra.

4-layer interruption + recovery mechanism for long dev tasks. Auto-save on any interruption, one-command resume with full context restore. Built on top of dev-task-memory state files.

Recover when the main agent is stuck mid-task. Search or read_file loops expanding without progress, response is explanation-only, or user sends "stop" / single-letter cues. Ship a minimal real artifact (ADR, spec doc, config) within a HARD 4-5 tool call budget. Distinct from subagent timeouts and session interruptions, this covers the gap where the main agent is still LIVE but has lost forward motion.

Build a tool-calling AI agent (function calling + tool registry + conversation memory + RAG over app data) for any product — CRM, support, internal tools. Use when the user wants a chat assistant that can ACT on the database (not just answer questions), multi-step reasoning, or integration with Slack/WhatsApp/email channels. Works with OpenAI / Anthropic / OpenRouter / MiniMax compatible APIs.

Add role-based access control (RBAC) + audit log to any backend API (Elysia, Express, Fastify, Hono, NestJS). Pattern: centralized permission map in shared package + middleware `requirePermission()` plugin + `AuditLog` table with action enum + auto-capturing `logEvent()` helper that grabs user/IP/UA without throwing. Use when user says 'user management', 'roles and permissions', 'audit log', 'who did what when', 'activity history', 'compliance log', or wants admin functionality (CRUD users, reset passwords, view who-changed-what). Pairs naturally with `crm-data-model` for CRM/sales tools.

Design and implement polymorphic line items in a sales/quoting system — single parent (Quotation/Invoice) with mixed child item types (Product vs Service with different field shapes). Use when a quotation/invoice/order can have line items of more than one domain type (e.g. physical products + consultancy services), or when item fields don't fit a flat single-table model. Covers Option A (separate tables + discriminator + dual FK), STI trade-offs, snapshot pricing for accounting immutability, and Prisma enum/JSON write casts. Pairs with `crm-data-model` and `backend-rbac-audit-log`.

Fix runtime errors caused by Prisma field types that serialize as strings over REST (Json / Decimal / BigInt / Date / Bytes) instead of their JS-typed equivalents — covers "options.map is not a function" (Json), "2.5 === "2.5" fails" (Decimal), "Cannot read property of bigint" (BigInt), and similar shape drift. Trigger when a Prisma field comes back as a quoted string but the caller expects array/number/object/Date, especially on PG.

Prisma schema 適配 SQLite 的正確方式 — enum 改 string、Json 改 String、Prisma 5 vs 7 差異、seed 注意事項、Bun 生態環境的常見坑。也涵蓋 Prisma 7 strict validation 嘅 generic pitfalls (適用於 SQLite / PostgreSQL),特別係 `prisma.config.ts` + Dockerfile COPY 嘅 deployment trap。

5-layer persistent memory for in-progress dev tasks — survives context compression, /new, gateway restart. State file + git checkpoints + external memory + cross-session search.

Set up AWS SES for transactional email — verify domain with DKIM, add Route53 DNS records, configure credentials for SDK use

Bootstrap a local full-stack TypeScript app with Bun 1.2 + Elysia backend + Vite 8 + React 19 + Tailwind v4. SQLite (dev) + Postgres (prod recommended) via Prisma 5. Use when user wants a quick local dev app (CRM, MVP, internal tool, exam app) and stack is the same family.

Audit project dependencies for known CVEs — fulfills 紅線 18 (Critical/High CVE must be 0 to merge). Class-level skill that covers BOTH npm + bun projects, lockfile quirks, and the "package is unmaintained, no fix available" trap (xlsx, node-ipc, etc.). Trigger conditions: - 紅線 18 enforcement (任何 ship / release 之前) - User 問「check security」、「CVE」、「npm audit」、「vulnerability」 - 任何 `package.json` / `bun.lock` / `package-lock.json` / `yarn.lock` 改動後 - 任何 new dep 引入(`bun add X`, `npm install X`) - Project 入面有 `xlsx`, `node-ipc`, `event-stream`, `getcookies`, `coa`, `rc`, `flatmap-stream` 等 known-unmaintained 嘅 package

Fix Docker multi-stage build where COPY . . overwrites fresh dist/ with stale host files due to missing .dockerignore

Build Docker images for shipping to customer servers (no source code, multi-arch amd64+arm64, tarball + load + install.sh workflow)

Build multi-arch (linux/amd64 + linux/arm64) Docker images and hand them to a customer as tarball(s) without a registry. Use when the user needs x86+arm support AND cannot use Docker Hub/ECR/localhost registry. Covers the `docker save` / `docker load` round-trip with per-arch tag handling and the known pitfalls of trying to create local-only manifest lists.

PM System deployment and development guide

UMAC AI 生產部署 SOP — backend + frontend + CDK + ECS 全流程

Sync `docs/*.md` to TWO standalone HTML previews in `docs/_html/` for user (David) confirmation — (1) engineering version for code review, (2) boss (decision) version with AI-generated summary cards, decisions, and risks in plain language. MD stays as source of truth. Trigger after any docs/*.md write or update in a project.

Docker build pitfalls on Mac arm64 (M1/M2/M3/M4) for Elysia (Bun) + Vite 8 (rolldown) projects. Covers missing libssl in oven/bun, npm optional native binding skip, package-lock.json darwin freeze, healthcheck wget absence, and frontend nginx reverse proxy setup.

Common TypeScript issues when building Elysia.js (Bun) APIs with typed routes — route parameter conflicts, derive context typing, t.Recursive, and inline handler patterns.

When building a chat / AI assistant UI that streams tokens from an LLM, render the reply with full Markdown + chart.js + data-fence support, and treat the agent's "I invoked a tool" marker rows as metadata (not empty bubbles). Class-level skill — covers any "AI chat panel" UI in any framework (React, Vue, Svelte, vanilla). Also load when debugging "empty bubble after tool call" in any AI chat UI, or when David reports "the chart didn't render" / "the markdown looks raw" / "the agent's reply is missing".

Add a search box to an existing React list page — client-side filter on the visible page (no server roundtrip). Covers the two-layer empty state (raw empty vs filter empty), header flex layout (button + search input), `useMemo` over `[data, query]`, and the 3-step "remove standalone page" checklist when a search box replaces a dedicated list page. Trigger when user says "加 search box" / "搜尋" / "filter list" / "拎走 menu + 加 search" / "list 加 search" / "list page 加 search" on a React/TypeScript frontend, or when a user says "menu 不用有" implying a standalone page should be retired in favor of sub-page search.

Audit and fix a web app for mobile RWD (responsive web design) using Playwright at iPhone viewport (390x844). Use when user says 'RWD', '手機兼容', 'mobile compatible', '手機睇', 'responsive', or when delivering a web app and you need to verify it works on small screens before declaring done.

Verify client-side API wrapper shapes (TypeScript request types, request bodies, response parsing) against the BACKEND SOURCE before committing — not against plan docs, design notes, or schema guesses. Catches field-name drift (e.g. `defaultTaxRate` vs `rate`), type drift (string vs object for nested fields), nullability drift, and the general "client wrapper written from plan doc wording but backend uses different names" class of bugs. Trigger when writing or modifying a typed API client wrapper (typed `request<T>()` call, Prisma model ↔ TS type mapping, zod schema ↔ DTO), or when "tsc passes but the endpoint 400s on the first real call".

When a patch edit corrupts a file (syntax error, mismatched braces, nested function inside wrong scope) — restore from git and re-patch cleanly instead of patching the broken state.

Run Prisma migrations on private RDS via ECS one-off task when CodeBuild can't reach the database

Discipline for writing frontend code that wraps backend endpoints — verify wire shape against backend source (not plan/spec doc), handle prefill races, refactor pages into tabbed layouts without double chrome, wire URL-driven Tabs.

Add server-side pagination to an admin list page WITHOUT breaking summary stats (count/sum/avg) or full-dataset exports (Excel/CSV). The core invariant — stats cards and exports always read from a server aggregate over the FULL filtered set, while the table view is paged. Trigger when the user says "the list page is slow, add pagination", "the page loads thousands of rows", "stats are wrong after I added pagination", "Excel export must include everything even when I paginate", or "total count drops as I change pages". Class-level — applies to any admin/data-table page (orders, users, audit logs, transactions, work logs, time entries) on any ORM (Prisma/Drizzle/Sequelize) and any backend framework (Elysia/Express/Fastify/Hono/NestJS).

Per-US test closure cadence for closing out NONE/PARTIAL P0 user stories in a project's QA-TRACKER.md. Class-level, applies to any project that uses the US ↔ Test 對照 tracker pattern (PM-System, crm-system, llm-acp, future projects). Trigger when a project's QA tracker shows rows with NONE / PARTIAL / DRAFT for P0 user stories, or when the user says "close out P0 US test gap", "Sprint N P0 test push", "做嗰啲 NONE 嘅 US", "ship 嗰啲 P0 test by test", or "audit NONE US". Per-US rhythm is audit source, write derive-or-source test, run + fix, commit + tracker sync + push. Distinct from a multi-axis code review (see `code-review-pipeline`) and from full Sprint retrospective writing.

為已有 project 補 / 重做 8 份結構性文檔(PROJECT-OVERVIEW / PRD / ARCHITECTURE / ADR / API / TEST-COVERAGE / TECH-DEBT / QA-TRACKER / REGRESSION-GUARD / retros) 以對齊 SOUL.md 紅線 10 + 11 + 12 + 13 + 14 + 16。Use when David 講「我補一下文檔」「補 doc」「對齊 red line 10」「project 缺 overview / PRD / QA tracker」或新接手 project 要一次過補齊結構。 Class-level — 適用於任何 project(backend / frontend / mobile / infra),不限特定 codebase。

記錄和追蹤技術債，幫忙估算修復時間。Template based，系統化追蹤優先級、修復成本、業務影響。

E2E test design patterns for Playwright + full-stack (Docker) apps — caller IP isolation vs backend rate limit (RG-008/RG-012 invariant), per-test setup hooks, Tiptap/ProseMirror rich-text-editor interaction patterns (ClipboardEvent + image/* File for paste, NOT innerHTML+dispatchEvent), graceful seed-data fallback (try-fixture → first-item → self-create), 4-option triage when a Playwright pre-existing failure reveals a real backend bug (default-to-fix over skip), 7-step diagnostic that starts with `git status` + `docker exec` source check, and "implementation vs tracker plan divergence" reconciliation. Trigger when designing E2E suites, debugging flaky 429s, testing Tiptap editors, writing fixtures, triaging pre-existing E2E failures, or when tracker plan says X but implementation does Y.

Systematically add unit test coverage to a project's P0 US with NONE/PARTIAL/PASS-E2E-only test status. Trigger when user says "test 未做的都要做", "補 unit test", "P0 US 全部要有 test", "紅線 12 守到", or asks to fix QA-TRACKER.md gaps. Class-level — covers any backend (Elysia/Express/Hono/Fastify/NestJS) or any TypeScript project with inline route logic. The 3-step playbook: parse QA-TRACKER + count P0 US, for each P0 US decide derive pure helper vs integration test vs DEFERRED (raise blocker EARLY for the third bucket), then commit series + tracker sync. Pairs with regression-guard, tech-debt-register, and code-review-pipeline.

Bun dev server requires --env-file flag to load .env; AWS SDK needs region env vars

Fix "401 Unauthorized" in Elysia.js when JWT tokens signed by auth routes are rejected by protected routes — caused by multiple JWT plugin instances.