Skill: briandavisbikes-code/briandavis-file-mgmt (version 1.0.0)

# File Management Skill _A battle-tested approach to keeping your AI agent workspace organized and maintainable._ ## Overview This skill documents the file management system developed through real-world use of OpenClaw. It covers workspace structure, naming conventions, dead file detection, and cleanup practices. ## When to Use This Skill - Onboarding a new agent or setting up a fresh workspace - Performing periodic workspace audits - Before making significant changes to workspace structure - When workspace feels cluttered or disorganized ## Core Principles ### 1. Every File Has a Purpose - **Active files**: Scripts, configs, and data in use by cron jobs or agents - **Reference files**: Documentation, strategies, and notes - **Archived files**: Old versions, completed project artifacts - **Dead files**: Abandoned scripts, old experiments, unused utilities ### 2. Structure Mirrors Function ``` workspace/ ├── memory/ # Daily session logs and working context ├── skills/ # Installed skill directories ├── project-1/ # Project-specific directories ├── project-2/ ├── ACTIVE.md # Currently running projects & priorities ├── DREAMS.md # Background processing notes └── ARCHIVED/ # Completed or abandoned projects ``` ### 3. Naming Conventions - **Scripts**: Use `.sh` for bash, `.py` for Python, `.js` for JavaScript - **Logs**: End with `.log` - **Configs**: End with `.json`, `.yaml`, or `.md` - **Daily notes**: `memory/YYYY-MM-DD.md` format ### 4. Audit Regularly Run workspace audits monthly or after major changes. Use the audit script to identify: - Dead files (no references from active crons or scripts) - Large files consuming storage - Outdated documentation ## Quick Audit Commands ```bash # Find files not referenced by any cron or script grep -r "filename" ~/path/to/workspace/ --include="*.sh" --include="*.py" --include="*.js" # Find recently modified files find ~/path/to/workspace -type f -mtime -7 # Check disk usage by directory du -sh ~/path/to/workspace/*/ ``` ## Cleanup Best Practices 1. **Never delete immediately** — use `trash` instead of `rm` 2. **Document before deleting** — note what a file did in memory first 3. **Verify before cleanup** — confirm no active references 4. **Commit before major cleanup** — create a revert point ## Full Documentation See `FILE-MANAGEMENT.md` for the complete reference implementation, including: - Directory structure explainer - Active vs archived file definitions - Dead file detection criteria - Example cleanup checklists

path: FILE-MANAGEMENT.md
content: # File Management Reference

_This is the actual file management system used in production. Adapt to your own setup._

---

## Current Workspace Structure

```
~/.openclaw/workspace/
├── AGENTS.md          # Agent configuration and personality
├── MEMORY.md          # Long-term curated memory (loaded in main session only)
├── DREAMS.md          # Background/ dreaming notes
├── SOUL.md            # Agent persona and tone guidelines
├── USER.md            # User profile and preferences
├── TOOLS.md           # Local tool-specific notes
├── HEARTBEAT.md       # Heartbeat configuration
│
├── memory/            # Daily session logs
│   ├── YYYY-MM-DD.md  # Daily notes (canonical format)
│   ├── dreaming/       # Dream state processing
│   └── archives/      # Old memory archives
│
├── skills/            # Skill directories
│   └── [skill-name]/  # Individual skills
│
├── [project-dirs]/    # Project-specific directories
│
├── api/               # API-related files
├── data/              # Data files
├── public/            # Public assets
├── scripts/           # Utility scripts
├── state/             # State files
└── [*.md]            # Reference docs (strategies, notes)
```

---

## File Categories

### Bootstrap Files (Read-Only)
These define the agent and should rarely change:
- `AGENTS.md` - Workspace instructions
- `SOUL.md` - Persona definition
- `USER.md` - User profile
- `MEMORY.md` - Long-term memory
- `TOOLS.md` - Tool notes
- `IDENTITY.md` - Agent identity
- `DREAMS.md` - Background processing
- `HEARTBEAT.md` - Periodic task config

### Active Reference Files
Currently in use by agents or systems:
- Strategy documents (e.g., `gunner-strategy.md`)
- Project documentation (e.g., `truckpedia-*.md`)
- Team documentation (e.g., `deckhand-tasks.md`)

### Scripts & Executables
- End with `.sh` (bash), `.py` (Python), `.js` (JavaScript)
- Must have executable bit (`chmod +x`) to run via cron
- Location: `~/scripts/` for system crons, workspace for agent-specific

### Logs
- End with `.log`
- Written to by cron jobs and scripts
- Should be gitignored (contain sensitive data sometimes)

---

## Dead File Detection

A file is dead if:

1. **No active cron references it**
   ```bash
   crontab -l | grep filename
   openclaw cron list | grep filename
   ```

2. **No script references it**
   ```bash
   grep -r "filename" ~/scripts/ --include="*.sh"
   grep -r "filename" ~/.openclaw/workspace/ --include="*.sh" --include="*.py"
   ```

3. **Not loaded by any skill or agent**
   ```bash
   grep -r "filename" ~/.openclaw/skills/
   grep -r "filename" ~/.openclaw/agents/
   ```

4. **No recent meaningful modification** (older than 30+ days and obvious stale content)

---

## Cleanup Checklist

Before deleting any file:

- [ ] Check if referenced by any cron job
- [ ] Check if referenced by any script
- [ ] Check if loaded by any skill
- [ ] Check git history for recent changes (may indicate active use)
- [ ] Document what the file did (in case of rollback need)
- [ ] Create git commit with message describing removal
- [ ] Use `trash` not `rm` (recoverable)

