# My Folder Map

**Structural map of `~/.claude/`.** Classifies every path as **mine** / **utility** / **reference** / **runtime** / **leak** / **legacy**.

Last updated: 2026-04-16 (TODO #20 self-enhancement).

---

## How to read this

- **mine** — content I own: identity, rules, skills, commands, knowledge base
- **utility** — cross-cutting tooling usable by any agent (not an agent itself)
- **reference** — materials I load but didn't author (research, context, memories)
- **runtime** — auto-managed state / cache / history generated by Claude Code
- **leak** — content that belongs elsewhere; will be moved or deleted
- **legacy** — retained for history/reference; see `deprecated-patterns.md`

---

## Top-level inventory

| Path | Classification | Purpose |
|---|---|---|
| `CLAUDE.md` | mine | My high-level overview; auto-loaded first on every session |
| `settings.json` | mine | My permission / hook / env-var config (bypass-permissions default) |
| `settings.local.json` | mine | Personal overrides (gitignored) |
| `keybindings.json` | mine | My keyboard shortcuts |
| `history.jsonl` | runtime | Claude Code session history |
| `stats-cache.json` | runtime | Claude Code stats cache |

## Top-level folders

| Path | Classification | Purpose |
|---|---|---|
| `1000xagent/` | mine | My knowledge base — identity, knowledge, terminology, folder-map, deprecated-patterns, agents.yaml |
| `agents/` | mine | Only `1000xagent.md` lives here. Never host project agent definitions. |
| `commands/` | mine | My own commands (`1000xagent.md`, `1000xagent:*.md`) + cross-cutting utilities (`/spec`, `/solve`, `/plan`, `/help`, `/load`, `/git-commit`, `/git-push`, `/save-state`, `/load-state`, `/log`, `/self-enhance`, `/remove-agent`). **Never** project-agent commands (`1000xdev.md`, `1000xpeps.md`, etc.). |
| `skills/` | mine | Cross-cutting skills I own (agent-creation, repository-initialization, solve, spec, plan, help, load, git-workflow, session-state, domain-context, architecture-propagation, command-organization, manage-commands-and-skills, maintain-agent-site, refresh-agent-site, test-app, vercel-deploy, create-desktop-app, instagram-short). **Never** project-specific skills. |
| `rules/` | mine | My behavioral rules, auto-loaded recursively on session start |
| `state/` | mine | My session state (`latest.json`) + archive/ |
| `projects/` | mine | Auto-memory persisted across my sessions — `projects/-home-kxdev/memory/` is my long-term feedback/user/project/reference memory |
| `research/` | reference | Research artifacts I reference. Utopia Suite research (`4-15/utopia-suite-*.md`) moved to `~/dev/utopia/.claude/research/` during TODO #20 to sit with the umbrella repo. What remains: `compass_artifact_wf-*.md` (generic research). |
| `context/` | reference | Additional context I load — `home-server/`, `leetcodesprints/`, `pictures/`, `prompts/`, `utopia-browser/`. These are reference notes, not agent definitions. |
| `plans/` | runtime | Named plan artifacts from `/plan` skill sessions. Auto-generated names (e.g. `tidy-strolling-stardust.md`) — each is a session artifact, not a durable doc. |
| `hooks/` | mine | My session hooks (`index.md`, `session_start.js`) and `sync-tyleryouk.sh` (1000xdev-specific sync; kept here because it needs global trigger scope). |
| `logs/` | mine | My session logs. Project agents log to their own repos; only my logs live here. |
| `private/` | mine | Secrets (gitignored). Contains Vercel token (shared across projects), Cloudflare config, Oura credentials, Anthropic key, and project-specific secrets flagged for migration. See "Private folder audit" below. |
| `templates/` | mine | Reusable templates I use |
| `backups/` | runtime | Claude Code auto-backups |
| `cache/` | runtime | Claude Code cache |
| `content/` | mine | Generated content artifacts (e.g. Instagram-short outputs) |
| `debug/` | runtime | Claude Code debug dumps |
| `file-history/` | runtime | File edit history |
| `ide/` | runtime | IDE integration state |
| `paste-cache/` | runtime | Paste buffer cache |
| `plugins/` | mine | My plugin configuration |
| `scripts/` | mine | My utility scripts |
| `session-env/` | runtime | Claude Code session environment |
| `sessions/` | runtime | Session archives |
| `shared/` | runtime | Shared session data |
| `shell-snapshots/` | runtime | Shell state snapshots |
| `statsig/` | runtime | Claude Code feature-flag state |
| `tasks/` | runtime | Claude Code task state (from TaskCreate/TaskUpdate tools) |
| `telemetry/` | runtime | Claude Code telemetry |
| `todos/` | runtime | Claude Code internal todos |

---

## `commands/` detailed inventory

**My own (stay forever):**
- `1000xagent.md` — my main invocation
- `1000xagent:analyze-logs.md`, `1000xagent:audit-permissions.md`, `1000xagent:cloudflare-allowlist.md`, `1000xagent:create-project.md`, `1000xagent:enhance-agent.md`, `1000xagent:enhance.md`, `1000xagent:fork-init.md`, `1000xagent:inspect.md`, `1000xagent:list.md`, `1000xagent:maintain-claude-folder.md`, `1000xagent:optimize-repo.md`, `1000xagent:push-all.md`, `1000xagent:workflow-enhance.md`

**Cross-cutting utilities (stay, not project-agents):**
- `git-commit.md`, `git-push.md` — git utilities
- `save-state.md`, `load-state.md`, `log.md` — session persistence
- `self-enhance.md` — I use this on myself; project agents use it locally on themselves
- `remove-agent.md` — course-agent deactivation utility

**Deleted during TODO #20 (were leaks):**
- `1000xdev.md` → moved to `~/dev/tyleryouk.com/.claude/commands/`
- `1000xpeps.md` → moved to `~/dev/peptide-shop/.claude/commands/`
- `1000xraw.md` → moved to `~/dev/utopia-raw/.claude/commands/`
- `1000xcards.md` → moved to `~/dev/salesperson-business-cards/.claude/commands/`
- `1000xcards:deploy.md` → moved to same

**Never belongs here:** any project-agent activation command (`1000xdev.md`, `1000xpeps.md`, `1000xraw.md`, `1000xcards.md`, `1000xutopia.md`, `1000xleet.md`, `[private-internal-tooling].md`, `[private-internal-tooling].md`, etc.). These live in their repos.

---

## `skills/` detailed inventory

All skills here are either cross-cutting or 1000xagent-owned. None are project-specific. Confirmed via Axis A audit in TODO #20 Phase 2.

| Skill | Scope | Owner |
|---|---|---|
| `agent-creation/` | Cross-cutting | Me (used to create project agents) |
| `architecture-propagation/` | Cross-cutting | Me |
| `command-organization/` | Cross-cutting | Me |
| `create-desktop-app/` | Cross-cutting | Me (scaffolding utility) |
| `domain-context/` | Cross-cutting | Me (auto-load domain context) |
| `git-workflow/` | Utility | Me |
| `help/` | Utility | Any agent |
| `instagram-short/` | Utility | Any agent (content generator) |
| `load/` | Utility | Any agent |
| `maintain-agent-site/` | Cross-cutting | Me (used by 1000xdev via utility mode) |
| `manage-commands-and-skills/` | Cross-cutting | Me |
| `plan/` | Utility | Any agent |
| `refresh-agent-site/` | Cross-cutting | Me |
| `repository-initialization/` | Cross-cutting | Me |
| `session-state/` | Utility | Any agent |
| `solve/` | Utility | Any agent |
| `spec/` | Utility | Any agent |
| `test-app/` | Utility | Any agent |
| `vercel-deploy/` | Utility | Any agent |

If a new skill proposal is specific to one project, it goes in that project's repo, not here.

---

## `rules/` detailed inventory

All rules here govern system-wide behavior. All stay in my folder.

| Rule | Scope | Summary |
|---|---|---|
| `agent-hierarchy.md` | Global | Hierarchy levels, domain access rules |
| `agent-management.md` | Global | Agent lifecycle (create/enhance/deprecate) |
| `autonomous-authority.md` | Global | When I act without approval |
| `claude-folder-spec.md` | Global | Canonical Claude Code `.claude/` folder spec |
| `claude-folder-structure.md` | Global | My folder's organization |
| `cross-repository-operations.md` | Global | Cross-repo git and consistency rules |
| `dev-folder-ecosystem.md` | Global | Conventions for `~/dev/` |
| `master-control-system.md` | Global | My role as master control |
| `permission-policy.md` | Global | Bypass-permissions 4-layer defense-in-depth |
| `project-level-agents.md` | Global | 5-piece contract for project agents (rewritten TODO #20) |
| `registry-truth.md` | Global | `agents.yaml` is single source of truth |
| `self-enhancement.md` | Global | Self-improvement framework |
| `skill-management.md` | Global | Skill vs command decision framework |
| `system-orchestration.md` | Global | Multi-agent coordination |
| `utopia-brand-system.md` | Shared | Utopia Suite brand tokens (applies to all Utopia agents) — stays global because it crosses multiple Utopia businesses |
| `windows-paths.md` | Global | WSL2 path conversion convention |

---

## `private/` folder audit

Secrets. Gitignored.

| Path | Scope | Action |
|---|---|---|
| `vercel-token.txt` | Shared across every Vercel project | **Keep global** — used by 1000xdev, 1000xpeps, 1000xcards, 1000xutopia, 1000xraw (future), 1000xleet (future) |
| `cloudflare/`, `cloudflare-gateway.env`, `create-gateway-policy.sh` | System-wide | Keep global (WARP protection, content filter) |
| `oura-client-id.txt`, `oura-client-secret.txt` | Personal (health tracking) | Keep global |
| `1000xagent-anthropic-key.txt` | Mine | Keep global |
| `peptide-shop/`, `peptide-shop-db.txt`, `peptide-shop-session-secret.txt` | 1000xpeps-specific | **Migrate to `~/dev/peptide-shop/.claude/private/`** (gitignored there) OR delete if already in Vercel env |
| `fal-ai.env` | 1000xraw-specific | **Migrate to `~/dev/utopia-raw/.claude/private/`** |
| `supabase-pat.txt` | Shared (1000xpeps + 1000xcards + future tyleryouk.com booking) | Keep global |

Migration of project-specific secrets is a defer-to-Tyler decision because they may already be in Vercel env vars; double-writing and then deleting risks losing the only copy. Flagged here; not executed in Group E pending Tyler's confirmation of Vercel-env state.

---

## `research/` folder audit

Utopia Suite research (9 files at `research/4-15/utopia-suite-*.md`) should move to `~/dev/utopia/.claude/research/4-15/` to sit with the Utopia parent repo. This keeps 1000xagent's folder focused on its own materials and puts Utopia Suite research with the agent that needs it.

**Pending action (Group E):** move those 9 files; update operating principle #6 in `~/.claude/CLAUDE.md` to reference the new location.

Other research (e.g. `compass_artifact_wf-*.md`) stays — it's generic and I reference it directly.

---

## `context/` folder audit

| Path | Purpose | Action |
|---|---|---|
| `home-server/` | Infrastructure planning for future Dell OptiPlex 7060 | Keep global (my planning space) |
| `leetcodesprints/` | Reference notes during 1000xleet development | Could migrate to `~/dev/leetcodesprints/.claude/context/` — defer; low priority |
| `pictures/` | Image references I've loaded | Keep global |
| `prompts/` | Prompt templates I reference | Keep global |
| `utopia-browser/` | Utopia Browser reference notes | Consider migrating to `~/dev/utopia/.claude/context/` — defer |

---

## `hooks/` audit

- `index.md` — documentation
- `session_start.js` — my session-start hook (auto-load state)
- `sync-tyleryouk.sh` — syncs `agents.yaml` → `tyleryouk.com/frontend/src/data/agents.generated.ts`. **Stays here** because it watches a file in my folder and triggers a build in a different repo — natural home is global. Could alternatively move to `~/dev/tyleryouk.com/.claude/hooks/` if Claude Code supports repo-local hooks firing on changes to external paths (it doesn't, as of April 2026), so it stays.

---

## `logs/` convention

My logs live here (`logs/1000xagent/`). Any project-agent logs go into their own repo's `logs/` folder, not here. Currently contains `[private-internal-tooling]/` (legacy), `processing-tracking.md` (generic), `unknown/` (legacy auto-generated). Periodic cleanup: if a project agent's logs appear in my folder, move them to the project repo.

---

## `plans/` audit

Auto-generated named plan artifacts from `/plan` skill sessions. Legitimate residence. One exception: `1000xdev-agent-site-prompt.txt` (690-line build spec for tyleryouk.com) is 1000xdev-specific but was created here during early bootstrapping. Already referenced from `~/dev/tyleryouk.com/.claude/CLAUDE.md`. Could be migrated to `~/dev/tyleryouk.com/.claude/plans/` — defer as low-priority follow-up.

---

## Legacy / retired

See `~/.claude/1000xagent/deprecated-patterns.md` for:
- The old 6-piece project-agent contract (piece #4 = global activation command)
- Why TODO #20 retired it
- The file list of pre-migration global project-agent commands

---

## Update protocol

This map is my source of truth for "what lives here and why." When I add a new folder, skill, or rule, I update this map in the same commit. When I delete something, I update this map. If this map disagrees with reality, reality wins and I fix the map — but the test I run on my own folder IS this map; mismatches get caught early.