workspace-librarian

name	workspace-librarian
description	Place notes, decisions, and artifacts in the right workspace bucket. Extend the PARA taxonomy when justified; resist sprawl.
version	1.0.0
author	Kevin
tags	["workspace","organization","para","memory"]

workspace-librarian

You are the workspace librarian. When a piece of content needs a home — a note, a decision, a draft, a recipe, a meeting recap, a debugging session — you decide where it lives.

The taxonomy (PARA-extended)

Bucket	Path	Holds
Projects	projects/{name}/	Finite work with a defined outcome
Areas	areas/{topic}/	Ongoing responsibilities, no end date
People	people/{slack_handle}/	One folder per person worth remembering
Daily	daily/{YYYY}/{MM}/{DD}/	Curated journal and daily notes
Meetings	meetings/{YYYY}/{MM}/{DD}/	Meeting notes, one file per meeting

Hardcoded runtime dirs (memory/, sessions/, state/, cron/, skills/) — the Rust runtime references these names literally. Don't hand-edit memory/ or sessions/ or state/ or cron/; those are tool-written. skills/ is hand-authored but follows a strict layout (skills/{name}/SKILL.md with YAML frontmatter).

PARA dirs are agent-convention — the runtime doesn't scan them, but ZeroClaw reads/writes them via file tools during normal work.

Full workspace map

~/.zeroclaw/workspace/
├── SOUL.md, USER.md, IDENTITY.md       # who you are
├── MEMORY.md                           # curated long-term memory (auto-injected)
├── AGENTS.md, BOOTSTRAP.md             # operating instructions
├── TOOLS.md, HEARTBEAT.md              # tool/runtime notes
│
├── projects/{name}/                    # PARA: finite work
├── areas/{topic}/                      # PARA: ongoing responsibilities
├── people/{handle}/                    # PARA: people you track
├── daily/{YYYY}/{MM}/{DD}/             # PARA: curated journal
├── meetings/{YYYY}/{MM}/{DD}/          # PARA: meeting notes
│
├── memory/YYYY-MM-DD.md                # runtime: raw daily log (flat, tool-written)
├── sessions/                           # runtime: transcripts (sqlite + jsonl)
├── state/                              # runtime: model cache, etc
├── cron/jobs.db                        # runtime: scheduled jobs
└── skills/{name}/SKILL.md              # runtime: loaded skills

Why memory/ stays flat instead of nesting PARA inside it: the Rust runtime hardcodes memory/{date}.md. memory/ is the raw capture stream (what happened). PARA is curated knowledge (what I decided to keep). Keeping them as separate trees preserves that distinction.

Placement procedure

1. Does it have an outcome and an end state? → projects/{name}/
2. Is it an ongoing responsibility? → areas/{topic}/
3. Is it primarily about a person? → people/{handle}/
4. Is it a meeting? → meetings/{YYYY}/{MM}/{DD}/{HHMM-slug}.md
5. Is it today's log or journal? → daily/{YYYY}/{MM}/{DD}/notes.md
6. None of the above? Stop. Ask Kevin before inventing a new bucket.

Cross-cutting content: file it in the most-specific bucket and link from the others. Don't duplicate.

Extension rules

PARA is a scaffold. Extend it when usage justifies it, not preemptively.

Add a subdir when:

• You've filed 3+ related items in the same parent bucket.
• The parent's listing is hard to scan.
• The subtopic has its own recurring cadence (weekly sync, quarterly review).

Resist when:

• You've only seen one example.
• The subdir name overlaps with another bucket (a new areas/meetings/ duplicates the top-level meetings/).
• It would only hold one file for the foreseeable future.

Never add a new top-level bucket without checking with Kevin.

Naming

• Directories: lowercase, hyphens (home-infra, not Home_Infra).
• People: exact slack handle, lowercase.
• Meetings: HHMM-slug.md 24-hour (e.g. 1400-kevin-1on1.md) so sort order = chronological.
• Daily files: default notes.md; split when a day has multiple distinct threads (2026/04/19/sleep-log.md, 2026/04/19/deploy-postmortem.md).

Per-project scaffolding (two-tier pattern)

Projects and skills are different things that cross-reference:

• projects/{name}/ holds context and data — read by the agent, edited by the human.
• skills/{name}/SKILL.md holds loadable behavior — registered at startup with YAML frontmatter.

A project can exist without a skill (just a knowledge folder). A skill can exist without a project (pure capability). When both exist, the skill reads from the project folder rather than duplicating its content.

Typical projects/{name}/ files (create on demand, not preemptively):

• CONTEXT.md — why this exists, goals, constraints (authoritative for preferences)
• TOOLS.md — project-specific tool notes
• SKILLS.md — pointer file to skills/{slug}/SKILL.md, not the skill itself
• Data files (MEALS.md, drafts, artifacts, etc.)

Start with CONTEXT.md. Add the rest when they'd carry real content. Promote behavior to a real loadable skill the moment you want it to run — don't let procedure rot in a project's SKILLS.md where the runtime can't see it.

See projects/meal-planning/ + skills/meal-planner/ for the canonical pair.

Per-person scaffolding

people/{handle}/ typically grows toward:

• notes.md — what you know about them
• prefs.md — how they like to work / be contacted
• threads/ — conversation snippets worth keeping

Same rule: create files on demand, not preemptively.

Anti-patterns

• Duplicating content across buckets instead of linking
• Creating empty directories "just in case"
• Filing everything in daily/ because it's easy — daily/ is for journal entries, not durable knowledge
• Letting areas/ become a junk drawer — if areas/misc/ exists, something went wrong
• Hand-editing files in memory/, sessions/, state/, cron/

When to update this skill

If you routinely violate a rule here because it's wrong, or extend the taxonomy the same way repeatedly, update this file instead of carrying the exception mentally. Skills compound; workarounds don't.