# OpsMan — Construction Company Operations System

*AI Operations Manager for Civil Construction Companies*

---

## Overview

OpsMan is a Clawdbot-based operations system that runs a construction company's back office. It tracks crew attendance, manages job costing, generates timesheets, tracks tools and materials, and learns from every job to improve pricing accuracy.

**Built for:** LF Construction Services (first deployment)
**Built by:** Michael McLoughlin / Rivet
**License:** Free for LFCS, template for future clients

---

## Core Philosophy

**"The AI is the Operations Manager"**

Not a tool the ops manager uses — the AI *is* the ops manager. It:
- Watches WhatsApp for crew updates
- Tracks every hour against every job
- Tracks tools, materials, and vehicle stock
- Flags discrepancies automatically
- Learns what jobs actually cost
- Suggests better pricing for next time

---

## System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    OpsMan System                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   WhatsApp   │    │   Telegram   │    │    Cron      │  │
│  │   Channel    │    │   Topics     │    │   Jobs       │  │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘  │
│         │                   │                   │           │
│         └───────────────────┼───────────────────┘           │
│                             │                               │
│                   ┌─────────▼─────────┐                     │
│                   │    Clawdbot       │                     │
│                   │    Gateway        │                     │
│                   └─────────┬─────────┘                     │
│                             │                               │
│         ┌───────────────────┼───────────────────┐           │
│         │                   │                   │           │
│  ┌──────▼──────┐   ┌───────▼────────┐   ┌──────▼──────┐    │
│  │  Crew Agent │   │  Costing Agent │   │ Timesheet   │    │
│  │  (Topic 1)  │   │   (Topic 2)    │   │ Agent       │    │
│  │             │   │                │   │ (Topic 3)   │    │
│  │ - Attendance│   │ - Quoted vs    │   │             │    │
│  │ - Clock in  │   │   actual       │   │ - Compile   │    │
│  │ - No-shows  │   │ - Variance     │   │ - Discrep   │    │
│  └──────┬──────┘   └───────┬────────┘   └──────┬──────┘    │
│         │                  │                   │            │
│         └──────────────────┼───────────────────┘            │
│                            │                                │
│                  ┌─────────▼──────────┐                     │
│                  │   Assets Agent     │                     │
│                  │   (Topic 5)        │                     │
│                  │                    │                     │
│                  │ - Tools in/out     │                     │
│                  │ - Service alerts   │                     │
│                  │ - Stock takes      │                     │
│                  └─────────┬──────────┘                     │
│                            │                                │
│                  ┌─────────▼──────────┐                     │
│                  │   File System      │                     │
│                  │   memory/          │                     │
│                  │   - work-logs/     │                     │
│                  │   - job-costs/     │                     │
│                  │   - workers/       │                     │
│                  │   - assets/        │                     │
│                  └────────────────────┘                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Topic Structure

| Topic | Agent | Purpose | Channel |
|-------|-------|---------|---------|
| **Topic 1: Daily Ops** | Crew Agent | WhatsApp monitoring, attendance, clock in/out | WhatsApp Group |
| **Topic 2: Job Costing** | Costing Agent | Pricing, estimates, actuals, variance | Telegram DM |
| **Topic 3: Timesheets** | Timesheet Agent | Weekly compile, discrepancies, export | Telegram DM |
| **Topic 4: Invoicing** | Invoice Agent | Xero export, client billing | Telegram DM |
| **Topic 5: Assets** | Assets Agent | Tools, materials, vehicles, stock takes | Telegram DM |

---

## Agent Definitions

### Crew Agent (Daily Ops)

**Trigger:** Messages in WhatsApp group "LFCS Daily Crew"

**Input Format (Expected):**
```
Monday 10 Feb
- Rocky: 7am start
- Mike: 7am start  
- Jack: sick
```

**Auto-Response:**
- Parse each line → worker + status
- Clock in: Log start time
- Sick/away: Flag absence
- Unknown name: "Who is [name]? Add to worker list?"

**Daily Cron (5pm):**
- Check for missing clock-outs
- Send reminder: "Still waiting on clock-outs for: Rocky, Mike"

**Weekly Cron (Friday 6pm):**
- Compile attendance summary
- Flag: "Jack: 2 sick days this week"

---

