@rubytech/taskmaster 1.13.4 → 1.14.2

package/skills/sales-closer/references/objection-handling.md

@@ -0,0 +1,101 @@
+# Objection Handling
+
+## Pivots vs Objections
+
+The most important distinction in closing: is the prospect **pivoting** (changing topic to avoid commitment) or **objecting** (raising a genuine concern that needs resolving)?
+
+**Pivots** look like:
+- Asking a tangential technical question right after a close attempt
+- Changing the subject entirely: "By the way, can it also do X?"
+- Asking about features that were not previously discussed
+- "That's interesting, what about...?"
+
+**Objections** look like:
+- Expressing a specific concern: "I'm worried about the cost"
+- Raising a blocker: "I need to check with my business partner first"
+- Questioning capability directly: "Can it actually handle our volume?"
+- Asking for evidence: "Do you have any case studies?"
+
+**The rule:** Handle pivots with acknowledge-then-anchor. Handle objections with empathy, resolution, then close.
+
+## Acknowledge-Then-Anchor (for Pivots)
+
+The pattern:
+
+1. **Acknowledge** — Show you heard the question. Do not dismiss it.
+2. **Brief answer** — 1-2 sentences maximum. Enough to satisfy curiosity, not enough to derail.
+3. **Re-anchor** — Return to the commitment ask. Use the same close technique or a different one.
+
+The key is that the brief answer is *genuine* — you are not dodging the question, you are prioritising the close while still being helpful.
+
+If the prospect asks the same question again after the re-anchor, treat it as an objection and give a full answer. A repeated question is no longer a pivot — the prospect genuinely needs the answer.
+
+## Common Objection Patterns
+
+### Price: "I need to think about it" / "That's more than I expected"
+
+This is usually about value, not money. The prospect is not sure the product is worth the price.
+
+1. Acknowledge the concern without defensiveness
+2. Restate the specific value that matches their stated needs (not generic features)
+3. If pricing authority exists, offer alternatives (different tier, trial period)
+4. If no pricing authority, hand off to the business owner: "Totally fair — let me get Joel to walk you through the options. He can find the right fit for your budget."
+
+Never discount without owner authorisation. Never make the prospect feel bad for asking about price.
+
+### Timing: "Not right now" / "Maybe next month"
+
+Respect the timing. Do not push against an explicit deferral.
+
+1. Acknowledge: "No problem at all"
+2. Set a concrete follow-up: "Shall I check back in with you on [specific date]?"
+3. Save the deferral to memory with the agreed follow-up date
+4. When the follow-up date arrives, use the Return Close — they were interested, just not ready
+
+### Capability: "Can it do X?" / "What about Y integration?"
+
+If this comes mid-close, it is likely a pivot. If it comes before any close attempt, it is genuine discovery.
+
+**Mid-close (pivot):**
+> "Good question — [brief honest answer]. We can go deeper on that once you're set up. Shall we get you started?"
+
+**Pre-close (genuine):**
+Answer fully. This is discovery, not closing. The prospect needs to understand the product before they can commit. Do not try to close during discovery.
+
+### Authority: "I need to check with my partner/team"
+
+This is a legitimate blocker — the prospect cannot commit alone.
+
+1. Respect it: "Of course — makes sense to discuss together"
+2. Make it easy: "Want me to put together a quick summary you can share with them?"
+3. Set a follow-up: "When do you think you'll have had a chance to chat? I can check back in"
+4. Save to memory: who the decision-maker is, when the follow-up should happen
+
+### Competition: "I'm also looking at [competitor]"
+
+1. Never disparage the competitor
+2. Ask what matters most to them — let them tell you what to sell
+3. Position on genuine differentiators, not feature lists
+4. If unsure of differentiators, hand off to the business owner
+
+### Trust: "How do I know it actually works?"
+
+1. Offer a trial or demo — the product selling itself is the strongest close
+2. Reference other customers if the business owner has shared testimonials (check memory)
+3. Offer to show a specific example relevant to their use case
+4. If no social proof exists, be honest: "We're a young product — the best way to see is to try it. That's why we offer [trial/guarantee]"
+
+## Escalation to Business Owner
+
+Some objections require the human. Escalate when:
+
+- The prospect wants to negotiate pricing or terms
+- The prospect wants a personal guarantee or commitment the agent cannot make
+- The prospect raises a concern the agent cannot resolve from memory or product knowledge
+- The objection has been addressed but the prospect is still not moving forward after 3 attempts
+
+When escalating, provide the business owner with context:
+- What the prospect needs
+- What objection was raised
+- What has already been tried
+- A recommended next step

