workspace-organizing

# Workspace Organizing Keep agent workspaces tidy, predictable, and collision-free — and discoverable via memory, Vault, and the knowledge graph. This is a **discipline** skill: it runs *before* file writes to decide where a file belongs (and whether it already exists), and *after* the fact when asked to clean up or find something. ## Scope This skill governs file/folder layout and discovery inside: - `ActivePath` — primary read/write root for the current run - `inputs/` — read-only staged input alias available during an Agent Link artifact run - `TeamPath` — team workspace root (when in a team context) - **Vault** — the cross-workspace knowledge index (personal / team / shared scopes); searched via `vault_search`, read via `vault_read` Does NOT govern: code edits inside an existing project tree (e.g. a cloned repo), system paths, ephemeral `/tmp` files, or any path outside the resolved workspace. ## Two Modes Pick **one** mode per workspace root. They do not nest. ### Mode A — Flat (default for ad-hoc work) Use for scattered, short-lived, or one-off tasks: quick notes, a single report, a CSV cleanup, an isolated script. ``` workspace-root/ ├── notes/ ← markdown thinking, drafts, summaries, decisions ├── data/ ← structured input data the agent will re-read ├── outputs/ ← final deliverables for the user ├── scripts/ ← code the agent wrote to execute ├── archive/ ← superseded files (move, don't delete) └── (optional) tmp/ assets/ logs/ ``` ### Mode B — Project (for multi-file, named work) Use when the user names a project, when the task produces ≥3 related files of mixed kinds (docs + assets + code + reports), or when work continues across sessions. ``` workspace-root/ └── projects/ └── <project-slug>/ ├── docs/ ← project documentation, specs, design notes, READMEs ├── assets/ ← images, media, generated artifacts (PNG, MP4, SVG) ├── source/ ← code the project produces (scripts, snippets, configs) ├── reports/ ← analyses, audits, status reports for this project └── research/ ← raw research material, references, scraped data ``` `<project-slug>` is kebab-case and descriptive: `customer-churn-q2`, `landing-page-redesign`. ### Choosing the mode | Signal | Mode | |--------|------| | User mentions a project/campaign name | B | | Task produces ≥3 files of mixed kinds | B | | Work spans multiple sessions / will be revisited | B | | Ad-hoc single deliverable | A | | Existing workspace already uses one mode | Match it | If two projects coexist, both live under `projects/`. Flat-mode folders never live inside a project — `projects/<slug>/notes/` is wrong; use `projects/<slug>/docs/` instead. ## Discovery First: Memory, Vault, Knowledge Graph **Before writing or organizing, search.** Duplicating a file someone already wrote — or burying a new one where Vault cannot index it — is the failure mode this skill exists to prevent. ### The discovery tools | Tool | What it finds | When to use | |------|---------------|-------------| | `vault_search` | Cross-source discovery across **vault docs + memory + knowledge graph** | Primary entry point. Use first for "is there anything related to X?" | | `memory_search` | Prior decisions, todos, dates, people, preferences from MEMORY.md + memory/*.md | When the question is "what did I do last time", "what did we decide" | | `knowledge_graph_search` | People, projects, organizations, and their connections | Multi-hop relationships: "who worked on X with Y", project ↔ owner ↔ file | | `memory_expand` | Full content of an episodic memory by `episodic_id` | After a search surfaces an episodic hit you need in full | | `vault_read` | Full vault doc content by `doc_id` | After a search surfaces a vault hit | | `memory_get` | Targeted line-range read from a memory file by path | Pull only the snippet, keep context small | ### Id routing (do not misroute) `vault_search` returns three id types in one stream. Each id routes to one and only one follow-up tool: - `doc_id` → `vault_read(doc_id)` *(vault document)* - `entity_id` → `knowledge_graph_search(entity_id=...)` *(KG entity, NOT vault_read)* - `episodic_id` → `memory_expand(id=episodic_id)` *(episodic memory, NOT vault_read)* Sending an `entity_id` or `episodic_id` to `vault_read` will fail. Read the id name on each result before calling the follow-up tool. ### Language matching `memory_search` requires the query language to match the stored content language. If memory was written in Vietnamese, search in Vietnamese. Mismatched language drops recall dramatically. ## Pre-Write Discovery Workflow Before calling `write_file` for any new file in a shared workspace, or any file in project mode: 1. **Search Vault first.** Run `vault_search(query="<short topic>")` — Vault indexes filesystem + memory + KG. 2. **If results exist**, decide: update an existing file, link to it, or genuinely write a new one. 3. **If no results**, also run `memory_search` for personal context (prior decisions on this topic) and `knowledge_graph_search` if the work involves named people/projects. 4. **Only then write.** Pick the folder from the decision table below. 5. **Make the new file discoverable**: write a one-line top heading + descriptive intro paragraph so future `vault_search` recall is good. Reference related vault docs/KG entities by name in the body. Skip discovery only for: pure `tmp/` files, archive moves, or when the user has already explicitly named the target path. ## Decision: Where Does This File Go? Before calling `write_file`, ask in order: 1. **Is this an intermediate file I'll re-read and discard?** → `tmp/` (flat) — do not deliver 2. **Is the user going to download/read this as the result?** → `outputs/` (flat) or `projects/<slug>/reports/` (project) 3. **Is this code to be executed?** → `scripts/` (flat) or `projects/<slug>/source/` (project) 4. **Is this generated media (image/video/audio)?** → `assets/` (flat) or `projects/<slug>/assets/` (project) 5. **Is this raw research material or structured data?** → `data/` (flat) or `projects/<slug>/research/` (project) 6. **Is this me thinking/summarizing in prose?** → `notes/` (flat) or `projects/<slug>/docs/` (project) 7. **Am I replacing a previous version?** → move the old one to `archive/` first, then write the new one in its original folder When unclear, default to `notes/` (flat) or `projects/<slug>/docs/` (project). **Never write to workspace root.** ## Naming Rules - **kebab-case** with descriptive nouns: `customer-churn-analysis.md` (not `Analysis 1.md`) - **Long names are fine** if they make the purpose obvious — file names are read by both LLMs and humans - **ISO date prefix** (`YYYY-MM-DD-`) on time-sensitive files: meeting notes, status updates, dated reports - **Task slug** when relevant: `pr-123-review.md`, `q2-forecast-chart.png` - **No spaces, no special characters** other than `-` and `_`. Lowercase always - **Extensions match content** (`.md` for markdown, `.csv` for CSV) - **No `untitled`, `output`, `result`, `test`, `temp`, `final`** as standalone names — if you can't think of a better name, the file probably should not be written yet ## Vault Integration The Vault is a content-addressed, scoped index of agent-readable documents. It synchronises with workspace files and exposes wikilinks + hybrid search. This skill assumes: - **Files in `outputs/`, `reports/`, `docs/`, `notes/`, and `research/` are Vault-indexable.** Write them well — clear titles, intro paragraphs, named entities — so `vault_search` recall works. - **Files in `tmp/`, `scripts/`, `data/`, `source/` are usually NOT meant for Vault.** Keep noise out of the index. - **Vault scope mirrors workspace scope.** A file under personal workspace → personal vault scope. A file under `shared/_common/` → team vault scope. Where the file lives determines who can find it via `vault_search`. - **Use wikilinks** (`[[other-file-title]]` or `[[doc_id]]`) inside markdown notes/docs/reports to create durable cross-references. Vault auto-resolves and traverses these. - **Promote to Vault explicitly** when a draft from `notes/` becomes canonical: move to `outputs/` or `reports/`, write a clear title, and the Vault sync layer will index it. When the user says "save this to my vault" / "lưu vào vault", interpret it as: write to the appropriate folder under the user's personal workspace (`notes/` or `outputs/`), with a strong title and a brief intro paragraph, so Vault indexing surfaces it later. ## Tool Behavior: `deliver` Flag When the file-write tool exposes a `deliver` boolean (GoClaw filesystem tools): - `deliver=true` → only for files the user should receive/see. Belongs in `outputs/`, `projects/<slug>/reports/`, or `projects/<slug>/assets/` (when the asset is the deliverable) - `deliver=false` → everything in `notes/`, `data/`, `scripts/`, `tmp/`, `logs/`, `research/`, `source/`, `docs/` Never set `deliver=true` on a `tmp/` file or unpromoted draft. ## Workspace-Specific Rules ### Personal workspace (`Scope = personal`) - Apply the convention when **creating new files** - Do **not** spontaneously reorganize existing files the user placed there manually - Only restructure existing layout when the user explicitly asks ("clean up", "organize", "tidy", "tổ chức lại") - The user is sole owner — preserve their conventions if they have one ### Team workspace (`Scope = team`, shared mode) - **Every write goes under `shared/<agent_key>/`** unless writing to `shared/_common/` - Inside `shared/<agent_key>/`, apply either flat or project mode (pick one per sandbox) - `shared/_common/` is for artifacts the whole team needs. Write here only when the user/teammate puts it in scope; treat as append-mostly - For team-wide projects, prefer `shared/_common/projects/<slug>/` and namespace files with `<agent_key>-` prefix or sub-folders - **Never overwrite a file in another teammate's namespace** (`shared/<other-agent-key>/...`). Read is fine; write/move/delete is not - Before writing in the team root, list the directory and run `vault_search` first ### Delegate workspace (`Scope = delegate`, isolated Agent Link exchange) - **Inputs from delegator** are readable only through logical `inputs/...` paths. - `ActivePath` is the logical `outputs/` root. Write output files using ordinary relative paths such as `report.md`; do not prefix them with `outputs/`. - Files are not visible to the caller until the run and every synchronous nested child finish, then runtime validation publishes them atomically. - After success, the caller can revisit the durable publication at `.delegations/<delegation-id>/`, including `manifest.json` and logical `outputs/...` entries. - End each delegated task with `SUMMARY.md` describing what was produced and where. The runtime publishes it as `outputs/SUMMARY.md`. ## Workflow: Before Every File Write in a Shared Workspace 1. Decide flat vs project mode (or match existing mode) 2. **Run `vault_search` for the topic** — confirm no similar file already exists 3. Resolve the target folder using the decision table 4. If in team scope, prefix with `shared/<agent_key>/` 5. List the parent directory — confirm no name collision; if collision, pick a more specific name or archive the old file 6. Write the file with a kebab-case descriptive name and the right `deliver` flag 7. Inside the file, reference related Vault docs by `[[wikilink]]` or by title so traversal works later ## End-of-Task File Summary After a complex task (≥3 files created, or any project-mode work), end the response with a manifest: ``` Created: - projects/q2-forecast/reports/forecast-summary.md ← deliverable - projects/q2-forecast/assets/forecast-chart.png ← deliverable - projects/q2-forecast/source/build-chart.py ← code used - projects/q2-forecast/research/raw-sales-2026.csv ← input data Related (existing): [[2026-q1-forecast]], KG entity "Sales Team" ``` Mark deliverables vs intermediates. Mention any `tmp/` cleaned up. List related Vault docs / KG entities the new files connect to. ## When User Asks to "Organize" or "Clean Up" 1. **List the workspace root + one level deep.** Identify loose files (anything at root that isn't a canonical folder) 2. **Detect existing mode.** If `projects/` already exists, stay in project mode; otherwise flat 3. **For each loose file, run a quick `vault_search`** to find related Vault docs — group files that belong to the same project together 4. **Categorize each loose file** using the decision table — propose a destination 5. **Show the move plan to the user first**. Do not move silently 6. After approval, move files; do not delete. Discardables go to `archive/<YYYY-MM>/` 7. Clean out `tmp/` and `.tmp/` (disposable by definition, but confirm before deleting) 8. Update or generate a `notes/README.md` (flat) or `projects/<slug>/docs/README.md` (project) summarizing what lives where — include wikilinks to key files ## When User Asks "Where Did I Save X?" Search Vault and memory **before** scanning the filesystem — they have semantic recall the filesystem does not. 1. **`vault_search(query="X")`** — covers vault docs + memory + KG in one call 2. **`memory_search(query="X")`** in the user's language if Vault returns nothing 3. **`knowledge_graph_search(query="X")`** if the answer hinges on a person/project relationship 4. **Filesystem grep/list** as last resort, scoped to the resolved workspace paths 5. Report matches with full path + last-modified time; route each id correctly (`doc_id` → `vault_read`, `entity_id` → `knowledge_graph_search`, `episodic_id` → `memory_expand`) 6. If a file is in the wrong folder per the convention, offer to move it (don't move without confirmation) ## Archive & Cleanup Policy - Move to `archive/`, never delete, unless the user says "delete" - Group long-lived archives by month: `archive/2026-05/old-draft.md` - `tmp/` and `.tmp/` are exempt — disposable; clean at end of task - If `archive/` exceeds ~50 items, propose collapsing older months into a zip — only on user request ## Anti-Patterns to Refuse - Writing `output.txt`, `result.md`, `untitled.md`, `test.py` at the workspace root - Creating an unrecognized top-level folder (`misc/`, `stuff/`, `wip/`) - Mixing modes: `projects/<slug>/notes/` (wrong → use `docs/`) or `projects/<slug>/outputs/` (wrong → use `reports/`) - Versioning by filename (`report-v2.md`, `report-final-FINAL-2.md`) — archive the old one, keep the canonical name - Writing into another agent's `shared/<other-agent>/` namespace - Reorganizing a user-curated personal workspace without being asked - Setting `deliver=true` on `tmp/` files or unfinished drafts - **Writing a new file without running `vault_search` first** in shared/project contexts — leads to silent duplication - **Misrouting ids**: passing `entity_id` to `vault_read`, or `episodic_id` to `vault_read`, instead of their proper tools - Searching memory in the wrong language (English query against Vietnamese memory) ## Quick Reference ``` # Flat mode (ad-hoc) workspace-root/ ├── notes/ ← Vault-indexed thinking ├── data/ ← inputs ├── outputs/ ← Vault-indexed deliverables (deliver=true) ├── scripts/ ← executable code ├── archive/ ← superseded └── tmp/ assets/ logs/ ← optional # Project mode (named, multi-file) workspace-root/ └── projects/<project-slug>/ ├── docs/ ← Vault-indexed project docs ├── assets/ ← images, media ├── source/ ← project code ├── reports/ ← Vault-indexed analyses (deliver=true) └── research/ ← raw research, references