### Costing Agent (Job Costing)

**Trigger:** User sends job details, drawings, or says "price this"

**Workflow:**
1. Parse drawings (PDF/image)
2. Count quantities (m³ concrete, m² formwork, kg steel)
3. Apply labor rates ($100/hr)
4. Add material costs
5. Apply margin (20%)
6. Store: quoted price

**Learning Loop:**
- When job finishes, compare quoted vs actual
- Store variance: "Footings: quoted $13,800, actual $15,992 (+16%)"
- After 3 similar jobs, suggest: "Add 15% contingency to footing jobs"

---

### Timesheet Agent

**Trigger:** Weekly (Wednesday 7am), or manual "compile timesheets"

**Input:**
- Daily attendance logs from Crew Agent
- Worker rates from config
- Any variations (overtime, day work)

**Output:**
- LFCS timesheet format (Excel/CSV)
- Summary: "Week 6: 94 total hours, $9,400 labor cost"
- Discrepancy report: "Rocky logged 44 hrs, but daily logs show 40 hrs"

**Export:**
- CSV for Xero
- PDF for email to accounts@lfcs.com.au

---

### Invoice Agent

**Trigger:** Job marked complete, or manual "invoice [job-name]"

**Input:**
- Job total from Costing Agent
- Timesheet hours from Timesheet Agent
- Any variations logged

**Output:**
- Xero-compatible CSV
- Invoice summary: "Eastern Creek LTP: $13,800 (footings only)"

---

### Assets Agent (Tools, Materials, Vehicles)

**Trigger:** User message or scheduled stock take reminder

**Core Functions:**

#### 1. Tool Tracking
**Check-out:**
```
Rocky: Taking laser level (S/N: LL-001) to Eastern Creek
```
Assets Agent logs:
- Tool: Laser Level LL-001
- Assigned: Rocky
- Job: Eastern Creek LTP
- Date out: 2026-02-09
- Expected return: 2026-02-13

**Check-in:**
```
Rocky: Returning laser level LL-001
```
Assets Agent logs:
- Date returned: 2026-02-09
- Condition: Good / Damaged / Missing
- Currently: In storage

**Overdue Alerts (Daily Cron):**
> "Laser level LL-001 overdue — Rocky, Eastern Creek, due back 3 days ago"

#### 2. Tool Service Tracking
**Service Schedule:**
- Laser level: Calibrate every 6 months
- Jackhammer: Service every 200 hours
- Company ute: Service every 10,000 km

**Service Alerts (Weekly Cron):**
> "Jackhammer JK-002 approaching 200 hrs — service due in 15 hours"
> "Ute UT-001 service overdue by 1,200 km"

#### 3. Material Tracking
**Job Allocation:**
```
Eastern Creek LTP — Materials issued:
- 20 x N16 bars
- 5 sheets 17mm F17 ply
- 1 box Z-bar ties
```

**Material Returns:**
```
Eastern Creek LTP — Materials returned:
- 3 sheets 17mm F17 ply (unused)
- 12 x Z-bar ties (leftover)
```

**Waste Tracking:**
```
Waste logged: 2 sheets ply (cut wrong)
Reason: Engineer height error
```

#### 4. Vehicle Stock Takes
**Expected Tool List per Vehicle:**
- Ute 1: Laser level, jackhammer, shovels x2, crowbars x2, etc.
- Ute 2: [list]

**Stock Take Reminder (Monthly):**
> "Monthly stock take due — Ute 1. Reply with what's missing."

**Stock Take Response:**
```
Ute 1 stock take:
- Laser level: present
- Jackhammer: missing (last with Rocky)
- Crowbar: 1 of 2 (1 missing)
```

Assets Agent flags:
> "Ute 1: Jackhammer missing, 1 crowbar missing. Last assigned: Rocky, Eastern Creek."

#### 5. Purchase Tracking
**New Tool Purchased:**
```
Bought: New laser level LL-003 from Sydney Tools
Cost: $1,200
Date: 2026-02-09
Warranty: 2 years
Service due: 2026-08-09 (6 months)
```

---

## File Structure

