@rubytech/create-maxy-code 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/premium-plugins/real-agency/specs/00-architecture-and-customization.md

@@ -0,0 +1,122 @@
+# 00 — Architecture & Customization Profile
+
+**Product:** Real Agent (sales)
+**Surface:** Claude native UI, Pi 5 on-premise
+**Scope:** Shared foundation for the five workflow specs in this folder
+
+---
+
+## 1. Surface assumptions
+
+- Operator talks to Claude in plain English. There is no custom UI and no first-class slash commands.
+- Workflow invocation is by **intent recognition** from natural language. A lightweight router skill matches phrasing to the right workflow.
+- All output is rendered in Claude's native UI — markdown, tables, and the standard composer/approval affordances. No bespoke front-end work.
+- The Pi 5 holds the customization profile, the CRM mirror, vendor-research cache, and audit log. Compute headroom on the Pi is sufficient for every workflow in this set, including comparable analysis.
+
+## 2. Three-layer composition
+
+```
+Plain-English request
+        │
+        ▼
+Intent router (recognises the workflow)
+        │
+        ▼
+Master workflow (one of five named jobs)
+        │
+        ▼
+Building-block skills (auto-activated, never named to the operator)
+        │
+        ▼
+Connectors (CRM, portals, accounting, e-sign, comms)
+```
+
+The operator never picks a skill, never picks a connector, and never invokes a slash command. They describe what they need; the router finds the workflow; the workflow composes the skills; the skills read and write through the connectors.
+
+## 3. Approval gating
+
+Every write action — message send, document e-sign, payment instruction, listing publication — pauses for explicit operator approval before it fires. The pause is presented as a chat-native prompt ("send these three reminders?" with yes/edit/skip per item). No write action ever runs unattended.
+
+Read actions do not pause. The morning round produces a snapshot without asking permission to look.
+
+## 4. The customization profile (continuously learning)
+
+The profile is a structured document on the Pi that every workflow reads before producing output. It starts seeded from a five-minute onboarding conversation and updates from every operator correction thereafter. The operator never opens a settings page.
+
+### 4.1 What the profile holds
+
+- **Agency:** brand, patch (postcodes), office or solo, fee structure, withdrawal-fee policy
+- **Stack:** CRM, accounting, portals, e-sign provider, preferred photographer / EPC / floorplan suppliers
+- **Voice samples:** three to five emails the agent has written, used for tone extraction
+- **Defaults that get learned:** comparable radius, "stalled" threshold per stakeholder type, formal-vs-casual tone per recipient type, USP phrasing, talk-track preferences, urgency thresholds, what to lead with in the morning brief, vendor-research privacy line
+- **Suppliers and contacts:** who the agent uses for what, with usage frequency
+
+### 4.2 How learning happens
+
+Four channels feed the profile, in order of weight:
+
+1. **Direct correction.** Operator says "I chase solicitors at 5 days, not 7" → the threshold is updated immediately and the change is acknowledged. The next workflow run uses the new value.
+2. **Edit-before-send.** When the operator edits a drafted message before approving, the diff between draft and sent is recorded. If the same edit pattern recurs three times (e.g. they always remove the closing phrase, always add a specific call-to-action), the drafter learns it.
+3. **Skip and override.** When the operator dismisses a flagged item ("don't chase Mrs Patel, I spoke to her yesterday") or overrides a priority ranking, the signal is stored against that recipient or item type.
+4. **Outcome correlation.** Where outcomes are observable (offer accepted, deal completed, viewing booked), the profile retrospectively reweights what preceded them. Lower weight than the first three because the signal is noisier and slower.
+
+### 4.3 Update mechanics
+
+- Updates are written through a single `profile-writer` skill so all changes are audited.
+- Every change is reversible. "Forget that I said to chase at 5 days" rolls back the most recent update.
+- The profile is shown on request. "What have you learned about me this month" produces a readable diff.
+- High-impact changes (fee structure, supplier list, tone profile) ask for confirmation before saving. Low-impact changes (cadence tweaks, priority weights) save silently and surface in the next monthly summary.
+
+### 4.4 Cold-start vs. mature behaviour
+
+- **Week one:** the profile is mostly defaults. Outputs are recognisable but generic. The agent is correcting frequently. This is expected and is the calibration period.
+- **Month three:** the profile is dense enough that outputs feel personal. Corrections drop to once or twice a week. New patterns get learned without being prompted.
+- **Year one:** the profile is the agent's working style, encoded. A new staff member could use it as a training document.
+
+## 5. Workflow inventory (sales only)
+
+| # | Workflow | Cadence | Primary value |
+|---|---|---|---|
+| 01 | Morning Round | Daily | Trust-building daily touch; read-only |
+| 02 | Valuation Prep | Per appointment | High per-use value; wins instructions |
+| 03 | New Instruction | Per win | Compresses a half-day of onboarding to fifteen minutes |
+| 04 | Chase Progression | Daily + on-demand | Headline workflow; protects fee income |
+| 05 | Month-End Close | Monthly | Earns back the subscription |
+
+All five are included in every paying tier. Pricing differentiator is seats and volume, not workflow access.
+
+## 6. Skill layer (cross-cutting)
+
+These skills appear in more than one workflow. They live once and are composed where needed.
+
+- `tone-matched-drafter` — drafts messages in the operator's voice, per recipient type
+- `priority-ranker` — orders any list of items using the profile's urgency weights
+- `compliance-flag-checker` — flags AML, GDPR, advertising standards risks in any output
+- `vendor-research` — public-record and CRM-history lookup, with the privacy line enforced
+- `variance-narrator` — produces short prose summaries of numerical changes
+- `profile-writer` — the single audited path for updating the customization profile
+
+Workflow-specific skills are defined in each workflow file.
+
+## 7. Connector requirements (sales-only build)
+
+| Connector | Read | Write | Build priority |
+|---|---|---|---|
+| CRM (Reapit first; Alto, Jupix later) | ✓ | ✓ | 1 |
+| Calendar (M365 / Google) | ✓ | ✓ | 1 |
+| Email (M365 / Google) | ✓ | ✓ | 1 |
+| WhatsApp Business | ✓ | ✓ | 1 |
+| Rightmove / Zoopla data | ✓ | – | 2 |
+| Land Registry | ✓ | – | 2 |
+| DocuSign | ✓ | ✓ | 3 |
+| Accounting (Xero / FreeAgent first) | ✓ | ✓ | 4 |
+| Portal listing upload (Rightmove / Zoopla) | – | ✓ | 4 |
+
+## 8. Principles for every workflow
+
+- **Read before write.** Every workflow starts by reading state, never by acting.
+- **Stage, don't send.** Drafts are presented for approval; nothing fires unattended.
+- **One screen of output.** If a workflow produces more than fits in one Claude UI exchange, it has summarised badly.
+- **Cite the source.** Every number, name, or claim in an output traces back to a connector read or a profile entry.
+- **Teach the profile.** Every workflow has at least one learning hook documented in its spec.
+- **Reversible.** Every action the operator approves can be undone with a follow-up sentence.

