Workspace Cleanup

Scope

• In-scope: clean up workspace ops artifacts according to the standard taxonomy, safe-first flow, dry-run first, path whitelist, retention threshold.
• Out-of-scope: reckless hard-delete or cleanup outside the workspace safe zone.

Indexed sub-skill references (source map)

• @[SKILL.md#L1-L111] Standard frontmatter (name, description).
• @[SKILL.md#L6-L111] Workspace Cleanup.
• @[SKILL.md#L8-L111] When to use.
• @[SKILL.md#L13-L111] Objectives.
• @[SKILL.md#L18-L111] Mandatory principles.
• @[SKILL.md#L27-L111] Standard taxonomy.
• @[SKILL.md#L40-L111] Default cleanup scope.
• @[SKILL.md#L52-L111] Hard excludes.
• @[SKILL.md#L59-L111] Standard SOP.
• @[SKILL.md#L80-L111] Suggested default policy.
• @[SKILL.md#L85-L111] Report template.
• @[SKILL.md#L92-L111] Do not do.

When to use

• After completing a task/work session.
• When the workspace accumulates many old operational artifacts that need cleanup.
• When Boss requests storage optimization while still preserving near-term rollback capability.

Objectives

1. Reduce technical clutter according to the correct lifecycle class.
2. Do not lose important data (memory, docs, real source).
3. Have before/after reports for audit.
4. Do not break the standard workspace/.ops/* taxonomy.

Mandatory principles

1. Dry-run first: always list the files/directories to be moved/purged before applying.
2. Workspace-only: do not touch anything outside /data/adb/openclaw/home/.openclaw/workspace.
3. Do not delete core memory/config: do not touch MEMORY.md, memory/, SOUL.md, USER.md, AGENTS.md, TOOLS.md.
4. Taxonomy-first: prioritize cleanup by .ops/* class, not ad hoc namespaces.
5. Default retention: keep recent backups (e.g. 7 days) and the latest N copies for each group.
6. Rollback-friendly: prefer moving into workspace/.ops/trash/<timestamp>/ before permanent purge.

Standard taxonomy

workspace/.ops/backups = rollback assets
workspace/.ops/staging = candidate artifacts
workspace/.ops/tmp     = disposable scratch artifacts
workspace/.ops/trash   = quarantined removed items
workspace/.ops/state   = metadata/checkpoints

Default cleanup scope

• Disposable artifacts:
  • workspace/.ops/tmp/**
  • temp files *.tmp, *.temp, *.swp, *.swo, *~
• Quarantined removals:
  • workspace/.ops/trash/** beyond retention
• Stale staging:
  • workspace/.ops/staging/** with no active run and beyond retention
• Rollback assets:
  • workspace/.ops/backups/** beyond retention or exceeding keep-count
• State artifacts:
  • workspace/.ops/state/** only purge when the run is closed and the metadata is no longer needed for audit
• Incomplete shadow leftovers created by profile-only attempts (for example ad hoc ~/.openclaw-<profile> homes migrated into the workspace taxonomy) should be classified explicitly, then quarantined or removed instead of being left ambiguous.
• Legacy/non-canonical tmp dirs in the workspace may only be touched when Boss explicitly requests separate migration.

Hard excludes

• memory/**
• docs/**
• skills/** (unless Boss requests separate cleanup)
• RAG/**
• core platform config files in the workspace root (AGENTS.md, SOUL.md, USER.md, MEMORY.md, TOOLS.md, HEARTBEAT.md)
• artifacts that have not been mapped to a clear lifecycle class

SOP

Step 1 — Inventory (dry-run)

• Measure storage usage before cleanup.
• List candidates by lifecycle class + file age.
• Print clearly: path, class (backups|staging|tmp|trash|state), size, mtime, reason selected.

Step 2 — Approval scope

• Lock the exact cleanup scope (class + age + how much to retain).
• If Boss says “standard cleanup”, use the skill's default policy.

Step 3 — Safe cleanup

• Move candidates into workspace/.ops/trash/<timestamp>/ if they are not already quarantined.
• Write cleanup-manifest.json in workspace/.ops/state/<timestamp>/ containing the list of moved/purged files.
• For incomplete shadow leftovers, include original method/context if known (example: profile-only shadow leftover, invalid-isolation) so future audits can distinguish runtime debris from normal staging.
• If real purge is needed, only purge workspace/.ops/trash/** beyond retention or artifacts that were explicitly approved.

Step 4 — Verify + report

• Compare storage usage before/after.
• Report the number of files cleaned and total reclaimed storage.
• Report what was retained according to retention + lifecycle class.

Suggested default policy

• tmp only clean when older than 3 days or the run is closed.
• staging only clean when older than 7 days and no active candidate remains.
• backups keep at least 3 newest rollback copies for each important group.
• trash purge when older than 14 days.
• state keep longer than tmp; only purge when the checkpoint no longer has audit value.

Report template

⚡ [cleanup] dry-run → 42 artifacts | 128 MB candidate
⚡ [cleanup] apply → moved 39 artifacts to .ops/trash/20260222-2230 | reclaimed 121 MB
🛡️ [WARN] kept newest rollback assets + all active staging/state artifacts

Do not do

• Do not delete directly with rm -rf outside the .ops/trash flow unless there is an explicit instruction.
• Do not clean outside the workspace.
• Do not clean secrets/runtime config outside the workspace.
• Do not mix artifact classes in the cleanup report.

Trigger Rules

• Positive: Trigger when the user request matches workspace-cleanup per the description: Clean up workspace ops artifacts according to the standard taxonomy after completing a task, using safe-first mode (dry-run first, path whitelist, retention threshold).
• Negative: Do not trigger for requests outside scope or that do not need this skill's workflow/expertise.
• Escalation: If there is external action/network write or sensitive manipulation, an approval checkpoint must be added before execution.

Error Handling

• If a path is outside the whitelist/workspace boundary: block and clearly state the boundary rule that was hit.
• If the dry-run shows the pattern/class match is too broad: stop and narrow the scope before actual deletion.
• If moving into .ops/trash or purge fails due to permission/path race: report which files failed and keep the rest unchanged in a safe best-effort manner.

Output Contract

• Deliverable: results aligned to the objectives of workspace-cleanup; clearly state class/path/steps performed (if any).
• Validation: report PASS/FAIL status with the main checks that were run.
• Failure mode: when errors occur, state the root cause + suggested remediation.