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!
|
||||
@@ -1,18 +1,28 @@
|
||||
# ClaudeTools Project Context
|
||||
|
||||
**FIRST: READ YOUR DIRECTIVES**
|
||||
**FIRST: READ YOUR DIRECTIVES AND FILE PLACEMENT GUIDE**
|
||||
|
||||
Before doing ANYTHING in this project, read and internalize `directives.md` in the project root.
|
||||
Before doing ANYTHING in this project:
|
||||
1. Read and internalize `directives.md` in the project root
|
||||
2. Review `.claude/FILE_PLACEMENT_GUIDE.md` for file organization
|
||||
|
||||
This file defines:
|
||||
**directives.md** defines:
|
||||
- Your identity (Coordinator, not Executor)
|
||||
- What you DO and DO NOT do
|
||||
- Agent coordination rules (NEVER query database directly)
|
||||
- Enforcement checklist (NO EMOJIS, ASCII markers only)
|
||||
|
||||
**If you haven't read directives.md in this session, STOP and read it now.**
|
||||
**FILE_PLACEMENT_GUIDE.md** defines:
|
||||
- Where to save new files (projects/ vs clients/ vs root)
|
||||
- Session log locations (project-specific vs general)
|
||||
- File naming conventions
|
||||
- Organization maintenance
|
||||
|
||||
Command: `Read directives.md` (in project root: D:\ClaudeTools\directives.md)
|
||||
**If you haven't read these in this session, STOP and read them now.**
|
||||
|
||||
Commands:
|
||||
- `Read directives.md` (in project root)
|
||||
- `Read .claude/FILE_PLACEMENT_GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
@@ -378,11 +388,27 @@ alembic upgrade head
|
||||
|
||||
**CRITICAL:** Use `/context` command when user references previous work
|
||||
|
||||
### Session Logs (session-logs/)
|
||||
- **Format:** `session-logs/YYYY-MM-DD-session.md`
|
||||
- **Content:** ALL credentials, infrastructure details, decisions, commands, config changes
|
||||
- **Purpose:** Full context recovery when conversation is summarized or new session starts
|
||||
- **Usage:** `/save` command creates/appends to today's session log
|
||||
### Organized File Structure (NEW - 2026-01-20)
|
||||
**All files are now organized by project and client:**
|
||||
- `projects/[project-name]/` - Project-specific work
|
||||
- `clients/[client-name]/` - Client-specific work
|
||||
- `session-logs/` - General/cross-project logs
|
||||
- **See:** `PROJECT_ORGANIZATION.md` for complete structure
|
||||
|
||||
### Session Logs (Multiple Locations)
|
||||
**Project-Specific:**
|
||||
- Dataforth DOS: `projects/dataforth-dos/session-logs/YYYY-MM-DD-session.md`
|
||||
- ClaudeTools API: `projects/claudetools-api/session-logs/YYYY-MM-DD-session.md`
|
||||
|
||||
**Client-Specific:**
|
||||
- Format: `clients/[client-name]/session-logs/YYYY-MM-DD-session.md`
|
||||
|
||||
**General/Mixed:**
|
||||
- Format: `session-logs/YYYY-MM-DD-session.md` (root)
|
||||
|
||||
**Content:** ALL credentials, infrastructure details, decisions, commands, config changes
|
||||
**Purpose:** Full context recovery when conversation is summarized or new session starts
|
||||
**Usage:** `/save` command determines correct location and creates/appends
|
||||
|
||||
### Credentials File (credentials.md)
|
||||
- **Content:** ALL infrastructure credentials (UNREDACTED)
|
||||
|
||||
@@ -1,7 +1,21 @@
|
||||
Save a COMPREHENSIVE session log to session-logs/ directory. This is critical for context recovery.
|
||||
Save a COMPREHENSIVE session log to appropriate session-logs/ directory. This is critical for context recovery.
|
||||
|
||||
## Determine Correct Location
|
||||
|
||||
**IMPORTANT: Save to project-specific or general session-logs based on work context**
|
||||
|
||||
### Project-Specific Logs
|
||||
If working on a specific project, save to project folder:
|
||||
- Dataforth DOS work → `projects/dataforth-dos/session-logs/YYYY-MM-DD-session.md`
|
||||
- ClaudeTools API work → `projects/claudetools-api/session-logs/YYYY-MM-DD-session.md`
|
||||
- Client-specific work → `clients/[client-name]/session-logs/YYYY-MM-DD-session.md`
|
||||
|
||||
### General/Mixed Work
|
||||
If working across multiple projects or general tasks:
|
||||
- Use root `session-logs/YYYY-MM-DD-session.md`
|
||||
|
||||
## Filename
|
||||
Use format `session-logs/YYYY-MM-DD-session.md` (today's date)
|
||||
Use format `YYYY-MM-DD-session.md` (today's date) in appropriate folder
|
||||
|
||||
## If file exists
|
||||
Append a new section with timestamp header (## Update: HH:MM), don't overwrite
|
||||
@@ -72,11 +86,30 @@ Format credentials as:
|
||||
|
||||
This log MUST contain enough detail to fully restore context if this conversation is summarized or a new session starts. When in doubt, include MORE information rather than less. Future Claude instances will search these logs to find credentials and context.
|
||||
|
||||
## ClaudeTools Integration
|
||||
## Project-Specific Requirements
|
||||
|
||||
For ClaudeTools project, also include:
|
||||
### Dataforth DOS Project
|
||||
Save to: `projects/dataforth-dos/session-logs/`
|
||||
Include:
|
||||
- DOS batch file changes and versions
|
||||
- Deployment script updates
|
||||
- Infrastructure changes (AD2, D2TESTNAS)
|
||||
- Test results from TS-XX machines
|
||||
- Documentation files created
|
||||
|
||||
### ClaudeTools API Project
|
||||
Save to: `projects/claudetools-api/session-logs/`
|
||||
Include:
|
||||
- Database connection details (172.16.3.30:3306/claudetools)
|
||||
- API endpoints created or modified
|
||||
- Migration files created
|
||||
- Test results and coverage
|
||||
- Any infrastructure changes (servers, networks, clients)
|
||||
|
||||
### Client Work
|
||||
Save to: `clients/[client-name]/session-logs/`
|
||||
Include:
|
||||
- Issues resolved
|
||||
- Services provided
|
||||
- Support tickets/cases
|
||||
- Client-specific infrastructure changes
|
||||
|
||||
Reference in New Issue
Block a user