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
- `SharedPath` — delegate exchange area (when delegating)
- `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/