```
/home/clawdbot/lfcs-ops/           # Client workspace
├── SOUL.md                        # OpsMan personality
├── AGENTS.md                      # Workspace rules
├── USER.md                        # Liam/LFCS profile
├── TOOLS.md                       # API keys, WhatsApp config
├── SECURITY.md                    # Data handling rules
├── TOPICS.md                      # Agent briefing
├── CRONS.md                       # Scheduled jobs
│
├── memory/
│   ├── work-logs/
│   │   ├── 2026-W05.md
│   │   ├── 2026-W06.md
│   │   └── ...
│   │
│   ├── job-costs/
│   │   ├── eastern-creek-ltp.md
│   │   ├── arncliffe-bollards.md
│   │   └── template.md
│   │
│   ├── workers/
│   │   ├── rocky-mcloughlin.md
│   │   ├── mike-[surname].md
│   │   └── jack-moritz.md
│   │
│   ├── attendance/
│   │   ├── 2026-02-09.md
│   │   ├── 2026-02-10.md
│   │   └── ...
│   │
│   ├── assets/
│   │   ├── tools/
│   │   │   ├── laser-level-001.md
│   │   │   ├── jackhammer-002.md
│   │   │   └── tool-inventory.md
│   │   ├── materials/
│   │   │   ├── job-allocations/
│   │   │   │   ├── eastern-creek-ltp.md
│   │   │   │   └── arncliffe-bollards.md
│   │   │   └── waste-log.md
│   │   └── vehicles/
│   │       ├── ute-001.md
│   │       ├── ute-002.md
│   │       └── stock-takes/
│   │           ├── 2026-02-09-ute-001.md
│   │           └── ...
│   │
│   └── learnings/
│       ├── pricing-patterns.md
│       ├── worker-reliability.md
│       └── job-variances.md
│
├── config/
│   ├── company.json               # LFCS details, rates
│   ├── workers.json               # Worker list + rates
│   └── xero.json                  # Xero API config
│
└── exports/                       # Generated files
    ├── timesheets/
    │   └── 2026-W06-lfcs.xlsx
    └── invoices/
        └── INV-001-eastern-creek.pdf
```

---

## Core Documents

### SOUL.md (OpsMan Personality)

```markdown
# SOUL.md — OpsMan

## Core

You are OpsMan, the Operations Manager for LF Construction Services.
Your job: Make sure every job is priced right, every worker is accounted for, and the company makes money.

## How You Think

**Be precise.** Construction is numbers. Hours, rates, margins — get them right.
**Be vigilant.** If someone's not clocked in, if a job's going over budget, flag it immediately.
**Be learning.** Every job teaches something. Track variances, build patterns, improve pricing.

## How You Talk

- Direct: "Rocky's not clocked in. Check with him."
- Numbers-first: "Job variance: +16%. Reason: engineer errors."
- Actionable: "Add 15% contingency to footing jobs going forward."

## Hard Rules

- Never share worker data outside this system
- Timesheets go to accounts@lfcs.com.au only
- Flag discrepancies immediately — don't wait
- Learn from every job — that's the point
```

### USER.md (LFCS Profile)

```markdown
# USER.md — LF Construction Services

## Company
- **Name:** LF Construction Services
- **ABN:** [to be added]
- **Address:** [to be added]
- **Contact:** admin@lfcs.com.au

## Key People
- **Owner:** Liam [surname]
- **Ops Manager:** OpsMan (AI)
- **Payroll:** Jo (accounts@lfcs.com.au)

## Rates
- **Standard labor:** $100/hour
- **Day work rate:** $850/day
- **Margin:** 20%

## Current Projects
- Ford Civil, Arncliffe (ongoing)
- Eastern Creek LTP (quoting)

## Workers
- Rocky McLoughlin — Steel Fixer / Supervisor — $100/hr
- Mike [surname] — Steel Fixer — $100/hr  
- Jack Moritz — [role] — $100/hr
```

### SECURITY.md

```markdown
# SECURITY.md — Data Handling

## Classifications

### 🔴 Confidential
- Worker personal details (addresses, phone numbers)
- Payroll information
- Client pricing
- Company financials

### 🟡 Internal
- Daily attendance
- Job costs (after completion)
- Worker reliability scores

### 🟢 Public
- Nothing — all data is internal or confidential

## Storage Rules

1. **No personal data in GitHub** — template only, no LFCS data
2. **Worker files** — first name + initial only in filenames
3. **API keys** — .env file only, never committed
4. **Backups** — encrypted Google Drive, daily

## Access Control

- **Liam:** Full access
- **Michael (builder):** Admin access for maintenance
- **OpsMan agents:** Read/write their topic areas only
```

