# Project Instructions

## Mandatory Process ("Follow the Process")

For any non-trivial work, follow these steps in order:

1. **Write a plan** in `docs/plans/` describing what and why
2. **Review agent** — open a new chat, paste the plan, ask for a confidence score and check for overengineering
3. **Incorporate feedback** — update the plan with findings you agree with
4. **User approval** — present the reviewed plan; wait for explicit approval. (Omit when "follow the process" was the instruction.)
5. **Implement** — execute the approved plan
6. **Update changelog** — add entry under [UNRELEASED] in CHANGELOG.md
7. **Mark plan as Done** — update its status

**Shortcut**: "Follow the process" pre-authorizes the full cycle autonomously.

**Non-trivial**: new features, architectural decisions, irreversible changes.
**Trivial** (no plan needed): typos, docs updates, minor corrections.

## Writing Plans

**Plan format:** Title / Problem / Solution / Verification.

**Avoid overengineering:**
- Don't create new tables when a column on an existing table works
- Don't build 6 UI tabs when 2 answer the business question
- Start with the simplest thing that solves the stated problem

**After writing a plan**, spawn a reviewer agent in a new chat (without conversation context):
```
Review this plan. Provide a confidence score (1–10) and check that it isn't overengineered.

[paste plan content]
```
Revise based on valid feedback before presenting to the user.

## Working Conventions

**Changelogs** — every commit must update CHANGELOG.md under [UNRELEASED]. Sections: Added, Changed, Fixed. Each bullet ≤ 100 characters.

**Conventional commits.** Use feat:, fix:, docs:, refactor:. Subject line under 72 characters.

**Never self-resolve issues.** Present findings and wait for user confirmation before marking resolved.

---
*Remember: plan before implementing; update CHANGELOG.md in every commit.*