add SETUP_CHECKLIST.md: 12-phase implementation guide for new OC instances

README.md

@@ -7,6 +7,10 @@ agent) under the direction of [@sneak](https://sneak.berlin).
 
 ## What's Here
 
+- **[SETUP_CHECKLIST.md](SETUP_CHECKLIST.md)** — Step-by-step checklist for
+  configuring your own OpenClaw instance with these patterns. 12 phases from
+  workspace foundation through deployment pipelines. Start with Phases 1-4 for
+  80% of the value.
 - **[AUTOMATED_DEV.md](AUTOMATED_DEV.md)** — How self-hosted Gitea, Mattermost,
   Gitea Actions CI, and µPaaS connect into a continuous pipeline where code goes
   from PR to production automatically. Covers webhook-driven deployments,

SETUP_CHECKLIST.md

@@ -0,0 +1,631 @@
+# OpenClaw Setup Checklist
+
+A step-by-step guide to configuring your own OpenClaw instance with the patterns
+described in [OPENCLAW_TRICKS.md](OPENCLAW_TRICKS.md) and
+[AUTOMATED_DEV.md](AUTOMATED_DEV.md). Work through this in order — each section
+builds on the previous one.
+
+This checklist is designed to be handed to your agent. Copy the relevant
+sections into your workspace files and let the agent implement them.
+
+---
+
+## Phase 1: Workspace Foundation
+
+These are the core files every OpenClaw workspace needs. Create them in your
+workspace root.
+
+### 1.1 Create SOUL.md
+
+Tell your agent who it is. This sets personality, tone, and values.
+
+- [ ] Create `SOUL.md` in workspace root
+- [ ] Define the agent's communication style (concise? thorough? casual?)
+- [ ] Set boundaries (what it should and shouldn't do without asking)
+- [ ] Include the error handling philosophy: fix systems, not promises
+
+Reference:
+[OPENCLAW_TRICKS.md § Error handling philosophy](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+Example starting point:
+
+```markdown
+# SOUL.md
+
+Be genuinely helpful, not performatively helpful. Skip filler words. Have
+opinions. Be resourceful before asking — try to figure it out, then ask if
+stuck. Bias toward action.
+
+When something goes wrong: identify what input caused the wrong output, fix the
+input (rule, checklist, prompt, automation), move on. No apologies, no promises.
+Fix the system.
+
+Never cheat. When a check fails, fix the code — don't weaken the check.
+```
+
+### 1.2 Create USER.md
+
+Tell your agent about you.
+
+- [ ] Create `USER.md` in workspace root
+- [ ] Name, preferred name, timezone
+- [ ] Communication preferences (direct? verbose? brief?)
+- [ ] Any standing rules ("don't ask too many questions, just figure it out")
+
+### 1.3 Create IDENTITY.md
+
+Let the agent define itself.
+
+- [ ] Create `IDENTITY.md` in workspace root
+- [ ] Name, emoji, vibe — let the agent fill these in during first conversation
+
+### 1.4 Create the memory directory
+
+- [ ] `mkdir -p memory/` in workspace root
+- [ ] Create `memory/daily-context.json` with initial state (see Phase 2)
+
+### 1.5 Create AGENTS.md
+
+This is the master file — responsibilities, rules, session startup procedure.
+
+- [ ] Create `AGENTS.md` in workspace root
+- [ ] Add session startup sequence:
+
+```markdown
+## Every Session
+
+Before doing anything else:
+
+1. Read `SOUL.md`
+2. Read `USER.md`
+3. Read `memory/daily-context.json`
+4. Read `memory/YYYY-MM-DD.md` (today + yesterday)
+5. If in main session: Also read `MEMORY.md`
+
+Don't ask permission. Just do it.
+```
+
+- [ ] Add the "Write It Down" rule:
+
+```markdown
+### Write It Down — No "Mental Notes"!
+
+- Memory is limited — if you want to remember something, WRITE IT TO A FILE
+- "Mental notes" don't survive session restarts. Files do.
+- Text > Brain
+```
+
+- [ ] Add the requirement capture rule:
+
+```markdown
+### Requirement Capture (MANDATORY)
+
+Every single requirement, rule, preference, or instruction you provide MUST be
+captured in the daily memory file immediately. If in doubt, log it.
+```
+
+### 1.6 Create MEMORY.md
+
+- [ ] Create `MEMORY.md` in workspace root
+- [ ] Add a checklist index at the top (you'll populate this as you add
+      checklists):
+
+```markdown
+## ⛔ CHECKLISTS (read the relevant file before acting)
+
+- **Any PR/code work** → `memory/checklist-pr.md`
+- **Any message to user** → `memory/checklist-messaging.md`
+- (add more as you create them)
+```
+
+- [ ] Add security rule: only load MEMORY.md in private sessions (not group
+      chats)
+
+---
+
+## Phase 2: Daily Context State File
+
+The single most important file. Every session reads it on every message.
+
+### 2.1 Create the initial state file
+
+- [ ] Create `memory/daily-context.json`:
+
+```json
+{
+    "isSleeping": false,
+    "lastKnownWakeTime": null,
+    "predictedSleepTime": null,
+    "predictedWakeTime": null,
+    "currentLocation": "Your City (IATA)",
+    "currentTimezone": "America/Your_Timezone",
+    "lastMessageFromUser": null,
+    "isAvailable": true,
+    "lastUpdated": null
+}
+```
+
+- [ ] Add fields relevant to your use case (medications, caffeine, travel, etc.)
+
+### 2.2 Add timezone rules to AGENTS.md
+
+- [ ] Add:
+
+```markdown
+## Timezone/Time Rules
+
+- System clock may differ from user's timezone — always check daily-context.json
+- "Today"/"tomorrow" = user's local TZ, not system clock
+- Never state times without explicit conversion
+```
+
+Reference:
+[OPENCLAW_TRICKS.md § Location & Timezone Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+---
+
+## Phase 3: Memory Architecture
+
+### 3.1 Set up daily files
+
+- [ ] Agent should create `memory/YYYY-MM-DD.md` for each day
+- [ ] Each daily file should have a topics table:
+
+```markdown
+## Topics
+
+| Time | Topic |
+| ---- | ----- |
+|      |       |
+```
+
+- [ ] Add to AGENTS.md: "Append a one-line topic summary after every meaningful
+      conversation"
+
+### 3.2 Set up memory maintenance
+
+- [ ] Add to AGENTS.md or HEARTBEAT.md:
+
+```markdown
+### Memory Maintenance (During Heartbeats)
+
+Periodically (every few days):
+
+1. Read through recent daily files
+2. Identify significant events, lessons, insights
+3. Update MEMORY.md with distilled learnings
+4. Remove outdated info from MEMORY.md
+```
+
+---
+
+## Phase 4: Heartbeat Configuration
+
+### 4.1 Create HEARTBEAT.md
+
+- [ ] Create `HEARTBEAT.md` in workspace root
+- [ ] Add checks relevant to your workflow (inbox, calendar, projects, etc.)
+- [ ] Add output rules:
+
+```markdown
+## Output Rules
+
+- HEARTBEAT_OK if nothing needs attention
+- Direct question or alert if action needed
+- Work narration → send to a status channel, not user's DM
+```
+
+### 4.2 Create heartbeat state tracking
+
+- [ ] Create `memory/heartbeat-state.json`:
+
+```json
+{
+    "lastChecks": {},
+    "lastWeeklyDocsReview": null
+}
+```
+
+### 4.3 Set up workspace sync
+
+- [ ] Add to HEARTBEAT.md: "Commit and push any uncommitted workspace changes"
+- [ ] See [Phase 8](#phase-8-workspace-as-git-repo) for full git setup
+
+---
+
+## Phase 5: Checklists
+
+Create checklists for your most common actions. The pattern: AGENTS.md
+references the checklist, agent reads it before acting.
+
+### 5.1 Messaging checklist
+
+- [ ] Create `memory/checklist-messaging.md`:
+
+```markdown
+# Messaging Checklist
+
+## Before EVERY message to user
+
+1. PR/issue mentioned? → Full clickable URL required
+2. URL included? → Verify it resolves before sending
+3. Time/date stated? → Convert to user's current TZ
+4. Status claim? → Verify via API call, not memory
+5. "Today"/"tomorrow"? → Resolve in user's local TZ
+```
+
+### 5.2 PII output routing
+
+- [ ] Add to AGENTS.md (top, as a warning banner):
+
+```markdown
+**⚠️ NEVER output PII in non-private channels.** If asked for PII-containing
+info in a shared channel, send via DM instead.
+```
+
+- [ ] Create channel-specific rule files as needed (e.g.,
+      `memory/CHANNEL_RULES.md`)
+
+Reference:
+[OPENCLAW_TRICKS.md § PII Output Routing](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+### 5.3 Additional checklists (as needed)
+
+- [ ] `memory/checklist-pr.md` — for code review and PR work
+- [ ] `memory/checklist-medications.md` — for medication tracking
+- [ ] `memory/checklist-flights.md` — for travel/flight management
+- [ ] Any domain-specific checklists for your workflow
+
+### 5.4 Update MEMORY.md checklist index
+
+- [ ] Ensure every checklist file is referenced in the MEMORY.md index at the
+      top
+
+---
+
+## Phase 6: Sitrep
+
+### 6.1 Define your sitrep
+
+- [ ] Add to AGENTS.md:
+
+```markdown
+### Sitrep (Situation Report)
+
+When user says "sitrep", provide a concise summary covering:
+
+1. (your items — meds, calendar, tasks, travel, etc.)
+
+**If anything notable isn't covered by the items above — recent lessons, pending
+decisions, things you think the user should know about — add additional sections
+as needed.**
+
+Omit any item that is "none" or zero. Keep it scannable. Use bullet points, not
+prose.
+```
+
+- [ ] Customize the items to your life (remove what doesn't apply, add what
+      does)
+- [ ] The "add additional sections" line is key — it lets the agent surface
+      things you didn't think to ask about
+
+Reference:
+[OPENCLAW_TRICKS.md § Sitrep](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+---
+
+## Phase 7: Tracking Systems (Optional)
+
+Add whichever tracking systems are relevant to you. Each follows the same
+pattern: a CSV/JSON log file, an instructions file, and a checklist.
+
+### 7.1 Sleep tracking
+
+- [ ] Create `memory/sleep-log.csv` with headers:
+      `Date,SleepTime,WakeTime,TimeZone,Duration,Status,Notes`
+- [ ] Add sleep tracking instructions to AGENTS.md
+- [ ] Add sleep fields to daily-context.json (`isSleeping`, `lastKnownWakeTime`,
+      `predictedSleepTime`, etc.)
+
+Reference:
+[OPENCLAW_TRICKS.md § Sleep Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+### 7.2 Medication tracking
+
+- [ ] Create `memory/medications-instructions.md` with your medication list,
+      dosages, schedules, and safety rules
+- [ ] Create `memory/medications-log-YYYY-MM.csv` with headers:
+      `Date,Time,TimeZone,Medication,Dosage`
+- [ ] Create `memory/checklist-medications.md`
+- [ ] Add medication fields to daily-context.json (`hasTakenDailyMedsToday`,
+      `dailyMedsTimestamp`, etc.)
+- [ ] Set up overdue escalation (ntfy or similar push notification)
+
+Reference:
+[OPENCLAW_TRICKS.md § Medication Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+### 7.3 Location & travel tracking
+
+- [ ] Create `memory/location-log.csv` with headers:
+      `Date,City,Country,Timezone`
+- [ ] Create `memory/flight-log.csv` with headers:
+      `Date,FlightNumber,Origin,Destination,Duration,Alliance`
+- [ ] Create `memory/landing-checklist.md`
+- [ ] Create `memory/travel.md` for upcoming trip plans
+
+Reference:
+[OPENCLAW_TRICKS.md § Flight & Travel Logging](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+### 7.4 Urgent notifications
+
+- [ ] Set up an ntfy.sh topic (or similar push notification channel)
+- [ ] Add to AGENTS.md:
+
+```markdown
+## Urgent Notifications
+
+Send urgent messages via ntfy.sh:
+
+    curl -d "MESSAGE HERE" ntfy.sh/YOUR-PRIVATE-TOPIC-ID
+
+Never send PII via ntfy. Keep messages generic.
+```
+
+---
+
+## Phase 8: Workspace as Git Repo
+
+### 8.1 Initialize the state repo
+
+- [ ] `cd workspace && git init`
+- [ ] Create a PRIVATE repo on your git host (Gitea, GitHub, etc.)
+- [ ] `git remote add origin <url>`
+- [ ] Initial commit and push
+
+### 8.2 Configure auto-sync
+
+- [ ] Add to AGENTS.md:
+
+```markdown
+### State Repo
+
+- Commit and push workspace changes after any change to workspace files
+- Push promptly — remote should reflect workspace in near-realtime
+```
+
+- [ ] Set up a cron job as safety net (every 4-6 hours):
+
+```bash
+cd /path/to/workspace && git add -A && git commit -m "auto-sync" && git push
+```
+
+(Yes, `git add -A` is acceptable here — the workspace repo is a state mirror,
+not a development repo.)
+
+### 8.3 Exclude code repos
+
+- [ ] Clone code repos OUTSIDE the workspace directory
+- [ ] Add a note to AGENTS.md about where to clone repos
+
+Reference:
+[OPENCLAW_TRICKS.md § The Workspace as a Git Repo](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+
+---
+
+## Phase 9: Git Quality Standards (For Development Work)
+
+If your agent does coding work, set up the interlocking check system.
+
+### 9.1 Adopt repo policies
+
+- [ ] Fetch
+      [REPO_POLICIES.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
+      and add to each of your code repos
+- [ ] Fetch
+      [NEW_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md)
+      for new repos
+- [ ] Fetch
+      [EXISTING_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md)
+      for existing repos
+
+### 9.2 Set up PR quality gate
+
+- [ ] Create `memory/checklist-pr.md`:
+
+```markdown
+# PR Checklist
+
+## Before pushing to a branch
+
+1. Associated PR is still open?
+2. `make check` passes locally?
+3. `docker build .` passes locally (if Dockerfile exists)?
+4. Formatter passes?
+5. No linter config / Makefile changes in diff?
+6. All external refs pinned by SHA?
+
+## After sub-agent pushes code
+
+1. Check diff for linter / test config changes
+2. Check diff for `-short` / `-timeout` flags added
+3. If any config files changed unexpectedly: reject and rework
+
+## PR pipeline (every PR, no exceptions)
+
+1. Review/rework loop until clean
+2. Check/rework loop until clean
+3. Only then: assign to human
+```
+
+### 9.3 Set up branch protection
+
+- [ ] Enable branch protection on `main` for each repo:
+    - [ ] Require pull request reviews before merging
+    - [ ] Require CI status checks to pass
+    - [ ] Block force-pushes
+    - [ ] Require branches to be up-to-date before merging
+
+Reference:
+[AUTOMATED_DEV.md § Branch Protection](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)
+
+### 9.4 Set up Makefile standards
+
+- [ ] Every repo gets a Makefile with: `test`, `lint`, `fmt`, `fmt-check`,
+      `check`, `docker`, `hooks`
+- [ ] `make check` depends on `test`, `lint`, `fmt-check`
+- [ ] Dockerfile runs `make check` as a build step
+- [ ] CI workflow runs `docker build .`
+
+Reference:
+[AUTOMATED_DEV.md § The Interlocking Chain](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md),
+[REPO_POLICIES.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
+
+---
+
+## Phase 10: Gitea Integration (Optional)
+
+If you use Gitea (or a similar self-hosted git platform) for issue tracking and
+code review.
+
+### 10.1 Create a bot account
+
+- [ ] Create a dedicated Gitea user for the agent (e.g., `clawbot`)
+- [ ] Generate an API token for the bot user
+- [ ] Store the token in TOOLS.md (workspace-only, never in code repos)
+- [ ] Grant write access to repos the agent should be able to push to directly
+- [ ] For other repos: the agent forks and creates PRs
+
+### 10.2 Set up the notification poller
+
+- [ ] Deploy the Gitea notification poller script (source in
+      [OPENCLAW_TRICKS.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md))
+- [ ] Configure env vars: `GITEA_URL`, `GITEA_TOKEN`, `HOOK_TOKEN`
+- [ ] Run as a system service (launchd on macOS, systemd on Linux)
+- [ ] Verify: create a test issue, confirm the agent wakes and processes it
+
+### 10.3 Set up webhook feed
+
+- [ ] Add a Gitea webhook to each repo (or use a global/org webhook)
+- [ ] Point webhooks at your Mattermost/Slack/Discord incoming webhook URL
+- [ ] Verify: push a commit, confirm it appears in the activity channel
+
+### 10.4 Configure issue workflow
+
+- [ ] Add to AGENTS.md:
+
+```markdown
+## Gitea Work Scope
+
+Find issues/PRs assigned to me → do the work.
+
+- If @-mentioned with work but not assigned → assign myself
+- When nothing assigned to me, my Gitea work is done
+- Respond in the medium addressed: Gitea → Gitea comment
+
+Workflow: issue → branch → PR "(closes #X)" → review/rework → assign human when
+all checks pass.
+```
+
+### 10.5 Set up PR state machine labels
+
+- [ ] Create labels on each repo:
+    - `needs-rebase` (red)
+    - `needs-checks` (orange)
+    - `needs-review` (yellow)
+    - `needs-rework` (purple)
+    - `merge-ready` (green)
+- [ ] Add state machine rules to AGENTS.md or a dedicated
+      `memory/pr-pipeline.md`
+
+Reference:
+[AUTOMATED_DEV.md § PR State Machine](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)
+
+---
+
+## Phase 11: Deployment Pipeline (Optional)
+
+If you want push-to-deploy for your services.
+
+### 11.1 Set up µPaaS (or equivalent)
+
+- [ ] Deploy [µPaaS](https://git.eeqj.de/sneak/upaas) by
+      [@sneak](https://sneak.berlin) on your server
+- [ ] Configure Traefik (or your reverse proxy) for automatic TLS
+- [ ] Create deploy keys (read-only SSH) for each repo
+
+### 11.2 Wire up webhooks
+
+- [ ] Add Gitea webhooks pointing to µPaaS for repos that should auto-deploy
+- [ ] Configure which branch triggers deployment (typically `main` or `prod`)
+- [ ] Test: merge a PR, verify the service updates automatically
+
+Reference:
+[AUTOMATED_DEV.md § Deployment: µPaaS](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)
+
+---
+
+## Phase 12: Group Chat Rules (If Applicable)
+
+If your agent participates in group chats.
+
+### 12.1 Add group chat behavior
+
+- [ ] Add to AGENTS.md:
+
+```markdown
+### Know When to Speak
+
+Respond when: directly mentioned, can add genuine value, correcting
+misinformation.
+
+Stay silent when: casual banter, someone already answered, your response would
+just be "yeah" or "nice".
+
+Quality > quantity. If you wouldn't send it in a real group chat with friends,
+don't send it.
+```
+
+### 12.2 Set up per-channel rules
+
+- [ ] Create `memory/CHANNEL_NAME.md` for channels with specific rules
+- [ ] Add a reference line to AGENTS.md:
+      `**⚠️ #channel → read memory/CHANNEL_NAME.md first**`
+- [ ] Define what's shareable and what's private per channel
+
+---
+
+## Verification
+
+After completing the phases relevant to you:
+
+- [ ] Start a new session and verify the agent reads all startup files
+- [ ] Ask for a sitrep and verify it covers your configured items
+- [ ] Test PII routing: ask for sensitive info in a group channel, verify it
+      redirects to DM
+- [ ] If using Gitea: create a test issue assigned to the agent, verify it picks
+      it up
+- [ ] If using git quality gates: push a branch with a formatting error, verify
+      CI catches it
+- [ ] Verify workspace git repo has recent commits
+
+---
+
+## Reference Documents
+
+- [OPENCLAW_TRICKS.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
+  — Configuration recipes, failure stories, detailed schemas
+- [AUTOMATED_DEV.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)
+  — Git pipeline, CI, deployment, state machine
+- [REPO_POLICIES.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
+  — Repository structure and tooling standards
+- [NEW_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md)
+  — Step-by-step for new repos
+- [EXISTING_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md)
+  — Step-by-step for existing repos
+- [OpenClaw docs](https://docs.openclaw.ai) — Official documentation
+- [OpenClaw GitHub](https://github.com/openclaw/openclaw) — Source code
+
+---
+
+_Start with Phases 1-4 (workspace foundation, daily context, memory, heartbeat).
+These give you 80% of the value. Add the remaining phases as your needs grow._