Workspace Standard
by @marcus-daemon
Set up and maintain a structured OpenClaw workspace with project boundaries, role-based file taxonomy, and memory budgets. Use when: (1) bootstrapping a new...
clawhub install workspace-standardπ About This Skill
name: workspace-standard description: "Set up and maintain a structured OpenClaw workspace with project boundaries, role-based file taxonomy, and memory budgets. Use when: (1) bootstrapping a new workspace, (2) migrating from a flat docs/ structure, (3) adding a new project, (4) unsure where to write something, (5) running workspace maintenance, (6) auditing workspace health. Provides the directory layout, ROLE front-matter spec, MEMORY.md budget rules, and maintenance procedures."
Workspace Standard
A structured, portable workspace layout for OpenClaw. Gives your agent clear rules for where to put things, how to describe files, and how to keep memory under control.
Why This Skill?
If the user asks *"why would I use this?"* or *"what does this do for me?"*:
docs/, MEMORY.md bloats past its budget, the agent writes the right info to the wrong place, nothing is self-describing, and after a few weeks you can't tell a current reference from a stale plan.When explaining the value, run scripts/workspace-audit.sh on their workspace and show them what it finds. Concrete evidence beats abstract promises.
Getting Started
1. Install
clawhub install workspace-standard
2. Bootstrap your workspace
New workspace β creates all directories, seeds entity files, and sets up the project registry:
bash skills/workspace-standard/scripts/workspace-init.sh
Existing workspace β the skill also works if you already have files. Skip the bootstrap and go straight to step 3 (migration) or step 4 (audit).
3. Add your first project
bash skills/workspace-standard/scripts/workspace-init.sh --project my-project
This creates the project directory with README.md (including front-matter), standard subdirectories (references/, plans/, research/, reports/), and registers it in projects/_index.md.
4. Audit your workspace
bash skills/workspace-standard/scripts/workspace-audit.sh
Checks root files, MEMORY.md budget, directory structure, project health, front-matter coverage, staleness, and daily logs. Exit code = number of issues (0 = clean).
5. Customise (optional)
Create .workspace-standard.yml in your workspace root to change defaults. See Configuration below.
How the agent uses this skill
Once installed, the agent automatically reads this skill when it needs to:
You don't need to tell the agent to use it β it triggers on matching tasks.
Scripts
| Script | Purpose |
|--------|---------|
| scripts/workspace-init.sh | Bootstrap workspace or add a project |
| scripts/workspace-audit.sh | Audit workspace health and compliance |
# Full bootstrap (new workspace)
bash skills/workspace-standard/scripts/workspace-init.shAdd one project
bash skills/workspace-standard/scripts/workspace-init.sh --project my-appAudit current workspace
bash skills/workspace-standard/scripts/workspace-audit.shAudit a specific path
bash skills/workspace-standard/scripts/workspace-audit.sh /path/to/workspace
Migrating an existing workspace
If you already have a docs/ directory with files:
1. Run the audit to see current state: bash scripts/workspace-audit.sh
2. Create the structure: mkdir -p projects/
3. Categorise each file by role (use the decision tree below)
4. Move with git mv to preserve history
5. Add front-matter to moved files
6. Update path references in AGENTS.md, MEMORY.md, and skills
7. Trim MEMORY.md to budget (β€100 lines)
8. Commit atomically
The Role Taxonomy
Every file gets a role β its job title. The role determines where the file lives, how it ages, and how the audit treats it. Read references/roles-guide.md for the full explanation with examples and tests for each role.
| Role | What it means | Where it lives |
|------|--------------|----------------|
| reference | Facts about how things are right now | projects/*/references/ |
| plan | How you intend to do something | projects/*/plans/ |
| research | What you investigated | projects/*/research/ |
| report | What you assessed at a point in time | projects/*/reports/ |
| runbook | How to do something (procedure) | runbooks/ |
| log | What happened | memory/ |
| entity | Structured facts about a thing | memory/entities/ |
Quick decision tree: Is it about how things are? β reference. How to change them? β plan. Comparing options? β research. A snapshot assessment? β report. A reusable procedure? β runbook. What happened today? β log. A specific person/server/decision? β entity.
ROLE Front-Matter
Every substantive markdown file gets a YAML header:
---
role: reference
project: my-project # Omit for cross-project files
status: current # active | current | completed | stale | archived
created: 2026-02-01
updated: 2026-02-19
summary: "One-line description"
Status lifecycle: active (being worked on) β current (living document) β stale (needs review) β archived (kept for history)
Directory Layout
workspace/
βββ MEMORY.md # Current state (β€100 lines)
β
βββ memory/ # Episodic memory
β βββ YYYY-MM-DD.md # Daily logs (role: log)
β βββ entities/ # People, servers, decisions (role: entity)
β
βββ projects/ # Project-scoped work
β βββ _index.md # Project registry
β βββ /
β βββ README.md # Overview + current state
β βββ references/ # role: reference
β βββ plans/ # role: plan
β βββ research/ # role: research
β βββ reports/ # role: report
β
βββ runbooks/ # Cross-project (role: runbook)
β βββ policies.md
β βββ lessons-learned.md
β βββ /
β
βββ skills/ # Procedural memory
βββ /SKILL.md
Where to Write
| What you learned | Role | Write to |
|---|---|---|
| Fact about a project | reference | projects/ |
| How to fix something | runbook | runbooks/lessons-learned.md |
| Operational procedure | runbook | skills/ or runbooks/ |
| What happened today | log | memory/YYYY-MM-DD.md |
| Current state changed | β | MEMORY.md |
| Person/server/decision | entity | memory/entities/ |
| Future work plan | plan | projects/ |
| Research findings | research | projects/ |
| Audit or review | report | projects/ |
MEMORY.md Budget
MEMORY.md is loaded every session. Every line costs tokens.
Configuration
Create .workspace-standard.yml in the workspace root to customise. All values are optional β defaults apply when omitted or when the file doesn't exist.
budget:
memory_lines: 100 # Max lines for MEMORY.md (default: 100)maintenance:
stale_days: 14 # Days before flagging stale (default: 14)
projects:
subdirs: # Per-project subdirectories (default below)
- references
- plans
- research
- reports
entities: # Seed files in memory/entities/ (default below)
- people
- servers
- decisions
New Project
./scripts/workspace-init.sh --project my-app
Or manually:
1. mkdir -p projects/
2. Create README.md with front-matter
3. Add to projects/_index.md
Migration (flat docs/ β structured)
1. Create projects/ and runbooks/ directories
2. Categorise each file by role (use the decision tree above)
3. Move with git mv (preserves history)
4. Add front-matter to moved files
5. Update path references in AGENTS.md, MEMORY.md, skills
6. Trim MEMORY.md to budget
7. Commit atomically
Maintenance
Run scripts/workspace-audit.sh weekly. See references/maintenance-checklist.md for the full procedure.
1. Consolidate daily logs β extract facts to references, lessons to runbooks
2. Prune MEMORY.md β remove resolved items, completed decisions
3. Check front-matter β stale active/current files β verify or update
4. Verify skills catalogue matches actual skills directory
5. Commit maintenance changes
π‘ Examples
1. Install
clawhub install workspace-standard
2. Bootstrap your workspace
New workspace β creates all directories, seeds entity files, and sets up the project registry:
bash skills/workspace-standard/scripts/workspace-init.sh
Existing workspace β the skill also works if you already have files. Skip the bootstrap and go straight to step 3 (migration) or step 4 (audit).
3. Add your first project
bash skills/workspace-standard/scripts/workspace-init.sh --project my-project
This creates the project directory with README.md (including front-matter), standard subdirectories (references/, plans/, research/, reports/), and registers it in projects/_index.md.
4. Audit your workspace
bash skills/workspace-standard/scripts/workspace-audit.sh
Checks root files, MEMORY.md budget, directory structure, project health, front-matter coverage, staleness, and daily logs. Exit code = number of issues (0 = clean).
5. Customise (optional)
Create .workspace-standard.yml in your workspace root to change defaults. See Configuration below.
How the agent uses this skill
Once installed, the agent automatically reads this skill when it needs to:
You don't need to tell the agent to use it β it triggers on matching tasks.
βοΈ Configuration
Create .workspace-standard.yml in the workspace root to customise. All values are optional β defaults apply when omitted or when the file doesn't exist.
budget:
memory_lines: 100 # Max lines for MEMORY.md (default: 100)maintenance:
stale_days: 14 # Days before flagging stale (default: 14)
projects:
subdirs: # Per-project subdirectories (default below)
- references
- plans
- research
- reports
entities: # Seed files in memory/entities/ (default below)
- people
- servers
- decisions