trades-builder

What this skill does

# Trades Operations Skill

## What This Skill Does

This skill defines how to build a **trades operations tool** — the estimate-to-payment workflow that construction trades and field service businesses run daily.

It is NOT a generic project management tool (Jira/Asana). It is NOT a CPQ tool (no product configuration). It is a workflow tracker specifically shaped for businesses that:
- Create estimates based on measured scope items (square footage, linear feet, units)
- Schedule and assign field work to crews or subtrades
- Track progress by scope item and location
- Pay subtrades based on completed measured work
- Invoice customers and collect payment

**Common verticals:** drywall, roofing, HVAC, plumbing, electrical, painting, flooring, concrete, landscaping, general contracting.

The builder reads this skill, reads the DOMAIN.md for the specific trade and terminology, and generates a working prototype that uses the customer's actual scope items, pricing, and workflow stages.

## When to Use This Skill

Use this skill when the transcript or DOMAIN.md contains these signals:

| Signal | Examples |
|---|---|
| **Scope items with measurements** | square footage, linear feet, board feet, units per area |
| **Field scheduling** | crew assignment, job calendar, field work planning |
| **Subtrade payments** | paying subs, trade payments, per-sqft pay rates |
| **Estimate-to-invoice workflow** | estimate → schedule → work → invoice cycle |
| **Trade-specific scopes** | insulation, drywall, taping, roofing, framing, plumbing rough-in |
| **Location-based specs** | different specs per floor, per room, per zone |
| **Dual invoicing** | trade invoices (outgoing to subs) AND customer invoices (incoming from clients) |

**Do NOT use this skill for:**
- Product configuration with dependencies → use cpq-builder
- Inventory and stock management → use erp-builder (future)
- Generic CRM or contact management → use crm-builder

---

## Template Contract

Before you start building, understand what the template gives you and what this skill adds. This is the contract:

**The template (`app/layouts/MainLayout.tsx`) ships with:**
- `SidebarProvider`, `Sidebar`, `SidebarContent`, `SidebarInset`, `SidebarTrigger` — already wired
- `SidebarContent` is **empty** — this is your landing zone
- One brand slot in the header (logo placeholder + company name)
- `ModeToggle` and user menu in the header's right cluster

**This skill fills:**
- `SidebarContent` — with the vertical stepper and saved projects (see Layout Pattern below)
- The brand slot in the header — with the client's logo and company name from DOMAIN.md
- The header's right cluster — adds a role switcher `DropdownMenu` before the existing user menu
- The `<Outlet />` in `<main>` — via route components for each of the five sections

**This skill does NOT:**
- Add a second `Sidebar` component. There is one sidebar.
- Put a brand tile inside `SidebarContent`. Brand lives in the header only.
- Rewire `SidebarProvider` or replace the collapsible behavior. Use what's there.
- Put the stepper as horizontal tabs in the main content area. The stepper is a vertical list inside `SidebarContent`.

If you find yourself wanting to restructure `MainLayout.tsx`, stop — the answer is almost always to fill `SidebarContent` instead.

---

## Section Definitions

The trades-builder tool has **FIVE sections**. These are fixed — they come from this skill, not from the business process described in the transcript.

### Section 1: Estimate

**What it does:** Capture the project details and build the scope-based estimate.

**Project details (editable inline):**
- Project name — inline editable text (click to edit, save on blur)
- Customer name — inline editable text
- Address — inline editable text
- Estimate number — auto-generated, read-only
- Lead source — `Select` dropdown if DOMAIN.md defines sources, otherwise free text
- Estimator notes — `Textarea`, always editable

**Scope items table (the core of this section):**
This table is the most important element in the app. Each row represents a scope of work with measured quantities.

| Column | Type | Editable | Notes |
|---|---|---|---|
| Scope | `Select` dropdown | Yes | Options from DOMAIN.md: insulation, drywall, taping, sanding, cleaning, priming, etc. |
| Location | Text input | Yes | e.g., "Main floor living room," "Basement suite" |
| Spec/Type | Text input or `Select` | Yes | e.g., "Type X," "Moisture resistant," "R-20 batt," "Level 4 finish" |
| Sq ft | Number input | Yes | Square footage for this scope at this location |
| Rate | Number input | Yes | Dollar rate per sqft (CAD) |
| Line total | Calculated | No | Sqft × Rate, auto-calculated |
| Actions | Delete button | — | Trash icon to remove the row |

- **"Add row" button** below the table to add more scope items
- **Multiple rows per scope type** — e.g., two drywall rows for different locations with different types
- **Auto-calculated footer:** Subtotal, Tax (GST 5%), Total — updates on every cell change
- **All cells are directly editable** — click a cell, type, blur to save. See frontend-design skill for inline editing pattern.

**Data from DOMAIN.md to use:**
- Entity Registry → Job Specification sub-items become the Scope dropdown options
- Business Rules → unit of measure (sqft, lft), tax type and rate, payment terms
- Terminology Glossary → exact scope names (not generic labels)

### Section 2: Schedule

**What it does:** Plan field work assignments and sequence.

**Fields (editable):**
- Assigned roles/people — `Select` dropdowns from DOMAIN.md Stakeholder Map, NOT free text
- Scope sequence — reorderable list showing which scope items happen in what order
- Start date — date picker, editable
- Target completion date — date picker, editable
- Field crew notes — `Textarea`, editable

**If DOMAIN.md mentions scheduling tools** (e.g., "Bold for scheduling"), reference them in the section description: "Use Bold to line up the field crew."

### Section 3: In Progress

**What it does:** Track work completion per scope item and location.

**Display:**
- Table populated from Estimate's scope items — same rows, now being tracked for completion

| Column | Type | Editable | Notes |
|---|---|---|---|
| Scope | Text | No | From Estimate |
| Location | Text | No | From Estimate |
| Sq ft | Number | No | From Estimate |
| Status | `Select` dropdown | Yes | Not Started / In Progress / Completed |

- Status changes save immediately to localStorage
- "Mark all completed" button for bulk update
- Progress indicator: "3 of 5 scope items completed"

### Section 4: Close Out

**What it does:** Handle the dual payment flow — pay subtrades and invoice the customer.

**Display — two invoice sections side by side:**

**Trade Invoice section:**
- Subtrade payment amount — auto-calculated from completed scope items (sqft × rate)
- Status: `Select` dropdown — Ready to pay / Paid
- Payment date — date picker, editable when status is Paid
- Reference to Bold if mentioned in DOMAIN.md

**Customer Invoice section:**
- Invoice amount — subtotal + tax from Estimate
- Status: `Select` dropdown — Ready to send / Sent / Paid
- Invoice date — date picker, editable
- Reference to Arvest if mentioned in DOMAIN.md

- "Close out job" action button that marks the project as Completed
- Both invoice statuses must be saved to localStorage

**If DOMAIN.md mentions invoicing tools**, reference them in the section headers: "Trade invoice (Bold)" and "Customer invoice (Arvest)."

### Section 5: Job Summary

**What it does:** Read-only summary of the completed project — the final output view.

**Layout (top to bottom):**
1. **Company header** — brand logo from domain.md Brand Logos section (use the logo URL or path provided) + company name + placeholder address ("123 Main St, City, Province, Postal Code — update in settings")
2. **Project metadata** — project name, customer, address, estimate number, dates, assigned to. Two-column grid of label/value pairs.
3. **