vertical-construction

name	vertical-construction
description	Domain knowledge for the construction vertical (contractors, field crews) so architect and pm don't spec construction products naively. Covers the vocabulary (bid vs estimate, takeoff, retainage, change order, AIA G702/G703, lien waiver, draw schedule), the non-obvious money rules that incumbents like Procore price out of reach for small contractors, what a naive build gets wrong (no assemblies, ignored retainage, ungated sub payments), and the entities that must be modelled. Applied by architect when writing ARCH-{slug}.md and by pm when writing PLAN-{slug}.md for any of the four construction products (bid-builder, project-mgmt, subcontractor-portal, field-docs).
when_to_use	Apply when: - architect writes ARCH-{slug}.md for a construction product (bid-builder, project-mgmt, subcontractor-portal, field-docs) - pm decomposes a construction feature into PLAN-{slug}.md tasks - design-advisor wireframes a construction screen (estimate, billing, sub payment, daily log) - any spec touches money flow (billing, payment, retainage) in the construction vertical Do NOT apply to non-construction verticals — the money rules (retainage, lien waivers, AIA pay apps) are construction-specific and will mislead elsewhere.
effort	low
allowed-tools	Read, Write, Grep, Glob
paths	["docs/architecture/**","docs/plans/**","docs/design/**"]

Vertical: construction — don't spec it naive

Construction has its own money physics. A spec that treats a contractor's billing like a SaaS invoice will ship something no contractor can use, because the cash flow it ignores (retainage held back, draws against a schedule of values, subs gated on lien waivers) is the thing the contractor is trying to manage. This skill gives architect and pm the vocabulary and the non-obvious rules so the four construction products are specced from domain reality, not intuition.

The four products and their incumbents:

Product	Archetype	Wedge against
bid-builder	marketplace-lite	Excel (small contractors estimate in spreadsheets)
project-mgmt	crud	Buildertrend, Contractor Foreman
subcontractor-portal	marketplace-lite	Procore, manual COI/payment tracking
field-docs	crud	Procore field tools, paper daily reports

Incumbents: Procore (enterprise, ~$375+/mo minimum — too expensive and heavy for small contractors; do not fight it head-on), Buildertrend (residential-focused), Contractor Foreman, Autodesk Construction Cloud (enterprise). The opening is small contractors priced and complexity'd out of these.

Domain vocabulary (use these terms exactly in specs)

• Estimate — internal cost calculation (what the job will cost the contractor). Bid — the priced number submitted to win the job (estimate + markup). Proposal — the customer-facing document wrapping the bid with scope, terms, exclusions. Estimate → bid → proposal are three artifacts, not synonyms.
• Takeoff (quantity takeoff) — counting/measuring quantities from plans (sq ft of drywall, linear ft of pipe) that feed the estimate. Garbage takeoff = garbage bid.
• Unit cost + assembly — an estimate is built from line items priced per unit (e.g. $/sq ft). An assembly bundles several unit-cost items into one (a "door assembly" = door + frame + hardware + labor). Real estimating is assemblies, not freehand numbers.
• Markup vs margin — markup is added on top of cost (cost × 1.20). Margin is the cut of the bid price (price − cost) / price. 20% markup ≠ 20% margin. Mixing them mis-prices the job. Spec which one a field means.
• Change order (CO) — a contracted change to scope/price after the bid is signed. Untracked COs are where margin leaks and disputes start.
• RFI (request for information) — formal question to the architect/owner about ambiguous plans; the answer can change scope (→ change order).
• Submittal — contractor's proposed material/product samples sent for approval before install.
• Draw schedule + progress billing — payment isn't lump-sum. The contractor bills in draws as work completes, against a schedule of values (the job broken into line items each with a contract value); each billing claims a % complete per line.
• Retainage / retention — the owner withholds a slice (typically 5–10%) of each payment until the job is complete/accepted. It is owed money the contractor can't touch yet — a first-class concept, not a discount.
• Lien / lien waiver — a mechanic's lien is a legal claim against the property for unpaid work; a lien waiver is the sub/supplier signing away that right in exchange for payment. Conditional (on payment clearing) vs unconditional (already paid).
• AIA G702/G703 — the industry-standard pay-application forms. G702 is the summary (application + certificate for payment); G703 is the continuation sheet (the schedule of values with this-period / to-date / retainage columns). Many owners require these exact forms.
• 1099 subcontractor — subs are typically 1099 contractors, not employees; the GC must collect a W-9 and issue a 1099 for tax reporting.
• COI (certificate of insurance) — proof a sub carries required insurance; must be current (not expired) before the sub works or gets paid.
• Daily log — the dated field record (crew on site, work done, weather, deliveries, delays). It is legal/dispute evidence, not a status update.
• Punch list — the end-of-job list of defects/incomplete items to fix before final payment / retainage release.
• Schedule of values (SOV) — the contract sum allocated across work items; the backbone of progress billing and G703.

