# CRITICAL FILE PLACEMENT RULES

## ABSOLUTE PROHIBITIONS - ZERO TOLERANCE

### **YOU MUST READ THIS BEFORE CREATING ANY FILE**

---

## RULE #1: NEVER CREATE .MD FILES IN ROOT DIRECTORIES

### **COMPLETELY FORBIDDEN LOCATIONS:**

```
<project-root>/*.md  (except README.md)
<project-root>/src/backend/*.md
```

### **REQUIRED LOCATIONS:**

**ALL backend documentation MUST go in:**
```
<project-root>/docs/{category}/filename.md
```

**ALL frontend documentation MUST go in:**
```
<project-root>/frontend/docs/{category}/filename.md
```

---

## RULE #2: NEVER CREATE .SH SCRIPTS IN BACKEND

### **COMPLETELY FORBIDDEN:**
```
<project-root>/src/backend/*.sh (except start.sh)
```

### **REQUIRED LOCATION:**
```
<project-root>/scripts/script_name.sh
```

---

## RULE #3: ALWAYS USE CORRECT BASE URL FORMAT

### **INCORRECT BASE URL PATTERNS:**

```bash
# WRONG: Including /api/v1 in the base URL variable
BASE_URL="https://your-api.example.com/api/v1"
```

### **CORRECT BASE URL PATTERN:**

```bash
# CORRECT: Base URL is domain only
BASE_URL="https://your-api.example.com"

# Then use with FULL API paths:
curl "$BASE_URL/api/v1/projects/"  # Explicit and clear
curl "$BASE_URL/health"            # Root-level endpoints also clear
```

### **WHY THIS MATTERS:**

1. **Clarity**: Full paths are immediately visible in code
2. **Consistency**: Same pattern across all documentation
3. **Maintainability**: Easy to update if API version changes
4. **Developer Experience**: No confusion about URL construction

---

## MANDATORY CATEGORIZATION GUIDE

### Backend Documentation Categories

| Filename Pattern | Destination | Examples |
|-----------------|-------------|----------|
| `ISSUE_*.md`, `BUG_*.md` | `docs/issues/` | ISSUE_24_SUMMARY.md |
| `*_TEST*.md`, `QA_*.md` | `docs/testing/` | QA_TEST_REPORT.md |
| `AGENT_SWARM_*.md`, `WORKFLOW_*.md` | `docs/agent-swarm/` | AGENT_SWARM_WORKFLOW.md |
| `API_*.md`, `*_ENDPOINTS*.md` | `docs/api/` | API_DOCUMENTATION.md |
| `*_IMPLEMENTATION*.md`, `*_SUMMARY.md` | `docs/reports/` | FEATURE_IMPLEMENTATION_SUMMARY.md |
| `DEPLOYMENT_*.md`, `RAILWAY_*.md` | `docs/deployment/` | DEPLOYMENT_CHECKLIST.md |
| `*_QUICK_*.md`, `*_REFERENCE.md` | `docs/quick-reference/` | QUICK_START_GUIDE.md |
| `CODING_*.md`, `*_GUIDE.md` | `docs/development-guides/` | CODING_STANDARDS.md |
| `PRD_*.md`, `BACKLOG*.md`, `*_PLAN.md` | `docs/planning/` | PRD_NEW_FEATURE.md |

---

## ENFORCEMENT CHECKLIST

### **BEFORE creating ANY .md or .sh file, you MUST:**

1. **CHECK:** Am I creating this file in a root directory?
2. **STOP:** If yes, determine the correct category
3. **CREATE:** In the correct `docs/{category}/` or `scripts/` location
4. **VERIFY:** File is NOT in any root directory

---

## YOUR RESPONSIBILITY

As an AI assistant, you MUST:

- **READ these rules** before creating ANY file
- **FOLLOW the categorization guide** for every .md file
- **CREATE files in correct locations** from the start
- **NEVER create files in root** directories
- **ASK if unsure** about categorization

---

## VERIFICATION COMMANDS

### After creating documentation, verify:

```bash
# Check project root (should only show README.md)
ls <project-root>/*.md

# Check backend (should show NO .md files)
ls <project-root>/src/backend/*.md

# Check backend scripts (should only show start.sh)
ls <project-root>/src/backend/*.sh
```

---

## THIS IS NOT A SUGGESTION - IT IS A REQUIREMENT

**These rules are MANDATORY and NON-NEGOTIABLE.**

**Every violation causes real harm to the project and wastes human time.**

**Follow these rules 100% of the time, no exceptions.**