package/templates/beagle-zanzibar/agents/admin/AGENTS.md

@@ -17,17 +17,54 @@ Before doing anything else:
 
 | Tool | Use |
 |------|-----|
-| `memory_search` | Find bookings, driver records, knowledge base content, operator notes |
-| `memory_get` | Read specific files (knowledge base, driver profiles) |
-| `memory_write` | Update knowledge base, store driver notes, flag follow-ups |
+| `memory_search` | Find bookings, driver state profiles, knowledge base content, operator notes |
+| `memory_get` | Read specific files (knowledge base, driver state profiles) |
+| `memory_write` | Update knowledge base, store driver state notes, flag follow-ups |
+| `contact_create` | Register a new driver in the contact roster |
+| `contact_lookup` | Find drivers or look up a specific driver's profile |
+| `contact_update` | Update a driver's static profile (vehicle type, plate, AC) |
+| `contact_delete` | Remove a driver from the roster |
 | `sessions_list` | Review recent tourist conversations the public agent has had |
 | `sessions_history` | Read specific past sessions for booking context |
 | `current_time` | Timestamps for notes, booking reviews, and follow-up scheduling |
 
+## Driver Data Model
+
+Driver data lives in two stores:
+
+| Store | Fields | Who writes |
+|-------|--------|------------|
+| Contact record | `name`, `phone`, `vehicle_type`, `vehicle_plate`, `ac`, `driver: true` | Admin only |
+| Memory (`drivers/{name}.md`) | `status`, `current_booking`, ratings, `trips_completed`, `response_rate`, `substitutions` | Public agent during operations |
+
+When adding a new driver, create both: a contact record via `contact_create` and an initial memory profile via `memory_write` at `drivers/{firstname-lastname}.md`:
+
+```
+# Driver: [Name]
+status: idle
+current_booking: null
+last_active: [timestamp]
+
+## Ratings
+rating_cleanliness: -
+rating_politeness: -
+rating_safety: -
+rating_knowledge: -
+rating_punctuality: -
+trips_completed: 0
+response_rate: 0
+
+## Route History
+(builds from booking data)
+
+## Substitution Record
+(none)
+```
+
 ## Operational Focus Areas
 
 ### Bookings
-- Booking records live at `bookings/{job-id}.md` in memory. Each tracks: route, fare, driver, status, timestamps, and ratings.
+- Booking records live at `bookings/{job-id}.md` in memory. Each tracks: route, fare, driver, status, timestamps, ratings, and any substitution flag.
 - Summarise recent booking activity: confirmed, completed, cancelled, no-shows
 - Flag bookings where the driver didn't show or the tourist complained
 - Track conversion patterns: how many enquiries become bookings
@@ -39,6 +76,15 @@ Before doing anything else:
 - Track driver state: who is available, who is mid-negotiation, who is booked
 - Recommend deprioritising unreliable drivers
 
+### Driver Substitution Follow-up
+
+When a substitution is flagged in a booking record:
+1. Identify the booked driver from the booking record
+2. Message the driver via WhatsApp: `[BGL-XXXX] We received feedback that a different driver completed this pickup. Can you explain what happened? Unannounced substitutions affect your standing with Beagle.`
+3. Record the driver's response (or non-response after 24 hours) in their memory profile under `Substitution Record`
+4. A single incident with a reasonable explanation (illness, emergency) is noted but not penalised
+5. No response, or a pattern of two or more incidents, escalates to the operator for a decision on deprioritisation
+
 ### Knowledge Base
 - Verify fare ranges against actual booking data — update when they drift
 - Update seasonal information (road conditions, high/low season patterns)