---

## Directory Conventions

### memory/
Daily session logs and working context.

- `YYYY-MM-DD.md` - One file per day (canonical)
- `dreaming/` - Background processing notes
- `archives/` - Old memory tarballs

### skills/
Installed skills following OpenClaw skill structure.

- Each skill in its own directory
- `SKILL.md` in each skill root
- Community skills in `~/.openclaw/skills/`

### scripts/
System-level scripts referenced by crontab.

- Typically bash scripts
- Must be executable
- Referenced by system crons in `/etc/crontab` or user crontab

### project-dirs/
Project-specific directories.

- Named after the project
- Contain project-specific files, scripts, configs
- Each project gets its own directory

---

## Naming Standards

| Type | Extension | Example |
|------|-----------|---------|
| Daily memory | `YYYY-MM-DD.md` | `memory/2026-04-27.md` |
| Strategy | `*-strategy.md` | `gunner-strategy.md` |
| Project plan | `*-plan.md` | `truckpedia-plan.md` |
| Notes | `*.md` | `deckhand-tasks.md` |
| Scripts | `.sh`, `.py`, `.js` | `truck-expansion.sh` |
| Logs | `.log` | `cron-output.log` |
| Configs | `.json`, `.yaml` | `systems.json` |

---

## Git Practices

### Before Cleanup
```bash
git add -A
git commit -m "Cleanup: Remove dead files"
git push
```

### Create Revert Point
```bash
git add -A
git commit -m "SAVEPOINT: Before major changes"
```

### Restore if Needed
```bash
git checkout <commit-hash> -- <filename>
```

---

## Common Pitfalls

1. **Deleting too aggressively** — Always verify, use trash
2. **Not documenting** — Note what files did before deleting
3. **No backup point** — Commit before major changes
4. **Inconsistent naming** — Follow the conventions above
5. **Ignoring logs** — Keep logs gitignored, they're not for versioning

---

## When to Audit

- Monthly scheduled review
- After major project completion
- When workspace feels cluttered
- Before major restructuring
- After system/agent issues

---

_This document reflects actual production practices. Update as your setup evolves._


path: audit-workspace.sh
content: #!/bin/bash
# Workspace Audit Script
# Scans workspace for dead files, large files, and cleanup opportunities

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

# Check for executable scripts
echo "📁 EXECUTABLE SCRIPTS (in workspace root)"
find "$WORKSPACE" -maxdepth 1 -type f -executable -name "*.sh" 2>/dev/null | while read f; do
    echo "  $f"
done
echo ""

# Check scripts directory
if [ -d "$WORKSPACE/scripts" ]; then
    echo "📁 SCRIPTS DIRECTORY"
    ls -la "$WORKSPACE/scripts/" 2>/dev/null | tail -n +4 | awk '{print "  "$NF" ("$5" bytes)"}'
    echo ""
fi

# Find recently modified files (last 7 days)
echo "📅 RECENTLY MODIFIED (7 days)"
find "$WORKSPACE" -type f -mtime -7 -not -path "*/.git/*" -not -path "*/memory/dreaming/*" 2>/dev/null | head -20 | while read f; do
    size=$(du -h "$f" 2>/dev/null | cut -f1)
    echo "  $f ($size)"
done
echo ""

# Find large files (>1MB)
echo "📊 LARGE FILES (>1MB)"
find "$WORKSPACE" -type f -size +1M -not -path "*/.git/*" 2>/dev/null | while read f; do
    size=$(du -h "$f" 2>/dev/null | cut -f1)
    echo "  $size $f"
done
echo ""

# Count files by extension
echo "📈 FILE COUNT BY TYPE"
echo "  Markdown (.md): $(find "$WORKSPACE" -maxdepth 1 -type f -name "*.md" 2>/dev/null | wc -l | tr -d ' ')"
echo "  Scripts (.sh): $(find "$WORKSPACE" -maxdepth 1 -type f -name "*.sh" 2>/dev/null | wc -l | tr -d ' ')"
echo "  Python (.py): $(find "$WORKSPACE" -maxdepth 1 -type f -name "*.py" 2>/dev/null | wc -l | tr -d ' ')"
echo "  Logs (.log): $(find "$WORKSPACE" -type f -name "*.log" 2>/dev/null | wc -l | tr -d ' ')"
echo "  JSON (.json): $(find "$WORKSPACE" -maxdepth 1 -type f -name "*.json" 2>/dev/null | wc -l | tr -d ' ')"
echo ""

# Directory sizes
echo "📂 DIRECTORY SIZES"
du -sh "$WORKSPACE"/*/ 2>/dev/null | sort -hr | head -10 | awk '{print "  " $1 "\t" $2}'
echo ""

# Memory directory check
if [ -d "$WORKSPACE/memory" ]; then
    echo "📅 MEMORY DIRECTORY"
    echo "  Daily logs: $(find "$WORKSPACE/memory" -maxdepth 1 -name "????-??-??.md" 2>/dev/null | wc -l | tr -d ' ') files"
    echo "  Total size: $(du -sh "$WORKSPACE/memory" 2>/dev/null | cut -f1)"
    echo ""
fi

# Dead file candidates (scripts with no references)
echo "⚠️  DEAD FILE CANDIDATES (no cron references)"
echo "  (Run grep checks manually to verify)"
echo ""

echo "=== Audit Complete ==="


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