Skill: vt-mmm/employee-reminder-ops (version 1.0.1)

--- name: employee-reminder-ops description: Google Sheets-driven employee reminder and special-event reporting workflow for internal operations. Use when setting up or migrating birthday reminders, daily management reports, Telegram/Discord reminder routing, Google Sheets staff/event schemas, or scheduled reporting jobs that read Sheets and send summaries into team chats. --- # Employee Reminder Ops Use this skill when working on the internal reminder workflow currently called Plan A. ## What this skill covers - Read employee and special-event data from Google Sheets - Generate daily reminder reports - Route reminder reports into Telegram or Discord groups/channels - Configure scheduler/runtime for daily 7:00 AM reports - Migrate the workflow to another machine ## Core workflow 1. Load staff and event data from Google Sheets 2. Normalize dates and detect upcoming birthdays/events 3. Render one report message per day 4. Send the report to the mapped chat/group/channel 5. Avoid duplicate sends for the same day ## Current data model ### Google Sheet - Spreadsheet ID is deployment config, not hardcoded in the skill - Staff tab example: `Trang tính1` - Event tab example: `NgayDacBiet` ### Staff columns - `Mã NV` - `Họ và Tên` - `Bộ Phận` - `Loại hình nhân sự` - `Vị trí` - `Ngày sinh` ### Event columns - `STT` - `Tên sự kiện` - `Ngày diễn ra` - `Loại sự kiện` - `Bộ phận phụ trách` - `Ghi chú` - `Nhắc trước` - `Kích hoạt` ## Deployment guidance Read `references/deployment.md` when setting up on a new machine. ## Runtime/config boundary Keep these outside the skill package: - Google OAuth tokens - Telegram/Discord bot tokens - group/channel IDs - `.env*` - `.state/*` - logs Bundle only: - workflow scripts - schema notes - templates/examples - scheduler examples - `assets/windows/` example env file and PowerShell helper for Windows bring-up ## Included references - `references/architecture.md` - Plan A architecture and routing notes - `references/deployment.md` - install/migrate checklist - `references/google-sheet-schema.md` - canonical Sheet structure for staff/events - `references/clawhub.md` - publish/install/update commands via ClawHub - `references/troubleshooting.md` - common runtime/scheduler/data issues - `references/windows.md` - Windows-specific deployment notes - `references/macos.md` - macOS-specific deployment notes

path: references/PLAN_A_DEMO_USAGE.md
content: # PLAN_A_DEMO_USAGE.md

## Script

- File: `plan-a-demo.js`

## Mục đích

Script này:
- đọc dữ liệu từ Google Sheet qua `gog`
- dựng báo cáo Plan A
- có thể gửi thẳng vào Discord channel bằng bot token
- có mode production với state file chống gửi trùng cùng ngày

## Yêu cầu

- `gog` đã auth với tài khoản có quyền đọc sheet
- bot Discord đã ở trong server và có quyền gửi message vào channel đích
- có `DISCORD_BOT_TOKEN`

## Biến môi trường hỗ trợ

- `PLAN_A_SHEET_ID`
- `PLAN_A_STAFF_TAB`
- `PLAN_A_EVENTS_TAB`
- `PLAN_A_REMIND_DAYS`
- `PLAN_A_RUN_DATE`
- `DISCORD_CHANNEL_ID`
- `DISCORD_BOT_TOKEN`
- `GOG_ACCOUNT`
- `PLAN_A_STATE_DIR`
- `PLAN_A_STATE_FILE`
- `PLAN_A_ALLOW_RESEND_SAME_DAY=true`
- `PLAN_A_INCLUDE_INVALID_DETAILS=true`

## Mặc định hiện tại

- Sheet ID: [REDACTED_SECRET]
- Staff tab: `Trang tính1`
- Events tab: `NgayDacBiet`
- Remind days: `3`
- Discord channel: `1483444824895000697`
- Gog account: `[REDACTED_SECRET]`
- State file: `.state/plan-a-state.json`

## File env cục bộ

Có thể dùng file `.env.plan-a` ở workspace root để lưu cấu hình chạy thật cục bộ.
Lưu ý: đây là file local, không nên commit vào git public.

## Cách chạy

### 1. Xem preview báo cáo

```bash
node plan-a-demo.js preview
```

### 2. Xem JSON chi tiết

```bash
node plan-a-demo.js json
```

### 3. Gửi demo vào Discord thật

```bash
DISCORD_BOT_TOKEN='YOUR_BOT_TOKEN' node plan-a-demo.js send
```

### 4. Gửi theo mode production (chống gửi trùng cùng ngày)

