# Standard Workflows

## PR Submission Process

1. Make changes on `config-YYYYMMDD-HHMM` branch
2. `git add` → `git commit` → `git push origin <branch>`
3. Create PR via GitHub API or gh CLI
4. After merge: `git checkout main && git pull origin main`
5. Immediately create new branch: `git checkout -b config-YYYYMMDD-HHMM`

## File Modification Process

1. All file changes must be made in the GitHub repo (`~/github/data-service-infra-ai-configurations/`)
2. Workspace points to repo files via symlinks
3. After changes: commit + PR, sync after merge

## Container Rebuild Process

1. Use `run.sh add/rebuild` (never `docker run` manually)
2. Must specify bridge network mode
3. Must copy auth-profiles.json during rebuild
4. rebuild must preserve existing app_id/app_secret

## Knowledge Base Update Mechanism

Knowledge accumulation uses **two triggers**:

### Trigger A: Problem Solved → Log Immediately
After any non-trivial fix, add an entry to `knowledge/debugging.md` right away.
```
## [Issue title]
- Symptom: ...
- Root cause: ...
- Fix: ...
- Prevention: ...
```
No separate step — just do it immediately after the fix.

### Trigger B: Weekly Review via Cron
A weekly cron (`cronjobs/team-admin/weekly-knowledge-review.py`) runs every Sunday at 22:00:
1. Pulls the past week's git commits
2. Compares against `knowledge/` to detect untracked learnings
3. If nothing new was added → sends alert to 王冰 asking for input
4. If new content found → appends summary to `knowledge/weekly-summary.md`

### Language Rule

All routine tasks use **Linux system crontab** (not OpenClaw built-in cron).

### How it works
A runner script (`cronjobs/run_cronjob_every_Nmins.py`) runs periodically and auto-discovers scripts in `cronjobs/team-admin/`:
```
*/10 * * * * cd ~/github/data-service-infra-ai-configurations && python3 cronjobs/run_cronjob_every_10mins.py >> /tmp/run-cronjob-10mins.log 2>&1
*/30 * * * * cd ~/github/data-service-infra-ai-configurations && python3 cronjobs/run_cronjob_every_30mins.py >> /tmp/run-cronjob-30mins.log 2>&1
0 21 * * * cd ~/github/data-service-infra-ai-configurations && python3 cronjobs/run_cronjob_daily.py >> /tmp/run-cronjob-daily.log 2>&1
```

### Adding a new cronjob
1. Drop a `.py` or `.sh` script into `cronjobs/team-admin/`
2. The runner will auto-discover and execute it — no crontab modification needed
3. Write cron interval as a comment at the top of the script file

## Team Employee Deployment Pattern
Source: skills/team-admin/team-employee/SKILL.md
- Use `run.sh add/rebuild` — never `docker run` manually
- **Always use bridge network mode** (not host mode) to avoid port conflicts with host Gateway
- Fixed port 18789 for rebuilt containers (consistent across all instances)
- When deploying: always mount `~/openclaw-team/shared-dir` as read-only into container
- Container home directory is auto-detected via test run + image inspection — no manual config needed

## Provider Switching Pattern
Source: skills/team-admin/switch-provider/SKILL.md
- For team members (container): switching provider triggers automatic container restart
- For current agent (me): provider switches immediately but requires manual `openclaw restart`
- Provider configs are preserved; only the active provider changes

## GitHub PR via App Authentication
Source: skills/team-admin/github-pr/SKILL.md
- Requires env vars: `GITHUB_APP_PRIVATE_KEY_PATH`, `GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`
- Flow: generate JWT → exchange for install token → use `gh pr create` with `GH_TOKEN`
- Always push branch before creating PR to avoid "Head sha can't be blank"

## Daily Inspection Session Aggregation
Source: cronjobs/team-admin/daily-inspection/README.md
- **Critical**: Must read both `.jsonl` and `.jsonl.reset.*` files — `.reset.*` files contain history after session reset, missing them loses historical data
- Date format: `YYYY-MM-DD`, day scope is UTC
- Multiple Feishu app credentials supported (accounts.main, accounts.explorer, etc.) — tries sequentially
- Some users may not be resolvable if they're in different Feishu orgs

