> 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-hard-reset-coordination-spec.md).

# claude-hard-reset-coordination-spec

## Claude Hard Reset — Coordination Logic + Parts 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-coordination-parts-redesign.md`
4. `docs/claude-everything-10of10-final.md`

Then inspect the actual current code before making any claims, especially:

* `components/fleetos/components/JobCard.tsx`
* `components/fleetos/components/dashboard/CustomSelect.tsx`
* `components/fleetos/pages/UnifiedDashboard.tsx`
* `hooks/useFleetOSDashboard.ts`
* `services/requests/RequestWorkflowService.ts`
* `services/shadow/ShadowInstrumentation.ts`
* `types/serviceRequest.ts`
* any current migrations / parts-related tables / query helpers

### Mission

Stop the UI churn. Stop the surface-only fixes. Do a hard reset around the actual product truth.

FleetOS must become a real coordination and scheduling tool, not a prettier request board. The coordination model must be locked first, then the parts workflow must be redesigned around that model, then the UI must be cleaned up around the new truth.

This is not a generic polish pass. This is not a 20-item punchlist. This is a product-logic reset.

***

### What went wrong

Assume this is true unless direct code inspection proves otherwise:

* recent work improved some surface areas but did not converge on one clean business model
* parts is still under-modeled and too slow for real operations
* JobCard has become a high-complexity hotspot
* coordination logic is implied in the UI but not formalized enough in the data/workflow model
* too many changes have been attempted without one locked definition of readiness, blockers, ownership, and team-mode behavior

You must fix this by locking the model first.

***

## PART 1 — First principles you must obey

### 1. One coordination model, not three products

FleetOS must support:

1. one-person team
2. two-person team
3. larger multi-role team

But it must do that with **one coordination model** using smart defaults and role ownership. Do not build separate product branches.

### 2. The four real dependencies

A job only becomes truly ready to start when these dependencies are satisfied:

* Bay
* Technician
* Vehicle
* Parts

These are not just UI rows. They are business dependencies.

### 3. Information should be entered once

The person closest to the truth should enter the relevant information once. Examples:

* fleet enters vehicle context / urgency / approval / delivery info
* coordinator aligns schedule and resource dependencies
* parts person enters supplier / ETA / PO / quantity / cost info
* technician confirms actual service and parts reality

### 4. Do not build ERP

Do not overbuild inventory, procurement, HR scheduling, or permissions. Build a coordination layer.

***

## PART 2 — Lock the business logic first

### 1. Formalize dependency state

Define an explicit model for each dependency:

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

Each dependency should support:

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

Use a sane status vocabulary. Suggested:

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

### 2. Derive job readiness

At work-order level derive:

* `job_readiness_status`
* `job_primary_blocker`

Suggested readiness states:

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

Suggested blockers:

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

### 3. Team-mode behavior

#### Solo operator

* same dependency model
* same four rows
* ownership defaults collapse to current user
* do not force role ceremony

#### Lean two-person team

* allow one person to own multiple roles
* show handoffs and blockers clearly
* keep setup minimal

#### Larger team

* explicit ownership becomes more important
* timestamps and blockers become more important

Do not implement different codepaths everywhere. Implement one model with defaults.

***

## PART 3 — Redesign parts properly

### Current problem to solve

The current parts workflow behaves too much like:

* add one field
* add one field
* add one field

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

### Required parts line model

Each part line must support at minimum:

* `description`
* `quantity`
* `part_number` optional
* `status`
* `eta`
* `supplier_name` optional
* `po_number` optional
* `unit_cost` or `estimated_cost` optional
* `source_location` optional
* `notes` optional
* `is_blocking`

Suggested parts statuses:

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

### UX rules for parts

* default fast path = quantity + description + status
* advanced fields can expand when needed
* mobile must remain usable
* do not create a giant back-office screen inside the job card
* do create a real parts coordination editor

***

## PART 4 — What to do in code

### A. Audit first, don’t guess

Before changing implementation, inspect the current state and tell the truth about:

* what parts fields really exist now
* what current UI really renders now
* what is claimed in recent commits vs what is actually persisted and displayed
* what current workflow events exist now

### B. Recommend schema path before coding

Explain which path you are taking:

#### Path 1 — Extend current parts model quickly

Use the current model and add structured fields fast.

#### Path 2 — Add a cleaner dependency model/table and keep parts lines separate

More correct long term.

State which one you choose and why. Do not skip this.

### C. Refactor in the right order

1. lock the coordination model
2. lock the parts model
3. update types/schema/services
4. update JobCard UI around that model
5. update dashboard derived metrics/filters
6. update shadow events for Blade training

Do not start with visual rearrangement.

***

## PART 5 — File expectations

### `types/serviceRequest.ts`

* expand `ServiceRequestPart`
* add explicit dependency-related types if needed
* stop pretending current thin fields are enough

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

* add explicit dependency update helpers
* add readiness/blocker computation helpers
* add structured parts create/update handling

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

* record dependency-level coordination events
* record parts events explicitly
* record blocker transitions explicitly

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

* stop adding random local state without structure
* refactor the parts editor into a real, fast structured UI
* surface readiness and blocker truth cleanly
* make solo vs multi-owner behavior sane

### `components/fleetos/pages/UnifiedDashboard.tsx` and dashboard hooks

* expose waiting-on-parts / waiting-on-vehicle / ready-to-start views
* use derived readiness truth, not only legacy status buckets

### Any migrations / query helpers

* keep them truthful and minimal
* do not add unnecessary enterprise complexity

***

## PART 6 — Guardrails

* No fake maturity
* No more surface thrash
* No more “looks structured” while data model is weak
* No more big claims without persisted truth
* No giant ERP drift
* Keep FleetOS focused on coordination + scheduling
* Keep Blade/OpenClaw training in mind: structured coordination events matter

***

## Required output style

Your first response must contain exactly these sections:

1. `What is actually true in the current code`
2. `What is broken or misleading right now`
3. `Locked coordination model`
4. `Locked parts model`
5. `Schema decision`
6. `Execution order`
7. `First files I will change`

Then start work.

***

## Definition of done

You are done only when:

* FleetOS has one clear coordination model
* parts is fast and structured enough for real operations
* readiness/blockers are real, not just implied in UI
* the product supports solo, lean, and multi-role teams without fragmentation
* Blade/OpenClaw can learn from structured coordination events
* JobCard is improved around real business logic, not just more patches


---

# 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-hard-reset-coordination-spec.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.