workspace-organization

# Workspace Organization

Standards and automated maintenance for clean OpenClaw deployments.

## Files Included

- `SKILL.md` — Agent instructions
- `README.md` — Setup guide
- `maintenance-audit.sh` — Run to audit workspace health
- `setup.sh` — Run once to initialize standard structure

**Note:** Scripts auto-detect your workspace. Pass a path as argument to override: `./maintenance-audit.sh /custom/path`

## Problem Solved

Workspaces degrade over time:
- Broken symlinks from moved files
- Empty directories from deleted projects
- Large files eating disk space
- Malformed names breaking scripts
- No visibility into workspace health

This skill provides automated audits + cleanup guidance to prevent entropy.

## When to Use

- **New workspace setup** — Initialize standard directory structure
- **Periodic maintenance** — Weekly/monthly health checks (cron recommended)
- **Pre-deployment cleanup** — Remove cruft before backups
- **Debugging workspace issues** — Find broken symlinks, malformed names
- **Disk space review** — Identify large files and bloat

## What It Provides

### 1. maintenance-audit.sh
Automated health check script that detects:
- ✅ Broken symlinks
- ✅ Empty directories (excluding node_modules, .git)
- ✅ Large files (>10MB)
- ✅ Malformed file/directory names (spaces, special chars)
- ✅ Disk usage by top-level directory
- ✅ File/directory counts
- ✅ Recent changes (last 24 hours)

### 2. setup.sh
Initializes standard workspace structure:
```
~/.openclaw/workspace/
├── projects/           # Active work
│   ├── writing/        # Writing projects
│   └── code/           # Code projects
├── notes/              # Organized notes
│   ├── daily-reviews/
│   ├── decisions/
│   └── cost-tracking.md
├── memory/             # Long-term memory
│   ├── owner/          # Cross-channel user memory
│   └── sessions/       # Per-session isolated memory
├── skills/             # Custom skills
├── subagents/          # Permanent specialists
│   └── _archived/...

# Workspace Organization - Installation & Setup

Automated maintenance and organization standards for OpenClaw workspaces.

## Quick Install

```bash
# Via ClawHub (when published)
clawhub install workspace-organization

# Or manual install
cd ~/.openclaw/workspace/skills
# Download from ClawHub or extract package
```

## First-Time Setup

1. **Initialize workspace structure (optional, if starting fresh):**
```bash
cd ~/.openclaw/workspace/skills/workspace-organization
./setup.sh
```

This creates:
```
workspace/
├── projects/       # writing/, code/
├── notes/          # daily-reviews/, decisions/, cost-tracking.md
├── memory/         # owner/, sessions/
├── skills/         # Custom skills
├── subagents/      # Permanent specialists + _archived/
├── docs/           # Documentation
└── scripts/        # Utility scripts
```

2. **Run first audit:**
```bash
./maintenance-audit.sh
```

3. **Schedule automated audits (recommended):**
```bash
openclaw cron add \
  --name "Weekly Workspace Audit" \
  --schedule "0 4 * * 0" \
  --task "Run workspace maintenance audit: bash skills/workspace-organization/maintenance-audit.sh. Log findings to notes/maintenance-log.md"
```

## Usage

### Manual Audit

```bash
cd ~/.openclaw/workspace/skills/workspace-organization
./maintenance-audit.sh
```

### Agent-Driven

Ask your agent:
```
"Run workspace maintenance audit"
"Check workspace health"
"What's taking up disk space?"
```

### Example Output

```
=== Workspace Maintenance Audit ===
Date: 2026-02-21 16:00
Path: /home/user/.openclaw/workspace

1. Checking for broken symlinks...
✓ No broken symlinks

2. Checking for empty directories...
ℹ️  Found empty directories:
/home/user/.openclaw/workspace/projects/abandoned

3. Checking for large files (>10MB)...
ℹ️  Found large files:
24M	logs/debug.log

4. Checking for malformed file/directory names...
⚠️  Found malformed names:
/home/user/.openclaw/workspace/my project/file.md
   Recommendation: Rename to 'my-project/file.md'

5. Disk usa...