@@ -62,3 +108,9 @@ Before doing anything else:
 - Surface issues early — don't wait for the operator to discover problems
 - Back up observations with data (booking counts, rating averages, response rates)
 - Distinguish between one-off incidents and patterns
+
+---
+
+## Spotting Repeatable Patterns
+
+When you find yourself repeatedly handling the same type of request — following the same steps, giving the same guidance, or applying the same rules — note the pattern in memory for review. Repeated patterns are candidates for skills, which encode a process so it's followed consistently without relying on memory or re-explanation.

package/templates/beagle-zanzibar/agents/admin/BOOTSTRAP.md

@@ -36,26 +36,49 @@ If anything needs updating, edit `memory/public/knowledge-base.md` directly. Use
 
 Explain that drivers need to be registered before the service can take bookings. For each driver, collect:
 
-- Name and WhatsApp number
+- Name and WhatsApp number (international format, e.g. +255712345678)
 - Vehicle type and plate number
-- Areas they cover (e.g., airport, north coast, east coast)
+- Does the vehicle have AC?
 
-Store each driver as a structured record in memory at `drivers/{first-name-lastname}.md`. Use this format:
+Note: you don't need to declare which routes a driver covers — the service learns route affinity over time from booking outcomes.
+
+Register each driver with two steps:
+
+**1. Contact record** — via `contact_create`:
+- `name`: driver's full name
+- `phone`: WhatsApp number
+- `vehicle_type`: e.g. "Toyota Hiace"
+- `vehicle_plate`: e.g. "T 123 ABC"
+- `ac`: true or false
+- `driver: true`
+
+**2. Memory profile** — via `memory_write` at `drivers/{firstname-lastname}.md`:
 
 ```
 # Driver: [Name]
-- WhatsApp: [number]
-- Vehicle: [type, year if known]
-- Plate: [plate number]
-- Routes: [areas covered]
-- Rating: not yet rated
-- Status: idle
-- Response rate: n/a (new)
+status: idle
+current_booking: null
+last_active: [timestamp]
+
+## Ratings
+rating_cleanliness: -
+rating_politeness: -
+rating_safety: -
+rating_knowledge: -
+rating_punctuality: -
+trips_completed: 0
+response_rate: 0
+
+## Route History
+(builds from booking data)
+
+## Substitution Record
+(none)
 ```
 
 Ask: **"Can you share the names and WhatsApp numbers for your initial driver pool? Even 3–5 drivers is enough to start."**
 
-If they'd prefer to add drivers later via conversation, note that they can tell you "Add driver: [name], [number], [vehicle]" at any time.
+If they'd prefer to add drivers later via conversation, they can say "Add driver: [name], [number], [vehicle], AC yes/no" at any time.
 
 ---
 

package/templates/beagle-zanzibar/agents/admin/HEARTBEAT.md

@@ -7,6 +7,7 @@ Check these periodically:
 - [ ] Any driver ratings below 3.5 average that need review?
 - [ ] Any tourist complaints or negative feedback in the last 24 hours?
 - [ ] Any knowledge base entries flagged as outdated or disputed?
+- [ ] Any unresolved driver substitution incidents in the last 7 days?
 - [ ] Anything the operator should know about?
 
 If nothing needs attention, reply HEARTBEAT_OK.

package/templates/beagle-zanzibar/agents/public/AGENTS.md

@@ -8,7 +8,20 @@ Before responding:
 1. Read `SOUL.md` — your personality and principles
 2. Read `IDENTITY.md` — what you are
 3. Check conversation history for any active bookings or prior context
-4. Load the zanzi-taxi skill for ride-matching behaviour
+4. Load the beagle-zanzibar skill for ride-matching behaviour
+
+---
+
+## Tools
+
+| Tool | Use |
+|------|-----|
+| `contact_lookup` | Look up the driver roster (filter `driver: true`) and individual driver profiles |
+| `memory_search` | Find bookings, knowledge base content, driver operational state |
+| `memory_get` | Read specific files (driver state, bookings, knowledge base) |
+| `memory_write` | Record bookings, update driver operational state, store tourist preferences |
+| `message` | Send WhatsApp messages and images to drivers (use for negotiation, reminders, QR code) |
+| `current_time` | Timestamps for booking records and reminder scheduling |
 
 ---
 
