> For the complete documentation index, see [llms.txt](https://t420.gitbook.io/t420/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t420.gitbook.io/t420/coordination-logic-file-plan.md).

# coordination-logic-file-plan

## FleetOS Coordination Logic + File-by-File Action Plan

### Objective

Turn FleetOS from a good request-tracking workflow into a true coordination and scheduling layer for external service work.

The core operational truth is: A job only really starts when **4 dependencies** are ready:

1. **Bay**
2. **Technician**
3. **Vehicle**
4. **Parts**

FleetOS already has good UI primitives for these dependencies. The next step is to formalize the business logic so the product works for:

* **1-person team**
* **2-person team**
* **larger / full-role team**

The goal is not to add random features. The goal is to make the coordination model explicit, role-aware, and trainable for Blade/OpenClaw.

***

## 1. Coordination model that should drive the product

### Four dependency objects per work order

Every work order should explicitly track:

* `bay_status`
* `technician_status`
* `vehicle_status`
* `parts_status`

Suggested status values:

* `unknown`
* `pending`
* `blocked`
* `ready`
* `complete`

Optional per-dependency metadata:

* `owner_contact_id`
* `owner_name`
* `updated_by_contact_id`
* `updated_at`
* `blocker_reason`
* `eta`
* `notes`

### Job-level derived state

Work order should compute:

* `job_readiness_status` = `blocked | almost_ready | ready_to_start | in_progress | complete`
* `job_primary_blocker` = one of:
  * `waiting_on_approval`
  * `waiting_on_vehicle`
  * `waiting_on_technician`
  * `waiting_on_bay`
  * `waiting_on_parts`
  * `waiting_on_supplier_response`

### Key principle

**Information gets entered once by the person closest to the truth.**

* Fleet coordinator owns fleet-side vehicle / urgency / approval / delivery details
* Service coordinator owns orchestration and scheduling
* Parts desk owns part sourcing / stock / ETA / PO
* Technician owns diagnosis and execution reality

***

## 2. Team modes the logic must support

### Mode A — One-person team

One person may be:

* service coordinator
* parts desk
* technician
* sometimes even business owner

#### Product behavior

* default all internal ownership to one contact
* keep the 4 dependency rows visible, because the dependencies still exist
* simplify the UI by auto-filling owner fields
* do not force separate role assignment steps
* let one user update all rows quickly

#### Business logic

* `service_coordinator_contact_id = current_user`
* `parts_contact_id = current_user` unless changed
* `technician_contact_id = current_user` unless changed
* scheduling is still constrained by bay / vehicle / parts / technician, but one person can move all states

#### Blade/OpenClaw implication

Blade learns from a single operator sequence:

* request comes in
* same person decides slot
* same person requests parts
* same person starts/completes job

This is great training data because it exposes end-to-end coordination in one thread.

***

### Mode B — Two-person team

There are two common real-world versions:

#### Version B1

* person 1 = service coordinator / parts desk
* person 2 = technician

#### Version B2

* person 1 = service coordinator
* person 2 = technician / parts desk

#### Product behavior

* allow one person to hold multiple roles
* do not require a rigid org chart
* allow separate assignment for:
  * coordinator
  * parts owner
  * technician
* if only two active team members exist, optimize defaults instead of making the UI look like enterprise software

#### Business logic

* `coordinator` and `parts` may be same or different
* `technician` may be separate
* workload and ownership become more important
* blocker visibility matters more because handoffs now exist

#### Blade/OpenClaw implication

This is where Blade starts to become useful as:

* service coordinator assistant
* parts desk assistant

Because the system can now see explicit handoffs and delays.

***

### Mode C — More / full-role team

Typical roles:

* fleet coordinator
* service coordinator
* parts desk
* technician
* manager / approver

#### Product behavior

* each dependency can have its own owner
* blockers and overdue dependencies must be visible
* role-specific updates should be easy and low-friction
* the UI should not ask everyone for everything

#### Business logic

* fleet side and supplier side are clearly distinct
* every update has authorship and timestamp
* schedule is no longer just a slot — it is a dependency alignment outcome

#### Blade/OpenClaw implication

This is the long-term training environment. Blade should observe:

* who updated what
* where coordination stalled
* what next action resolved the stall
* which actions improved readiness fastest

***

## 3. Strategic product decision

### Recommendation

Do **not** make team size the primary concept the user configures.

Instead, FleetOS should support:

* one person wearing multiple roles
* two people splitting roles
* larger teams with separate owners

#### Best implementation

Use **role ownership + smart defaults**, not hardcoded company-size branches everywhere.

Possible lightweight setting:

* `coordination_mode = solo | lean_team | multi_role_team`

But underneath, the real model should always be:

* dependencies
* owners
* blockers
* readiness

That way the product stays coherent.

***

## 4. What already exists in the codebase

### Already good

* `JobCard.tsx` already contains the UI wedge for Bay / Tech / Vehicle / Parts
* there is already a `Coordinator` row
* there is already a `Parts` contact row
* there is already parts line-item handling
* there is already request workflow ownership in `RequestWorkflowService.ts`
* there is already a shadow instrumentation layer for training

### What is missing

* explicit dependency data model
* explicit blocker model
* explicit composite readiness model
* role-ownership logic that scales cleanly from 1-person to many-person teams
* Blade-facing event semantics for service coordination vs parts coordination

***

## 5. File-by-file action plan

### A. `components/fleetos/components/JobCard.tsx`

#### Current state

This file already contains the most important coordination UI, but it is too large and is doing too much.

#### Changes needed

1. Split into subcomponents:

* `JobCardSummary`
* `JobCardDetails`
* `JobCoordinatorRow`
* `JobPartsOwnerRow`
* `JobScheduleBlock`
* `JobResponsePanel`
* `JobQuoteReviewPanel`
* `JobCompletePanel`

2. Upgrade the schedule block from visual coordination to explicit coordination

* add derived readiness status
* add blocker text
* support dependency owner display
* support solo vs multi-owner behavior cleanly

3. Make the 4 dependency rows canonical

* Bay
* Technician
* Vehicle
* Parts

4. Add per-row ownership metadata display when available

* owner name
* status
* blocker / ETA where relevant

5. Add job-level derived readiness banner Examples:

* `READY TO START`
* `WAITING ON PARTS`
* `WAITING ON VEHICLE DELIVERY`
* `WAITING ON TECHNICIAN`

#### Why

This turns the work order into a real coordination board.

***

### B. `services/requests/RequestWorkflowService.ts`

#### Current state

This is the workflow engine and already supports the main request lifecycle.

#### Changes needed

1. Add explicit workflow helpers for dependency updates Examples:

* `updateBayDependency(...)`
* `updateTechnicianDependency(...)`
* `updateVehicleDependency(...)`
* `updatePartsDependency(...)`

2. Add a derived-readiness computation helper

* compute readiness from the 4 dependencies
* compute blocker reason
* optionally persist derived status for reporting

3. Add role-authored updates into metadata / events

* who changed what dependency
* from which role context

4. Stop treating parts / bay / technician / vehicle as merely scattered request fields

* start treating them as coordination dependencies

#### Why

Business logic must match the UI wedge.

***

### C. `services/shadow/ShadowInstrumentation.ts`

#### Current state

The shadow layer is real and promising.

#### Changes needed

1. Record dependency-level coordination events Examples:

* `bay_assigned`
* `slot_booked`
* `technician_assigned`
* `vehicle_delivery_requested`
* `vehicle_checked_in`
* `parts_requested`
* `parts_eta_updated`
* `parts_received`
* `job_became_ready`
* `job_blocked`

2. Add role-aware decision points Examples:

* service coordinator chose slot
* parts desk chose supplier / ETA update
* technician changed parts requirement

3. Record blocker transitions

* when job moved from almost\_ready -> blocked
* when blocker cleared

#### Why

Blade should learn coordination decisions, not just status flips.

***

### D. `components/fleetos/pages/UnifiedDashboard.tsx`

#### Current state

Good composition shell.

#### Changes needed

1. Surface job readiness / blockers into list-level sorting and KPI views
2. Add filters like:

* waiting on parts
* waiting on vehicle
* waiting on approval
* ready to start

3. Ensure mobile and desktop both expose the same operational truth

#### Why

The dashboard should help operators triage coordination, not just status categories.

***

### E. `hooks/useFleetOSDashboard.ts` and dashboard sub-hooks

#### Changes needed

1. Add derived lists for:

* ready jobs
* blocked jobs
* jobs waiting on parts
* jobs waiting on vehicle
* jobs missing tech
* jobs missing bay

2. Add metrics for:

* average time to slot book
* average time to tech assignment
* average time to parts-ready
* average time to ready-to-start

#### Why

This is where the product becomes measurable and trainable.

***

### F. `components/fleetos/pages/SettingsPage.tsx`

#### Changes needed

1. Add lightweight coordination settings Examples:

* operating model / coordination mode
* default role assumptions
* default slot duration
* optional role visibility

2. Keep this lightweight Do not build a heavy permissions/ERP admin panel.

#### Why

Small teams need sane defaults without enterprise setup pain.

***

### G. Data / schema layer (new migration work likely needed)

#### Add explicit dependency fields or related table

Best path is likely a separate table rather than endlessly growing `service_requests`.

Suggested table: `work_order_dependencies`

Fields:

* `dependency_id`
* `request_id`
* `dependency_type` (`bay|technician|vehicle|parts`)
* `status`
* `owner_contact_id`
* `owner_name`
* `blocker_reason`
* `eta`
* `notes`
* `updated_by_contact_id`
* `updated_at`

Optional alternative: Use JSONB on `service_requests` first for speed, then normalize later.

#### Recommendation

If speed matters immediately, start with JSONB or explicit columns. If learning/analytics matter, normalize sooner.

***

## 6. Business rules to lock down now

### Rule 1

A job can be **scheduled** before it is fully ready.

### Rule 2

A job can only be **ready to start** when:

* bay = ready
* technician = ready
* vehicle = ready
* parts = ready or not required

### Rule 3

Parts should support:

* not required
* pending identification
* requested
* on order
* received

### Rule 4

Vehicle should support:

* at fleet
* delivery requested
* en route
* checked in
* ready for pickup

### Rule 5

In solo mode, owner defaults collapse to current user. In lean/multi-person mode, ownership should be explicit.

### Rule 6

Blade should never need to infer everything from text if the system can capture structured coordination truth.

***

## 7. Clear evals

### Product evals

* % jobs with all 4 dependency states known
* % jobs with explicit blocker when not ready
* time from request creation -> slot booked
* time from slot booked -> ready to start
* time waiting on parts
* time waiting on vehicle delivery
* time waiting on technician assignment

### Operator evals

* can a solo operator update all 4 dependencies quickly?
* can a 2-person team hand off without duplicate entry?
* can a larger team see exactly what is blocking progress?

### Blade evals

* can Blade correctly identify the current blocker?
* can Blade suggest the next best coordination action?
* can Blade draft the right follow-up to the right role?
* does Blade reduce time-to-readiness?

***

## 8. Final recommendation

### Yes, go forward with this direction

The product should absolutely move beyond request tracking into coordination and scheduling truth.

### No, do not turn it into a giant suite all at once

The correct path is:

1. formalize the 4 dependency model
2. add derived readiness/blocker logic
3. support role ownership cleanly across 1-person / 2-person / larger teams
4. teach Blade from those explicit coordination events

That is how FleetOS becomes the F1 pitstop layer without losing the wedge.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://t420.gitbook.io/t420/coordination-logic-file-plan.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.