trades-builder（交易建设者）

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:

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.

• "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

• 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. Scope summary table — all scope items with scope type, location, spec/type, sqft, rate, line total. Clean Table with right-aligned numeric columns.
4. Totals block — subtotal, tax (GST 5%), total. Total is large and bold.
5. Payment status — trade invoice status badge + customer invoice status badge, side by side.
6. Terms — payment terms (Net 30), currency (CAD).

This view is entirely read-only. No edit controls, no inputs, no dropdowns. Users click back to Estimate or Schedule in the stepper to make changes. The Job Summary is the output, not the workspace.

Layout Pattern

The trades-builder tool uses a three-panel layout with FIVE sections (not four). The builder MUST follow this layout.

Left sidebar (always visible, collapsible)

The template ships SidebarProvider, Sidebar, SidebarContent, and SidebarTrigger already wired in app/layouts/MainLayout.tsx. SidebarContent is empty — that's the slot this skill fills. Do not re-wire the sidebar, do not add a second Sidebar component, and do not put a brand tile inside it. Brand identity lives in the header only (see Template Contract above).

Sidebar heading: Use a contextual label like "Workflow" or "Project workflow" — not the company name. The heading describes what the navigation IS.

CRITICAL: Stepper labels come from THIS SKILL, not from DOMAIN.md. The DOMAIN.md state model may list estimated, scheduled, in progress, completed — those are the project's STATUS values for badges. The stepper LABELS are the skill's section names: Estimate, Schedule, In Progress, Close Out, Job Summary. These are different things. The stepper has 5 steps. The domain has 4 statuses. Do not use the domain status list as stepper labels — you'll get 4 steps instead of 5 and lose Close Out and Job Summary.

Main content (center — changes per section)

Only the active section renders. Do NOT stack all sections on one scrolling page. Do NOT combine multiple sections into one panel (e.g., "Schedule / In Progress / Close Out" as one section is WRONG — each is its own panel). Do NOT use horizontal tabs. Each stepper step shows its corresponding panel at FULL WIDTH of the main content area. All other panels are hidden.

Implementation: use a currentStep state variable (0–4). Render only the panel that matches currentStep.

// ALL FIVE panels, conditional rendering
{currentStep === 0 && <EstimatePanel />}
{currentStep === 1 && <SchedulePanel />}
{currentStep === 2 && <InProgressPanel />}
{currentStep === 3 && <CloseOutPanel />}
{currentStep === 4 && <JobSummaryPanel />}

Right sidebar (always visible)

RBAC behavior

• Seed localStorage with roles from DOMAIN.md User Roles or Stakeholder Map.
• Role switcher is a single DropdownMenu dropdown in the header bar — not separate buttons. Shows active role name and badge.
• Approval gating: If DOMAIN.md says only certain roles can close out or approve, disable those buttons for other roles.
• Role-specific views: If roles handle specific stages (e.g., estimator handles Estimate, project manager handles Schedule), show relevant context when that role is active.

Price visibility

• Show prices on the Estimate panel — unit rates, line totals, subtotal, tax, total.
• Show running totals in the right sidebar Project Summary.
• Use the currency, tax type, and tax rate from DOMAIN.md.
• Format prices with the currency code (e.g., "$3,900.40 CAD" or "$3,900.40" with "CAD" shown in the summary).

shadcn/ui component mapping

Treat cards as an exception, not the default layout primitive. Inline content into the page body whenever possible. Use cards only when something truly needs emphasis, separation, repetition, or dialog/detail framing. Do not build card-heavy dashboards, cards inside cards, or generic grids of floating panels.

Deterministic Mapping Rules

Entity → Scope Item Mapping

When the Knowledge Agent extracts entities from the transcript, map them to the trades-builder structure:

Business Rule → Validation Mapping

Integration → Reference Mapping

If DOMAIN.md lists integration points (e.g., Bold, Arvest, QuickBooks), reference them in section descriptions and workflow notes — but do NOT build integration UI. The prototype is localStorage-only. Integration comes in the full build.

Reference Files

This skill expects these files to exist:

The builder should read DOMAIN.md or .tasks/domain.md before writing any code.