@@ -34,7 +47,7 @@ When a tourist requests a ride:
 8. **Record the booking** — write a structured record to `bookings/{job-id}.md` on confirmation. Update at each lifecycle event (reminder, pickup, completion, rating).
 9. **Follow up** — after the estimated journey completion time, prompt for feedback and collect ratings.
 
-See the zanzi-taxi skill references for detailed behaviour at each phase.
+See the beagle-zanzibar skill references for detailed behaviour at each phase.
 
 ---
 

package/templates/beagle-zanzibar/memory/public/knowledge-base.md

@@ -154,3 +154,16 @@ Yes. Early morning flights, late arrivals — message us anytime.
 
 **What about luggage?**
 Tell us how many passengers and how much luggage when you request a ride. We'll match you with an appropriate vehicle.
+
+---
+
+## Terms of Service
+
+Full terms are in `memory/public/terms.md`. Key points for tourists who ask:
+
+- Beagle is a message relay service — we connect you to an independent driver, we don't operate the vehicle
+- The ride is a direct arrangement between you and the driver
+- Your driver's phone number is shared after you pay the booking fee — you can communicate directly
+- The booking fee is non-refundable
+- You pay the fare directly to the driver at the end of the journey
+- Full terms: beagle.cab/terms

package/templates/beagle-zanzibar/memory/public/terms.md

@@ -0,0 +1,81 @@
+# Beagle — Terms of Service
+
+**Last updated: 2025**
+
+These terms apply to the Beagle ride-matching service operating in Zanzibar (zanzibar.beagle.taxi / beagle.cab / beagle.taxi).
+
+---
+
+## 1. What Beagle Is
+
+Beagle is a **message relay and matching service**. We use WhatsApp to connect tourists with independent, self-employed local drivers. We facilitate the introduction, negotiate fares on your behalf, and handle booking confirmation.
+
+We are not a transport operator. We do not own or operate vehicles. We do not employ drivers.
+
+---
+
+## 2. Your Ride Contract
+
+The transport agreement — including the fare, the journey, and all obligations around it — is **entirely between you (the passenger) and the driver**. Beagle is not a party to that contract.
+
+Your ride is the same as if you had found the driver directly. Beagle simply made the introduction and negotiated the fare.
+
+---
+
+## 3. Driver Contact Details
+
+Once your booking fee is confirmed, Beagle shares the driver's name, phone number, vehicle details, and plate number with you. **You can communicate with your driver directly from that point.** The driver also has your name and pickup details.
+
+The driver's WhatsApp number is yours to keep. You can contact them directly about the ride, delays, or anything related to your journey.
+
+---
+
+## 4. Booking Fee
+
+The booking fee (5% of the agreed fare, minimum $2, maximum $5) is:
+
+- Charged at booking confirmation via Stripe
+- **Non-refundable** — it is a commitment device that confirms to the driver the booking is real
+- Separate from the fare — you pay the driver directly at the end of the journey
+- Beagle's service fee for the matching, negotiation, and coordination
+
+---
+
+## 5. Beagle's Limitations
+
+Beagle is not responsible for:
+
+- The conduct of drivers during the journey
+- Accidents, delays, vehicle condition, or any incident that occurs during the ride
+- Disputes between passenger and driver about fare, service quality, or any other matter
+- Events beyond our control (road closures, weather, mechanical failure)
+
+We maintain a driver rating system and track reliability, and we remove drivers who repeatedly fall short. But the ride itself is your arrangement with the driver.
+
+---
+
+## 6. How to Raise a Problem
+
+If something goes wrong with a booking — driver no-show, substitution, conduct issue — message Beagle on WhatsApp. We will:
+
+- Follow up with the driver
+- Record the incident
+- Take action on drivers who have a pattern of problems (deprioritisation or removal)
+
+We cannot issue refunds on the booking fee, but we will help find you an alternative driver and will escalate persistent driver issues.
+
+---
+
+## 7. Governing Law
+
+Beagle is a UK-registered company. These terms are governed by the laws of England and Wales. Any disputes not resolved through direct negotiation are subject to the exclusive jurisdiction of the courts of England and Wales.
+
+---
+
+## Summary (for tourists who ask)
+
+- Beagle connects you to a local driver — we don't drive you ourselves
+- Your ride is a direct arrangement between you and the driver
+- We share the driver's phone number with you after you pay the booking fee — you can talk to them directly
+- The booking fee covers our service and is non-refundable
+- The fare is paid directly to the driver at the end of the journey

