From b0495d5b564ddaf6c6a1ad1455662788bc08b9b7 Mon Sep 17 00:00:00 2001 From: user Date: Sat, 28 Feb 2026 03:22:08 -0800 Subject: [PATCH] rewrite SETUP_CHECKLIST.md: replace checklist items with paste-able agent prompts Each section now contains a self-contained prompt in a code block that adopting users can paste directly to their agent. Prompts include full URLs to raw reference docs. Fixes 'you provide' wording to 'your human provides'. Keeps same phase/section structure. --- SETUP_CHECKLIST.md | 960 +++++++++++++++++++++++++++++---------------- 1 file changed, 613 insertions(+), 347 deletions(-) diff --git a/SETUP_CHECKLIST.md b/SETUP_CHECKLIST.md index a2aca97..a565120 100644 --- a/SETUP_CHECKLIST.md +++ b/SETUP_CHECKLIST.md @@ -2,199 +2,258 @@ 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. +[AUTOMATED_DEV.md](AUTOMATED_DEV.md). -This checklist is designed to be handed to your agent. Copy the relevant -sections into your workspace files and let the agent implement them. +Each section contains a **prompt you can paste directly to your agent**. The +prompts are self-contained — your agent should be able to execute each one +without additional context. Work through them in order; each phase builds on the +previous one. --- ## Phase 1: Workspace Foundation -These are the core files every OpenClaw workspace needs. Create them in your -workspace root. +These are the core files every OpenClaw workspace needs. ### 1.1 Create SOUL.md -Tell your agent who it is. This sets personality, tone, and values. +This defines your agent's personality, tone, and values. Paste this to your +agent: -- [ ] 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 +``` +Create a SOUL.md file in the workspace root. This is who you are as an +agent. Include: -Reference: -[OPENCLAW_TRICKS.md § Error handling philosophy](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +- Communication style: concise, direct, no filler. Have opinions. Be + resourceful before asking. +- Error handling philosophy: 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. +- Integrity rules: never weaken checks to make things pass. When a check + fails, fix the code, not the check. +- Bias toward action: try to figure it out first, then ask if stuck. -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. +Reference for philosophy and examples: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md ``` ### 1.2 Create USER.md -Tell your agent about you. +This tells your agent about you — the human it's helping. Paste this to your +agent: -- [ ] 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") +``` +Create a USER.md file in the workspace root. Your human provides the +following info — ask them if not already known: + +- Name and preferred name +- Current timezone +- Communication preferences (direct? verbose? brief?) +- Standing rules (e.g. "don't ask too many questions, just figure it + out", "always confirm before sending emails") + +Keep it concise. This file is read every session. +``` ### 1.3 Create IDENTITY.md -Let the agent define itself. +Let the agent define itself. Paste this to your agent: -- [ ] Create `IDENTITY.md` in workspace root -- [ ] Name, emoji, vibe — let the agent fill these in during first conversation +``` +Create an IDENTITY.md file in the workspace root. This is YOUR identity +— fill it in yourself. Include: + +- Your chosen name (or accept what your human calls you) +- An emoji that represents you +- Your vibe / personality in a sentence +- Anything else that makes you YOU + +This is not instructions — it's self-expression. Make it yours. +``` ### 1.4 Create the memory directory -- [ ] `mkdir -p memory/` in workspace root -- [ ] Create `memory/daily-context.json` with initial state (see Phase 2) +This is where all state and logs live. Paste this to your agent: -### 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. ``` +Set up the memory directory structure: -- [ ] Add the "Write It Down" rule: +1. Create the directory: mkdir -p memory/ +2. Create memory/daily-context.json with this initial structure: -```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", + "currentLocation": null, + "currentTimezone": null, "lastMessageFromUser": null, "isAvailable": true, "lastUpdated": null } + +3. Create today's daily file: memory/YYYY-MM-DD.md (use actual date) + with a Topics table: + +## Topics + +| Time | Topic | +| ----- | ----- | +| | | + +## Notes + +Your human will tell you what fields to add to daily-context.json for +their specific needs (medications, travel, etc.). ``` -- [ ] Add fields relevant to your use case (medications, caffeine, travel, etc.) +### 1.5 Create AGENTS.md -### 2.2 Add timezone rules to AGENTS.md +This is the master configuration file — responsibilities, rules, and session +startup procedure. Paste this to your agent: -- [ ] Add: +``` +Create an AGENTS.md file in the workspace root. This is your operating +manual. Include the following sections: + +## Every Session + +Before doing anything else: +1. Read SOUL.md — this is who you are +2. Read USER.md — this is who you're helping +3. Read memory/daily-context.json — current state +4. Read memory/YYYY-MM-DD.md (today + yesterday) for recent context +5. If in main session: Also read MEMORY.md + +Don't ask permission. Just do it. + +## 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. +- When someone says "remember this" → update memory/YYYY-MM-DD.md or + relevant file +- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant + config +- Text > Brain + +## Requirement Capture (MANDATORY) + +Every single requirement, rule, preference, or instruction your human +provides MUST be captured in the daily memory file immediately. This +includes: project rules, workflow preferences, corrections, new +policies, technical decisions. If in doubt, log it. + +## Topic Log Maintenance + +Append a one-line summary to the Topics table in today's +memory/YYYY-MM-DD.md after every meaningful conversation or topic +change. Do this continuously as conversations happen. + +## Safety + +- Don't exfiltrate private data. Ever. +- Don't run destructive commands without asking. +- trash > rm (recoverable beats gone forever) +- When in doubt, ask. + +Reference for detailed patterns: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +``` + +### 1.6 Create MEMORY.md + +This is long-term curated memory — distilled insights, not raw logs. Paste this +to your agent: + +``` +Create a MEMORY.md file in the workspace root. This is your long-term +memory — curated, not raw. Include: + +1. A checklist index at the top (populate as you add checklists): + +## 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) + +2. A security rule: + +**Only load MEMORY.md in private/main sessions.** Never load it in group +chats or shared contexts — it contains personal information. + +3. Leave space below for curated memories. Over time, review daily files +and distill significant events, lessons, and decisions here. + +Reference for memory architecture: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Memory Architecture" and "MEMORY.md — Long-term curated memory") +``` + +--- + +## Phase 2: Daily Context State File + +The single most important runtime file. Every session reads it on every message. + +### 2.1 Add timezone rules + +Time bugs are the most common agent mistake. Paste this to your agent: + +``` +Add a "Timezone/Time Rules" section to AGENTS.md: -```markdown ## Timezone/Time Rules -- System clock may differ from user's timezone — always check daily-context.json +- 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 -``` +- Never state times without explicit timezone conversion +- When displaying times, show in user's local timezone first, then + UTC if relevant + +Also: review the daily-context.json file and update currentTimezone +and currentLocation based on what you know about your human. Ask if +you don't know. Reference: -[OPENCLAW_TRICKS.md § Location & Timezone Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Location & Timezone Tracking") +``` --- ## Phase 3: Memory Architecture -### 3.1 Set up daily files +### 3.1 Set up daily files and memory maintenance -- [ ] Agent should create `memory/YYYY-MM-DD.md` for each day -- [ ] Each daily file should have a topics table: +The two-tier memory system: daily files for raw logs, MEMORY.md for curated +insights. Paste this to your agent: -```markdown -## Topics - -| Time | Topic | -| ---- | ----- | -| | | ``` +Add a "Memory Maintenance" section to AGENTS.md (or HEARTBEAT.md if +you already have one): -- [ ] 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 +1. Read through recent memory/YYYY-MM-DD.md files +2. Identify significant events, lessons, insights worth keeping 3. Update MEMORY.md with distilled learnings 4. Remove outdated info from MEMORY.md + +Daily files are raw notes; MEMORY.md is curated wisdom. Think of it +like reviewing a journal and updating your mental model. + +Also verify that today's daily file exists and has a Topics table. If +not, create it now. + +Reference for the full memory architecture: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Memory Architecture", "Daily files", and "Memory maintenance") ``` --- @@ -203,83 +262,136 @@ Periodically (every few days): ### 4.1 Create HEARTBEAT.md -- [ ] Create `HEARTBEAT.md` in workspace root -- [ ] Add checks relevant to your workflow (inbox, calendar, projects, etc.) -- [ ] Add output rules: +Heartbeats let your agent be proactive — checking on things periodically without +being asked. Paste this to your agent: + +``` +Create a HEARTBEAT.md file in the workspace root. This is your +proactive checklist — things to check when you receive a heartbeat +poll. Structure it like this: + +## Checks (rotate through these, 2-4 times per day) + +- Emails — any urgent unread messages? +- Calendar — upcoming events in next 24-48h? +- Open issues/PRs — anything assigned to me? +- Workspace sync — any uncommitted changes to push? + +## Rules + +- Late night (23:00-08:00 user local time): only act on urgent items +- If nothing needs attention: reply HEARTBEAT_OK +- Work narration goes to a status channel, not user's DM +- Don't respond multiple times to the same trigger -```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 -``` +- Direct message to user only if action needed or urgent +- Status updates → dedicated channel (not DM) -### 4.2 Create heartbeat state tracking +Also create memory/heartbeat-state.json: -- [ ] Create `memory/heartbeat-state.json`: - -```json { "lastChecks": {}, "lastWeeklyDocsReview": null } + +Customize the checks list based on what's relevant to your human. +Remove what doesn't apply, add what does. + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Heartbeat Configuration" and "Heartbeat vs Cron") ``` -### 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. +Checklists prevent the most common agent mistakes. AGENTS.md references them; +the agent reads the checklist before acting. ### 5.1 Messaging checklist -- [ ] Create `memory/checklist-messaging.md`: +Prevents broken links, wrong timezones, and stale claims. Paste this to your +agent: + +``` +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 +3. Time/date stated? → Convert to user's current TZ (check + daily-context.json) 4. Status claim? → Verify via API call, not memory -5. "Today"/"tomorrow"? → Resolve in user's local TZ +5. "Today"/"tomorrow"? → Resolve in user's local TZ, not system clock + +Then add a reference to this checklist in the MEMORY.md checklist index. + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "PII Output Routing" and "Checklists Over Prose") ``` ### 5.2 PII output routing -- [ ] Add to AGENTS.md (top, as a warning banner): +Prevents leaking private info in shared channels. Paste this to your agent: -```markdown -**⚠️ NEVER output PII in non-private channels.** If asked for PII-containing -info in a shared channel, send via DM instead. ``` +Add the following warning banner near the TOP of AGENTS.md (before the +session startup section): -- [ ] Create channel-specific rule files as needed (e.g., - `memory/CHANNEL_RULES.md`) +**⚠️ NEVER output PII in non-private channels.** If asked for +PII-containing info (medical, financial, personal) in a shared channel, +send via DM to your human instead. + +Also add a PII section to memory/checklist-messaging.md: + +## PII Check (before every message in shared channels) + +1. Contains names, addresses, medical info, financial info? → DM only +2. Contains login credentials or tokens? → NEVER send, period +3. When in doubt → send via DM Reference: -[OPENCLAW_TRICKS.md § PII Output Routing](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "PII-Aware Output Routing") +``` -### 5.3 Additional checklists (as needed) +### 5.3 Additional checklists -- [ ] `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 +Create checklists for your specific workflow. Paste this to your agent: -### 5.4 Update MEMORY.md checklist index +``` +Review the following checklist templates and create any that are +relevant to your human's workflow. Ask your human which ones apply: -- [ ] Ensure every checklist file is referenced in the MEMORY.md index at the - top +- memory/checklist-pr.md — for code review and PR work. Key rules: + make check must pass with ZERO failures, never modify linter config + to make checks pass, rebase before pushing. + +- memory/checklist-medications.md — for medication tracking (if + applicable) + +- memory/checklist-flights.md — for travel/flight management (if + applicable) + +For each checklist created, add a reference line to the MEMORY.md +checklist index at the top. + +Reference for PR checklist patterns: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Git Quality Standards" and "Sub-Agent PR Quality Gate") + +Reference for medication checklist: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Medication Tracking") +``` --- @@ -287,88 +399,167 @@ Reference: ### 6.1 Define your sitrep -- [ ] Add to AGENTS.md: +The sitrep gives your human a scannable status overview on demand. Paste this to +your agent: + +``` +Add a "Sitrep" section to AGENTS.md: -```markdown ### Sitrep (Situation Report) -When user says "sitrep", provide a concise summary covering: +When your human says "sitrep", provide a concise summary. Include items +relevant to your setup — choose from: -1. (your items — meds, calendar, tasks, travel, etc.) +1. Current time (user's local TZ + UTC) +2. Open tasks/issues assigned to you +3. Open tasks/issues assigned to your human +4. Upcoming calendar events (next 48h) +5. Upcoming travel (next 72h + next known flight) +6. Medication status (if tracking) +7. Sleep summary (if tracking) +8. Weather alerts (if relevant) +9. Overdue reminders +10. Unanswered questions from your human -**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.** +Rules: +- Omit any item that is "none" or zero +- Keep it scannable — bullet points, not prose +- Don't recap things your human was directly involved in +- If anything notable isn't covered above, add additional sections +- When listing PRs/issues, always include full clickable URLs -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 +Customize this list: remove what doesn't apply to your human, add what +does. The "add additional sections" line is key — it lets you surface +things your human didn't think to ask about. Reference: -[OPENCLAW_TRICKS.md § Sitrep](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Sitrep (Situation Report)") +``` --- ## 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. +Add whichever tracking systems are relevant. 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.) +Paste this to your agent: + +``` +Set up sleep tracking. Create the following: + +1. memory/sleep-log.csv with headers: + Date,SleepTime,WakeTime,TimeZone,Duration,Status,Notes + +2. Add sleep tracking rules to AGENTS.md: + +### Sleep Tracking +- Infer sleep/wake times from message activity and explicit statements +- Log based on observed communication gaps, never from mathematical + predictions alone +- Update daily-context.json isSleeping field accordingly +- Sleep start = last activity before gap, wake = first activity after + +3. Add sleep fields to daily-context.json if not already present: + isSleeping, lastKnownWakeTime, predictedSleepTime, predictedWakeTime Reference: -[OPENCLAW_TRICKS.md § Sleep Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Sleep Tracking") +``` ### 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) +Paste this to your agent: + +``` +Set up medication tracking. Your human provides the medication list, +dosages, and schedules. Create: + +1. memory/medications-instructions.md — ask your human for their + medication list, dosages, frequency, and any safety rules (e.g. + interactions, maximum doses). Structure with sections: General Rules, + Daily Medications, Interval-Based Medications, Safety Rules. + +2. memory/medications-log-YYYY-MM.csv (current month) with headers: + Date,Time,TimeZone,Medication,Dosage + +3. memory/checklist-medications.md with verification steps: + - Before reporting status: verify against the CSV, not memory + - Before sending reminders: check if already taken today + - Overdue escalation: use push notification (ntfy or similar) + +4. Add medication fields to daily-context.json: + hasTakenDailyMedsToday, dailyMedsTimestamp + +5. Add the checklist to MEMORY.md's checklist index. Reference: -[OPENCLAW_TRICKS.md § Medication Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Medication Tracking") +``` -### 7.3 Location & travel tracking +### 7.3 Location and 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 +Paste this to your agent: + +``` +Set up location and travel tracking. Create: + +1. memory/location-log.csv with headers: + Date,City,Country,Timezone + +2. memory/flight-log.csv with headers: + Date,FlightNumber,Origin,Destination,Duration,Alliance + +3. memory/travel.md — for upcoming trip plans and unbooked flights + +4. memory/landing-checklist.md — things to do after every flight: + - Update daily-context.json location and timezone + - Update location-log.csv + - Log the flight in flight-log.csv + - Check for country-specific actions (SIM, currency, etc.) + +5. Add to AGENTS.md: + +### Landing Checklist +After EVERY flight, run through memory/landing-checklist.md. Trigger: +calendar event landing time or human messages after a flight. Do not +wait to be asked. Reference: -[OPENCLAW_TRICKS.md § Flight & Travel Logging](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Flight & Travel Logging" and "Landing Checklist") +``` ### 7.4 Urgent notifications -- [ ] Set up an ntfy.sh topic (or similar push notification channel) -- [ ] Add to AGENTS.md: +Paste this to your agent: + +``` +Set up urgent push notifications. Ask your human for their preferred +push notification channel (ntfy.sh topic, Pushover, etc.). + +Add to AGENTS.md: -```markdown ## Urgent Notifications -Send urgent messages via ntfy.sh: +Send urgent messages via push notification: curl -d "MESSAGE HERE" ntfy.sh/YOUR-PRIVATE-TOPIC-ID -Never send PII via ntfy. Keep messages generic. +Use for: overdue medications, critical system issues, time-sensitive +alerts. + +Rules: +- Never send PII via push notifications +- Keep messages generic (e.g. "daily meds overdue" not medication names) +- Only use for genuinely urgent items + +Replace the ntfy.sh URL with whatever your human provides. ``` --- @@ -377,38 +568,32 @@ Never send PII via ntfy. Keep messages generic. ### 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 ` -- [ ] Initial commit and push +Your workspace should be version-controlled for disaster recovery and debugging. +Paste this to your agent: -### 8.2 Configure auto-sync +``` +Set up the workspace as a git repo for state persistence: -- [ ] Add to AGENTS.md: +1. If not already a git repo: git init in the workspace root +2. Ask your human to create a PRIVATE repo on their git host +3. git remote add origin +4. Initial commit and push of all workspace files + +5. 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 -``` +- Auto-sync cron runs as a safety net (set up separately) -- [ ] 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 +6. IMPORTANT: Clone code repos OUTSIDE the workspace directory to avoid + embedded repo issues. Add a note to AGENTS.md about where to clone + repos (e.g. ~/repos/ or a dedicated path). Reference: -[OPENCLAW_TRICKS.md § The Workspace as a Git Repo](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "The Workspace as a Git Repo" and "State Repo") +``` --- @@ -418,127 +603,172 @@ 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 +Paste this to your agent: + +``` +Set up code quality standards for development repos. For each code +repo your agent works on: + +1. Fetch and add REPO_POLICIES.md: + https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md + +2. For new repos, also fetch: + https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md + +3. For existing repos, fetch: + https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md + +4. Ensure every repo has a Makefile with these targets: + 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: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md +(see "The Interlocking Chain") +``` ### 9.2 Set up PR quality gate -- [ ] Create `memory/checklist-pr.md`: +Paste this to your agent: + +``` +Create memory/checklist-pr.md with the PR quality gate: -```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)? +2. make check passes locally with ZERO failures? +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? +7. Rebased against main, no merge conflicts? ## After sub-agent pushes code - 1. Check diff for linter / test config changes -2. Check diff for `-short` / `-timeout` flags added +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 +3. Only then: assign to human for final review + +CRITICAL RULES: +- make check must pass with ZERO failures. No exceptions. +- Pre-existing failures are YOUR problem. Fix them. +- NEVER modify linter config to make checks pass. Fix the code. +- Never self-review. + +Add this checklist to the MEMORY.md checklist index. + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Git Quality Standards" and "The PR Pipeline") + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md +(see "PR State Machine") ``` ### 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 +Paste this to your agent: + +``` +For each code repo, enable branch protection on the main branch. Ask +your human to configure (or configure via API if you have admin +access): + +- Require pull request reviews before merging +- Require CI status checks to pass +- Block force-pushes to main +- Require branches to be up-to-date before merging + +These settings prevent both humans and agents from merging broken code. 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) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md +(see "Branch Protection") +``` --- ## Phase 10: Gitea Integration (Optional) -If you use Gitea (or a similar self-hosted git platform) for issue tracking and +If you use Gitea (or similar self-hosted git platform) for issue tracking and code review. -### 10.1 Create a bot account +### 10.1 Set up bot account and poller -- [ ] 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 +Paste this to your agent: -### 10.2 Set up the notification poller +``` +Set up Gitea integration. Your human provides: the Gitea instance URL, +a bot account username, and an API token. -- [ ] 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 +1. Store the Gitea URL and token in TOOLS.md (workspace-only, never in + code repos): -### 10.3 Set up webhook feed +## Gitea +- Instance: https://your-gitea-instance.example +- User: your-bot-username +- Token: (your human provides this) +- API base: https://your-gitea-instance.example/api/v1 -- [ ] 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 +2. Add Gitea workflow rules to AGENTS.md: -### 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 +- If @-mentioned with work but not assigned → assign myself, then work - When nothing assigned to me, my Gitea work is done -- Respond in the medium addressed: Gitea → Gitea comment +- Respond in the medium addressed: Gitea mention → Gitea comment +- Work done, no more work needed → close the issue +- My part done, need feedback → unassign myself, assign the party + responsible for the next step -Workflow: issue → branch → PR "(closes #X)" → review/rework → assign human when -all checks pass. -``` +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` +3. Set up the notification poller (see reference for implementation). + Configure env vars: GITEA_URL, GITEA_TOKEN, HOOK_TOKEN. Run as a + system service. Reference: -[AUTOMATED_DEV.md § PR State Machine](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Gitea Integration & Notification Polling") + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md +(see "The Notification Poller" and "Real-Time Activity Feed") +``` + +### 10.2 Set up PR state machine labels + +Paste this to your agent: + +``` +Set up PR state tracking with labels. For each code repo, create these +labels via the Gitea API: + +- needs-rebase (color: red) — PR has merge conflicts +- needs-checks (color: orange) — CI hasn't passed yet +- needs-review (color: yellow) — ready for human review +- needs-rework (color: purple) — reviewer requested changes +- merge-ready (color: green) — all gates passed, ready to merge + +Create memory/pr-pipeline.md documenting the state machine transitions +and assignment rules. + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md +(see "PR State Machine", "States", and "Transitions") +``` --- @@ -546,21 +776,34 @@ Reference: If you want push-to-deploy for your services. -### 11.1 Set up µPaaS (or equivalent) +### 11.1 Set up deployment -- [ ] 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 +Paste this to your agent: -### 11.2 Wire up webhooks +``` +Set up a deployment pipeline. This is environment-specific — ask your +human about their infrastructure. Common pattern: -- [ ] 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 +1. Deploy a PaaS layer on your server. Options: + - µPaaS (https://git.eeqj.de/sneak/upaas) — lightweight, + Docker-based, webhook-triggered + - Dokku, Coolify, or similar + +2. Configure your reverse proxy (Traefik, Caddy, nginx) for automatic + TLS + +3. Create deploy keys (read-only SSH) for each repo that should + auto-deploy + +4. Add Gitea webhooks pointing to your PaaS for repos that should + auto-deploy on merge to main + +5. 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) +https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md +(see "Deployment: µPaaS" and "The Full Pipeline") +``` --- @@ -570,43 +813,66 @@ If your agent participates in group chats. ### 12.1 Add group chat behavior -- [ ] Add to AGENTS.md: +Paste this to your agent: + +``` +Add group chat behavior rules to AGENTS.md: -```markdown ### Know When to Speak Respond when: directly mentioned, can add genuine value, correcting -misinformation. +important misinformation, something witty fits naturally. -Stay silent when: casual banter, someone already answered, your response would -just be "yeah" or "nice". +Stay silent when: casual banter between humans, someone already +answered, your response would just be "yeah" or "nice", the +conversation is flowing fine without you. -Quality > quantity. If you wouldn't send it in a real group chat with friends, -don't send it. +The human rule: humans in group chats don't respond to every message. +Neither should you. Quality > quantity. + +### React Like a Human + +On platforms that support reactions, use emoji reactions naturally: +- Appreciate something but don't need to reply → 👍 ❤️ +- Something made you laugh → 😂 +- Acknowledge without interrupting → 👀 +- One reaction per message max + +### Per-Channel Rules + +For channels with specific rules, create memory/CHANNEL_NAME.md and +add a reference line near the top of AGENTS.md: +**⚠️ #channel → read memory/CHANNEL_NAME.md first** + +Reference: +https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md +(see "Group Chat Behavior") ``` -### 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: +After completing the phases relevant to you, run these checks. Paste this to +your agent: -- [ ] 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 +``` +Run a verification check on the workspace setup: + +1. Start a fresh session — verify you read all startup files (SOUL.md, + USER.md, daily-context.json, today's daily file) +2. Run "sitrep" — verify it covers all configured items +3. If PII routing is set up: test by asking for sensitive info in a + hypothetical shared channel context — verify it would redirect to DM +4. If Gitea is set up: verify you can list issues assigned to you via + the API +5. If git quality gates are set up: verify make check passes on at + least one repo +6. Verify the workspace git repo has recent commits and is pushed +7. List any missing files or incomplete sections from the setup + +Report what passed and what needs attention. +``` --- @@ -627,5 +893,5 @@ After completing the phases relevant to you: --- -_Start with Phases 1-4 (workspace foundation, daily context, memory, heartbeat). +_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._