> 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/claude-coordination-parts-redesign.md).

# claude-coordination-parts-redesign

## Claude Prompt — Coordination Logic + Parts Workflow Redesign

Paste this into a fresh Claude Code terminal session at the FleetOS repo root.

***

You are working in the `ZBO19/FleetOS` repository.

Read these first:

1. `docs/f1-pitstop-coordination-model.md`
2. `docs/coordination-logic-file-plan.md`
3. `docs/claude-everything-10of10-final.md`
4. Inspect the actual current code before making claims, especially:
   * `components/fleetos/components/JobCard.tsx`
   * `services/requests/RequestWorkflowService.ts`
   * `services/shadow/ShadowInstrumentation.ts`
   * `components/fleetos/pages/UnifiedDashboard.tsx`
   * `hooks/useFleetOSDashboard.ts`
   * `types/serviceRequest.ts`

### Mission

Turn FleetOS from a good request-tracking UI with partial scheduling into a true coordination tool built around:

* Bay
* Technician
* Vehicle
* Parts

At the same time, redesign the **parts workflow** so it is fast, structured, and useful for real operations.

This is not just UI polish. This is business-logic work.

***

### Strategic goal

FleetOS must support three real operating modes without becoming three different products:

1. **Solo operator**
2. **Lean two-person team**
3. **Multi-role team**

Use one coordination model with smart defaults. Do not fork the product into separate versions.

***

## PART 1 — Lock down coordination logic

### 1. Formalize the 4 dependency model

Each work order should explicitly support dependency state for:

* `bay`
* `technician`
* `vehicle`
* `parts`

Each dependency should support:

* status
* owner
* last updated by
* updated at
* blocker reason
* eta (where relevant)
* notes (where relevant)

Suggested statuses:

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

### 2. Add derived job readiness

Derive at work-order level:

* `job_readiness_status`
* `job_primary_blocker`

Examples:

* `blocked`
* `almost_ready`
* `ready_to_start`
* `in_progress`
* `complete`

Primary blocker examples:

* `waiting_on_approval`
* `waiting_on_vehicle`
* `waiting_on_technician`
* `waiting_on_bay`
* `waiting_on_parts`
* `waiting_on_supplier_response`

### 3. Team-mode behavior

#### Solo

* same dependency model
* current user can own multiple roles by default
* no forced role ceremony

#### Lean two-person team

* same dependency model
* one person may own multiple roles
* handoffs and blockers become visible

#### Multi-role team

* same dependency model
* explicit ownership becomes more important
* blockers and timestamps matter more

Do not implement three separate systems. Use one model with role defaults.

***

## PART 2 — Fix the parts workflow properly

### Current problem to solve

Right now parts behaves too much like:

* add one line
* add one line
* add one line

This is too slow and too weak. It does not model real parts coordination well enough.

### Current issues to fix

* no quantity
* no part number
* no unit cost / expected cost
* no supplier field
* no PO field
* no location / stock source
* no structured intake flow
* too much repeated manual entry
* not optimized for parts desk workflow

### New parts model

Each part line should support at minimum:

* `description`
* `quantity`
* `part_number` (optional but supported)
* `status`
* `eta`
* `supplier_name` (optional)
* `po_number` (optional)
* `unit_cost` or `estimated_cost` (optional)
* `source_location` (optional)
* `notes` (optional)
* `is_blocking` boolean

Suggested statuses:

* `identified`
* `checking_stock`
* `in_stock`
* `requested`
* `on_order`
* `received`
* `not_needed`

### UX direction

Make parts entry fast for real work. Possible patterns:

* inline table-style parts editor
* quick-add row with quantity + description as minimum
* expandable advanced fields
* mobile-friendly compact row editor

The default fast path should be:

* quantity
* description
* status

Advanced fields can expand only when needed.

### Important

Do not overbuild a full procurement suite. Do not build ERP. Build a parts coordination layer.

***

## PART 3 — What to change in code

### A. `types/serviceRequest.ts`

* expand `ServiceRequestPart`
* add the missing fields needed for real parts coordination
* keep types clean and explicit

### B. `JobCard.tsx`

* split the current schedule/parts logic into focused subcomponents
* redesign parts UI to support structured line items
* make parts faster than current repeated text-entry behavior
* preserve mobile usability
* preserve current visual language

### C. `RequestWorkflowService.ts`

* add explicit dependency update helpers
* add parts-specific create/update helpers with structured fields
* add derived readiness/blocker helper
* stop treating parts as just a single loose description field plus minimal line items

### D. `ShadowInstrumentation.ts`

* record parts coordination events more explicitly
* examples:
  * `parts_identified`
  * `parts_requested`
  * `parts_eta_updated`
  * `parts_received`
  * `parts_blocking_changed`
  * `job_blocked_by_parts`
  * `job_unblocked_by_parts`

### E. `UnifiedDashboard.tsx` + `useFleetOSDashboard.ts`

* expose blocked/ready views driven by dependency logic
* add filters or derived views for jobs waiting on parts

### F. DB / schema layer

Choose the fastest sensible path.

#### Acceptable path 1

Extend current parts table/model with more fields.

#### Acceptable path 2

Add a new normalized work-order dependency table and keep parts lines separate.

Explain your recommendation before implementing.

***

## PART 4 — Guardrails

* Do not turn this into a giant ERP build.
* Do not add enterprise complexity just because it is possible.
* Keep the current wedge: coordination and scheduling.
* Make the product more truthful, more useful, and more trainable.
* Keep Blade/OpenClaw in mind: structured coordination events matter.

***

## Required output style

Your first response must contain exactly these sections:

1. `Current coordination logic gaps`
2. `Current parts workflow gaps`
3. `Recommended business logic model`
4. `Schema recommendation`
5. `Execution plan`
6. `First files I will change`

Then start work.


---

# 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/claude-coordination-parts-redesign.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.