claudetools/.claude/FILE_PLACEMENT_GUIDE.md

File Placement Guide - Where to Save Files

Purpose: Ensure all new files are saved to appropriate project/client folders Last Updated: 2026-01-20

---

Quick Reference

File Type	Example	Save To
DOS Batch Files	*.BAT	projects/dataforth-dos/batch-files/
DOS Deployment Scripts	deploy-*.ps1, fix-*.ps1	projects/dataforth-dos/deployment-scripts/
DOS Documentation	DOS_*.md	projects/dataforth-dos/documentation/
DOS Session Logs	Session notes	projects/dataforth-dos/session-logs/
Client Info	Client details	clients/[client-name]/CLIENT_INFO.md
Client Session Logs	Support notes	clients/[client-name]/session-logs/
ClaudeTools API Code	*.py, migrations	api/, migrations/ (keep existing structure)
ClaudeTools API Logs	Session notes	projects/claudetools-api/session-logs/
General Session Logs	Mixed work	session-logs/YYYY-MM-DD-session.md
Credentials	All credentials	credentials.md (root - shared)

---

Rules for New Files

1. Determine Context First

Ask yourself: What project or client is this related to?

• Dataforth DOS → projects/dataforth-dos/
• ClaudeTools API → projects/claudetools-api/ or root API folders
• Specific Client → clients/[client-name]/
• Multiple projects → Root or session-logs/

2. Choose Appropriate Subfolder

Within project folder:

projects/[project-name]/
├── batch-files/          # .BAT files (DOS only)
├── scripts/              # .ps1, .sh, .py scripts
├── deployment-scripts/   # Deployment-specific scripts (DOS)
├── documentation/        # .md documentation files
├── session-logs/         # Daily session logs
└── [custom-folders]/     # Project-specific folders

Within client folder:

clients/[client-name]/
├── CLIENT_INFO.md        # Master client information
├── session-logs/         # Support session logs
├── documentation/        # Client-specific docs
└── [custom-folders]/     # Client-specific folders

3. Naming Conventions

Session Logs:

• Format: YYYY-MM-DD-session.md
• Location: projects/[project]/session-logs/ or clients/[client]/session-logs/

Documentation:

• Descriptive names: DOS_FIX_SUMMARY.md, DEPLOYMENT_GUIDE.md
• Location: projects/[project]/documentation/

Scripts:

• Descriptive names: deploy-to-nas.ps1, fix-xcopy-error.ps1
• Location: projects/[project]/deployment-scripts/ or projects/[project]/scripts/

Batch Files (DOS):

• Uppercase: NWTOC.BAT, UPDATE.BAT
• Location: projects/dataforth-dos/batch-files/

---

Examples by Scenario

Scenario 1: Working on Dataforth DOS Bug Fix

Files Created:

• NWTOC.BAT (modified) → projects/dataforth-dos/batch-files/NWTOC.BAT
• deploy-nwtoc-fix.ps1 → projects/dataforth-dos/deployment-scripts/deploy-nwtoc-fix.ps1
• NWTOC_FIX_2026-01-20.md → projects/dataforth-dos/documentation/NWTOC_FIX_2026-01-20.md
• Session log → projects/dataforth-dos/session-logs/2026-01-20-session.md

Scenario 2: Helping Horseshoe Management Client

Files Created:

• Update client info → clients/horseshoe-management/CLIENT_INFO.md
• Session log → clients/horseshoe-management/session-logs/2026-01-20-session.md
• Fix script (if created) → clients/horseshoe-management/scripts/fix-glance.ps1

Scenario 3: Adding ClaudeTools API Endpoint

Files Created:

• New router → api/routers/new_endpoint.py (existing structure)
• Migration → migrations/versions/xxx_add_table.py (existing structure)
• Session log → projects/claudetools-api/session-logs/2026-01-20-session.md
• API docs → projects/claudetools-api/documentation/NEW_ENDPOINT.md

Scenario 4: Mixed Work (Multiple Projects)

Files Created:

• Session log → session-logs/2026-01-20-session.md (root)
• Reference all projects worked on in the log
• Project-specific files still go to project folders

---

Automatic File Placement Checklist

Before saving a file, ask:

1. Is this project-specific?

   • YES → Save to projects/[project-name]/[appropriate-subfolder]/
   • NO → Continue to next question

2. Is this client-specific?

   • YES → Save to clients/[client-name]/[appropriate-subfolder]/
   • NO → Continue to next question

3. Is this a session log?

   • Project-specific work → projects/[project]/session-logs/
   • Client-specific work → clients/[client]/session-logs/
   • Mixed/general work → session-logs/ (root)

4. Is this shared infrastructure (credentials, main configs)?

   • YES → Save to root (e.g., credentials.md, SESSION_STATE.md)
   • NO → Reevaluate context

5. Is this core ClaudeTools API code?

   • YES → Use existing structure (api/, migrations/, etc.)
   • NO → Project folder

---

When to Update Index Files

After creating new files, update:

1. Project Index:

   • projects/[project-name]/PROJECT_INDEX.md
   • Add new files to relevant sections
   • Update file counts
   • Update "Last Updated" date

2. Client Info:

   • clients/[client-name]/CLIENT_INFO.md
   • Add new issues/resolutions
   • Update "Last Contact" date

3. Master Organization:

   • PROJECT_ORGANIZATION.md (only for major changes)
   • Update file counts quarterly or after major restructuring

---

Special Cases

Temporary/Test Files

• Keep in root temporarily
• Move to appropriate folder once work is confirmed
• Delete if no longer needed

Shared Utilities/Scripts

• If used across multiple projects → scripts/ (root)
• If project-specific → projects/[project]/scripts/

Documentation That Spans Projects

• Create in most relevant project folder
• Reference from other project indexes
• Or save to root documentation/ if truly cross-project

Archived Projects

• Move to projects/[project-name]-archived/
• Update PROJECT_ORGANIZATION.md

---

Enforcement

When using /save command:

• Automatically determine correct session-logs/ location
• Remind user of file placement rules
• Update relevant index files

During code review:

• Check file placement
• Verify project/client organization
• Ensure indexes are updated

Monthly maintenance:

• Review root directory for misplaced files
• Move files to correct locations
• Update all index files

---

Quick Commands

Create new project:

mkdir -p projects/[project-name]/{scripts,documentation,session-logs}
cp PROJECT_INDEX_TEMPLATE.md projects/[project-name]/PROJECT_INDEX.md

Create new client:

mkdir -p clients/[client-name]/session-logs
cp CLIENT_INFO_TEMPLATE.md clients/[client-name]/CLIENT_INFO.md

Find misplaced files:

# Files that should be in project folders
ls -1 *.BAT *.ps1 *FIX*.md *DEPLOY*.md | grep -v projects/

---

Remember: Good organization now saves hours of searching later!

Context Recovery Depends On: Files being in predictable, consistent locations!