Construction PM

production-tested construction project management toolkit. built from real roofing company workflows managing 36+ active jobs and $1.8M+ pipeline.

intent

construction PM tracks jobs through their full lifecycle (lead to paid), generates daily briefings on pipeline health, flags stale permits and aging jobs, parses PM emails for status updates, and monitors revenue at each stage. use this when you need to manage 10+ concurrent jobs, forecast cash flow, catch projects falling through cracks, or generate quick snapshots of pipeline status for leadership.

inputs

database setup:

• bash scripts in scripts/ directory (add-job.sh, pipeline.sh, briefing.sh, permit-check.sh, parse-email.sh, init.sh)
• jq binary for JSON parsing
• writable directory for data storage (defaults to construction-pm-data/ in workspace, configurable via DATA_DIR env var)

job data schema (JSON):

• job number (string, must match accounting/CRM system)
• customer name (string, specific names only, no generics)
• address (string)
• project manager name (string)
• job value (integer, no currency symbols or "k" notation, plain dollars: 49000 not $49,000)
• status (enum: lead, estimate, sold, permitted, scheduled, in-progress, complete, invoiced, paid, on-hold, cancelled)
• permit status (enum: pending, approved, denied, expired)
• permit number (string, optional but required for inspections)
• notes (string, free text for context)
• created date (ISO 8601, YYYY-MM-DD)
• updated date (ISO 8601, YYYY-MM-DD)
• history array (audit trail of all status changes with timestamps and notes)

external inputs (email parsing):

• plain text email files or stdin containing job number, customer name, status keywords, permit mentions, dates
• email format is flexible (parses unstructured text)

configuration parameters:

• stale-days threshold (default 14 days, configurable per command, typical 7-30 days)
• permit-check threshold (default 30 days, jurisdiction-dependent)
• custom data directory path (via DATA_DIR env var or --data-dir flag)

procedure

1. initialize the database

• input: workspace directory, optional DATA_DIR env var or --data-dir flag
• run: bash scripts/init.sh or DATA_DIR=/custom/path bash scripts/init.sh
• output: creates construction-pm-data/jobs.json with empty jobs array and metadata, creates construction-pm-data/ directory structure if missing
• note: idempotent, safe to run multiple times

2. add or update a job

• input: job number (required), customer, address, pm name, value (integer), status, permit-status, permit-number (optional), notes
• run: bash scripts/add-job.sh --number "12043" --customer "Nichols" --address "123 Main St" --pm "Greg" --value 49000 --status "permitted" --permit-status "approved" --notes "Roof replacement, 30sq"
• output: appends job to jobs.json, generates history entry with timestamp, updates "updated" field to today
• on update: bash scripts/add-job.sh --number "12043" --status "in-progress" --notes "Crew on site Monday" finds existing job by number, appends new history entry, preserves all prior fields
• validation: job number must be non-empty string, value must be integer >= 0, status must be valid enum, customer name must be specific (rejects generic names)

3. view pipeline with optional filters

• input: optional filters (--status, --pm, --stale N, --summary flag), optional --data-dir
• run: bash scripts/pipeline.sh (all jobs), bash scripts/pipeline.sh --status permitted (single status), bash scripts/pipeline.sh --pm Greg (single PM), bash scripts/pipeline.sh --stale 14 (jobs not updated in 14+ days), bash scripts/pipeline.sh --summary (aggregated stats)
• output: formatted table or JSON with job number, customer, address, PM, value, status, updated date, notes; summary mode shows count and total revenue by status
• filtering: stale check compares today's date to job's "updated" field

4. generate daily briefing

• input: optional --stale-days flag (default 14), optional output file path, optional --data-dir
• run: bash scripts/briefing.sh or bash scripts/briefing.sh --stale-days 7 > /path/to/briefing.md
• output: markdown file with sections for (1) jobs starting this week, (2) permits pending > threshold days, (3) stale jobs (no update in N+ days), (4) pipeline summary by status with revenue totals, (5) cash flow forecast by stage
• content: pulls data from jobs.json, groups by status and start date, calculates aging for permits