```bash
DISCORD_BOT_TOKEN='YOUR_BOT_TOKEN' node plan-a-demo.js prod-send
```

## Giả lập ngày chạy

Ví dụ giả lập ngày `17/03/2026`:

```bash
PLAN_A_RUN_DATE=2026-03-17 node plan-a-demo.js preview
```

hoặc

```bash
PLAN_A_RUN_DATE=17/03/2026 node plan-a-demo.js preview
```

## Ví dụ production sau này

Khi chuyển từ test sang dữ liệu thật:

```bash
PLAN_A_STAFF_TAB='Trang tính1' \
PLAN_A_EVENTS_TAB='NgayDacBiet' \
DISCORD_BOT_TOKEN='YOUR_BOT_TOKEN' \
node plan-a-demo.js prod-send
```

## Logic production hiện tại

- Sinh nhật được tính theo ngày/tháng, bỏ qua năm sinh
- Rule global đang là nhắc trước 3 ngày
- Event dùng `Nhắc trước` riêng của từng dòng
- Dòng lỗi/thiếu dữ liệu bị bỏ qua khỏi báo cáo chính và được thống kê ở mục `Dữ liệu cần rà soát`
- Có state file để chống gửi trùng cùng ngày
- Nếu lỗi gửi hoặc lỗi đọc sheet, script ghi `lastError` vào state file
- Case 29/02 ở năm không nhuận hiện bị đánh dấu là dữ liệu cần rà soát

## Lưu ý bảo mật

- Không hardcode Discord bot token vào file
- Chỉ truyền token bằng biến môi trường khi chạy
- Nếu token từng bị lộ trong chat/log, nên rotate token sau khi test xong


path: references/architecture.md
content: # Plan A Architecture

## Purpose
Daily management/employee reporting based on Google Sheets.

## Inputs
- Google Sheets staff tab
- Google Sheets special-events tab

## Outputs
- Telegram management group or Discord test channel

## Rules
- Daily run at 7:00 AM local time
- Birthday comparison uses day/month, not birth year
- Special events use full date and optional remind-before setting
- Avoid duplicate sends on the same day

## Current implementation assets in workspace
- `plan-a-demo.js`
- `run-plan-a.sh`
- `com.flexclaw.plan-a.plist`
- `PLAN_A_TEST.md`
- `PLAN_A_DEMO_USAGE.md`

## Migration note
Abstract hardcoded paths into env variables when porting to a different machine.


path: references/clawhub.md
content: # ClawHub Publish / Install Notes

## Install CLI

```bash
npm i -g clawhub
```

## Login for publish

```bash
clawhub login
clawhub whoami
```

## Publish this skill

```bash
clawhub publish ./skills/employee-reminder-ops --slug employee-reminder-ops --name "Employee Reminder Ops" --version 1.0.0 --changelog "Initial release: Google Sheets reminder workflow, Telegram/Discord routing, scheduler notes"
```

## Install on a new machine

```bash
npm i -g clawhub
clawhub install employee-reminder-ops
```

## Upgrade

```bash
clawhub update employee-reminder-ops
```


path: references/google-sheet-schema.md
content: # Google Sheet Schema for Employee Reminder Ops

## Staff tab example
Suggested tab name:
- `Trang tính1`

### Required columns
- `Mã NV`
- `Họ và Tên`
- `Bộ Phận`
- `Loại hình nhân sự`
- `Vị trí`
- `Ngày sinh`

## Special event tab example
Suggested tab name:
- `NgayDacBiet`

### Required columns
- `STT`
- `Tên sự kiện`
- `Ngày diễn ra`
- `Loại sự kiện`
- `Bộ phận phụ trách`
- `Ghi chú`
- `Nhắc trước`
- `Kích hoạt`

## Date rules
- birthdays use `dd/MM/yyyy`
- birthday reminder logic compares day/month only
- special events use full event date


path: references/macos.md
content: # Employee Reminder Ops on macOS

## Hỗ trợ hiện tại
- Plan A reminder workflow: supported
- Google Sheets reading: supported
- current scheduler example in workspace uses `launchd`

## Runtime
- Node.js
- gog CLI

## Scheduler
- use `launchd`
- example plist already bundled in scripts

## Notes
macOS là môi trường hiện tại đã test Plan A nhiều nhất.


path: scripts/run-plan-a.sh
content: #!/bin/zsh
set -euo pipefail
cd /Users/vtammm/.openclaw/workspace
set -a
source ./.env.plan-a
set +a
/usr/bin/env node plan-a-demo.js prod-send


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (HIGH)