Angel Trucking
One system for four trucking jobs — hiring, shop, marketplace, fleet — usable from a phone in a cab.
For a founder — cost, outcome, time
- Modules
- 4
- People
- ~150
- Trucks
- ~100
- Status
- pre-launch
A ~100-truck Ohio carrier runs hiring, its maintenance shop, a marketplace and fleet ops in four disconnected systems — none usable from a cab with no signal.
One platform for all four jobs, designed so every feature follows the same five-role pipeline.
- Next.js 16
- TypeScript
- Supabase
- Tailwind v4
- Claude Sonnet 4.6
Angel replaces four disconnected trucking systems — HR screening, maintenance shop, marketplace, fleet ops — with one platform that a driver can log into from a phone in a cab.
Four modules, one phone-first UI, a mobile cookie-auth drivers use with no signal. The agent pipeline is designed before the first production line of code — not retrofitted after.
Context
Angel Trucking is a real ~100-truck carrier in Ohio. ~150 people touch the system: 1–2 admins, 3–5 managers, 5–10 mechanics, 50–70 drivers, plus candidates and the public marketplace. This is the only client project in my portfolio — the rest are personal.
Problem
Every existing trucking SaaS handles one slice: TMS, or maintenance, or hiring. None cover all four and work on a phone in a cab with no signal. Screening drivers manually is slow. Booking shop time by phone is chaos. Marketplace listings never get to Facebook. The client didn't need better software for one problem — they needed one system for four.
Division of Labor
| Layer | Who |
|---|---|
| Business rules (e.g. "3-year speeding = auto-reject") | Me |
| Task in plain language | Me (Ukrainian or English) |
| Clarification, spec, design, code, review | Claude (5-stage pipeline) |
| Sprint approval | Me |
| Deployment | Me |
Prompt Architecture — the 5-stage pipeline
Every task passes through five roles, in order: Orchestrator → PM → Designer → Developer → Reviewer. Each role has its own AGENTS.md-declared contract.
One task → five explicit handoffs
The 5-role contract — declared in AGENTS.md, enforced per task
every sprint runs this
- Person / role
- Process step
- Decision / gate
- Flow
- Key path / outcome
Read as steps (4)
- 01Me → PM
- 02PM → Designer
- 03Designer → Developer
- 04Developer → Reviewer (✓ approved)
AGENTS.md — the 5-role contractprompt
The PM asks up to 5 clarifying questions and then writes a Task Brief. The Designer never codes. The Developer never re-designs. The Reviewer validates against three docs: Brief, Design Spec, V9 tokens.
The rule that keeps sessions sharp: "Spec + one file, not the codebase." Claude never reads the whole tree — every task hands it the Brief and the specific files by name. This is what stops mid-session context rot.
Iteration Moment
Only one commit exists (b652cd3, 2026-05-12) — the entire agent architecture and 4-sprint roadmap were built before production code. That's the pivot: instead of jumping into features and refactoring later, I front-loaded the agent design. All four sprints (auth, HR, marketplace, shop + fleet) have since been built in the working tree against that scaffold; what remains is the client deployment and the first live users. Lesson: for a 4-module product, an hour designing the pipeline saves a week of rewrites.
Trade-Offs
Driver auth = phone-cookie, not Supabase Auth
Drivers log in with a phone number and a cookie, offline. Supabase Auth needs email + connectivity. Cost: I maintain two auth systems.
3-year speeding violation = auto-reject
No manual appeal. Insurance risk in trucking makes the appeal path a liability, not a feature.
30-min shop slots, not dynamic
Admin configures hours + bay count; slots are a fixed grid. Predictable UX beats optimal packing.
Marketplace is fully public
No login, no saved favorites. Maximizes reach; loses buyer tracking.
Results (honest)
- 1 commit pushed (
b652cd3, 2026-05-12); Sprint 1 complete, Sprints 2 & 3 within ~1 open item each, Sprint 4 at 27/27 checklist items in the working tree agents/holds the orchestrator, PM, UI-UX designer, developer, and reviewer contracts plus aWORKFLOW.mdmeta spec;docs/holds ARCHITECTURE, CONTEXT_MAP, DB_SCHEMA, DESIGN_SYSTEM, DPPA_COMPLIANCE, INTEGRATIONS- V9 design system: mobile-first at 375px, Ohio timezone hard-coded
Reflection
- Multi-stage prompts scale where single prompts collapse. By Sprint 3, one-prompt "just build the shop module" would have produced slop. Five-stage forced explicit design decisions before code.
- Business rules belong in code, not docs. The 3-year speeding rule lives in
lib/ai/screening.ts, not a policy PDF. If the rule changes, one file changes. - The most valuable file in the repo is
AGENTS.md, not the code. Anyone reading it can predict how the next feature will get built.
Receipts
How it was made
Token scorecard
Pre-ShipLoop sessions ran in shared home-dir logs; token attribution isn’t reconstructable.
- Complexity
- S
- Duration
- scaffold only
- Tier
- 0 · naked
Model mix
- Sonnet
- 100%
Have a Angel Trucking-sized problem?
Send one paragraph about it. I reply within two business days with a scope and a fixed price.