Skill: ortegarod/workspace-review (version 1.0.2)

--- 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

path: references/checklist.md
content: # Workspace Review Checklist

Quick-reference for periodic audits.

## Structure (Required Files)

- [ ] `AGENTS.md` exists
- [ ] `SOUL.md` exists
- [ ] `USER.md` exists
- [ ] `IDENTITY.md` exists
- [ ] `TOOLS.md` exists
- [ ] `memory/` directory exists

## Structure (Optional Files)

- [ ] `HEARTBEAT.md` — if using heartbeats
- [ ] `MEMORY.md` — if maintaining long-term memory
- [ ] `BOOT.md` — if using boot-md hook (runs every gateway restart)
- [ ] `BOOTSTRAP.md` — one-time first run (delete after)
- [ ] `skills/` — if using workspace skills

## File Purpose (No Scope Creep)

- [ ] AGENTS.md: Only operating instructions, no memories
- [ ] SOUL.md: Only persona/tone, no tasks or tech details
- [ ] USER.md: Only user info, no agent memories
- [ ] IDENTITY.md: Only identity facts, no philosophy
- [ ] TOOLS.md: Only environment notes, no procedures
- [ ] HEARTBEAT.md: Short checklist only, no full docs
- [ ] MEMORY.md: Curated insights only, no raw logs

## File Sizes

- [ ] AGENTS.md < 1000 lines
- [ ] SOUL.md < 200 lines
- [ ] USER.md < 100 lines
- [ ] IDENTITY.md < 50 lines
- [ ] HEARTBEAT.md < 100 lines

## Memory Hygiene

- [ ] Daily files use `YYYY-MM-DD.md` naming
- [ ] Reference docs in `memory/` use descriptive names (not dates)
- [ ] No duplicate content between MEMORY.md and daily files
- [ ] Recent daily files reviewed and distilled
- [ ] No API keys or passwords in memory files

## Automatic Features (Awareness)

- [ ] **Pre-compaction flush:** OpenClaw auto-triggers memory save before compaction
- [ ] **Heartbeat response:** `HEARTBEAT_OK` stripped when nothing needs attention
- [ ] **Empty HEARTBEAT.md:** Skipped entirely to save API calls

## Vector Search Alignment

- [ ] Only `MEMORY.md` and `memory/**/*.md` are indexed by default
- [ ] `memorySearch.extraPaths` adds other paths if needed
- [ ] `memorySearch.experimental.sessionMemory` indexes session transcripts if enabled

## Git Status

**⚠️ Workspace is PRIVATE — never push to GitHub**

- [ ] No public remote configured
- [ ] Working tree clean (or intentionally dirty)
- [ ] No untracked files that should be tracked
- [ ] .gitignore excludes secrets
- [ ] No secrets committed

## No Rogue Files

- [ ] No README.md duplicating AGENTS.md purpose
- [ ] No NOTES.md or similar duplicates
- [ ] No credentials stored in workspace
- [ ] No files that belong in ~/.openclaw/

## Skills (if present)

- [ ] Each skill has SKILL.md
- [ ] Each SKILL.md has name + description frontmatter
- [ ] SKILL.md files are lean (< 500 lines)
- [ ] No duplicate skills vs managed/bundled


path: references/openclaw-conventions.md
content: # OpenClaw Workspace Conventions

Source: OpenClaw docs (`/docs/concepts/agent-workspace.md`, `/docs/concepts/memory.md`)

## Workspace Location

- Default: `~/.openclaw/workspace`
- Override via `agents.defaults.workspace` in `~/.openclaw/openclaw.json`
- Profile-specific: `~/.openclaw/workspace-<profile>` when `OPENCLAW_PROFILE` is set

**Important:** Only ONE active workspace. Multiple workspaces cause auth/state drift.

## What Lives WHERE

### In Workspace (`~/.openclaw/workspace/`)

| File | Purpose | Loaded |
|------|---------|--------|
| `AGENTS.md` | Operating instructions, memory workflow, behavior rules | Every session |
| `SOUL.md` | Persona, tone, boundaries | Every session |
| `USER.md` | User profile, preferences | Every session |
| `IDENTITY.md` | Agent name, vibe, emoji, external handles | Every session |
| `TOOLS.md` | Environment-specific tool notes | Every session |
| `HEARTBEAT.md` | Short checklist for heartbeat runs | On heartbeat |
| `BOOT.md` | Startup checklist on gateway restart | On boot |
| `BOOTSTRAP.md` | One-time first-run ritual | Once, then delete |
| `MEMORY.md` | Curated long-term memory | Main session only |
| `memory/YYYY-MM-DD.md` | Daily logs | Read today + yesterday |
| `memory/*.md` | Reference docs (deep dives, projects) | On demand |
| `skills/` | Workspace-specific skills | On demand |
| `canvas/` | Canvas UI files | On demand |