---

## WhatsApp Integration

### Group: "LFCS Daily Crew"

**Expected Message Format:**

```
Monday 10 Feb — Eastern Creek
Rocky: 7am start
Mike: 7am start
Jack: sick
```

**Auto-Parse:**
- Date: Monday 10 Feb
- Job: Eastern Creek
- Rocky: clocked in 7am
- Mike: clocked in 7am
- Jack: absence (sick)

**End of Day:**
```
Rocky: 4:30pm finish
Mike: 4:30pm finish
```

**OpsMan Response:**
- Log hours: Rocky 9.5 hrs, Mike 9.5 hrs
- Flag: Jack absent (sick day logged)

---

## Cron Jobs

| Time | Job | Action |
|------|-----|--------|
| 5:00 AM | Morning Brief | Send today's crew list + job + weather |
| 5:00 PM | Clock-out Reminder | List missing clock-outs |
| 6:00 PM | Daily Summary | Hours logged today, any issues |
| **6:00 PM** | **Overdue Tools** | **List tools not returned, overdue** |
| Friday 6PM | Weekly Compile | Attendance summary, flag patterns |
| Wednesday 7AM | Timesheet Export | Generate timesheet for payroll |
| **1st of Month** | **Vehicle Stock Take** | **Reminder: Complete stock takes** |
| **Weekly (Mon)** | **Service Due** | **List tools/vehicles needing service** |
| Sunday 8PM | Learning Report | Job variances, pricing insights |

---

## Pricing Engine (V1)

### Input
- PDF drawings
- Scope description ("footings only", "tanks included")

### Process
1. Image/PDF analysis (count elements)
2. Quantity takeoff (m³, m², kg)
3. Labor hours (historical data + rules)
4. Material costs (config rates)
5. Margin application

### Output
```markdown
## Quote: Eastern Creek LTP (Footings Only)

### Labor
- Formwork: 30 hrs × $100 = $3,000
- Steel tying: 40 hrs × $100 = $4,000
- Pouring: 15 hrs × $100 = $1,500
- **Subtotal labor: $8,500**

### Materials
- Formwork ply/timber: $3,000
- **Subtotal materials: $3,000**

### Total
- Subtotal: $11,500
- Margin (20%): $2,300
- **Quote: $13,800**

### Duration
- ~85 hours
- 2 steel fixers + 2 chippies = ~9 working days
```

---

## Learning Engine (V2)

After every completed job:

```markdown
## Job Post-Mortem: Eastern Creek LTP

### Quoted vs Actual
| Item | Quoted | Actual | Variance |
|------|--------|--------|----------|
| Labor | $8,500 | $10,200 | +20% |
| Materials | $3,000 | $3,200 | +7% |
| **Total** | **$13,800** | **$15,992** | **+16%** |

### Why?
- Engineer errors: 2 days rework ($1,600)
- Material waste: $200

### Lesson
Footing jobs with new engineers: **Add 20% contingency**
```

After 3 similar jobs, system suggests:
> "Based on last 3 footing jobs, actual costs average 18% over quote. Recommend adding 20% contingency to future footing quotes."

---

## Assets Tracking Examples

### Tool Check-out/Check-in

**Worker messages:**
```
Rocky: Taking laser level LL-001 to Eastern Creek today
```

**OpsMan responds:**
> ✅ Laser level LL-001 checked out to Rocky for Eastern Creek LTP. Due back: 2026-02-13.

---

**End of job:**
```
Rocky: Returning laser level LL-001
```

**OpsMan responds:**
> ✅ Laser level LL-001 returned. Condition: Good. Currently: In storage.

---

### Overdue Alert

**Daily cron detects:**
> ⚠️ **Overdue Tools:**
> - Laser level LL-001 — Rocky, Eastern Creek, due 3 days ago
> - Jackhammer JK-002 — Mike, Arncliffe, due 1 week ago

---

### Service Reminder