package/templates/beagle-zanzibar/skills/beagle-zanzibar/SKILL.md

@@ -29,9 +29,13 @@ This skill applies whenever a tourist:
 | Ride matching | Tourist requests a ride or asks about booking | `references/ride-matching.md` |
 | Local knowledge | Tourist asks about routes, destinations, or Zanzibar tips | `references/local-knowledge.md` |
 | Post-ride | Journey complete, time to collect feedback | `references/post-ride.md` |
+| Route learning | Selecting drivers with route history for a specific run | `references/route-learning.md` |
+| Stripe payment | Generating booking fee payment links | `stripe` skill |
+| PIN and QR code | Generating the pickup PIN and driver QR code at Phase 5 | `references/pin-qr.md` |
 
 ## Key Rules
 
+- **Driver roster is in contacts.** Use `contact_lookup` with `driver: true` to list registered drivers. Operational state (status, ratings, history) lives in memory at `drivers/{name}.md`.
 - **One negotiation per driver at a time.** Never contact a driver with a pending or active negotiation for another booking.
 - **Driver details after payment only.** Name, phone, vehicle — all gated by confirmed Stripe payment.
 - **Job ID on every driver message.** Prepend `[BGL-XXXX]` to every message sent to a driver.

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/pin-qr.md

@@ -0,0 +1,52 @@
+# PIN and QR Code — Pickup Verification
+
+## Overview
+
+Each confirmed booking gets a unique 4-digit pickup PIN. The tourist holds the PIN. The driver receives a QR code image that encodes it. At pickup, the tourist scans the QR code or asks the driver to read the PIN aloud — both parties should see the same number.
+
+## Generating the PIN
+
+Pick a random 4-digit integer between 1000 and 9999. No uniqueness check against other bookings is required.
+
+Store the PIN in the booking record immediately at `bookings/{job-id}.md`:
+
+```
+pin: 4827
+```
+
+## Generating the QR Code Image
+
+Construct the QR image URL from the PIN:
+
+```
+https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+```
+
+Example — PIN 4827:
+`https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=4827`
+
+This URL returns a PNG image of the QR code. No separate API call is needed to generate it.
+
+## Sending to the Driver
+
+Use the `message` tool to send the QR code as an inline WhatsApp image:
+
+```
+action: send
+channel: whatsapp
+target: {driver_phone_number}
+media: https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+caption: [BGL-XXXX] Your passenger's verification code. Show this QR code at pickup — your passenger will scan it to confirm you're the right driver.
+```
+
+The driver opens WhatsApp, sees the QR code image inline, and shows their phone screen to the tourist at pickup.
+
+## Sending to the Tourist
+
+Send the PIN with an explanation alongside the other driver details (in the main conversation):
+
+> "Your driver verification PIN is **{pin}**. When your driver arrives, ask them to show their QR code — scan it with your phone camera and it should display your PIN. Or ask the driver to read the number aloud. If it matches, you've got the right driver. Works offline — no internet needed."
+
+## Timing
+
+Generate the PIN immediately after payment is confirmed (Phase 4). Send both as part of Phase 5 — QR image to driver and PIN to tourist — before setting up any pickup reminders.

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/post-ride.md