**Note:** Only `MEMORY.md` and `memory/**/*.md` are vector-indexed.

### NOT in Workspace (lives in `~/.openclaw/`)

- `openclaw.json` — Config
- `credentials/` — OAuth tokens, API keys
- `agents/<agentId>/sessions/` — Session transcripts
- `skills/` — Managed/installed skills
- `memory/<agentId>.sqlite` — Vector index (SQLite with embeddings)

**Never commit these to git.**

## File Specifications

### AGENTS.md
- **Purpose:** Operating instructions for the agent
- **Contains:** Rules, priorities, "how to behave", memory workflow instructions
- **Size:** < 500 lines ideal, < 1000 max
- **Anti-patterns:**
  - Personal memories (use MEMORY.md or daily files)
  - Skill-specific procedures (use skills/)
  - Environment config (use TOOLS.md)

### SOUL.md
- **Purpose:** Persona definition
- **Contains:** Identity philosophy, tone guidelines, boundaries, emotional character
- **Size:** < 200 lines ideal
- **Anti-patterns:**
  - Task lists
  - Technical instructions
  - Memories about what happened

### USER.md
- **Purpose:** User profile
- **Contains:** Name, pronouns, timezone, preferences, how to address them
- **Size:** < 100 lines ideal
- **Anti-patterns:**
  - Agent memories
  - System configuration
  - Relationship history (that goes in MEMORY.md)

