Complete project organization: move all DOS files to projects/dataforth-dos, create client folders, update Claude config
This commit is contained in:
224
.claude/FILE_PLACEMENT_GUIDE.md
Normal file
224
.claude/FILE_PLACEMENT_GUIDE.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 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:**
|
||||
```bash
|
||||
mkdir -p projects/[project-name]/{scripts,documentation,session-logs}
|
||||
cp PROJECT_INDEX_TEMPLATE.md projects/[project-name]/PROJECT_INDEX.md
|
||||
```
|
||||
|
||||
**Create new client:**
|
||||
```bash
|
||||
mkdir -p clients/[client-name]/session-logs
|
||||
cp CLIENT_INFO_TEMPLATE.md clients/[client-name]/CLIENT_INFO.md
|
||||
```
|
||||
|
||||
**Find misplaced files:**
|
||||
```bash
|
||||
# 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!
|
||||
Reference in New Issue
Block a user