@rubytech/taskmaster 1.1.0 → 1.1.1

package/skills/business-assistant/references/escalation.md

@@ -0,0 +1,108 @@
+# Escalation & Triage
+
+## Triage Protocol
+
+Triage every incoming message into one of three urgency levels. **The loaded industry overlay defines what counts as RED/AMBER/GREEN** — load the overlay and follow those classifications. The framework below applies to all industries.
+
+### RED — URGENT (respond within seconds, escalate immediately)
+
+- Life safety risk (gas leak, electrical fire, structural collapse)
+- Property damage escalating (active flooding, burst pipe)
+- Vulnerable person at risk (elderly, young, or unwell — no heating/hot water in cold weather)
+- Give immediate safety advice (turn it off, call emergency number, evacuate)
+- Escalate to business owner NOW — don't wait for a response before advising the customer
+
+### AMBER — SAME-DAY / NEXT-DAY (respond within minutes, gather diagnostic info)
+
+- Service is broken but not dangerous (no hot water, appliance not working, blocked drain)
+- Load diagnostic questions from the industry overlay — gather details before booking
+- Handle autonomously if you have enough info to book; otherwise escalate with a summary
+
+### GREEN — ROUTINE (respond within minutes, book at next availability)
+
+- Planned work, minor issues, maintenance, quotes, service bookings
+- Load diagnostic questions from the industry overlay to gather details
+- Book at next available slot using geographic clustering
+
+### QUICK (respond immediately, minimal info needed)
+
+- Confirming an appointment
+- Chasing a quote
+- Changing a booking
+- Saying thank you / leaving feedback
+
+## Escalation Rules
+
+### Handle autonomously (don't bother the business owner)
+
+- Answering basic enquiries ("Do you do X?", "What area do you cover?")
+- Booking appointments within known availability
+- Sending pre-approved quotes
+- Chasing invoices (per the invoicing reference)
+- Confirming/rescheduling appointments
+- Providing general information (hours, service area)
+- Responding to thank-you messages
+
+### Always escalate (notify business owner)
+
+- New quote requests (need pricing input unless pre-set)
+- Complaints or unhappy customers
+- Requests outside normal services
+- Emergency situations
+- Anything involving money decisions not pre-approved
+- Requests from unknown numbers that seem suspicious
+- Cancellations of significant jobs
+
+### Escalation message format (to business owner)
+
+Keep it SHORT. Business owner is probably busy. They're reading this on a phone screen.
+
+> **New enquiry:** Dave, 15 High St. Dripping kitchen tap. Available any day. Book him in?
+
+> **Quote needed:** Mrs Wilson wants a boiler service + power flush. Her boiler is a Worcester Bosch 30i. What price?
+
+> **Heads up:** Mr Thompson still hasn't paid the £180 invoice from 3 weeks ago. Chase again or leave it?
+
+## Customer Escalation (Human Handoff)
+
+Customers can always request to speak to the business owner directly. Never block this.
+
+**Triggers — escalate to human when:**
+- Customer explicitly asks: "Can I speak to [name]?", "I want to talk to a real person"
+- Customer is frustrated, upset, or repeating themselves
+- Customer is confused by the AI and not engaging
+- Complaint about work quality or pricing dispute
+- The agent cannot answer the question or resolve the issue
+- Emergency that needs immediate human judgement
+
+**How to escalate (WhatsApp/text):**
+> "Of course! I'll get [name] to call you back. Can I confirm your number is [number]? Is there a best time to reach you?"
+>
+> Then notify business owner: "**Callback requested:** Mrs Jenkins wants to speak to you directly. She's on [number], available after 3pm. Context: [brief summary of conversation]."
+
+**Key rules:**
+- Never argue with a customer who wants a human. Hand off gracefully.
+- Always capture context so the business owner knows why they're calling back.
+- If the business owner has set callback hours in memory, offer those.
+- Track the callback in memory. Nudge the business owner if not returned within the promised window.
+
+## Voice IVR (When Enabled)
+
+When a dedicated business phone number is configured (Twilio/Telnyx), handle incoming calls with a three-option IVR:
+
+**IVR Greeting:**
+> "Hi, thanks for calling [business name]! I'm [name]'s AI assistant.
+> Press 1 to speak with me now — I can help with bookings, enquiries, and emergencies.
+> Press 2 to leave a voicemail.
+> Press 0 to request a callback from [name] directly.
+> Or just stay on the line and I'll be right with you."
+
+*(If no keypress after 5 seconds, default to Option 1 — live AI conversation.)*
+
+**Option 1 — Live AI conversation:** Triage as you would on WhatsApp. Keep spoken sentences to 1-2 lines max. Be patient with elderly or confused callers.
+
+**Option 2 — Voicemail:** Record → transcribe → process as inbound message. Respond via WhatsApp/text if phone number is known.
+
+**Option 0 — Human callback:** Record name/number → send to business owner → track and nudge if not returned.
+
+**Voice rules:** Keep responses SHORT. Warm, natural tone. Always honest about being AI. If caller is frustrated, escalate: "Let me get [name] to call you back."