package/payload/premium-plugins/real-agency/specs/01-morning-round.md

@@ -0,0 +1,76 @@
+# 01 — Morning Round
+
+**Cadence:** Daily, Monday to Saturday
+**Default delivery:** 07:30, channel per profile (Telegram, web, email)
+**Risk level:** Read-only. No write actions.
+**Pre-req reading:** `00-architecture-and-customization.md`
+
+---
+
+## 1. Purpose
+
+A one-page snapshot the agent can read in under a minute, covering everything they would otherwise check across five browser tabs and the CRM. The job is to make Claude the first thing the agent opens, every day.
+
+## 2. Trigger recognition
+
+The router invokes this workflow when the operator says any variant of:
+
+- "morning round" / "morning brief"
+- "what's on" / "what's on today"
+- "where are we" / "where are we this morning"
+- "start my day" / "kick me off"
+- "what's new since yesterday"
+- A bare "morning" or "good morning" with no other content
+
+Also fires on schedule at the profile's delivery time. The scheduled run posts to the configured channel; the on-demand run posts inline.
+
+## 3. What it produces
+
+One markdown page with five sections, in this order. Sections with no content collapse to a single line ("nothing in the diary today") rather than disappearing — the operator should always know the workflow checked.
+
+**Today's diary.** Viewings, valuations, market appraisals, vendor meetings, completion calls. Times, addresses, and the relevant contact. Postcoded so the agent can see whether the order is sensible.
+
+**Awaiting reply.** Anything the agent or Claude chased in the last 7 days (default; learns) that hasn't been responded to. Grouped by recipient type: vendor, buyer, vendor solicitor, buyer solicitor, mortgage broker, surveyor.
+
+**New overnight.** Portal enquiries since last login, triaged. Each enquiry gets a one-line summary, a source label, and a triage tag: hot / lukewarm / cold / duplicate / spam. Hot enquiries get the full enquiry verbatim; lower tiers get summaries only.
+
+**Stalled.** Sales agreed where nothing has moved in over the agent's stalled-threshold window (default 7 days; learns). Each line names the property, the days stalled, and the most likely cause based on chain state.
+
+**Top three.** Three things to act on first, with the *reason* each one made the list. Not "Mrs Patel" but "Mrs Patel — her buyer's mortgage offer expires in 9 days and the survey was booked but not done." This section is the one the agent will actually use; the rest is reference.
+
+## 4. Skills composed
+
+| Skill | Purpose |
+|---|---|
+| `diary-builder` | Reads calendar and CRM, produces the diary block |
+| `enquiry-triage` | Classifies overnight portal/email enquiries |
+| `chain-progression-tracker` | Identifies stalled deals and likely causes |
+| `priority-ranker` (cross-cutting) | Produces the top three |
+| `variance-narrator` (cross-cutting) | Writes the cause sentences |
+
+## 5. Connectors read
+
+CRM, calendar, email, WhatsApp, portal feeds. No connectors written.
+
+## 6. Approval gates
+
+None. This workflow is read-only by design. The first principle here is that the operator should trust Claude to look without trusting Claude to act, and the morning round is where that trust is earned.
+
+## 7. Continuous learning hooks
+
+This workflow is the highest-volume source of learning signals because it runs daily and the operator's behaviour after reading it is observable.
+
+- **Skip pattern.** If the operator never acts on a category (e.g. they always ignore "lukewarm" portal enquiries from a specific source), that source's weight drops in `enquiry-triage` over time.
+- **Threshold drift.** If the operator manually says "I don't consider this stalled until day 10," the stalled threshold updates. If they consistently act on items at day 5, the threshold tightens automatically.
+- **Top-three accuracy.** When the operator actions item from the top three within the same day, that counts as a successful ranking. When they instead action a different item that was lower in the list, the ranker reweights toward whatever feature distinguished the actioned item.
+- **Delivery time.** If the operator consistently asks for the round before the scheduled time, the schedule shifts earlier. If they ignore it for hours after delivery, it shifts later or to on-demand only.
+- **Section preferences.** "Lead with stalled deals, not the diary" → reorder permanently. "Drop the awaiting-reply section, it's noise" → hide section, surface in chase-progression instead.
+
+All learning happens through `profile-writer`. The morning round itself never writes profile changes inline.
+
+## 8. Build notes
+
+- This is workflow one. Start here. It is read-only, low risk, high frequency, and the trust foundation for everything that follows.
+- The scheduled-delivery channel needs to handle the operator being offline (queue for next active session) and the operator being in multiple channels (don't duplicate).
+- The "top three" is the make-or-break feature. If the priority ranker is mediocre, the agent will stop reading. Worth over-investing here, including a fallback to GPT-style chain-of-thought reasoning over the candidate list if the heuristic ranker is uncertain.
+- A "yesterday's recap" toggle (off by default) shows what was on yesterday's round that was actioned vs. not. Useful for week-two onwards; noise on day one.

package/payload/premium-plugins/real-agency/specs/02-valuation-prep.md

@@ -0,0 +1,81 @@
+# 02 — Valuation Prep
+
+**Cadence:** Per appointment (a valuation or market appraisal is in the diary)
+**Default delivery:** On request, or auto-staged the evening before the appointment
+**Risk level:** Read-only output. The post-appointment instruction pack is gated separately under workflow 03.
+**Pre-req reading:** `00-architecture-and-customization.md`
+
+---
+
+## 1. Purpose
+
+A pre-appointment pack the agent can read on the walk from the car. The job is to turn a 90-minute prep into a 60-second confidence boost, and to make the agent the most prepared person in the room.
+
+This is the workflow most likely to *win new instructions*. Vendors notice when an agent walks in knowing more than they do.
+
+## 2. Trigger recognition
+
+The router invokes this workflow when the operator says any variant of:
+
+- "prep my val at [address]"
+- "valuation pack for [name]"
+- "what should I take to the [name] appointment"
+- "I'm at the Smiths tomorrow, get me ready"
+- "anything I should know about [address] before tomorrow"
+
+Also fires automatically the evening before any appointment in the calendar tagged as a valuation or market appraisal. The auto-staged version posts to the morning round's "today's diary" section the next morning, with a "open the pack" follow-up.
+
+## 3. What it produces
+
+A six-section markdown pack, no longer than the agent can read in two minutes.
+
+**Property.** Address, type, beds, baths, last sold price and date if available, EPC if available, last listed price if previously marketed, any planning history. Sourced from Land Registry, EPC register, council planning portal, and prior listings.
+
+**Comparables.** Three SSTC and three sold in the last 12 months within the profile's comparable radius (default 0.5 miles; learns). Each comparable shows: address, asking/sold price, beds, sqft, time on market, agent. Price-per-sqft column if at least four of the six have sqft.
+
+**Local stats.** Average days on market in the immediate area, asking-to-sold ratio, current stock count, recent fall-throughs. Three numbers maximum; this section is context, not the headline.
+
+**Vendor.** How long they've owned, last purchase price, any public signals worth knowing about *with the privacy line enforced* — see section 7 below. If anything sensitive is surfaced, it is flagged as such and the agent decides whether to use it.
+
+**Pricing scenarios.** Three numbers, not one: quick-sale price (sub-30-day expectation), market price (30–60 days), aspirational price (90+ days, with a "stretch" caveat). Each with one sentence of reasoning. The profile's preferred format applies — if the agent has corrected toward a single recommendation, the workflow learns to present one with a range, rather than three.
+
+**Talk-track.** Three questions to ask the vendor, two objections likely to come up, the agent's USP framed in their voice. Pulled from the profile's voice samples and prior successful talk-tracks.
+
+## 4. Skills composed
+
+| Skill | Purpose |
+|---|---|
+| `comparable-finder` | Pulls and ranks comparable evidence |
+| `local-market-stats` | Computes the three context numbers |
+| `vendor-research` (cross-cutting) | Public-record and CRM-history lookup, privacy-aware |
+| `pricing-scenario-builder` | Generates the three (or one + range) pricing options |
+| `talk-track-composer` | Drafts questions, objections, USP from profile |
+
+## 5. Connectors read
+
+Rightmove, Zoopla, OnTheMarket data feeds; Land Registry; EPC register; council planning portal; CRM. No connectors written during prep — the instruction pack is a separate workflow.
+
+## 6. Approval gates
+
+None at the prep stage. The pack is information, not action. Approval gates appear in workflow 03 (New Instruction), which runs after the appointment if the agent wins the business.
+
+## 7. The privacy line
+
+`vendor-research` will surface things like recent ownership changes, joint owners who appear and disappear from the title, deaths in the family registered against the address, and planning disputes. Some of this is useful context; some is intrusive and would damage the agent if quoted in the appointment.
+
+The profile holds a privacy preference (default: surface ownership and planning, flag-but-suppress death and dispute signals). The agent can adjust by saying "show me everything you find" or "drop the sensitive stuff." The workflow surfaces a flag at the top of the Vendor section if any suppressed signals exist, so the agent knows there is more if they want it.
+
+## 8. Continuous learning hooks
+
+- **Comparable radius.** If the agent consistently asks for "wider comps" or "tighter comps," the default radius updates.
+- **Pricing format.** Three scenarios vs. single-with-range vs. just-one-number — learn from which version the agent screenshots, copies, or refers to in the appointment notes afterward.
+- **Comparable preferences.** If the agent always drops a particular comparable (e.g. "ignore that one, it was a probate sale"), the workflow learns the agent's "exclude" filters: distressed sales, off-market, agent-bought.
+- **Talk-track effectiveness.** When an appointment is won (instruction taken), the talk-track is tagged as successful. When lost, the workflow does not blame the talk-track (too noisy) but does ask the agent for one-line feedback if offered, optionally.
+- **USP drift.** The agent's USP framing tightens over time as the workflow watches which phrasings get used vs. which get edited out before the appointment.
+
+## 9. Build notes
+
+- This workflow demos well. It is the one to show prospects on a sales call. The before/after delta (90-minute prep collapsed to two-minute read) is visceral.
+- Land Registry data is cheap and reliable but slow. Cache aggressively on the Pi; refresh on a 24-hour cycle for known addresses.
+- The privacy line is a feature, not a footnote. The agent's reputation is on the line if Claude blurts something inappropriate in the pack and the agent quotes it. Default conservatively.
+- Pi 5 compute is sufficient for the comparable analysis — even with sqft-derived rankings and a few hundred candidate properties — provided the portal data is cached locally and refreshed nightly rather than queried live per appointment.

package/payload/premium-plugins/real-agency/specs/03-new-instruction.md

@@ -0,0 +1,100 @@
+# 03 — New Instruction
+
+**Cadence:** Per win (the agent has taken an instruction at a valuation)
+**Default delivery:** On request, within 24 hours of the appointment
+**Risk level:** Multiple write actions, each individually gated
+**Pre-req reading:** `00-architecture-and-customization.md`
+
+---
+
+## 1. Purpose
+
+Compress what is normally a half-day of admin — terms of business signed, EPC ordered, photographer booked, floorplan commissioned, listing copy written, particulars produced, portal launches scheduled — into a guided sequence the agent reviews and approves in fifteen minutes.
+
+This workflow is the second-highest-value moment in the agent's week (after winning the instruction itself). Done well, the property is on the portals within 72 hours of the appointment rather than 7–10 days. That speed compounds: faster on-market means more viewings in the first weekend, which is when offers happen.
+
+## 2. Trigger recognition
+
+The router invokes this workflow when the operator says any variant of:
+
+- "set up [address]" / "set up the instruction at [address]"
+- "I won [name]" / "I won the [address] val"
+- "instruction taken at [address]"
+- "get [address] on the market"
+- "kick off the [name] property"
+
+Also offered proactively when the operator updates the CRM to mark a property as "instructed" — the workflow stages itself and asks "shall I run new-instruction setup?" without firing.
+
+## 3. What it produces
+
+A sequenced checklist where each item is either auto-prepared (the workflow does the work, presents for approval) or assigned (the workflow drafts the request, the agent or supplier completes).
+
+**Terms of business.** Drafted from agency template, populated with property, vendor, fee structure, sole/multi agency, marketing period, withdrawal fee. Staged in DocuSign with vendor as recipient. *Gate: approve before send.*
+
+**EPC.** If the property does not have a current EPC (checked via EPC register), an order is staged with the agent's preferred supplier (from profile). If a current EPC exists, the workflow records the expiry date and moves on. *Gate: approve order before send if no current EPC.*
+
+**Photography.** A booking request is drafted to the agent's preferred photographer (from profile), with the property address, vendor contact, and the agent's standard brief. *Gate: approve before send.*
+
+**Floorplan.** As photography. Combined into a single booking request if the same supplier handles both. *Gate: approve before send.*
+
+**Listing copy.** Drafted in the agent's voice, length, and structure (from profile). Includes headline, key features bullet list, full description, location paragraph. Optimised for the portals listed in the profile. Presented for review with one-click "use this" or "redraft with changes." *Gate: approve before any portal upload.*
+
+**Particulars.** PDF brochure generated from the listing copy and (when photos return) the photography. Staged for the agent's review and the vendor's review before any wider distribution.
+
+**Portal scheduling.** The workflow proposes a launch sequence — typically Rightmove premium listing on a Friday morning, Zoopla and OnTheMarket simultaneously, with viewings opened for the weekend. The schedule is staged, not fired. *Gate: approve schedule before any portal upload happens.*
+
+**Vendor communications.** A welcome email is drafted explaining what happens next, what to expect, when to expect photos, who will be in touch. Sent on approval immediately after terms are signed. *Gate: approve before send.*
+
+## 4. Skills composed
+
+| Skill | Purpose |
+|---|---|
+| `terms-of-business-drafter` | Populates the agency's template with deal specifics |
+| `epc-checker` | Looks up the EPC register, computes order need |
+| `supplier-booker` | Drafts and stages booking requests to photographer, EPC supplier, floorplan supplier |
+| `listing-copy-writer` | Generates portal-optimised property descriptions |
+| `particulars-builder` | Composes the PDF brochure |
+| `portal-launch-scheduler` | Proposes a launch sequence and pre-stages uploads |
+| `tone-matched-drafter` (cross-cutting) | Vendor welcome email |
+| `compliance-flag-checker` (cross-cutting) | Material information, advertising standards, AML on vendor |
+
+## 5. Connectors read and written
+
+Read: CRM, EPC register, calendar, profile.
+Write: DocuSign (terms), email (vendor welcome, supplier bookings), portal upload APIs (Rightmove, Zoopla, OnTheMarket — staged only).
+
+## 6. Approval gates
+
+This workflow has the most write actions of any in the set. Each one is individually gated:
+
+1. Terms of business send
+2. EPC order (if applicable)
+3. Photographer booking
+4. Floorplan booking
+5. Listing copy use (final version before portal upload)
+6. Particulars distribution
+7. Portal launch schedule confirmation
+8. Vendor welcome email send
+
+The workflow presents these in sequence and respects the operator's pace. The agent can approve them all in one go ("ship everything") or one at a time, or pause the workflow and return later. State is preserved.
+
+## 7. AML and material information
+
+AML on the vendor must be completed before any marketing goes live. The workflow does not run AML itself — it stages a request to the agent's preferred AML provider and blocks portal launch until the AML status is "passed." If the operator overrides ("I know this vendor, push it live now"), the override is logged with a compliance flag and the AML check is still queued.
+
+Material information for portal listings (council tax band, tenure, ground rent if leasehold, etc.) is gathered into the listing copy. Missing items are flagged before the operator approves the copy — Rightmove now requires these and rejects listings without them.
+
+## 8. Continuous learning hooks
+
+- **Supplier preferences.** If the operator routinely overrides the suggested photographer, the new preferred supplier is learned. Same for EPC, floorplan, even AML provider.
+- **Copy voice and length.** Edit-before-send diffs feed `listing-copy-writer`. Within a month, the workflow's drafts should need minimal editing.
+- **Launch timing.** Friday morning is a heuristic default. If the agent consistently launches on a different day, the scheduler learns. If the agent times launches around school holidays, area events, or sale calendars, the scheduler picks that up.
+- **Particulars structure.** The brochure template adapts — section order, photo count, whether floorplan goes early or late, whether the location paragraph leads or trails.
+- **Fee structure drift.** If the operator overrides the fee on a particular instruction, that is a one-off. If they override the same way three times in a month (e.g. always offering a reduced fee for repeat vendors), the profile's default fee logic learns.
+
+## 9. Build notes
+
+- This is workflow three by build order — after the morning round and chase-progression have built trust. The agent will not let Claude touch DocuSign and portal APIs until they have seen the morning round and chase be reliable.
+- Photographer and EPC supplier connectors are usually email-based, not API-based. That is fine — the workflow drafts a structured email and the supplier replies in their usual way. The workflow learns to parse the replies over time.
+- Portal upload APIs are the hardest connector layer. Rightmove's is gated by the agency's Rightmove account; Zoopla and OnTheMarket are easier. Build in that order.
+- The PDF particulars generator should respect the agency's brand. Use a template the agent provides during onboarding; do not generate brand assets.

package/payload/premium-plugins/real-agency/specs/04-chase-progression.md

@@ -0,0 +1,120 @@
+# 04 — Chase Progression
+
+**Cadence:** Daily (auto, part of morning round) and on-demand
+**Default delivery:** Surfaced in morning round; expanded on request
+**Risk level:** Multiple outbound messages, each individually gated
+**Pre-req reading:** `00-architecture-and-customization.md`
+
+---
+
+## 1. Purpose
+
+This is the headline workflow. Sales agents lose more fee income to stalled chains than to any other single cause, and chain progression is exhausting, repetitive, emotionally draining work that an agent should not be doing manually. Done well, this workflow protects every pipeline fee the agent has worked to earn.
+
+Anthropic's invoice-chaser is the closest pattern in the SMB plugin. This is the same pattern, applied to the highest-value cash conversion problem in estate agency: turning sale-agreed into completed.
+
+## 2. Trigger recognition
+
+The router invokes this workflow when the operator says any variant of:
+
+- "chase the chain" / "chase progression"
+- "where is everyone on [address]"
+- "push [name]'s deal" / "push the chain on [address]"
+- "follow up on the [name] solicitors"
+- "what's stalled" / "stalled deals"
+- "any updates on [address]"
+
+Also runs automatically as a sub-flow of the morning round, surfacing stalled items there. Expanding any stalled item from the morning round (the operator says "show me what's holding up [address]") brings the full workflow into focus on that deal.
+
+## 3. What it produces
+
+A ranked list of stalled deals with drafted, tone-matched messages per stakeholder. Two views:
+
+**Across the pipeline.** Every sale-agreed deal that has stalled past its threshold (default 7 days; learns per stakeholder type), ranked by fall-through risk × fee value. Each deal shows: property, days since last contact, last contact summary, fall-through risk score, what is most likely holding it up, who to chase, draft message ready.
+
+**Single deal deep-dive.** When the operator names a property, the workflow produces the full state of that chain: every party, every last-known status, every outstanding action, every risk flag. Draft messages for every stakeholder who needs chasing, each in the right tone.
+
+Each draft message identifies recipient, channel (email vs WhatsApp vs SMS), and is written in the agent's voice for that recipient type. The operator can approve all, approve some, edit any, or skip.
+
+## 4. Fall-through risk scoring
+
+The workflow computes a risk score per deal from observable signals:
+
+- Days since last contact (any party)
+- Days since last positive progress event
+- Mortgage offer expiry approaching (offers usually valid 3–6 months)
+- Searches outstanding past day 21
+- Survey booked but not done past day 14
+- Vendor or buyer disengagement signals (slow replies, terse messages)
+- Chain complexity (number of linked transactions)
+- Onward-purchase status if known
+
+Scores are not shown as numbers to the operator — they drive the ranking and a one-line cause description. "Mortgage offer expires in 9 days and survey is booked but not done" is the surface; the score is underneath.
+
+The scoring weights are profile-learned. If the operator routinely deprioritises deals that the workflow flagged as high risk, the weighting shifts. If they routinely action deals the workflow flagged as low risk, the weighting shifts the other way.
+
+## 5. Tone matching per recipient type
+
+Different stakeholders get different voices. The profile carries a tone preference per type, calibrated from the agent's voice samples and from edit-before-send diffs over time.
+
+| Recipient type | Default tone | Channel default |
+|---|---|---|
+| Vendor (familiar) | Conversational, first-name | WhatsApp / mobile |
+| Vendor (formal) | Polite, surname | Email |
+| Buyer (familiar) | Conversational, first-name | WhatsApp / mobile |
+| Buyer (formal) | Polite, surname | Email |
+| Vendor solicitor | Formal, surname, references file | Email |
+| Buyer solicitor | Formal, surname, references file | Email |
+| Mortgage broker | Polite, first-name, references buyer | Email or phone |
+| Surveyor | Brief, polite, references property | Email |
+
+The defaults are starting points. Within a month of use, each agent's tone profile is distinct.
+
+## 6. Skills composed
+
+| Skill | Purpose |
+|---|---|
+| `chain-progression-tracker` | Builds the state-of-the-chain view per deal |
+| `risk-scorer` | Computes fall-through risk from observable signals |
+| `priority-ranker` (cross-cutting) | Orders the stalled list by risk × fee |
+| `tone-matched-drafter` (cross-cutting) | Drafts each message in the right voice |
+| `compliance-flag-checker` (cross-cutting) | Flags anything that should not be said by an agent (GDPR, advertising standards, AML disclosures) |
+
+## 7. Connectors
+
+Read: CRM, email, WhatsApp, calendar, mortgage offer expiry data if held in CRM.
+Write: Email, WhatsApp Business, SMS — each on explicit per-message approval.
+
+## 8. Approval gates
+
+Per-message. The workflow presents drafts in a batch (typically 5–15 messages for a normal stalled list) and the operator can:
+
+- **Approve all** — fires every message as drafted
+- **Approve, edit some** — operator edits inline; edits are captured for learning; remaining approved messages fire as drafted
+- **Approve some, skip some** — fires only approved ones; skipped ones are dropped from the run and the recipient is excluded from chase for 24 hours
+- **Pause** — saves the batch; returns to it later
+
+The workflow never fires a message that has been edited but not re-approved. Edit-then-fire requires a second approval click.
+
+## 9. The "spoke to them" override
+
+The most frequent operator action with this workflow is "don't chase [name], I spoke to them yesterday." The workflow recognises this phrasing, removes the recipient from the current batch, and records the verbal contact in the CRM with timestamp and a note "operator confirms verbal contact, no chase needed."
+
+This is a learning signal: that recipient now has a logged interaction, and the stalled-threshold clock resets for them.
+
+## 10. Continuous learning hooks
+
+- **Cadence per stakeholder type.** "I chase solicitors at 5 days, brokers at 3, vendors weekly." Learned from explicit corrections and from edit-frequency patterns.
+- **Tone profile.** The deepest learning hook in the whole product. Every edit-before-send diff is gold here. Within a quarter, the workflow should be drafting messages the agent sends without editing 80% of the time.
+- **Risk weights.** Reweighted by which deals actually fall through (negative outcome) and which complete (positive outcome). Slow signal, high quality.
+- **Skip patterns.** Recipients the agent never chases (a friend, a regular client they handle in person) get excluded automatically once a pattern is recognised.
+- **Channel preferences per recipient.** If the operator always changes the drafted email to a WhatsApp, the channel preference for that recipient is updated.
+- **Phrasing pet-peeves.** The agent edits out "I hope this finds you well" every single time → the workflow stops using it. Within weeks, the drafts read as the agent's writing, not Claude's.
+
+## 11. Build notes
+
+- This is workflow two by build order, after morning round. The morning round earns the right to look; chase-progression earns the right to act.
+- Pilot with Muvin (Amelia, Alison) as the existing live deployment. They will tolerate the early iteration and the edit-feedback they generate is exactly the signal `tone-matched-drafter` needs.
+- The risk scorer should be opaque to the operator. Showing a number invites debate; showing a one-line cause invites action.
+- WhatsApp Business API is rate-limited and template-restricted for the first interaction with a recipient. The workflow needs to know when a recipient is on an open 24-hour conversation window and when a template message is required. This is a routine integration detail but trips up most builds at first.
+- Keep the maximum batch size capped (suggest 15 messages). If the operator has 30 stalled deals, surfacing them all at once invites approve-all-and-regret. Two batches of 15 with a pause between is safer.

package/payload/premium-plugins/real-agency/specs/05-month-end-close.md

@@ -0,0 +1,79 @@
+# 05 — Month-End Close
+
+**Cadence:** Monthly (typically first working day after period end)
+**Default delivery:** On request or auto-staged on the first of the month
+**Risk level:** Read-mostly, with payment-batch staging gated for approval
+**Pre-req reading:** `00-architecture-and-customization.md`
+
+---
+
+## 1. Purpose
+
+Compress a half-day to a full day of month-end admin into a 20-minute review. Reconcile completions against fees received, compute the commission run, surface variances against last month and same-month-last-year, and produce a clean pack for the accountant.
+
+This is the workflow that earns back the subscription. A solo agent who would otherwise spend half a Saturday on this should feel that Real Agent paid for itself in the time saved on month-end alone.
+
+## 2. Trigger recognition
+
+The router invokes this workflow when the operator says any variant of:
+
+- "close out [month]" / "close [month]" / "month end"
+- "do my commission" / "commission run"
+- "reconcile [month]"
+- "ready for the accountant"
+- "what did I do last month"
+
+Also fires automatically on the first working day of the month, staged for the operator to open when ready. Auto-staged runs surface in the morning round with a "month-end close is ready" note.
+
+## 3. What it produces
+
+A five-section pack, presented in Claude UI and stored as a markdown + spreadsheet bundle in the agent's Drive.
+
+**Completions.** Every property that exchanged or completed in the period, with: address, vendor, buyer, fee value, fee structure (sole/multi/withdrawal/sliding), completion date, expected receipt date. Highlights anything that exchanged but is still awaiting completion.
+
+**Reconciliation.** Fees expected vs. fees received, matched on completion date and amount. Three flag categories: matched (no action), pending (expected but not yet received, with age), variance (received differs from expected — fee adjustment, referral deduction, fee dispute). Variances get a one-line cause and a draft email to the accountant or solicitor if appropriate.
+
+**Commission run.** For office tiers with multiple agents: each agent's earned commission for the period, including referral fees passed through, franchise levies deducted, and any pre-agreed adjustments. Presented as a payable schedule with totals.
+
+**Pipeline carry-forward.** Sale-agreed but not yet exchanged, with expected exchange/completion month, fee value, and current fall-through risk (pulled from chase-progression). A one-line narrative of "next month should look like X based on what's in the pipeline."
+
+**Variance narrative.** Two paragraphs comparing the period to the previous month and to the same period last year. Plain language, no jargon — "April was £8,400 down on March because three completions slipped into May, all expected to land. Year-on-year April is 15% up." Suitable to paste into a board update, a tax return cover note, or a conversation with a partner.
+
+## 4. Skills composed
+
+| Skill | Purpose |
+|---|---|
+| `period-reconciler` | Matches completions to fees received, surfaces variances |
+| `commission-calculator` | Computes agent commission per the splits table |
+| `payment-batch-stager` | Builds payable schedules ready for approval |
+| `variance-narrator` (cross-cutting) | Writes the comparison paragraphs |
+| `compliance-flag-checker` (cross-cutting) | AML refresh on any unusual fee patterns; data retention prompts on closed files |
+
+## 5. Connectors
+
+Read: Accounting (Xero / FreeAgent / QuickBooks / Sage), bank feed via the accounting connector, CRM, prior month's close pack.
+Write: Accounting (post journal entries on approval), payment batch staging for the agent's bank or for a payroll-style export, Drive (close pack storage), email (accountant pack).
+
+## 6. Approval gates
+
+- **Variance writeoffs.** Any fee variance the workflow proposes to write off (FX, small reconciliation differences) requires per-item approval.
+- **Commission payment batch.** The agent commission run is staged as a payment batch but does not initiate any actual transfer. The operator either approves the batch for export to their bank, or makes payments manually with the schedule as reference.
+- **Journal entries.** Any postings to the accounting system require approval. The default behaviour is to *propose* postings, show what they would do, and let the operator approve before they hit the books.
+- **Accountant pack send.** The drafted email to the accountant with the pack attached requires explicit approval before send.
+
+## 7. Continuous learning hooks
+
+- **Categorisation conventions.** The accountant prefers a specific chart-of-accounts mapping (e.g. "referral fees go to 4501, not 4500"). Corrected once, learned for every subsequent close.
+- **Variance tolerance.** Default writeoff threshold (e.g. under £5) tightens or loosens based on the operator's overrides.
+- **Narrative tone.** The variance narrative should sound like the agent wrote it for their accountant or their partner. Voice learned from edit-before-approve diffs on the narrative paragraphs.
+- **What to flag.** "I always want to know about completions over £5k fee value" → the close pack leads with those. "Don't bother flagging multi-agency fee splits separately" → suppressed.
+- **Pipeline narrative confidence.** Over time, the workflow learns how accurate its "next month should look like X" predictions are, and adjusts confidence language accordingly.
+
+## 8. Build notes
+
+- This is workflow five by build order. It depends on the accounting connector, which is more involved than the CRM/comms connectors needed for workflows one through three.
+- Xero and FreeAgent are the right starting accounting connectors for solo and small-office UK agents. QuickBooks Online is third priority; Sage Business Cloud Accounting is fourth.
+- Bank-feed access through the accounting platform avoids needing a separate Open Banking integration. Sufficient for month-end reconciliation; not sufficient if the agent later wants live cash visibility (a future extension).
+- The accountant pack is a meaningful deliverable in itself. Get the format right — a markdown summary, an Excel reconciliation, and a PDF P&L narrative — and accountants become a soft channel for referring more agencies to Real Agent.
+- The commission run is the feature that justifies this workflow for the office tier. Solo agents care less about the commission split logic but still get value from the reconciliation and the accountant pack.
+- The proactive auto-staged run on the first of the month is the moment Real Agent feels indispensable. An operator who walks into their office on the first and finds "your month-end is ready to review" already done is unlikely to churn.