> 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-kickoff-prompt.md). # Claude Kickoff Prompt > **Status: EXECUTED** — This prompt was run and the work completed as of 2026-04-04. QueryService split, dashboard hooks decomposed, App.tsx slimmed, API Phase 1 implemented. Retained as historical context. Paste this into a fresh Claude Code terminal session at the FleetOS repo root. *** You are working in the `ZBO19/FleetOS` repository. Start by reading these files in this order: 1. `docs/agent.md` 2. `docs/production-plan.md` 3. `docs/api-mcp-spec.md` 4. `docs/openapi.yaml` Your mission: Refactor FleetOS into a cleaner, more reliable operations product **without changing core user-facing behavior**, and begin implementing **Phase 1 of the API-first external service execution layer**. ## Product context FleetOS is not a generic ticketing app. It is a cross-company fleet ↔ supplier service coordination layer. It should handle: * work order creation * supplier communication * quote submission * fleet approval * technician / bay / parts coordination * completion and audit trail * future agent-to-agent workflows It should let fleets keep their current systems while FleetOS becomes the coordination layer. ## Non-negotiables * Preserve supplier vs fleet role behavior. * Preserve current core workflow behavior. * Do not rip out major features. * Keep compatibility wrappers during refactor. * Prefer smaller focused files over giant controller files. * Keep all new code strongly typed. * Favor operational clarity over cleverness. ## Immediate goals ### Goal 1 — architecture cleanup Refactor top-down in this order: 1. `services/shared/QueryService.ts` 2. `hooks/useFleetOSDashboard.ts` 3. `App.tsx` 4. `components/fleetos/types/dashboard.ts` 5. `components/fleetos/pages/UnifiedDashboard.tsx` 6. `components/fleetos/forms/AddJobModal.tsx` 7. `components/fleetos/pages/CleanLanding.tsx` ### Goal 2 — API Phase 1 implementation Use `docs/openapi.yaml` as the implementation contract. Build Phase 1 only: * work order creation * work order retrieval and listing * quote submission * approve / decline quote * assignment * start work * parts update * ready for pickup * request delivery * complete work * cancel work * attachments * webhook contract scaffolding * API key auth scaffolding ## Required approach ### Step 1 Read and summarize the four docs above in your own words so you are grounded. ### Step 2 Inspect the current repo structure and identify: * existing API/backend surface * current request/workflow models * current auth model * likely implementation path for `docs/openapi.yaml` ### Step 3 Produce a concrete execution plan with: * files to change first * new files to create * compatibility risks * migration risks * what can be done immediately vs later ### Step 4 Begin implementation with the highest-leverage architecture split first: * split `QueryService.ts` into focused services while preserving compatibility ### Step 5 After that, begin API Phase 1 scaffolding from `docs/openapi.yaml` ## Naming rules Replace vague names over time: * `counterparty` * `counterparty_name` * `phone_only_name` Prefer explicit names such as: * `fleetCompanyName` * `fleetContactName` * `supplierCompanyName` * `supplierContactPhone` * `supplierContactEmail` ## Status model guidance Do not let legacy single-field status remain the long-term truth. Work toward: * `commercial_status` * `operational_status` * `priority` But keep compatibility with the current implementation while refactoring. ## Output style * Be concrete. * Show exact files changed. * Keep a running checklist. * Make incremental commits. * Do not ask broad philosophical questions. * Do not rebuild from scratch. ## First response format Your first response should contain exactly these sections: 1. `What I read` 2. `What the repo appears to do today` 3. `Highest-risk architectural issues` 4. `Implementation plan` 5. `First code changes I will make` Then start work. *** ## Shorter version If you want a shorter kickoff, use this: Read: * `docs/agent.md` * `docs/production-plan.md` * `docs/api-mcp-spec.md` * `docs/openapi.yaml` Then: 1. summarize the docs 2. inspect the repo and map current architecture 3. propose a file-by-file execution plan 4. start by splitting `services/shared/QueryService.ts` with compatibility wrappers 5. then scaffold Phase 1 API implementation from `docs/openapi.yaml` Preserve current behavior. Do not rebuild from scratch. Keep changes incremental and strongly typed. --- # 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-kickoff-prompt.md?ask=&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.