**Weekly cron detects:**
> 🔧 **Service Due:**
> - Jackhammer JK-002: 195 hrs logged (service at 200 hrs)
> - Ute UT-001: 11,200 km (service overdue by 1,200 km)

---

### Material Allocation

**Foreman messages:**
```
Eastern Creek — Materials out:
- 20 x N16 bars
- 5 sheets 17mm ply
- Box of Z-bars
```

**OpsMan logs:**
> Materials allocated to Eastern Creek LTP. Total value: ~$450.

---

### Material Return

```
Eastern Creek — Materials back:
- 3 sheets ply (unused)
- 12 x Z-bars (leftover)
```

**OpsMan logs:**
> Materials returned. Waste/scrap: $85. Next job: can reuse 3 sheets ply.

---

### Vehicle Stock Take

**Monthly reminder:**
> 📋 **Stock Take Due:** Ute 1
> Reply with missing items.

**Worker responds:**
```
Ute 1 stock take:
- Laser level: present
- Jackhammer: MISSING (last with Rocky)
- Crowbars: 1 of 2
```

**OpsMan flags:**
> 🚨 Ute 1 Stock Discrepancy:
> - Jackhammer missing — last assigned Rocky, Eastern Creek
> - 1 crowbar missing — investigate

---

## Deployment Steps

### 1. Infrastructure
```bash
# New DigitalOcean droplet
# Ubuntu 22.04, 2 vCPU, 4GB RAM
# SSH key for Michael
```

### 2. Clawdbot Install
```bash
# Install Clawdbot gateway
# Configure for LFCS workspace
# Set up WhatsApp + Telegram channels
```

### 3. Agent Configuration
```bash
# Create topic agents
# Configure prompts (Crew, Costing, Timesheet, Invoice, Assets)
# Set up cron jobs
```

### 4. Data Import
```bash
# Worker list from Liam
# Current rates
# Xero API credentials
```

### 5. Testing
```bash
# Send test WhatsApp message
# Verify parsing
# Test timesheet export
# Verify Xero connection
```

---

## Maintenance Plan

### Daily (Automated)
- Cron jobs run
- Data backups to Google Drive
- Health checks

### Weekly (Michael)
- Review any system errors
- Check backup integrity
- Verify WhatsApp connection stable

### Monthly (Michael)
- Update Clawdbot if needed
- Review learning data
- Optimize agent prompts based on usage

### On Failure
1. Self-healing cron restarts services
2. If fails, alert Michael
3. Michael SSHs in, runs recovery scripts
4. If stuck, escalate to Michael (human)

---

## Future Enhancements

### V2 (Month 3-4)
- GPS clock in/out (optional, worker phones)
- Photo logging with auto-tagging
- Client portal (view job progress)
- Supplier price integration

### V3 (Month 5-6)
- Predictive pricing (ML on job history)
- Optimal crew allocation
- Safety incident tracking
- Advanced equipment analytics (utilization, ROI per tool)

### V4 (Sellable Product)
- Multi-company support
- White-label branding
- Self-service deployment
- Subscription billing

---

## Success Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| Attendance accuracy | 99% | Daily logs vs timesheet |
| Quote accuracy | ±10% | Quoted vs actual |
| Timesheet generation | <5 min | From raw data to export |
| Admin time saved | 10 hrs/week | Liam's manual work reduced |
| Learning insights | 1/week | Actionable pricing feedback |

---

## Open Questions

### Core System
1. **Worker privacy:** What personal data does Liam track? (just names, or more?)
2. **Xero integration:** Full API push, or just CSV import?
3. **Photo logging:** Does Liam want progress photos stored/linked to jobs?
4. **Variations:** How are job scope changes handled? (variations, extras)
5. **Subcontractors:** Does LFCS use subs, or only employees?

### Assets & Tools
6. **Tool inventory:** How many tools need tracking? (laser levels, jackhammers, etc.)
7. **Vehicles:** How many utes/trucks? What's the expected tool list per vehicle?
8. **Service schedules:** Who currently tracks tool/vehicle servicing?
9. **Material tracking:** Does Liam want full material allocation per job, or just major items?
10. **Stock takes:** How often? Currently done? Who does them?

---

*Spec Version: 1.1*
*Date: 2026-02-09*
*Built by: Rivet for LFCS*
*Last Updated: Added Assets Agent (tools, materials, vehicles)*