@@ -37,6 +37,19 @@ If the tourist reports a serious issue (safety concern, fare dispute, driver mis
 - Don't promise specific outcomes ("we'll remove the driver") — explain that the operator reviews all feedback
 - Offer to help with their next ride if they need one
 
+## Substitution Check
+
+When checking in with the tourist, naturally ask whether the booked driver completed the ride: "Was it [driver name] who picked you up?" Keep it casual — this is a service quality question, not an accusation.
+
+**If yes:** proceed with ratings as normal.
+
+**If no, or if the tourist names a different person:**
+- Do not alarm the tourist or make promises about consequences
+- Record a substitution flag in the booking record at `bookings/{job-id}.md`
+- Add an entry to the driver's memory profile (`drivers/{name}.md`) under `Substitution Record`:
+  `[date]: Substitute reported for [job-id] — tourist named [substitute name if given]`
+- The admin agent handles follow-up with the booked driver operationally
+
 ## Timing
 
 Don't follow up too quickly (they might still be at their destination) or too late (they've moved on). A reasonable window is 30–60 minutes after estimated arrival.

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/ride-matching.md

@@ -18,9 +18,11 @@ Check the knowledge base to confirm you know the route. If the route isn't cover
 ## Phase 2: Driver Negotiation
 
 Before contacting drivers:
-- Check driver states — only contact drivers marked as `idle`
-- Select ~3 drivers based on: rating, response rate, route familiarity, availability
+- Use `contact_lookup` with `driver: true` to get the full driver roster
+- Check `drivers/{name}.md` in memory for each driver's current `status` — only contact drivers marked as `idle`
+- Prefer drivers whose route history shows strong performance on this specific route — see `references/route-learning.md`
 - Prepend every message with the job ID: `[BGL-XXXX]`
+- Set each contacted driver's status to `awaiting_response` in their memory profile before sending
 
 Negotiate in Swahili. The driver quotes their fare for the route. Collect responses and compare.
 
@@ -46,24 +48,28 @@ If only one driver responded, present it honestly: "One driver available for thi
 
 When the tourist chooses an offer:
 1. Confirm the details: route, time, fare, vehicle
-2. Explain the booking fee: "A small booking fee of [amount] confirms your ride. You pay [remaining fare] directly to your driver at the end."
-3. Send the Stripe payment link
-4. Wait for payment confirmation — do not proceed until Stripe confirms
+2. Explain the booking fee and terms in one message: "A small booking fee of [amount] confirms your ride. You pay $[fare] directly to your driver at the end. Beagle is a matching service — the ride is between you and the driver directly. By paying, you accept our terms: beagle.cab/terms"
+3. Load the `stripe` skill — follow `stripe/references/payment-links.md` to calculate the fee and generate a Checkout Session link
+4. Send the payment link to the tourist
+5. When the tourist says they've paid, verify the session status via the Stripe API — do not proceed to Phase 5 until payment is confirmed
 
 ## Phase 5: Post-Payment
 
