← Back to feature database

File Naming, Track IDs & Versioning

FTR-08

What this is

The naming and versioning discipline for the whole project: the default filename format, the multi-track document ID system (for projects with 10+ documents), dual versioning (file version vs. internal footer version), and the roll-up/aggregate document pattern. This is what makes every document uniquely referenceable by a short code.
install file-naming-and-versioning
Optional: false · Depends on: [FTR-04] · Registry refs: [2.07, 5.07, 5.11]

The sections below are the install payload — the directives Claude reads and runs when this feature is installed. Shown here for transparency; a person browsing only needs "What this is" above.

Assess first
- Confirm the project code is established (from Agent Role & Project Identity). Naming depends on it.
- Read `admin\AGENT_INSTRUCTIONS.md` for any existing track table or naming convention and carry it forward.
- Look at existing filenames in the project to see whether a track ID scheme is already in use.
Ask, only if needed
- If the project has (or will have) 10+ documents and no track table exists: "Let's set up document tracks -- functional groupings like Technical, Legal, Financial, Operations. I'll suggest a set based on your project type; you confirm." Use the project-type track defaults; confirm the finalized table.
- For legal projects, use the Legal file-naming convention from the Legal Preferences feature instead of the default format.
- Otherwise nothing to ask.
Write (payload written into admin\AGENT_INSTRUCTIONS.md)
Add this section to `admin\AGENT_INSTRUCTIONS.md`:

```
* FILE NAMING & VERSIONING

Track document format:
  [ProjectCode]-[TRACK][NUMBER]_[Short_Title].[ext]
General document format:
  [ProjectCode]_[DocType]_[Subject]_[YYYY-MM-DD]_v[X.X][_Draft].[ext]
Tracker files: static filename -- version lives inside the file header,
  never in the name.

DOCUMENT ID SYSTEM (multi-track library, recommended for 10+ documents)
Every document gets a unique, short, referenceable ID.
Examples:
  THZ-T02_Network_Architecture.docx        (Technical, doc #2)
  THZ-L05_Door_Egress_Compliance_v5.docx   (Legal, doc #5, major rev)
  WOW-B01_Organization_Profile.docx        (Business, doc #1)

Track table (finalize at setup):
| Track | Code            | Scope                          | Folder            |
|-------|-----------------|--------------------------------|-------------------|
| [Name]| [Code]-[L]##    | [Scope]                        | docs\[folder]\    |
| Ref   | --               | Strategic docs w/o track IDs   | docs\reference\   |

Common track letters: T Technical · C Construction · P Procurement ·
F Financial · O Operations · L Legal · B Business · R Relations ·
M Marketing. Assign the next sequential number within a track when a new
document is created. Reference documents by their ID code in conversation.

DUAL VERSIONING
- File version: changes only when a major revision must be preserved as a
  distinct file on the file system (e.g., _v4 archived, _v5 current).
- Internal version: tracked in the document footer; increments freely
  without renaming the file (Draft v0.1 -> v0.2 -> v0.3 -> v1.0).
- Rule: rename the file only when the old version must be preserved
  separately. Otherwise update the footer version. Prevents filename churn.

VERSIONING RULES (summary)
- All files start at v1.0 or internal v0.1
- Draft files carry _Draft in the name; final files drop it
- Only current version in the active folder -- previous to archive\ (never
  delete)
- One document = one tracker card = one active file

ROLL-UP / AGGREGATE PATTERN
When a master summary aggregates sub-documents:
- Always build sub-documents first; build the master/roll-up last
- The master reflects the current state of all sub-documents
- Never edit line-item detail in the master -- edit the sub-document, then
  rebuild the roll-up
```
Confirm
Confirm: your naming convention, track ID system, and dual versioning are in the agent instructions -- every document now gets a unique, referenceable code. Want to install another, or is that everything for now?