--- feature_id: FTR-15 title: Project Cache category: Foundation optional: false depends_on: none (soft: benefits from FTR-36 for the Excel manifest, FTR-12 for non-text files, and FTR-13 if installed) registry_refs: [5.30, 8.01, 8.02, 8.03, 8.04, 8.05, 8.06, 8.07, 8.08, 8.09] --- # Project Cache Depends on: none. Soft links, used when installed: [FTR-36 — Excel Tracker (Base Capability)](../items/excel-tracker-base-capability.md) (Excel manifest), [FTR-12 — Markdown Sidecars](../items/markdown-sidecars.md) (text views of non-text files), [FTR-13 — Document Registry](../items/document-tracker-system.md) ## What this is A flat staging directory (`project_cache\`) plus a manifest tracker that keeps Claude's Project Files current. Registered files get copied to the cache on one command; the user opens the folder, selects all, and drags to Project Files. It closes the gap between "the right files exist somewhere" and "the right files are loaded into every conversation." `admin\AGENT_INSTRUCTIONS.md` and `CLAUDE.md` are deliberately never registered here, no matter how important they are to the project — see the EXCLUDED FROM AUTO-REGISTRATION rule in the Write payload below for why. **Why this is a Foundation feature (v2.0).** An agent can only work well in a project folder if it can find the right context quickly. The Project Cache is where that context is held: one folder (`project_cache\`) and one index (`INDEX.md`, backed by `INDEX.json`). That structure is the project's context contract: every agent in the project, in claude.ai or in Claude Code, reads the index first and opens only the cached file it points to. The CACHE INDEX rules in the Write payload below govern how agents reach cached context. Because other features rely on that contract, this feature has no hard dependencies and installs in the Foundation pass. **The manifest has two modes (v2.0).** With FTR-36 installed, the manifest is an Excel workbook (via FTR-36's mechanics) at `trackers\data\[ProjectCode]_Project_Cache.xlsx`, a workbook instead of a markdown table. Without FTR-36, the manifest is a markdown table at `admin\Project_Cache_Manifest.md` with the same columns, so this feature has no hard dependency and installs in the Foundation pass; when FTR-36 is installed later, the rows move into the workbook and the markdown file is retired. **The cache directory itself is completely unaffected**: it remains flat, copy-only, never a source for edits, exactly as before. This is a narrow, self-referential case worth naming: in workbook mode, the manifest's own markdown sidecar (per FTR-36's own sidecar rule) becomes itself a cacheable file, and gets a row in the manifest pointing to itself — not circular in a problematic way, just the same pattern every other tracker's sidecar already follows. **Cache index (v2.0).** The cache also carries a generated index: `INDEX.md` (the short view an AI reads to choose a file) and `INDEX.json` (the full record: hashes, heading outlines, summaries, tiers). Files are indexed where they are; nothing is moved or duplicated. It lets an agent with no Project Files retrieval (Claude Code on a Linux VM) use the cache as precisely as a claude.ai Project does, and gives claude.ai's retrieval a short document that points at the right file. The full format is in `admin\feature-prompts\project-cache-index.md` (pointer-style). ## Assess first - Check whether `project_cache\` exists at the project root — create it if missing (flat, no subdirectories, unchanged). - Check which manifest mode applies. If FTR-36 is installed, look for the workbook at `trackers\data\[ProjectCode]_Project_Cache.xlsx`; otherwise look for the markdown manifest at `admin\Project_Cache_Manifest.md`. Create whichever applies if it is missing. - Locate the auto-registerable files so you can register what exists and mark the rest "Not Yet Found": - `[ProjectCode]_Logo.png` in `brand\` - `Brand_Standards.md` in `brand\` - `[Entity]_Profile_Sanitized.md` in `admin\` - `tracker_index.md` in `trackers\` - Do NOT include `admin\AGENT_INSTRUCTIONS.md` or `CLAUDE.md` in this list, even though they're two of the most important files in the project — see the Write payload's EXCLUDED FROM AUTO-REGISTRATION rule for why (unchanged). - Check whether FTR-36 is installed. If it is, the manifest workbook is written and edited via its access method; if not, use the markdown manifest (FTR-36 can take it over later). - Check whether `project_cache\INDEX.json` and `project_cache\INDEX.md` exist; if `INDEX.json` exists, check that it parses and read its `schema` and counts (stale, missing). - Treat both files as generated: never register them in the manifest, never list them as scan candidates, never hand-edit them. - For each registered non-text file (.xlsx, .pdf, .docx), check whether a sidecar exists (FTR-12). A non-text file is indexed only through its sidecar; list the ones that lack one. ## Ask, only if needed - After auto-registering, offer: "I've set up the project cache with [N] auto-registered files. Want to run the first refresh now?" If yes, run it immediately. - Otherwise nothing to ask — the auto-registration list requires no input. ## Write Create `project_cache\` at the project root (unchanged). Create the manifest: with FTR-36 installed, the workbook at `trackers\data\[ProjectCode]_Project_Cache.xlsx` via FTR-36's access method; otherwise the markdown manifest at `admin\Project_Cache_Manifest.md`. Auto-register all applicable files. If `trackers\README.md` exists, update it to include the cache manifest entry. After creating the cache and manifest, create `admin\feature-prompts\project-cache-index.md` from the asset [project-cache-index-spec.md](https://claude.sotekzone.com/data/items/project-cache-index-spec.md) (check for an existing file first), and offer: "Want me to build the first cache index now?" Then add this section to `admin\AGENT_INSTRUCTIONS.md` (merge additively; if a `◆ PROJECT CACHE` section already exists, update it in place): ``` ◆ PROJECT CACHE (in workbook mode the manifest nests under FTR-36's EXCEL TRACKER section) Cache Directory: [project_root]\project_cache\ (flat — no subdirectories, unchanged) Manifest: trackers\data\[ProjectCode]_Project_Cache.xlsx (via FTR-36) when FTR-36 is installed; otherwise admin\Project_Cache_Manifest.md (markdown table, same columns) Context index: project_cache\INDEX.md + INDEX.json (generated; see CACHE INDEX) The Project Cache directory itself is unaffected by this feature's Excel conversion — it remains a flat staging directory, registered files are copied here on refresh, exactly as before. Open the folder, select all, drag to Claude Project Files. PURPOSE: Claude's Project Files hold the closest-in-context reference material. The cache keeps them current without manual file hunting. EXCLUDED FROM AUTO-REGISTRATION — HARD RULE (unchanged) admin\AGENT_INSTRUCTIONS.md and CLAUDE.md never go in the Project Cache, regardless of how important they are to the project or how they turn up in a scan. AGENT_INSTRUCTIONS.md's content already reaches every conversation automatically through the Claude Project Instructions field — caching a copy too would add nothing. CLAUDE.md is read directly off disk by Cowork and Claude Code, never through Project Knowledge, so caching it serves no purpose either. If either file is ever suggested as a cache candidate — by "scan for cache candidates," by a person asking to add it, or by any other route — decline and explain why rather than registering it. This applies regardless of which other files are or aren't in the cache. AUTO-REGISTERED FILES (unchanged) [ProjectCode]_Logo.png <- brand\ (Critical) Brand_Standards.md <- brand\ (High) [Entity]_Profile_Sanitized <- admin\ (High) tracker_index.md <- trackers\ (Medium) If a file isn't found at setup, register it as "Not Yet Found" and pick it up automatically at first refresh once it exists. COMMANDS (apply to the manifest in either mode; index commands are under CACHE INDEX) "refresh project cache" / "update project cache" → copies all registered files to project_cache\ "add [file] to project cache" → permanently registers (row added to the manifest); included in all future refreshes (except AGENT_INSTRUCTIONS.md and CLAUDE.md — see the hard rule above; if asked to add either, explain why instead) "show project cache" → reads the manifest, lists registered files and current status "scan for cache candidates" → recursive scan for unregistered cacheable files REFRESH BEHAVIOR — HARD RULES (against the manifest in whichever mode is installed) 1. Read the manifest (the workbook via FTR-36's access method, or the markdown table) 2. For each registered file: locate at its source path; copy if not yet in cache; copy only if source is newer (skip if identical); if source not found, mark Not Found and CONTINUE (do not abort the run) 3. Update the manifest with new statuses and timestamps (workbook mode: follow FTR-36's own commit protocol — backup, edit, save, verify) 4. Rebuild the cache index incrementally (see CACHE INDEX): refresh bytes, sha256 and outline for every cached file; keep every current summary; mark changed files stale; add new files as missing; regenerate INDEX.md. If summaries cannot be written now, the refresh still completes and the index is left marked stale. 5. Report: N copied · N skipped · N not found · index: N entries, N current, N stale, N missing 6. No manual intervention once started — the run goes to completion CACHE INDEX — GOVERNING FOR CONTEXT, HARD RULES (new in v2.0) Two generated files sit at the root of project_cache\ (the directory stays flat): INDEX.md short view: what each cached file covers and when to read it. Drag it to Project Files with the rest. INDEX.json full record: hashes, outlines, summaries, tiers. For agents and scripts. Do NOT drag it into Project Files. Files are indexed where they are. Nothing is moved, re-copied or duplicated for the index. Both files are generated: never edited by hand, never registered in the manifest, never scan candidates. Format, field rules and build procedure: admin\feature-prompts\project-cache-index.md Read that file before building, checking or changing an index. Format name: schema "project-cache-index/1". COMMANDS "build cache index" (re)build INDEX.json and INDEX.md incrementally; write summaries only for stale or missing entries "check cache index" report only: every cached file indexed, every sha256 current, no stale or missing summary, JSON parses, excluded files absent "show cache index" print INDEX.md, or one entry AGENT CONTRACT — applies to any agent in this project, in claude.ai or in Claude Code: 1. Before opening any file in project_cache\, read project_cache\INDEX.md and choose the file by its "Read when". 2. Tier 0: the index line is enough. Tier 1: read the whole file when the task matches. Tier 2: never read whole; use the outline line ranges in INDEX.json and read only those lines. 3. Cache files are copies. Never edit one. The source of truth is the file's "source" in INDEX.json. Change the source, then "refresh project cache". 4. If a file's sha256 no longer matches INDEX.json, or its summary is stale, still use the file, say the index is stale, and offer "build cache index". 5. After adding or changing a cache file, rebuild the index. 6. Say which cache files you relied on. 7. admin\AGENT_INSTRUCTIONS.md and CLAUDE.md stay excluded and are never indexed. Never index anything from keys\ or any credential file. 8. If project_cache\INDEX.md does not exist yet, say so, work from the manifest, and offer "build cache index". POINTER — Full detail: admin\feature-prompts\project-cache-index.md Invoke when: building, checking or changing INDEX.json or INDEX.md. COPY RULE — HARD (unchanged) Copy only. Never move. Never modify source files. Newer source overwrites the cached version; identical version is skipped. Mechanism: Windows MCP Copy-Item (K:\ path) preferred, Filesystem MCP fallback. If neither can write to project_cache\: present the file list for manual copy and flag as a Bootstrap Reconciliation Item. RECURSIVE SCAN ("scan for cache candidates", unchanged) Walk the project tree; flag files matching, not already in the manifest: *.png in brand\ · *Brand_Standards* · *_Profile*.md in admin\ · tracker_index.md anywhere · any .md in docs\reference\ · any .html in trackers\templates\. Never flag AGENT_INSTRUCTIONS.md or CLAUDE.md as a candidate, no matter where they're found — the exclusion above is unconditional, not just a matter of them not being on this pattern list. Present candidates; user confirms → permanently registered. Skip INDEX.md and INDEX.json; they are generated and never candidates. DIRECTORY CONSTRAINTS — HARD (unchanged) Flat — no subdirectories; all files at root level only. Staging only — never a source for edits, drafts, or production. Files here are copies; the source of truth is always the registered source path. User workflow: refresh → open project_cache\ → select all except INDEX.json → drag to Claude Project Files. The only generated files allowed at the root are INDEX.md and INDEX.json. MANIFEST TRACKING (a single Excel workbook via FTR-36 when installed, otherwise a markdown table at admin\Project_Cache_Manifest.md) Workbook mode: workbook at trackers\data\. Static filename; version tracked inside the workbook itself (a Meta sheet or header cell, per FTR-36's own versioning convention). Columns: File Name, Source Path, Type, Priority, Last Copied, Status. Status values: Current / Updated / Not Found / Not Yet Copied. Priority: dropdown, Critical / High / Medium / Low. Every write follows FTR-36's own commit protocol (pre-edit backup, COM edit, fresh-session round-trip verification). Markdown mode: the same columns as a markdown table, edited as an ordinary file (read it first, change only the rows concerned, re-read to verify). INDEX.md and INDEX.json never appear as manifest rows (generated, not copied). A sidecar for a cached non-text file (FTR-12) is registered like any other file, so it reaches project_cache\ by the normal refresh. WHEN USER ASKS ABOUT PROJECT FILES "Claude's Project Files are the closest-in-context storage in every conversation. The Project Cache makes sure they stay current. Refresh when files change, open project_cache\, select all except INDEX.json, and drag to Project Files. INDEX.md tells Claude which cached file to open, so keep it current: say 'build cache index' after a refresh. AGENT_INSTRUCTIONS.md and CLAUDE.md are the two exceptions; they reach conversations through other mechanisms already, so they're never part of this cache. That's the full workflow." ``` Manifest columns (workbook at `trackers\data\[ProjectCode]_Project_Cache.xlsx`, or the same columns as a markdown table at `admin\Project_Cache_Manifest.md`): ``` Meta (header cell or dedicated sheet): Project Code, Cache Dir, Last Refresh (datetime), Version Data sheet columns: # | File Name | Source Path | Type | Priority | Last Copied | Status Example rows (values only, dropdowns per FTR-36's own conventions for Priority and Status): 1 | [ProjectCode]_Logo.png | brand\ | Logo | Critical | [date] | Current 2 | Brand_Standards.md | brand\ | Brand | High | [date] | Current 3 | [Entity]_Profile_Sanitized.md | admin\ | Profile | High | [date] | Updated 4 | tracker_index.md | trackers\ | Index | Medium | [date] | Not Yet ``` Note: `admin\AGENT_INSTRUCTIONS.md` and `CLAUDE.md` deliberately never appear as a row in this workbook — see the EXCLUDED FROM AUTO-REGISTRATION rule above. ## Confirm Confirm: your Project Cache is set up with [N] auto-registered files, tracked in [an Excel workbook (via FTR-36) | a markdown manifest], and now carries a generated index (INDEX.md for Project Files, INDEX.json for agents). Say "refresh project cache" to stage files, then "build cache index" to keep the index current. Want to build the first index now, install another, or is that everything for now?