contractor-ops
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}
]
}
clientandprojectare required;itemsmust be a non-empty list.deposit_pctdefaults to 30 and must be between 0 and 100.- The progress payment is always 40%; the final balance is the remainder.
- Optional
--milestonerenames the progress-payment trigger (default:
"tear-off complete, underlayment installed").
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.