156 lines
6.0 KiB
Markdown
156 lines
6.0 KiB
Markdown
---
|
|
name: workspace-review
|
|
description: Audit workspace structure and memory files against OpenClaw conventions. Use when asked to "review workspace", "audit files", "check structure", or during periodic self-maintenance. Helps catch drift from standard patterns.
|
|
---
|
|
|
|
# Workspace Review
|
|
|
|
A self-audit process to verify workspace files follow OpenClaw conventions and haven't drifted into non-standard patterns.
|
|
|
|
## When to Run
|
|
|
|
- Periodically (weekly or after major changes)
|
|
- When asked to "review", "audit", or "check" workspace
|
|
- After bootstrap or significant reorganization
|
|
- During heartbeat maintenance cycles
|
|
|
|
## Review Process
|
|
|
|
### 1. Structure Check
|
|
|
|
Verify expected files exist in correct locations:
|
|
|
|
```
|
|
~/.openclaw/workspace/
|
|
├── AGENTS.md ← Operating instructions (REQUIRED)
|
|
├── SOUL.md ← Persona/tone (REQUIRED)
|
|
├── USER.md ← User profile (REQUIRED)
|
|
├── IDENTITY.md ← Agent name/vibe/emoji (REQUIRED)
|
|
├── TOOLS.md ← Local tool notes (REQUIRED)
|
|
├── HEARTBEAT.md ← Heartbeat checklist (optional)
|
|
├── MEMORY.md ← Curated long-term memory (optional)
|
|
├── BOOT.md ← Runs on gateway restart (optional, boot-md hook)
|
|
├── BOOTSTRAP.md ← One-time first-run ritual (delete after use)
|
|
├── memory/ ← Daily logs + reference docs (vector-indexed)
|
|
│ └── YYYY-MM-DD.md
|
|
└── skills/ ← Workspace-specific skills (optional)
|
|
```
|
|
|
|
**Note on BOOT.md vs BOOTSTRAP.md:**
|
|
- `BOOT.md` — Persistent; runs every gateway restart (if `boot-md` hook enabled)
|
|
- `BOOTSTRAP.md` — One-time; agent follows it on first run, then deletes it
|
|
|
|
**Check:** Run `ls -la` on workspace root. Flag missing required files.
|
|
|
|
### 2. File Purpose Audit
|
|
|
|
Each file has ONE job. Check for scope creep:
|
|
|
|
| File | Should Contain | Should NOT Contain |
|
|
|------|----------------|-------------------|
|
|
| AGENTS.md | Operating instructions, memory workflow, behavior rules | Personal memories, daily logs, tool configs |
|
|
| SOUL.md | Persona, tone, boundaries, identity philosophy | Task lists, technical details, credentials |
|
|
| USER.md | User profile, preferences, how to address them | Agent memories, system config |
|
|
| IDENTITY.md | Name, emoji, vibe, external identities (wallets, handles) | Instructions, memories |
|
|
| TOOLS.md | Environment-specific notes (camera names, SSH hosts, voices) | Skill instructions, operating procedures |
|
|
| HEARTBEAT.md | Short checklist for periodic checks | Long procedures, full documentation |
|
|
| MEMORY.md | Curated lessons, key context, important people/projects | Daily logs, raw notes |
|
|
| memory/*.md | Daily logs, raw notes, session summaries | Long-term curated memories |
|
|
|
|
**Check:** Skim each file. Flag content in wrong location.
|
|
|
|
### 3. Memory Hygiene
|
|
|
|
- [ ] Daily files use `YYYY-MM-DD.md` or `YYYY-MM-DD-slug.md` format
|
|
- [ ] Hook-generated session files (`session-memory` hook creates `YYYY-MM-DD-slug.md`) reviewed periodically
|
|
- [ ] Reference docs use descriptive names (not dates): `project-notes.md`, `api-guide.md`
|
|
- [ ] MEMORY.md contains curated insights, not raw logs
|
|
- [ ] No duplicate information across MEMORY.md and daily files
|
|
- [ ] Old daily files reviewed and distilled to MEMORY.md periodically
|
|
- [ ] No sensitive data (API keys, passwords) in memory files
|
|
|
|
**Automatic Memory Flush:** OpenClaw triggers a silent agent turn before session compaction to write durable memories. The agent receives a prompt to flush important context to `memory/YYYY-MM-DD.md`. This is automatic — no action needed, but be aware your context WILL be compacted after ~180k tokens.
|
|
|
|
### 4. Vector Search Alignment
|
|
|
|
- [ ] Only `MEMORY.md` and `memory/**/*.md` are indexed by default
|
|
- [ ] Daily logs use `YYYY-MM-DD.md`; reference docs use descriptive names
|
|
- [ ] Files outside `memory/` can be indexed via `memorySearch.extraPaths` in config
|
|
|
|
**Session Memory (Experimental):** If `memorySearch.experimental.sessionMemory = true`, session transcripts are also indexed and searchable via `memory_search`.
|
|
|
|
### 5. Git Status
|
|
|
|
**⚠️ This workspace is PRIVATE. Never push to GitHub or any public remote.**
|
|
|
|
```bash
|
|
cd ~/.openclaw/workspace && git status
|
|
```
|
|
|
|
- [ ] No remote configured (or only private backup)
|
|
- [ ] No untracked files that should be tracked
|
|
- [ ] No tracked files that should be gitignored
|
|
- [ ] No uncommitted changes lingering for days
|
|
- [ ] .gitignore excludes secrets (*.key, *.pem, .env, secrets*)
|
|
|
|
### 6. Rogue Files Check
|
|
|
|
Look for files that don't fit the standard layout:
|
|
|
|
```bash
|
|
ls -la ~/.openclaw/workspace/
|
|
```
|
|
|
|
Flag anything that:
|
|
- Duplicates bootstrap file purposes (e.g., README.md alongside AGENTS.md)
|
|
- Stores credentials in workspace (should be in ~/.openclaw/credentials/)
|
|
- Creates non-standard directories without clear purpose
|
|
|
|
**Note:** Only `MEMORY.md` and `memory/**/*.md` are vector-indexed. Files outside `memory/` can be added via `memorySearch.extraPaths` in config.
|
|
|
|
### 7. Size Check
|
|
|
|
Bootstrap files should be lean (loaded every session):
|
|
|
|
- AGENTS.md: < 500 lines ideal, < 1000 max
|
|
- SOUL.md: < 200 lines ideal
|
|
- USER.md: < 100 lines ideal
|
|
- IDENTITY.md: < 50 lines ideal
|
|
- HEARTBEAT.md: < 100 lines (token burn concern)
|
|
|
|
```bash
|
|
wc -l AGENTS.md SOUL.md USER.md IDENTITY.md HEARTBEAT.md TOOLS.md MEMORY.md 2>/dev/null
|
|
```
|
|
|
|
### 8. Skills Check
|
|
|
|
If `skills/` exists:
|
|
- [ ] Each skill has SKILL.md with valid frontmatter (name, description)
|
|
- [ ] No duplicate skills (workspace vs managed)
|
|
- [ ] Skills follow progressive disclosure (lean SKILL.md, references for details)
|
|
|
|
## Output Format
|
|
|
|
After review, report:
|
|
|
|
```
|
|
## Workspace Review — YYYY-MM-DD
|
|
|
|
### ✅ Passing
|
|
- [list what's correct]
|
|
|
|
### ⚠️ Warnings
|
|
- [list minor issues]
|
|
|
|
### ❌ Issues
|
|
- [list things that need fixing]
|
|
|
|
### 📋 Recommendations
|
|
- [specific actions to take]
|
|
```
|
|
|
|
## References
|
|
|
|
- [references/openclaw-conventions.md](references/openclaw-conventions.md) — Full workspace file specifications
|
|
- [references/checklist.md](references/checklist.md) — Quick-reference checklist
|