diff --git a/Makefile b/Makefile
new file mode 100644
index 00000000..8ba18ab3
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,22 @@
+# LangBot Makefile
+# Quick developer commands
+
+.PHONY: test test-quick lint
+
+# Run all tests (full suite with coverage)
+test:
+	bash run_tests.sh
+
+# Quick self-test for developers (lint + unit + smoke, no real credentials needed)
+test-quick:
+	bash scripts/test-quick.sh
+
+# Run linting only
+lint:
+	ruff check src/langbot/ tests/
+	ruff format --check src/langbot/ tests/
+
+# Fix linting issues
+lint-fix:
+	ruff check --fix src/langbot/ tests/
+	ruff format src/langbot/ tests/
\ No newline at end of file
diff --git a/scripts/test-quick.sh b/scripts/test-quick.sh
new file mode 100755
index 00000000..e91cff76
--- /dev/null
+++ b/scripts/test-quick.sh
@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# Quick developer self-test command
+# Runs linting, unit tests, and smoke tests without requiring real provider keys
+# Suitable for local branch validation
+
+set -e
+
+echo "=== LangBot Quick Self-Test ==="
+echo ""
+
+# 1. Ruff check
+echo "[1/3] Running ruff check..."
+if command -v ruff &> /dev/null; then
+    ruff check src/langbot/ tests/ --quiet || {
+        echo "⚠ Ruff check found issues. Run 'ruff check --fix' to auto-fix."
+    }
+else
+    echo "⚠ ruff not installed, skipping lint check"
+fi
+echo ""
+
+# 2. Unit tests
+echo "[2/3] Running unit tests..."
+uv run pytest tests/unit_tests/ -q --tb=short 2>&1 | tail -5
+echo ""
+
+# 3. Smoke tests (if exists)
+echo "[3/3] Running smoke tests..."
+if [ -d "tests/smoke" ]; then
+    uv run pytest tests/smoke/ -q --tb=short 2>&1 | tail -5
+else
+    echo "No smoke tests found, skipping"
+fi
+echo ""
+
+echo "=== Quick Self-Test Complete ==="
\ No newline at end of file
diff --git a/tests/README.md b/tests/README.md
index 58827fac..8e40607b 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -11,18 +11,57 @@ Due to circular import dependencies in the pipeline module structure, the test f
 ```
 tests/
 ├── __init__.py
-├── unit_tests/                    # Unit tests
-│   ├── box/                       # Box module tests
-│   ├── config/                    # Configuration tests
-│   ├── pipeline/                  # Pipeline stage tests
-│   │   └── conftest.py           # Shared fixtures and test infrastructure
-│   ├── platform/                  # Platform adapter tests
-│   ├── plugin/                    # Plugin system tests
-│   ├── provider/                  # Provider tests
-│   └── storage/                   # Storage tests
-└── README.md                      # This file
+├── factories/                    # Shared test factories
+│   ├── __init__.py              # Factory exports
+│   ├── app.py                   # FakeApp factory
+│   ├── message.py               # Message/query factories
+│   ├── provider.py              # FakeProvider factory
+│   └── platform.py              # FakePlatform factory
+├── smoke/                        # Smoke tests (quick validation)
+│   └── test_fake_message_flow.py
+├── unit_tests/                   # Unit tests
+│   ├── box/                      # Box module tests
+│   ├── config/                   # Configuration tests
+│   ├── pipeline/                 # Pipeline stage tests
+│   │   └── conftest.py          # Shared fixtures and test infrastructure
+│   ├── platform/                 # Platform adapter tests
+│   ├── plugin/                   # Plugin system tests
+│   ├── provider/                 # Provider tests
+│   └── storage/                  # Storage tests
+└── README.md                     # This file
 ```
 
+## Test Factories
+
+The `tests/factories/` package provides reusable test factories:
+
+```python
+from tests.factories import (
+    FakeApp,          # Mock application
+    FakeProvider,     # Fake LLM provider
+    FakePlatform,     # Fake platform adapter
+    text_query,       # Create text query
+    group_text_query, # Create group query
+    command_query,    # Create command query
+)
+
+# Create fake app
+app = FakeApp()
+
+# Create query with text
+query = text_query("hello world")
+
+# Create fake provider that returns specific response
+provider = FakeProvider().returns("test response")
+
+# Create fake platform for outbound capture
+platform = FakePlatform()
+await platform.reply_message(query.message_event, reply_chain)
+outbound = platform.get_outbound_messages()
+```
+
+See `tests/factories/__init__.py` for all available factories.
+
 ## Test Architecture
 
 ### Fixtures (`conftest.py`)
@@ -43,7 +82,28 @@ The test suite uses a centralized fixture system that provides:
 
 ## Running Tests
 
-### Using the test runner script (recommended)
+### Quick self-test for developers
+
+For local branch validation without real provider keys:
+
+```bash
+make test-quick
+```
+
+or
+
+```bash
+bash scripts/test-quick.sh
+```
+
+This runs:
+1. Ruff lint check
+2. Unit tests
+3. Smoke tests
+
+Suitable for quick validation before committing.
+
+### Using the test runner script (recommended for full coverage)
 ```bash
 bash run_tests.sh
 ```