5. check permit status and flag aging

• input: optional --threshold N (default 30 days), optional --data-dir
• run: bash scripts/permit-check.sh (all permits) or bash scripts/permit-check.sh --threshold 30 (flag permits older than 30 days)
• output: list of jobs with permit status, permit number, days pending, flag if exceeds threshold
• calculation: days pending = today's date minus date permit status changed to "pending" (tracked in history)

6. parse PM email for job updates

• input: plain text email (via --file /path/to/email.txt or stdin), optional --data-dir
• run: bash scripts/parse-email.sh --file /path/to/email.txt or echo "Job 12043 Nichols - permit approved" | bash scripts/parse-email.sh
• output: structured JSON with extracted fields (job_number, customer_name, status_keywords, permit_mentions, dates)
• parsing: regex extracts 5-digit job numbers, common status words (approved, denied, pending, completed, on-site, crew, inspection), permit mentions, ISO or natural-language dates
• note: does not auto-update jobs.json; output is for review before manual update via add-job.sh

decision points

on init.sh if data directory already exists:

• if construction-pm-data/ exists and jobs.json is valid JSON, skip creation and report "database ready"
• if jobs.json exists but is corrupted or missing, exit with error and ask user to backup and delete manually
• if DATA_DIR env var is set, use that path instead of default

on add-job.sh if job number already exists in jobs.json:

• treat as update: merge new fields with existing, preserve all unspecified fields, append new history entry with timestamp
• if --status is not provided on update, do not change status (only update other fields)

on pipeline.sh if no filters provided:

• return all jobs (both open and closed statuses)
• if --stale N is provided but no jobs are older than N days, return empty result with message "no stale jobs"

on briefing.sh if no jobs have status "permitted" or "scheduled":

• include those sections but note "none this week" or "none pending"

on permit-check.sh if permit_number field is empty:

• flag job as "permit number missing" and include in output for user to add number (does not auto-fail)
• if permit_status is not "pending" or "approved", skip permit aging check (already denied or expired)

on parse-email.sh if extraction finds 0 job numbers:

• output warning "no job numbers found, manual review required" and return raw email text
• if multiple job numbers found in single email, extract all and output as array

on any script if DATA_DIR is unreachable or unwritable:

• exit with error "cannot write to DATA_DIR: /path" and suggest checking permissions

output contract

jobs.json format:

{
  "jobs": [
    {
      "number": "12043",
      "customer": "Nichols",
      "address": "123 Main St",
      "pm": "Greg",
      "value": 49000,
      "status": "permitted",
      "permit_status": "approved",
      "permit_number": "PERMIT-2026-001",
      "notes": "Roof replacement, 30sq",
      "created": "2026-02-08",
      "updated": "2026-02-10",
      "history": [
        {"date": "2026-02-08", "from": "", "to": "permitted", "note": "Initial entry"},
        {"date": "2026-02-10", "from": "permitted", "to": "permitted", "note": "Crew on site Monday"}
      ]
    }
  ]
}

pipeline.sh output: formatted table with columns: number, customer, address, pm, value, status, updated, notes; or JSON with --json flag; or summary stats (count by status, total revenue by status)

briefing.sh output: markdown file with h2 sections: "jobs this week", "aging permits", "stale jobs", "pipeline summary", "revenue forecast"; ready to pipe to email, Obsidian vault, or Telegram

permit-check.sh output: table with columns: number, customer, permit_number, permit_status, days_pending, flag (yes/no if exceeds threshold)

parse-email.sh output: JSON object: {"job_numbers": ["12043"], "customers": ["Nichols"], "status_keywords": ["approved", "crew"], "permit_mentions": ["permit approved"], "dates": ["2026-02-10"]}

all scripts on error: exit code non-zero,