@rubytech/create-maxy-code 0.1.4 → 0.1.6

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.