# CLAUDE.md — Agent Operating Instructions

**Project:** The Landlord Manager — production PMS for vacation/seasonal rentals.
**Stack:** Laravel 12 + React 19 + TypeScript 5.7 + Inertia.js 2 + Tailwind CSS 4 + MySQL.

---

## Session Startup

1. Read `errors.md` — internalize past mistakes.
2. Read `STATUS.md` — understand where we left off.
3. Read `ARCHITECTURE.md` — refresh system understanding.
4. Greet user with a brief status summary and ask: continue or new task?

## Session Shutdown

1. Update `STATUS.md` with current progress.
2. Ensure `errors.md` is up to date.
3. Summarize what was done and what remains.

---

## The Five Laws

**Law 1 — Plan Before You Code**
Never write a single line of code without a validated plan. Present the plan to the user. Wait for explicit approval before writing any code.

Plan format:
```
## Task Plan: [Name]
Objective / Architecture decisions (controllers, services, models, pages, migration?, permission?) / Steps / Dependencies / Risks / Exit criteria
```

**Law 2 — Delegate to Sub-Agents**
Delegate when: >150 lines of changes, 3+ files simultaneously, or deep single-domain focus. Write a precise self-contained brief. Review output before integrating. Re-delegate if wrong — don't fix it manually unless trivial.

**Law 3 — Error Logging**
Read `errors.md` at session start. After every error (build failure, wrong assumption, bad architecture), append an entry: Context / What went wrong / Root cause / Fix applied / Lesson learned. File is append-only.

**Law 4 — Mandatory Testing**
No task is complete until all tests pass. If no tests exist for your code — write them. Read `.claude/TESTING.md` before writing tests.

**Law 5 — Fix Bugs Yourself**
Own every failing test until it passes. After 3 failed attempts: stop, document in `errors.md`, escalate to user with full context.

---

## File Triggers (read before acting)

| Before... | Read |
|---|---|
| Writing any PHP or React code | `.claude/PATTERNS.md` |
| Adding any route or feature | `.claude/PERMISSIONS.md` |
| Writing or running tests | `.claude/TESTING.md` |
| Writing any migration or query | `.claude/DATABASE.md` |
| Touching Rentals United or email | `.claude/INTEGRATIONS.md` |
| Any query touching user data | `.claude/MULTI_TENANCY.md` |
| Running dev commands | `.claude/COMMANDS.md` |

---

## Communication Format

```
**Status:** ✅ Complete | 🔧 In Progress | ❌ Blocked | ⚠️ Needs Input

[Brief summary]

**Details** (if relevant):
- Point 1

**Next step:** [What happens next]
```

Rules: one question at a time. No apologies. No explaining things the user already knows. No half-finished work without labeling it.

---

## Git Rules

- Commit messages: Conventional Commits format (`feat(x): ...`, `fix(x): ...`).
- Never commit broken code. Never commit `.env` or secrets.
- **Never add co-author attributions to commits.** Commits are authored by the user only.

---

## Escalation

If stuck after 3 attempts on the same problem: stop, document everything in `errors.md`, and ask the user with a clear summary of what was tried, what failed, and what is suspected.