contractor-ops

v1.0.0 MIT business updated 2026-09-27

Turn line-item JSON into a customer-ready project estimate Markdown file — line items, subtotal, a 30/40/30 deposit–progress–final payment schedule tied to named milestones, and a change-order policy section. Use when bidding contracting jobs (roofing, remodeling, trades) and you need professional paperwork fast. Includes a payment-structure playbook explaining why 30/40/30 protects both sides and how to word each payment trigger.

$ skillbank install contractor-ops@1.0.0
# pins exactly 1.0.0 · README + changelog included

Contractor Ops

Overview

A bid scribbled on a napkin loses to a clean estimate every time — and a clean payment schedule is what keeps you from financing the customer's job. Contractor Ops takes line-item JSON and writes a complete estimate Markdown file: numbered line items, subtotal, a 30/40/30 payment schedule (deposit at signing, 40% at a named midpoint milestone, final balance on walkthrough sign-off), a change-order policy, and signature lines. The percentages are of the subtotal and the final balance is computed as subtotal − deposit − progress, so the three payments always total exactly 100% — rounding can never leave a gap. The playbook in references/payment-structure.md explains why 30/40/30 protects both sides and how to word milestones the customer can actually see.

Installation

1. Copy the contractor-ops/ directory anywhere convenient. 2. Make the script executable (Unix):


   chmod +x scripts/estimate.py

No pip install needed — standard library only.

Configuration

No config file. Each job is an input JSON file:


{
  "client": "Maria Santos",
  "project": "Asphalt shingle roof replacement",
  "deposit_pct": 30,
  "items": [
    {"desc": "Tear off old roof (2 layers)", "cost": 3200.00},
    {"desc": "Materials — shingles, underlayment, flashing", "cost": 8900.00}
  ]
}

Inputs

| Command | Arguments | Returns | |---------|-----------|---------| | estimate.py | estimate.json --out estimate.md [--milestone TEXT] | Writes the estimate Markdown; also prints the payment amounts to the terminal |

Payment math, exactly as implemented:


deposit       = subtotal * deposit_pct / 100
progress      = subtotal * 40 / 100
final balance = subtotal - deposit - progress   # always totals 100%

Money rounds to 2 decimals (half-up). Missing --out, bad JSON, or invalid numbers prints a clear message to stderr and exits nonzero — never a traceback.

Worked example

Sample input, roof.json:


{
  "client": "Maria Santos",
  "project": "Asphalt shingle roof replacement, 1,850 sq ft",
  "deposit_pct": 30,
  "items": [
    {"desc": "Tear off old roof (2 layers)", "cost": 3200.00},
    {"desc": "Architectural shingles, underlayment, flashing, vents", "cost": 8900.00},
    {"desc": "Labor — installation and cleanup", "cost": 4800.00},
    {"desc": "Dumpster, permits, disposal", "cost": 1600.00}
  ]
}

$ ./scripts/estimate.py roof.json --out roof-estimate.md
wrote roof-estimate.md
  client:   Maria Santos
  project:  Asphalt shingle roof replacement, 1,850 sq ft
  subtotal: $18,500.00
  deposit (30%): $5,550.00
  progress (40%): $7,400.00
  final (30%): $5,550.00

Hand-check: subtotal $18,500; 30% = $5,550; 40% = $7,400; final = 18,500 − 5,550 − 7,400 = $5,550; total of the three = $18,500. roof-estimate.md contains the full line-item table, the payment schedule with the milestone trigger, the change-order policy, and signature lines — ready to send to the customer.

Safety notes

These are benign business tools. estimate.py reads your JSON and writes a Markdown file to the path you choose — it never uploads anything. Your client names, pricing, and job details stay on your machine.

Version history

1.0.0 — 2026-09-27

  • Initial release: scripts/estimate.py estimate Markdown generator (line items, 30/40/30 payment schedule, change-order policy, signature lines); references/payment-structure.md playbook.
  • Zero-dependency Python 3 scripts (stdlib only), MIT license.

← back to catalog