### IDENTITY.md
- **Purpose:** Agent's external identity
- **Contains:** Name, nickname, emoji, avatar, external handles (GitHub, Twitter, wallets)
- **Size:** < 50 lines ideal
- **Anti-patterns:**
  - Philosophy about identity (that's SOUL.md)
  - Instructions

### TOOLS.md
- **Purpose:** Environment-specific notes
- **Contains:** Camera names, SSH hosts, voice preferences, device nicknames
- **Size:** Variable
- **Anti-patterns:**
  - Skill instructions (use skills/)
  - Operating procedures (use AGENTS.md)

### HEARTBEAT.md
- **Purpose:** Checklist for periodic heartbeat runs
- **Contains:** Short, actionable items to check
- **Size:** < 100 lines (token burn concern)
- **Anti-patterns:**
  - Full procedures (just reference them)
  - Documentation

**Heartbeat Response Contract:**
- Reply `HEARTBEAT_OK` when nothing needs attention
- `HEARTBEAT_OK` at start/end of reply is stripped; if remaining content ≤ 300 chars, reply is dropped
- For alerts, do NOT include `HEARTBEAT_OK` — just return the alert text
- If HEARTBEAT.md is empty (only headers/blank lines), heartbeat is skipped to save API calls

### MEMORY.md
- **Purpose:** Curated long-term memory
- **Contains:** Distilled lessons, key people, important projects, lasting context
- **Loaded:** Main/private session ONLY (never in group chats)
- **Anti-patterns:**
  - Raw daily logs (use memory/*.md)
  - Duplicate of daily file content
  - Sensitive credentials

### memory/YYYY-MM-DD.md
- **Purpose:** Daily log
- **Contains:** What happened today, raw notes, session summaries
- **Naming:** Strict `YYYY-MM-DD.md` format
- **Workflow:** Read today + yesterday on session start
- **Anti-patterns:**
  - Curated insights without also putting in MEMORY.md
  - Very old files never reviewed

### memory/*.md (reference docs)
- **Purpose:** Searchable reference material
- **Contains:** Deep dives, project docs, technical references
- **Why here:** `memory/` is vector-indexed for semantic search. Files elsewhere are NOT searchable.
- **Examples:** `api-integration-notes.md`, `project-alpha.md`
- **Note:** Daily logs use `YYYY-MM-DD.md` naming; reference docs use descriptive names

## Git Conventions

**⚠️ IMPORTANT: This workspace is PRIVATE. Never push to GitHub or any public remote.**

The workspace contains personal memory, identity, and potentially sensitive context. Git is for LOCAL version control and backup only.

### Do Track (locally)
- All bootstrap files (AGENTS.md, SOUL.md, etc.)
- memory/*.md
- skills/

### Do NOT Track (gitignore)
```gitignore
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
```

### Never Do
- Push to GitHub or any public repository
- Commit API keys, OAuth tokens, passwords
- Commit anything from ~/.openclaw/
- Share raw chat dumps with sensitive content

## Memory Workflow

1. **During sessions:** Write notable things to `memory/YYYY-MM-DD.md`
2. **Periodically:** Review daily files, distill insights to `MEMORY.md`
3. **On session start:** Read today + yesterday's daily files
4. **In main session:** Also read MEMORY.md
5. **In group chats:** Do NOT read MEMORY.md (security)

### Automatic Memory Flush (Pre-Compaction)

OpenClaw automatically triggers a **silent agent turn** before context compaction:

- Fires when session approaches ~180k tokens (configurable via `compaction.reserveTokensFloor` + `softThresholdTokens`)
- Agent receives system prompt: "Session nearing compaction. Store durable memories now."
- Agent should write lasting notes to `memory/YYYY-MM-DD.md`, then reply `NO_REPLY`
- One flush per compaction cycle (tracked in sessions.json)

Config (`agents.defaults.compaction.memoryFlush`):
```json5
{
  enabled: true,
  softThresholdTokens: 4000,
  systemPrompt: "Session nearing compaction. Store durable memories now.",
  prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
}
```

### Vector Search

Only `MEMORY.md` and `memory/**/*.md` are indexed by default.

**Extra paths:** To index files outside `memory/`, add them to config:
```json5
agents: {
  defaults: {
    memorySearch: {
      extraPaths: ["../team-docs", "/srv/shared-notes"]
    }
  }
}
```

**Session memory (experimental):** Enable `memorySearch.experimental.sessionMemory = true` to also index session transcripts. This allows `memory_search` to recall conversations.

See [Memory docs](/concepts/memory) for full details on vector search, hybrid search, and session memory.

## Skill Conventions

- Workspace skills in `<workspace>/skills/` override managed skills
- Each skill needs `SKILL.md` with frontmatter (`name`, `description`)
- Keep SKILL.md lean (< 500 lines)
- Use `references/` for detailed docs
- Use `scripts/` for executable code
- Use `assets/` for templates/files used in output

## Common Anti-Patterns

1. **Scope creep** — File grows beyond its purpose
2. **Duplication** — Same info in multiple files
3. **Wrong location** — Memories in SOUL.md, instructions in IDENTITY.md
4. **Bloat** — Bootstrap files too large (loaded every session)
5. **Rogue files** — README.md, NOTES.md that duplicate bootstrap purposes
6. **Secrets in workspace** — API keys should be in ~/.openclaw/credentials/
7. **Stale daily files** — Never reviewed, insights never curated


path: scripts/workspace-status.sh
content: #!/bin/bash
# workspace-status.sh — Quick workspace health check
# Run from workspace root or pass path as argument

WORKSPACE="${1:-$HOME/.openclaw/workspace}"

echo "=== Workspace Status: $WORKSPACE ==="
echo ""

# Check if workspace exists
if [ ! -d "$WORKSPACE" ]; then
    echo "❌ Workspace not found: $WORKSPACE"
    exit 1
fi

cd "$WORKSPACE"

echo "## Required Files"
for file in AGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md; do
    if [ -f "$file" ]; then
        lines=$(wc -l < "$file")
        echo "✅ $file ($lines lines)"
    else
        echo "❌ $file MISSING"
    fi
done

echo ""
echo "## Optional Files"
for file in HEARTBEAT.md MEMORY.md BOOT.md BOOTSTRAP.md; do
    if [ -f "$file" ]; then
        lines=$(wc -l < "$file")
        echo "✅ $file ($lines lines)"
    else
        echo "⬜ $file (not present)"
    fi
done

echo ""
echo "## Directories"
for dir in memory skills docs canvas; do
    if [ -d "$dir" ]; then
        count=$(find "$dir" -type f | wc -l)
        echo "✅ $dir/ ($count files)"
    else
        echo "⬜ $dir/ (not present)"
    fi
done

echo ""
echo "## Memory Files (last 7 days)"
if [ -d "memory" ]; then
    find memory -name "*.md" -mtime -7 -exec basename {} \; 2>/dev/null | sort -r | head -7
else
    echo "No memory directory"
fi

echo ""
echo "## Git Status"
if [ -d ".git" ]; then
    if git diff --quiet && git diff --cached --quiet; then
        echo "✅ Working tree clean"
    else
        echo "⚠️  Uncommitted changes:"
        git status --short
    fi
    
    untracked=$(git ls-files --others --exclude-standard | wc -l)
    if [ "$untracked" -gt 0 ]; then
        echo "⚠️  $untracked untracked files"
    fi
else
    echo "⬜ Not a git repository"
fi

echo ""
echo "## File Sizes (lines)"
wc -l AGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md HEARTBEAT.md MEMORY.md 2>/dev/null | grep -v total

echo ""
echo "## Potential Issues"
# Check for rogue files
for file in README.md NOTES.md TODO.md; do
    if [ -f "$file" ]; then
        echo "⚠️  Found $file — may duplicate bootstrap file purposes"
    fi
done

# Check for secrets
if grep -r -l "sk-" --include="*.md" . 2>/dev/null | grep -v node_modules; then
    echo "⚠️  Possible API key found in .md files"
fi

if [ -f ".env" ]; then
    echo "⚠️  .env file in workspace (should be gitignored)"
fi

echo ""
echo "=== End Status ==="


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