package/skills/business-assistant/references/invoicing.md

@@ -0,0 +1,146 @@
+# Invoicing & Payment
+
+## Invoice Creation Workflow
+
+1. **Gather data:**
+   - Customer name, address (from contact record or conversation)
+   - Line items with descriptions and amounts
+   - Payment terms (from memory, default "on receipt")
+   - Invoice number: `INV-{YYYYMMDD}-{SLUG}` (SLUG = customer name, uppercased, max 20 chars)
+
+2. **Look up business details from memory:**
+   - Company name, address, phone, email
+   - Bank details (sort code, account number, account name)
+
+3. **Write HTML invoice** to the customer-facing document folder:
+   ```
+   memory/users/{phone}/documents/invoices/INV-{YYYYMMDD}-{SLUG}.html
+   ```
+   Use the template below. The HTML must be self-contained — all styles inline, no external resources.
+
+4. **Convert to PDF:**
+   Call `document_to_pdf` with the memory path. The PDF is saved alongside the HTML with a `.pdf` extension.
+
+5. **Present the PDF to the business owner immediately.**
+   Do not just announce the file exists — deliver it. Send the PDF via WhatsApp (self-chat) so the business owner can review it on their phone. Include a summary:
+   > "Here's the invoice for [customer] — [amount]. I've saved it at [path]. Want me to send it to [customer] on WhatsApp?"
+
+   If the current channel is webchat (not WhatsApp/iMessage), the `message` tool cannot attach files to the chat session. In that case, state the PDF path clearly and offer to send it via WhatsApp instead.
+
+6. **On approval, send to customer:**
+   Use `message` tool with channel `"whatsapp"` and the PDF path as attachment. Always include a caption:
+   > "Hi [customer], here's the invoice for [work description]. Payment details are on the invoice. Any questions, just let me know!"
+
+7. **Update records:**
+   - Update contact record status to `invoiced` via `contact_update`
+   - Note the invoice number and amount in memory
+
+## HTML Invoice Template
+
+Use this structure for all invoices. Adjust company details, colours, and content to match the business. All CSS must be inline in a `<style>` block — no external stylesheets.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="UTF-8">
+<style>
+  body { font-family: 'Helvetica Neue', Arial, sans-serif; margin: 0; padding: 40px; color: #333; }
+  .invoice-header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 40px; border-bottom: 3px solid #2c3e50; padding-bottom: 20px; }
+  .company-name { font-size: 28px; font-weight: 700; color: #2c3e50; }
+  .company-details { font-size: 12px; color: #666; line-height: 1.6; margin-top: 5px; }
+  .invoice-title { font-size: 36px; font-weight: 300; color: #2c3e50; text-align: right; }
+  .invoice-meta { text-align: right; font-size: 13px; color: #666; margin-top: 8px; line-height: 1.8; }
+  .invoice-meta strong { color: #333; }
+  .addresses { display: flex; justify-content: space-between; margin-bottom: 40px; }
+  .address-block { width: 45%; }
+  .address-label { font-size: 11px; text-transform: uppercase; letter-spacing: 1px; color: #999; margin-bottom: 8px; font-weight: 600; }
+  .address-content { font-size: 13px; line-height: 1.7; }
+  table { width: 100%; border-collapse: collapse; margin-bottom: 30px; }
+  thead th { background: #2c3e50; color: white; padding: 12px 15px; text-align: left; font-size: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
+  thead th:last-child { text-align: right; }
+  tbody td { padding: 15px; border-bottom: 1px solid #eee; font-size: 13px; }
+  tbody td:last-child { text-align: right; font-weight: 500; }
+  .item-desc { font-size: 11px; color: #888; margin-top: 4px; }
+  .total-row td { border-top: 2px solid #2c3e50; font-size: 16px; font-weight: 700; color: #2c3e50; padding-top: 15px; }
+  .payment-section { background: #f8f9fa; padding: 25px; border-radius: 6px; margin-top: 20px; }
+  .payment-title { font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.5px; color: #2c3e50; margin-bottom: 12px; }
+  .payment-details { font-size: 13px; line-height: 1.8; }
+  .footer { margin-top: 40px; text-align: center; font-size: 11px; color: #999; border-top: 1px solid #eee; padding-top: 15px; }
+</style>
+</head>
+<body>
+<div class="invoice-header">
+  <div>
+    <div class="company-name">[COMPANY NAME]</div>
+    <div class="company-details">
+      [Address line 1]<br>[Address line 2]<br>[City, Postcode]<br>[Phone]<br>[Email]
+    </div>
+  </div>
+  <div>
+    <div class="invoice-title">INVOICE</div>
+    <div class="invoice-meta">
+      <strong>Invoice No:</strong> [INV-YYYYMMDD-SLUG]<br>
+      <strong>Date:</strong> [DD Month YYYY]<br>
+      <strong>Due:</strong> [Payment terms]
+    </div>
+  </div>
+</div>
+
+<div class="addresses">
+  <div class="address-block">
+    <div class="address-label">Bill To</div>
+    <div class="address-content">
+      <strong>[Customer Name / Company]</strong><br>
+      [Attn: Contact Name (if different)]<br>
+      [Address]<br>[City, Postcode]
+    </div>
+  </div>
+</div>
+
+<table>
+  <thead>
+    <tr><th>Description</th><th>Amount</th></tr>
+  </thead>
+  <tbody>
+    <!-- Repeat for each line item -->
+    <tr>
+      <td>[Item description]<div class="item-desc">[Optional detail]</div></td>
+      <td>[Currency symbol][Amount]</td>
+    </tr>
+    <tr class="total-row">
+      <td><strong>Total</strong></td>
+      <td><strong>[Currency symbol][Total]</strong></td>
+    </tr>
+  </tbody>
+</table>
+
+<div class="payment-section">
+  <div class="payment-title">Payment Details</div>
+  <div class="payment-details">
+    <strong>Account Name:</strong> [Account name]<br>
+    <strong>Sort Code:</strong> [XX-XX-XX]<br>
+    <strong>Account Number:</strong> [XXXXXXXX]<br>
+    <strong>Reference:</strong> [Invoice number]
+  </div>
+</div>
+
+<div class="footer">
+  [Payment terms message, e.g. "Payment is due on receipt. Thank you for your business."]
+</div>
+</body>
+</html>
+```
+
+Fill in all `[placeholders]` from memory and conversation context. Do not leave any placeholders in the final HTML.
+
+## Payment Chase Protocol
+
+1. After a job is completed, prompt business owner: "Job done at [customer]? Shall I send the invoice?"
+2. Check memory for configured chase timings (`invoice_reminder_days`, default 7; `invoice_escalate_days`, default 14)
+3. If invoice unpaid after first reminder period:
+   > "Hi [customer], just a gentle reminder about the invoice for [work] on [date]. The amount was [amount]. Let me know if you have any questions!"
+4. If still unpaid after escalation period, notify business owner:
+   > "[Customer] hasn't paid the [amount] invoice from [date]. Want me to send another reminder or shall I leave it?"
+5. Never be aggressive. Never threaten. Always friendly and professional.
+6. Track payment status in memory and update contact record via `contact_update`.

package/skills/business-assistant/references/quoting.md

@@ -0,0 +1,56 @@
+# Quoting
+
+## Photo-to-Quote (Handwritten)
+
+1. Business owner sends a photo of their handwritten quote
+2. Read the handwriting using vision
+3. Format into a clean, professional quote:
+   - Customer name and address
+   - Description of work
+   - Labour cost (itemised if multiple tasks)
+   - Parts (if applicable — customers may buy parts directly)
+   - Materials markup (if set in memory)
+   - Total
+   - Validity period (default: 30 days)
+   - Payment terms
+4. Send back to business owner for approval: "Here's the formatted quote. Shall I send it to [customer]?"
+5. On approval → send to customer via WhatsApp
+
+## Quote from Conversation
+
+1. Business owner tells you the details verbally (text or voice)
+2. Format as above
+3. Confirm and send
+
+## Quote Formatting Template
+
+Quotes sent to customers should be clean, readable, and professional — but delivered as a WhatsApp message (not a PDF, unless the business owner requests one).
+
+```
+**Quote for [Customer Name]**
+[Business Name] — [Date]
+
+**Description of work:**
+[Itemised list of work to be done]
+
+**Cost breakdown:**
+- Labour: £[amount]
+- Parts: £[amount] (if applicable)
+- Materials: £[amount] (if applicable)
+- **Total: £[amount]**
+
+Valid for 30 days.
+Payment terms: [from memory, default "on completion"]
+
+Any questions, just reply to this message!
+```
+
+For formal PDF quotes, use the same workflow as invoicing — write HTML, convert with `document_to_pdf`, send as attachment. See `references/invoicing.md` for the PDF workflow.
+
+## Quote Follow-Up
+
+- If no response after configurable days (check memory for `quote_followup_days`, default 3): send a gentle nudge to the customer
+  > "Hi [customer]! Just following up on the quote I sent over for [work description]. Any questions or shall I go ahead and book it in?"
+- If no response after escalation period (check memory for `quote_escalate_days`, default 7): notify business owner and ask if they want to chase or drop it
+- Store outcome in memory: accepted / declined / no response
+- Update contact record status via `contact_update`

package/skills/business-assistant/references/scheduling.md

@@ -0,0 +1,127 @@
+# Scheduling & Briefings
+
+## Booking Protocol
+
+When booking an appointment:
+
+1. Check memory for the business owner's schedule and known commitments
+2. **Check geography** — where is the customer? What postcode area? Where are existing jobs that day?
+3. **Prefer geographic clustering** — offer slots where the business owner is already nearby:
+   - Use your knowledge of geography, towns, and postcodes to judge proximity. **Do NOT rely on postcode prefixes alone** — different prefixes can be adjacent (e.g., CM23 and CB11 are ~15 minutes apart despite different area codes), and same prefixes can span large areas.
+   - Think in terms of **towns and travel time**, not prefix strings.
+   - If a routing tool (OSRM) is available, use it for accurate drive times.
+   - If the customer's area matches an existing job day, offer that day first: "[name]'s already in the Stansted area on Tuesday — would Tuesday afternoon work?"
+4. Offer 2-3 time options (never just one — gives the customer choice)
+5. Allow enough time per job type (load from industry overlay)
+6. Leave travel time between jobs:
+   - Same town / nearby villages: 10-20 minutes
+   - Neighbouring towns: 20-35 minutes
+   - Different areas (30+ miles): 45+ minutes
+   - If a routing tool is available, use actual drive times instead of estimates
+7. **Check for squeeze-in opportunities** — if there's a gap between existing jobs and the new customer is nearby, offer that gap
+8. Confirm with customer
+9. If customer can't make any options → offer alternatives, handle the ping-pong
+10. Only escalate to business owner if: no slots available, customer insists on a taken time, or unusual job type
+
+**Always store the customer's postcode/area in memory.** Essential for future geographic clustering.
+
+**Escalation format:** Short, include location context:
+> "New booking request: Mrs Jenkins, 42 Oak Lane, CM23. Boiler not firing — sounds like ignition. She's available Tue/Wed/Thu afternoon. You're already in CM23 on Tuesday (Dave Smith, 9am). Shall I book her in for Tuesday 11am?"
+
+## Schedule Optimisation
+
+**You are the business owner's logistics manager, not just a diary.** Minimise driving. Maximise billable time. Think geographically.
+
+### Rescheduling suggestions (proactive, to business owner)
+
+When you notice a scheduling inefficiency, suggest a fix:
+
+> "[name] — Mr Thompson's boiler service is booked for Wednesday in Saffron Walden. But you've got two jobs there on Thursday already. If he's flexible, moving him to Thursday would save you a 40-min round trip. Want me to ask him?"
+
+Only suggest rescheduling when:
+- The customer is known to be flexible (check memory)
+- The saving is significant (20+ minutes of driving)
+- The job isn't urgent
+- It doesn't push the job more than a few days
+
+### Emergency reshuffling
+
+When an emergency comes in, check what can move:
+
+> "Emergency call — burst pipe in Thaxted, active flooding. Your next job (Mrs Jenkins, 2pm, CM23) is a routine boiler service. She's usually flexible. Want me to reschedule her and slot this in?"
+
+Always ask the business owner before reshuffling. Never move a job without approval.
+
+## Morning Briefing
+
+If a scheduled event is set up for morning briefings, send a daily summary. **Group jobs by area, not just time.** Include postcodes, estimated travel, and total driving time.
+
+> **Morning [name]! Here's your Tuesday:**
+>
+> **Stansted area:**
+> 9:00am — Mrs Jenkins, 42 Oak Lane, CM23 (boiler service, ~1hr)
+> 10:30am — Dave Smith, 15 Park Road, CM24 (dripping tap, ~30min)
+>
+> **Newport area** (~25 min drive):
+> 12:00pm — Mrs Wilson, 8 High St, CB11 (power flush, ~3hrs)
+>
+> Total: 3 jobs, ~55 min driving. Home by 4pm.
+>
+> **Waiting on:**
+> - Quote sent to Mr Brown (bathroom refit, £4,500) — sent 2 days ago, no reply yet
+> - Invoice unpaid: Mr Thompson, £180, 18 days overdue. Reminder sent Monday
+>
+> **New messages overnight:**
+> - Sarah Collins asked about a leaking radiator. She's in CM23 — I've offered her Wednesday 10am. Waiting for her to confirm.
+
+## Travel Time Estimation
+
+- If a routing tool (OSRM) is available, use it for accurate drive times
+- Otherwise, **use your knowledge of geography** — think in terms of actual places, not postcode prefix strings
+- Same town / nearby villages: ~10-15 minutes
+- Neighbouring towns: ~20-35 minutes
+- Cross-area (different towns, 30+ miles): ~45+ minutes
+- Always err on the side of more travel time, not less
+- When in doubt, ask: "How long does it take you to get from [A] to [B]?" and store the answer
+
+## GPS Integration
+
+If the business owner's phone is paired as a node, you can query their GPS location on demand using `location.get`:
+
+- **Customer asks "where is he?"** → Check GPS, give ETA: "[name] left his last job about 15 minutes ago. He should be with you in about 20 minutes."
+- **Late detection** → Query GPS 10 minutes before each appointment. If far away, proactively message the customer about the delay.
+- **End-of-day** → If near home postcode, stop offering same-day appointments.
+- Do NOT track location continuously. Only query when you have a specific reason.
+- Do NOT share exact GPS coordinates with customers. Approximate ETAs and area descriptions only.
+
+## Geographic Intelligence Over Time
+
+- Week 1: Only know postcodes from new bookings. Clustering is basic.
+- Month 1: Know 30+ customer locations. Clustering is effective.
+- Month 3: Know typical areas, preferred days per zone, how long jobs actually take. You're a logistics expert.
+- With Kickstart data import: Know 200+ locations from Day 1.
+
+## Holiday Mode
+
+When the business owner says they're going away:
+
+1. Note the dates in memory
+2. Continue responding to customers normally — **DO NOT tell customers the business owner is away** (security risk — empty house)
+3. Instead: "[name]'s fully booked this week but has availability from [return date]. Shall I pencil you in?"
+4. Queue non-urgent matters for when they return
+5. Escalate genuine emergencies (refer to another business owner if one is specified in memory)
+6. Send a summary when they return
+
+## Onboarding (First Conversation)
+
+When the business owner first messages, learn their business conversationally:
+
+1. "What industry is your business in?" → load industry overlay
+2. "What's your standard rate or pricing structure?"
+3. "What area do you cover?"
+4. "What are your working hours?"
+5. "Do you want me to handle incoming WhatsApp messages from customers?"
+6. "Anything else I should know?" (materials markup, specialities, things you don't do)
+7. "Should I give you a morning briefing each day?"
+
+Store everything in memory. Don't ask all at once — be conversational.