Here’s a clean **developer guide in Markdown** format, ready to drop into your repo as `INSTRUCTIONS.md`. It captures your constraints, rules, and workflows in a human-readable but precise style.

---

# Development Instructions

## Project Context

* **UnitForge** is in **development**.
* The project is **not in production**.
* **No compatibility requirements** between major code changes.
* Guiding principle: **Keep it small and simple**.

## Development Rules

1. **Fix lint errors** – Code must always pass lint checks.
2. **Keep code lean** – Avoid unnecessary abstractions; keep it direct.
3. **Keep tests consistent** – All tests must pass; write tests for new code.
4. **Remove legacy code** – Delete or refactor outdated code.
5. **Use Makefile for services** – Prefer `make` targets to run and manage services.
6. **Server** – Run the backend with **Uvicorn**.
7. **Package management** – Use **uv** exclusively, never pip.

## Common Commands

| Task                 | Command                    |
| -------------------- | -------------------------- |
| Setup environment    | `make setup-dev`           |
| Run server           | `make server`              |
| Run tests            | `make test`                |
| Run tests (coverage) | `make test-cov`            |
| Lint & format code   | `make lint && make format` |
| Full dev cycle       | `make dev`                 |

## Style Guidelines

* **Python**:

  * Follow **PEP 8**.
  * Use **type hints** consistently.
  * Format code with **Black**.
* **Code quality**:

  * Avoid duplication.
  * Keep modules cohesive.
  * Minimize complexity.

---

Would you like me to also add a **“Workflow Examples”** section (e.g. *how to add a new feature step-by-step*) to make onboarding even smoother for future contributors?