Skip to content

Workspace map (agent-friendly inventory) ​

Starter Conceptual guide for multi-project machines — no client list here.

The problem ​

A developer disk often holds dozens or hundreds of repos, dumps, and tooling under one tree (e.g. a single sites folder). Agents that recursive-grep the whole tree waste tokens, hit node_modules / uploads, and still miss intent.

The pattern (three layers) ​

text
Layer 0 — CATALOG (cheap)
  Shallow scan for project markers (.git, package.json, composer.json, …)
  Output: a small markdown/JSON table of paths + kinds + stack hints
  Agents read this first. Seconds to regenerate. No LLM required.

Layer 1 — PER-PROJECT deep map (opt-in)
  Run graphify / IDE index / RepoMap *inside one repo only*
  Output stays under that project (e.g. graphify-out/)

Layer 2 — META (optional)
  Graph or notes over the catalog + hand-written project notes
  Never ingest every client codebase into one mega-graph by default

Agent protocol ​

  1. Open the catalog (markdown or JSON), not the raw disk root.
  2. Pick one project path that matches the task.
  3. Work only in that path (or monorepo apps/ / packages/ children).
  4. For architecture questions, use that project's deep graph if present.
  5. If a project is missing, refresh the catalog — do not full-tree scan.

What a catalog row should include ​

FieldWhy
pathWhere to work
name / kindQuick match (“docs site”, “php-wp”, “hubspot”)
stack hintsnext, vitepress, ddev, docker, …
git remoteOrigin for context — strip credentials before write
short README blurbHuman intent without opening the tree
last writeRecency signal

Hygiene ​

  • Skip noise dirs: node_modules, vendor, .git, dist, coverage, uploads, caches.
  • Cap scan depth; treat marker folders as project roots (optional monorepo children only).
  • Catalog files contain machine-local absolute paths — treat as private operator data, not a public release.
  • Never store https://user:token@host/... remotes in the catalog.

Operators on this machine ​

Local control plane (not part of this public site's content tree):

  • Hub: D:\sites\graphify\
  • Rebuild: pwsh D:\sites\graphify\scripts\catalog.ps1 (or -Quiet)
  • Agent rules: D:\sites\graphify\AGENTS.md
  • Artifacts: D:\sites\graphify\out\catalog.md · catalog.json

Helpers (this site) stays conceptual and command-focused. The live project list lives only on the operator machine.