@rubytech/create-maxy-code 0.1.3 → 0.1.5

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.