## Container Environment Monitoring Pattern
Source: cronjobs/team-admin/container-env-check/README.md, cronjobs/team-admin/container-health-check/README.md
- 12 env vars monitored across 5 containers: JIRA_API_TOKEN, GRAFANA_API_TOKEN, AWS_BEARER_TOKEN_BEDROCK, AWS_REGION, ANTHROPIC_MODEL, CLAUDE_CODE_USE_BEDROCK, MINIMAX_API_KEY, GITHUB_REPO_LOC, GITHUB_APP_PRIVATE_KEY_PATH, GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID
- PEM file existence and content checked against host version
- Both checks run on `*/30 * * * *` (every 30 minutes) and alert to Feishu group oc_2c586abb5204eca2ddf6ddf5de338bf6 on mismatch/failure

## Backup Retention Pattern
Source: skills/team-admin/backup-config/SKILL.md
- Backups named `openclaw-config-YYYYMMDD-HHMMSS.tar.gz`
- Default retention: 7 days (configurable via `RETENTION_DAYS` in run.sh)
- Compresses all openclaw-* config directories in `~/openclaw-config/`

### Active cronjobs
| Script | Interval | Purpose |
|--------|----------|---------|
| `check-openclaw-status-alert.sh` | Every 30min | Container health + host metrics alert |
| `daily-report.sh` | Daily 21:00 | System daily report via Feishu bot |

## Language Rule

> **All documentation and code must be in English.** No exceptions. This includes:
> - README files
> - Knowledge base articles
> - Commit messages
> - PR descriptions
> - Comments in code
> - SOUL.md and AGENTS.md

If writing in Chinese is required, use a note to remind: "This content should be translated to English before committing."

---

## Crontab Architecture (CRITICAL)

### Structure
Three parallel crontab entries, one per team. Each sources `~/.bashrc` first to load Feishu app credentials:
```
*/10 * * * * . /home/ubuntu/.bashrc && cd ~/github/data-service-infra-ai-configurations && python3 cronjobs/run_cronjob_every_10mins.py team-admin >> /tmp/run-cronjob-10mins.log 2>&1
*/10 * * * * . /home/ubuntu/.bashrc && cd ~/github/data-service-infra-ai-configurations && python3 cronjobs/run_cronjob_every_10mins.py team-workflow >> /tmp/run-cronjob-workflow-10mins.log 2>&1
*/10 * * * * . /home/ubuntu/.bashrc && cd ~/github/data-service-infra-ai-configurations && python3 cronjobs/run_cronjob_every_10mins.py code-expert >> /tmp/run-cronjob-code-expert-10mins.log 2>&1
```

### Required env vars in ~/.bashrc (per team)
```bash
export CRONJOB_TEAM_ADMIN_APP_ID="cli_a..."
export CRONJOB_TEAM_ADMIN_APP_SECRET="..."
export CRONJOB_TEAM_WORKFLOW_APP_ID="cli_a..."
export CRONJOB_TEAM_WORKFLOW_APP_SECRET="..."
```

### How it works
1. System crontab fires the runner every 10 minutes
2. Runner reads `cronjobs/<team>/cronjob.json`
3. Matches jobs against current time using cron expression
4. Executes matching jobs and logs results
5. On failure: sends Feishu notification via `send_feishu_notification()`

### Adding a new cronjob
1. Create `cronjobs/<team>/<job-name>/` directory
2. Add script (Python or bash) inside
3. Register in `cronjobs/<team>/cronjob.json` with name, command, schedule (cron expr), description
4. Do NOT add a separate crontab entry — runner auto-discovers it

### ⚠️ Red Lines for crontab
- NEVER remove or overwrite the three runner crontab entries
- NEVER add individual job crontab entries — always register in cronjob.json
- NEVER point multiple runners at the same team (duplicate execution)