# The Three Types of Commands

This framework deliberately separates *how* you interact with the system into three distinct command types. The split is not cosmetic; it encodes safety, intent, and operational assumptions directly into the tooling so that mistakes are harder to make under stress.

The guiding idea: **production should feel boring and safe; exploration should feel powerful and a little dangerous; the application itself should not care how it is being operated.**

---

## 1. Application Commands (`app`)

**What they are**
Commands defined *by the application itself*, for its own domain needs. They are not part of the framework, even though they are built on top of it.

The framework provides structure and affordances; the application supplies meaning.

**Core properties**

* Express domain behavior, not infrastructure concerns
* Safe by definition
* Deterministic and repeatable
* No environment‑dependent semantics
* Identical behavior in dev, staging, and production

**Examples**

* Handling HTTP requests
* Rendering templates
* Running background jobs / queues
* Sending emails triggered by application logic

**Non‑goals**

* No schema changes
* No data backfills
* No destructive behavior
* No operational or lifecycle management

**Rule of thumb**
If removing the framework would require rewriting *how* it runs but not *what* it does, the command belongs here.

---

## 2. Management Commands (`mgmt`)

**What they are**
Operational, *production‑safe* commands used to evolve and maintain a live system.

These commands assume real data exists and must not be casually destroyed.

**Core properties**

* Forward‑only
* Idempotent or safely repeatable
* Designed to run in production
* Explicit, auditable intent

**Examples**

* Applying migrations
* Running seeders that assert invariant data
* Reindexing or rebuilding derived data
* Rotating keys, recalculating counters

**Design constraints**

* No implicit rollbacks
* No hidden destructive actions
* Fail fast if assumptions are violated

**Rule of thumb**
If you would run it at 3am while tired and worried, it must live here.

---

## 3. Development Commands (`develop`)

**What they are**
Sharp, *unsafe by design* tools meant exclusively for local development and experimentation.

These commands optimize for speed, learning, and iteration — not safety.

**Core properties**

* Destructive operations allowed
* May reset or mutate large amounts of data
* Assume a clean or disposable environment
* Explicitly gated in production

**Examples**

* Dropping and recreating databases
* Rolling migrations backward
* Loading fixtures or scenarios
* Generating fake or randomized data

**Safety model**

* Hard to run in production
* Requires explicit opt‑in if ever enabled
* Clear, noisy warnings when invoked

**Rule of thumb**
If it would be irresponsible to run against real user data, it belongs here.

---

## Why This Split Matters

Many frameworks blur these concerns, leading to:

* Fearful production operations
* Overpowered dev tools leaking into prod
* Environment‑specific behavior and bugs

By naming and enforcing these three command types:

* Intent is visible at the CLI level
* Safety properties are architectural, not cultural
* Developers can move fast *without* normalizing risk

---

## One‑Sentence Summary

> **App commands run the system, mgmt commands evolve it safely, and develop commands let you break things on purpose — but only where it’s allowed.**