-Once payment clears, send the tourist:
-- Driver name
-- Driver phone number
-- Vehicle description and plate number
-- Pickup PIN (4-digit code)
-- Explanation: "Your driver has a QR code. Scan it with your phone camera to see the PIN, or ask the driver to quote it. If it matches your PIN, you've got the right driver. Works offline — no internet needed."
-
-Confirm the driver has received:
-- Passenger name
-- Pickup time and location
-- Fare confirmed
-- QR code (encodes the tourist's PIN)
+Once payment clears:
+
+1. **Generate the pickup PIN and QR code** — load `references/pin-qr.md` and follow the instructions there to generate the PIN and construct the driver's QR code URL.
+
+2. **Send the tourist:**
+   - Driver name
+   - Driver phone number
+   - Vehicle description and plate number
+   - Pickup PIN with verification explanation (see `references/pin-qr.md`)
+
+3. **Send the driver:**
+   - Passenger name
+   - Pickup time and location
+   - Fare confirmed
+   - QR code URL (encodes the tourist's PIN — see `references/pin-qr.md`)
 
 ## Phase 6: Driver Pickup Reminders
 

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/route-learning.md

@@ -0,0 +1,61 @@
+# Route Learning — Building Driver Route Affinity
+
+## What This Is
+
+Route affinity is the service's accumulated understanding of which drivers tend to perform best on which routes. It is not declared upfront — it emerges from booking outcomes and ratings over time. A driver who consistently earns strong ratings on airport-to-north-coast runs becomes a stronger candidate for that route in future negotiations. A driver with a poor completion record on east coast routes gets deprioritised for those bookings, even if they quote competitively.
+
+## Where the Data Lives
+
+Booking records in memory (`bookings/{job-id}.md`) contain the raw data:
+- The route (pickup → destination)
+- Which driver completed the ride
+- The rating received
+- Whether the booking completed or was cancelled/no-show
+
+Driver memory profiles (`drivers/{name}.md`) contain the aggregated view. The Route History section builds as bookings complete:
+
+```
+## Route History
+- 2026-02-14: Airport → Nungwi | BGL-0018 | Rating: 4.6
+- 2026-02-28: Airport → Stone Town | BGL-0031 | Rating: 4.1
+- 2026-03-01: Stone Town → Paje | BGL-0037 | Rating: 4.8
+```
+
+## How Affinity is Used During Driver Selection (Phase 2)
+
+When selecting ~3 drivers to contact for a negotiation, prefer drivers whose history shows:
+- Completed rides on this specific route (or similar routes in the same area)
+- Consistent ratings above 4.0 on those runs
+
+New drivers (no history) are treated neutrally — they need the opportunity to build a record. Never exclude a driver solely for lacking route history.
+
+Do not apply affinity rigidly. A great driver with no history on a route is still a viable choice. Route history is a signal that improves selection over time, not a gatekeeping rule.
+
+## How the Public Agent Maintains Route History
+
+After each completed booking, the public agent adds a route entry to the driver's memory profile:
+
+```
+- [date]: [Pickup] → [Destination] | [job-id] | Rating: [score]
+```
+
+If the ride was cancelled, a no-show, or ended in a complaint, note it:
+
+```
+- [date]: Airport → Nungwi | BGL-0052 | No-show
+```
+
+These entries are the raw material the admin agent uses to identify patterns.
+
+## Admin Agent: Periodic Route Analysis
+
+The admin agent should periodically review route history across the driver roster and surface meaningful patterns to the operator:
+
+- Drivers consistently rated above 4.5 on a specific route — flag as strong matches worth prioritising
+- Drivers consistently rated below 3.5 on a specific route — recommend exclusion from that route
+- Routes where no driver achieves strong ratings — flag as a coverage or quality gap worth investigating
+- Drivers whose ratings vary sharply by route — worth noting (excellent on airport runs, poor on east coast, for example)
+
+## Limits
+
+Patterns need volume to be meaningful. A driver with two rides on a route does not have a pattern — they have a sample. Apply judgement: five or more completed rides on a route with consistent ratings is a reliable signal. Fewer than that warrants patience rather than conclusions.

package/templates/beagle-zanzibar/skills/stripe/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: stripe
+description: "Generates Stripe Checkout Session payment links for Beagle booking fees, and verifies payment status before releasing driver details."
+metadata: {"taskmaster":{"always":false,"emoji":"💳","skillKey":"stripe"}}
+---
+
+# Stripe — Payment Links
+
+## Your Role
+
+Generate a Stripe Checkout Session link for each confirmed booking and verify payment before releasing driver details to the tourist.
+
+## When to Activate
+
+Load this skill when the tourist has chosen an offer and the booking is ready to confirm (Phase 4 of the ride-matching flow).
+
+## Reference Table
+
+| Task | When | Reference |
+|------|------|-----------|
+| Create payment link | Tourist confirms offer, booking fee needs collecting | `references/payment-links.md` |
+
+## Key Rules
+
+- **Never release driver details before payment is confirmed.** Always verify the Stripe session status before proceeding to Phase 5.
+- **Minimum fee is $2, maximum is $5.** Calculate as 5% of the agreed fare, clamped to this range.
+- **Each booking gets its own Checkout Session.** Never reuse a payment link between bookings.
+- **Test mode is fine to start.** Use `sk_test_...` keys during setup. Switch to live keys when real bookings begin.