Home / Ops / Housekeeping and Process

Affirmology - File Organization Plan (SAFE, nothing moved yet)

Updated Jun 26, 2026 · Affirmology_FileOrg_Plan_v1.md

Summary. /CLAUDE/AFFIRMOLOGY is the project folder, with real sub-project folders inside it. A nested CLAUDE OUTPUTS/Affirmology folder grew inside it and is redundant and confusing. Root cause: a line in the personal global instructions ("everything

title: Affirmology - File Organization Plan (SAFE, nothing moved yet) type: plan status: PHASE 0 DONE 2026-06-20 (convention locked in CLAUDE.md, nothing moved). Phases 1-2 PHYSICAL MIGRATION NOW OPTIONAL as of 2026-06-26 (see the note below): the Resource Hub solves the real goal without moving anything. created: 2026-06-20 tags: [affirmology, file-org, plan, housekeeping]

✦ File Organization Plan

[!note] 2026-06-26 update: the Resource Hub supersedes the urgency of this plan. Jeff's real goal was never the folder layout itself. It was: keep things indexed and linked, cluster related docs across files, and never lose good info when resuming a topic that lives across multiple documents. The new Resource Hub (resource-hub/, deploying to resources.affirmology.ai) solves exactly that. It reads every doc IN PLACE, including everything in CLAUDE OUTPUTS/Affirmology, groups related docs into searchable topic clusters with overviews, and never moves or modifies a source file. Consequence: the physical migration in Phases 1 and 2 below is now OPTIONAL. Old resources can stay in the CLAUDE OUTPUTS/Affirmology folder. New docs already go into the project's own structure (Phase 0 convention in CLAUDE.md). The 2 hardcoded code paths in hermes_tools.py and craft_seed.py stay untouched, so nothing can break. Do the physical move later only if you specifically want it; the Hub's manifest.json is the ready catalog for it. Until then, treat Phases 1-2 as on hold by choice, not as pending work.

[!warning] Nothing has been moved. This is a plan only. No files were moved, renamed, or deleted to create it. We agree the structure first, then migrate in small reversible steps with pointers left behind.

Why we're doing this

/CLAUDE/AFFIRMOLOGY is the project folder, with real sub-project folders inside it. A nested CLAUDE OUTPUTS/Affirmology folder grew inside it and is redundant and confusing. Root cause: a line in the personal global instructions ("everything you create goes in CLAUDE OUTPUTS/<project>/"), written for a generic setup, fires even though this folder is already the project. It will keep recreating that folder in every project until the global line is changed (see "Stop the recurrence" below).

What we actually found (the real dependency surface)

The scary part is small. A full scan turned up only 15 files that reference the CLAUDE OUTPUTS path:

Where Count Risk Handling
Root docs (prose, incl. PROJECT_STATE.md) 10 Low Find/replace the path string
Inside CLAUDE OUTPUTS/Affirmology (prose) 3 Low Find/replace, or moot after move
Code that hardcodes the path 2 High Update explicitly (see below)

The two code files are the only things that would break a running script:

Other facts that make this safe:

The "won't break" technique (your pointer idea, made concrete)

Two layers of pointer so nothing dangles:

  1. Symlink pointers (the load-bearing one). When a file or folder finally moves, leave a symlink at the OLD path pointing to the new location. macOS, Obsidian, browsers, and Python all follow symlinks, so any old hardcoded path keeps resolving even before we update it. The old CLAUDE OUTPUTS/Affirmology becomes a symlink to the new home.
  2. A human-readable _MOVED.md stub in the old folder explaining where things went, for anyone (or any chat) that looks with their eyes instead of a path.

For the 2 code files, we don't rely on symlinks, we update the path in the code directly, because code should point at the truth, not a redirect.

Proposed target structure (DRAFT - react/edit freely)

Keep the existing code/engine sub-folders exactly as they are (affirmology-agent, affirmology-site, affirmology-studio, affirmology-demo-site, corpus, baselines). Only the loose docs get organized. Draft doc folders inside the project root:

/AFFIRMOLOGY
├── (ROOT, never move)  CLAUDE.md, MEMORY.md, Affirmology_PROJECT_STATE.md  ← the harness auto-loads CLAUDE.md + MEMORY.md from the project root, and CLAUDE.md tells every chat to read PROJECT_STATE here. Keep all three at root.
├── 00_START/        SystemInterface guide, Reports index, and pointers to the root entry files
├── Strategy/        business, investor, briefs, brand, competitor, cofounder, advisor, funds
├── Product/         app + Atlas specs, gamification, delivery, studio specs, roadmaps
├── Engine/          corpus, craft, agents, hermes, reading-craft, council design (technical)
├── Council/         character + visual sheets (Atlas, Wisdom Circle, oracle sheets, visual bible)
├── Video/           investor video, avatars, scenes, b-roll, VideoEditKit, prompt kits, remotion
├── Readings/        Jeff/Sol/Colin charts, wealth codes, vedic profiles, custom-audio briefs
├── Audio/           audio production, music, openings frameworks
├── Ops/             deploy, runbooks, build briefs, onboarding
├── Archive/         superseded versions (a v1 when a v3 exists, old briefs)
└── (code folders unchanged)

This is a starting point, not a lock. We can split, merge, or rename any of these.

Pre-flight checklist (the "things to check" before any move)

Stop the recurrence (so this never regrows)

  1. This project's CLAUDE.md: add a line stating deliverables go in the structure above and that no CLAUDE OUTPUTS folder is to be created here. A future chat reads this and complies.
  2. Your personal global instructions (Settings, the global CLAUDE.md): this is the real source. The line telling Claude to write into CLAUDE OUTPUTS/<project>/ should be changed to "save into the active project folder's own structure." I can't edit your global settings file, but I'll hand you the exact line to change. Until that's done, the project CLAUDE.md override handles it for Affirmology specifically.

Suggested phasing (each step reversible)

Affirmology_FileOrg_Plan_v1 - plan only, nothing moved. Next decision: approve or edit the target structure, then we run Phase 0.