Non-obvious domain rules (the ones that trip a naive spec)

1. Procore is enterprise and expensive. Don't out-feature it for small contractors — undercut on price and simplicity. The wedge is "good enough, cheap, no onboarding consultant."
2. Small contractors estimate in Excel. bid-builder's wedge is replacing the spreadsheet with real estimate math (unit costs + assemblies + markup). It's revenue-adjacent and low-switching — the easiest first sale.
3. Retainage is core, not an edge case. 5–10% withheld until completion changes every billing number. A billing model that doesn't carry a retainage column is wrong.
4. Progress billing runs through the schedule of values. You bill % complete per SOV line, not a flat invoice. Model the SOV first; billing falls out of it.
5. Subs are gated on documents before payment. A sub can't be paid until COI is current and the lien waiver for the period is signed. Payment without that gate is a real-money liability for the GC.
6. Untracked change orders eat margin and cause disputes. Every CO must adjust the contract sum and the SOV, with a signature trail.
7. Daily logs are dispute evidence. Photo + timestamp + weather + crew make them hold up; a free-text note that "we worked today" does not.

What a naive build gets wrong

• Estimating as a flat list of typed-in dollar amounts — no unit costs, no assemblies, no markup/margin distinction. Result: numbers nobody can defend or reuse.
• Billing that ignores retainage — invoices the full amount, so the contractor's books don't match what the owner actually pays.
• project-mgmt that ignores the draw schedule / progress billing — a generic task board that never connects to how money actually arrives.
• Subcontractor payment with no lien-waiver / COI gate — pays subs without the documents that protect the GC from liens and uninsured-work liability.
• No change-order flow — scope changes live in email; margin leaks; disputes have no paper trail.
• Daily logs without photo + timestamp + weather — useless as evidence when a delay or defect claim arrives.

Must-model entities

Hand these to the data model in ARCH (and apply [[migration-ready-schema]] — contractors bring their job list and customer list from the incumbent).

• Estimate — line items with unit_cost, quantity, and assemblies; carries a markup (and derived margin) → produces a Bid.
• Bid / Proposal — the priced submission; references the Estimate it came from.
• ChangeOrder — adjusts contract sum + SOV; has status + signature trail; linked to the Project.
• Subcontractor — its own entity (not an inline field) with COI status + expiry, lien-waiver status (the payment gate), and 1099 / W-9 info.
• Project — carries a Schedule of Values, a draw schedule, and a retainage percentage/balance.
• DailyLog — photos, weather, crew, timestamp; append-only enough to serve as evidence.

Money in integer minor units (*_cents); retainage and SOV math must not float-drift.

Per-product notes

• bid-builder (marketplace-lite) — Wedge: revenue-adjacent, low-switching replacement for the estimating spreadsheet. The one domain thing: real estimate math — unit costs + assemblies + the markup/margin distinction producing a defensible bid. Get this wrong and it's just a worse Excel.
• project-mgmt (crud) — Wedge: lightweight project + daily-log tool vs heavy Buildertrend/Contractor Foreman. The one domain thing: draw schedule / progress billing off the schedule of values — don't ship a generic task board disconnected from billing.
• subcontractor-portal (marketplace-lite) — Wedge: manage subs, docs, and payments without Procore. The one domain thing: lien-waiver + COI gating before payment — the portal's whole value is that a sub can't be paid until the documents are clean.
• field-docs (crud) — Wedge: photo/daily-report/inspection capture vs paper and Procore's field module. The one domain thing: photo + timestamp + weather + crew on every entry so the record is dispute-grade evidence.

Compliance (light — flag, don't gold-plate)

• Lien law is state-specific — preliminary notice deadlines and lien-waiver forms vary by state; treat waiver forms as state-configurable, not hardcoded.
• Retainage law — many states cap the retainage % and regulate timing of release; surface it as a setting.
• 1099 for subs — collect W-9, track payments, support 1099 reporting.
• Prevailing wage — on public/government projects (Davis-Bacon), wage rates are mandated and certified payroll is required; flag if the product targets public work.
• COI verification — verify current (non-expired) coverage before sub work/payment.
• OSHA — relevant to field-docs (safety inspections, incident records) but keep light.

These pair with [[vertical-onboarding]] (importing the contractor's existing jobs, subs, and customers as the low-switching wedge) and [[lifecycle-messaging]] (COI-expiry reminders, lien-waiver requests, draw/payment notifications — the messages that make the money flow run).