@rubytech/create-realagent-code 0.1.23 → 0.1.24

package/payload/premium-plugins/real-agency/plugins/listings/skills/terms-of-business-drafter/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: terms-of-business-drafter
+description: "Populate the agency's terms of business template with the deal specifics for a new instruction and stage it in DocuSign with the vendor as recipient. Built for use inside new-instruction; the operator does not invoke it directly. Owned by the compliance specialist."
+---
+
+# Terms of business drafter
+
+A building-block skill called by `new-instruction`. Produces the terms document the vendor signs before any marketing begins.
+
+## What it does
+
+Reads the agency's terms-of-business template path from the profile, then populates it with:
+
+- Property full address and tenure
+- Vendor name(s) and contact details
+- Fee structure (sole agency, multi agency, with-other-agents, or the agent's named variant)
+- Fee amount or percentage
+- Minimum fee where applicable
+- Marketing period in weeks
+- Withdrawal fee policy
+- Notice period
+- VAT inclusion and registration number
+- CMP scheme membership, redress scheme membership, ICO registration (TPO code requires display)
+- Effective date
+
+The populated document is staged in DocuSign as a recipient envelope with the vendor as signatory. Nothing is sent until the operator approves.
+
+## Compliance ground
+
+The terms of business is the document the Estate Agents Act 1979 s.18 requires to be in writing before instruction is accepted. Failure to comply makes the contract unenforceable except by court order. The Consumer Rights Act 2015 fee transparency obligations also bear on this document. `compliance-flag-checker` runs against the populated draft before the operator sees it.
+
+If the populated draft is missing any of the mandatory fields, the missing fields are listed at the top of the staged output so the operator can fill them before approving.
+
+## What it does not do
+
+- It does not send. Sending requires the operator's explicit approval.
+- It does not amend the agency template. Template changes are made out-of-band.
+- It does not negotiate fees with the vendor. The agreed fee is captured at the appointment.
+
+## Connectors
+
+Read: profile (template path, fee defaults), CRM (vendor and property records).
+Write (staged only): DocuSign envelope creation.
+
+## Profile keys
+
+- `realagent.terms_template_path`
+- `realagent.fee_structure.default`
+- `realagent.fee_structure.minimum`
+- `realagent.fee_structure.withdrawal_fee`
+- `realagent.fee_structure.marketing_period_weeks`
+- `realagent.compliance.cmp_scheme_membership`
+- `realagent.compliance.redress_scheme`
+- `realagent.compliance.ico_registration`

package/payload/premium-plugins/real-agency/plugins/listings/skills/valuation-prep/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: valuation-prep
+description: "Produce the pre-appointment pack the agent reads on the walk from the car to a valuation or market appraisal. Six sections: property, comparables, local stats, vendor, pricing scenarios, talk-track. Triggers when the operator says '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."
+---
+
+# Valuation prep
+
+The master workflow owned by the valuer specialist. Turns a 90-minute prep into a 60-second read. This is the workflow most likely to win new instructions; vendors notice when an agent walks in knowing more than they do.
+
+## Inputs
+
+- Address of the property to value, supplied by the operator or read from the calendar entry.
+- The vendor's name if it is in the diary entry or the CRM.
+- The customisation profile.
+
+If the address is ambiguous, the workflow asks once for the postcode rather than guessing. Every other input is derived from connectors.
+
+## Architecture principles encoded here
+
+- Read before write. Read-only output; the post-appointment instruction pack is a separate workflow.
+- Stage, don't send. Nothing to send.
+- One screen of output. Six short sections, readable in two minutes.
+- Cite the source. Every comparable cites the portal or Land Registry. Every vendor signal cites Land Registry, the title, or the CRM. Every stat cites the area data feed.
+- Teach the profile. Learning hooks documented below.
+- Reversible. Read-only.
+
+## Output shape
+
+Six sections in this order.
+
+1. **Property.** Address, type, beds, baths, last sold price and date if available, EPC if available, last listed price if previously marketed, planning history. Sourced from Land Registry, the EPC register, the council planning portal, and prior portal listings.
+2. **Comparables.** Three SSTC and three sold in the last 12 months within the profile's comparable radius (default 0.5 miles, learns). Each comparable: address, asking or sold price, beds, square footage, time on market, agent. Adds a price-per-square-foot column if at least four of the six have square footage. Built by `comparable-finder`.
+3. **Local stats.** Three numbers maximum: average days on market in the immediate area, asking-to-sold ratio, current stock count. Context, not headline. Built by `local-market-stats`.
+4. **Vendor.** How long they have owned, last purchase price, public signals worth knowing with the privacy line enforced. Built by `vendor-research`. Sensitive signals are flagged at the top of the section if suppressed, so the operator knows there is more if they want it.
+5. **Pricing scenarios.** Three numbers by default: quick-sale (sub-30-day expectation), market (30 to 60 days), aspirational (90 days plus, marked "stretch"). Each with one sentence of reasoning. If the profile has corrected toward a single recommendation with a range, the workflow learns and presents that format instead. Built by `pricing-scenario-builder`.
+6. **Talk-track.** Three questions to ask the vendor, two objections likely to come up, the agent's USP in the agent's voice. Built by `talk-track-composer` reading the profile's voice samples and prior successful talk-tracks.
+
+## The privacy line
+
+`vendor-research` will surface ownership changes, joint owners who appear and disappear, deaths registered against the address, and planning disputes. The profile holds a privacy preference, default: surface ownership and planning, flag-but-suppress death and dispute signals. The operator can adjust by saying "show me everything you find" or "drop the sensitive stuff".
+
+The default is conservative because the agent's reputation is on the line if Claude blurts something inappropriate and the agent quotes it.
+
+## Approval gates
+
+None at the prep stage. The pack is information, not action. Approval gates appear in `new-instruction`, which runs after the appointment if the agent wins the business.
+
+## Continuous learning hooks
+
+- Comparable radius. "Wider comps" or "tighter comps" updates the default radius.
+- Pricing format. Three scenarios versus single-with-range versus a single number. Learned from which version the agent screenshots, copies, or refers to in the appointment notes.
+- Comparable preferences. "Ignore that one, it was a probate sale" feeds the exclude filters: distressed sales, off-market, agent-bought.
+- Talk-track effectiveness. Won appointments tag the talk-track as successful. Lost appointments do not blame the talk-track (too noisy) but ask the agent for one-line feedback if offered.
+- USP drift. The USP tightens as the workflow watches which phrasings get used versus edited out before the appointment.
+
+All writes go through `profile-writer`.
+
+## Connectors
+
+Read: Rightmove, Zoopla, OnTheMarket data feeds; Land Registry; EPC register; council planning portal; CRM. No writes.
+
+## Profile keys
+
+- `realagent.comparable_radius_miles` (default 0.5)
+- `realagent.pricing_format` ("three_scenarios" | "single_with_range" | "single_number")
+- `realagent.comparable_exclude_filters` (list, learned)
+- `realagent.privacy_line.surface` (list)
+- `realagent.privacy_line.suppress` (list)
+- `realagent.usp_phrases` (list, learned)

package/payload/premium-plugins/real-agency/plugins/loop/PLUGIN.md

@@ -25,6 +25,12 @@ tools:
   - loop-marketing-enquiry
   - loop-customer-preferences
   - loop-supplier
+skills:
+  - skills/tone-matched-drafter/SKILL.md
+  - skills/priority-ranker/SKILL.md
+  - skills/compliance-flag-checker/SKILL.md
+  - skills/vendor-research/SKILL.md
+  - skills/variance-narrator/SKILL.md
 always: false
 metadata: {"platform":{"optional":true,"embed":["admin"]}}
 ---
@@ -71,3 +77,17 @@ Use Loop tools when the user asks about CRM data: properties, people, viewings,
 Default to writes when the user's intent is to *change* data in Loop, not just look it up. Reads return information; writes record the user's decision in Loop.
 
 Write operations require specifying which team to act through. If no teams are registered, suggest using `loop-key-register` to add team API keys. If a write fails with a permission error (`Team "X" does not have <group> permission`), the registered key was scoped to fewer than 8 endpoint groups — re-register with the full permissions array (`["properties","people","viewings","feedback","team","marketing","customer","supplier"]`).
+
+## Cross-cutting skills hosted here
+
+This plugin also hosts the five cross-cutting skills that more than one Real Agent workflow composes. They live here rather than in a workflow-specific plugin because every workflow that produces a message, a ranking, a compliance check, a vendor lookup, or a narrative paragraph reuses them.
+
+| Skill | Owner specialist | Purpose |
+|-------|------------------|---------|
+| `tone-matched-drafter` | negotiator | Drafts every outgoing message in the operator's voice per recipient type |
+| `priority-ranker` | shared | Orders any list using the profile's urgency weights |
+| `compliance-flag-checker` | compliance | Flags AML, GDPR, DMCCA material info, ASA standards, Equality Act risks |
+| `vendor-research` | negotiator | Public-record and CRM-history lookup with the privacy line enforced |
+| `variance-narrator` | compliance | Short prose summaries of numerical changes |
+
+The cross-cutting skill `profile-writer` named in spec 00 §6 maps to the Maxy platform's existing `profile-update` tool; no new skill is shipped for it.

package/payload/premium-plugins/real-agency/plugins/loop/skills/compliance-flag-checker/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: compliance-flag-checker
+description: "Flag AML, GDPR, DMCCA 2024 material information, ASA/CAP advertising standards, and Equality Act risks in any output before the operator approves it. Cross-cutting skill called by every workflow that produces an outbound message, a listing, terms of business, or a payment batch. Owned by the compliance specialist."
+---
+
+# Compliance flag checker
+
+A cross-cutting building-block skill. Runs against every output that touches a regulated surface (a portal listing, a terms-of-business document, an outgoing message to a buyer or vendor, a payment batch, the AML status on a deal). Returns a list of flags the operator should see before approval.
+
+## What it checks
+
+- **Material information.** DMCCA 2024 disclosure requirements for property listings: council tax band, tenure, ground rent and service charge if leasehold, property type, construction, utilities, heating, broadband, parking, and the wider Part C signals (flood risk, listed status, structural issues, planning permission, mining, and the rest). Missing items are flagged with the specific legislative requirement.
+- **Advertising standards.** ASA upheld-complaint patterns: fee transparency (VAT inclusion, mandatory surcharges disclosed), property descriptions accurate and substantiated, "local" claims supported, "leading" and "number one" claims substantiated.
+- **EPC display.** Asset rating present in any commercial media for the listing.
+- **AML state on the vendor.** Blocks a portal launch unless AML status is "passed" or the operator has explicitly overridden.
+- **GDPR.** Marketing messages to non-existing-client contacts checked for PECR opt-in basis. Data-retention prompts surfaced on close files.
+- **Equality Act.** Listing copy and outgoing messages checked for discriminatory phrasing (most commonly the "No DSS" pattern in lettings, court-declared as unlawful indirect discrimination).
+- **EAA s.21 personal interest disclosure.** Flags any output where the agent has a personal interest in the property and the disclosure has not been made.
+- **Renters' Rights Act 2025.** Where the workflow produces lettings output: bidding-ban compliance (must publish asking rent, must not request or accept above-advertised offers), discrimination ban (benefits, children), pet provisions, PRS database registration check, ombudsman membership display.
+- **Client money handling.** EAA 1979 ss.12 to 17 obligations on prescribed accounts, interest, trust requirements.
+
+## Output
+
+Each flag returns:
+
+- The cited legislation (Act, SI, regulation, code provision), with format like `[DMCCA 2024, Part 4, s.237]`
+- The specific issue
+- The remediation required
+- The penalty exposure for non-compliance
+
+The calling workflow surfaces the flags at the top of the staged output. The operator clears the flags or accepts the residual risk before approving.
+
+## What it does not do
+
+- It does not block approval. The operator decides; the skill informs.
+- It does not provide legal advice. Use "the legislation requires", "the regulatory position is", "this appears to fall short of". Never "you should" or "my advice is".
+- It does not certify a transaction or a listing as compliant. It flags gaps and cites requirements.
+- It does not amend the output it checks. Remediation is for the calling workflow or the operator.
+
+## Connectors
+
+Read: profile (compliance state, AML provider, scheme memberships), CRM (deal, vendor, listing), the deep-research tool when an unfamiliar provision needs verification.
+Write: none.
+
+## Profile keys
+
+- `realagent.compliance.cmp_scheme_membership`
+- `realagent.compliance.redress_scheme`
+- `realagent.compliance.ico_registration`
+- `realagent.compliance.mlro_designation`
+- `realagent.compliance.aml_provider`
+- `realagent.compliance.tpo_membership`
+- `realagent.compliance.propertymark_membership`

package/payload/premium-plugins/real-agency/plugins/loop/skills/priority-ranker/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: priority-ranker
+description: "Order any list of items using the profile's urgency weights. Cross-cutting skill used by the morning round's top three and chase-progression's stalled list."
+---
+
+# Priority ranker
+
+A cross-cutting building-block skill. Given a list of items with feature attributes, returns the same list ordered by relative urgency.
+
+## Inputs
+
+The calling workflow passes:
+
+- A list of items. Each item has a feature attribute map (for chase-progression, the features are risk score, fee value, days stalled, recipient type, and so on).
+- An optional cap on how many top items to return (the morning round uses 3).
+
+## What it does
+
+Reads the profile's weights for the relevant features. Returns the items in descending urgency order. If the cap is supplied, returns only the top N.
+
+For the top-three case the skill also returns, alongside each item, the feature that contributed most to its rank. The calling workflow uses that feature to write the reason sentence the operator reads ("Mrs Patel, her buyer's mortgage offer expires in 9 days and the survey was booked but not done").
+
+## Learning
+
+When the operator actions a different item than the top-ranked one within the same session, the weighting reweights toward whatever feature distinguished the actioned item. Slow signal, high quality. All writes go through `profile-writer`.
+
+## What it does not do
+
+- It does not generate the reason sentence. That is `variance-narrator`.
+- It does not decide what to do with the ranked items. The calling workflow owns that.
+- It does not write to the CRM.
+
+## Connectors
+
+Read: profile (weights). No writes.
+
+## Profile keys
+
+- `realagent.priority_weights.*` (per feature, learned)
+- `realagent.priority_weights.fee_multiplier`

package/payload/premium-plugins/real-agency/plugins/loop/skills/tone-matched-drafter/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: tone-matched-drafter
+description: "Draft a message in the operator's voice for a specific recipient type and channel. Cross-cutting skill used by chase-progression, new-instruction (vendor welcome), and any other workflow that needs an outgoing message. Never sends; the calling workflow owns the send gate."
+---
+
+# Tone-matched drafter
+
+The cross-cutting skill that produces every outgoing message in Real Agent. The deepest learning hook in the product: edit-before-send diffs feed back here.
+
+## Inputs
+
+The calling workflow passes:
+
+- Recipient type (vendor familiar, vendor formal, buyer familiar, buyer formal, vendor solicitor, buyer solicitor, mortgage broker, surveyor, photographer, EPC supplier, floorplan supplier, accountant, other)
+- Channel (WhatsApp, email, SMS, or "infer from recipient")
+- Intent (chase the solicitor on searches, welcome a new vendor, request a viewing, confirm a meeting, and so on)
+- Reference data (the deal record, the property record, the contact's prior messages)
+
+## What it does
+
+Reads the profile's tone preference for the recipient type and the agent's voice samples. Drafts a message that matches:
+
+- The agent's vocabulary (the words they actually use)
+- The agent's sentence length and rhythm
+- The agent's preferred greeting and sign-off for the recipient type
+- The phrases the agent has previously edited out (the pet-peeve list), which are never included
+- The channel's constraints (WhatsApp templating for first contact, email subject lines, SMS character limits)
+
+The draft is returned to the calling workflow with the channel decision attached. The workflow decides when to surface the draft to the operator and when to fire on approval.
+
+## What it does not do
+
+- It never sends. The calling workflow owns the send gate.
+- It does not negotiate. Drafts are messages the operator would send; negotiating substance is the operator's decision.
+- It does not invent facts. Every reference to a number, name, or date is read from the deal record or the connector. If a field is missing, the draft says so explicitly and the operator fills it.
+
+## Learning
+
+Every time the operator edits a draft before approval, the diff is captured and weighted into the profile's tone preference and pet-peeve list. Within a quarter, the workflow should produce drafts the agent sends without editing 80% of the time on the common recipient types.
+
+## Connectors
+
+Read: profile (tone, voice samples, pet peeves, channel preferences), CRM (deal and contact records).
+Write: none. The calling workflow handles sends.
+
+## Profile keys
+
+- `realagent.tone_profile.*` (per recipient type)
+- `realagent.voice_samples`
+- `realagent.phrasing_pet_peeves`
+- `realagent.channel_preference.<recipient_id>`
+- `realagent.tone_profile.greetings.*`
+- `realagent.tone_profile.signoffs.*`

package/payload/premium-plugins/real-agency/plugins/loop/skills/variance-narrator/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: variance-narrator
+description: "Write short prose summaries of numerical changes. Used by the morning round to write the cause sentence under each stalled deal, and by month-end-close to write the two paragraphs comparing the period to the prior month and the same period last year."
+---
+
+# Variance narrator
+
+A cross-cutting building-block skill. Turns a set of numbers and structured events into a sentence or short paragraph in plain English, in the agent's voice.
+
+## Two output shapes
+
+### Cause sentence (used by morning round and chase-progression)
+
+Given a deal's state, produces one short sentence that names the most likely cause of the stall. The skill picks the pattern that fits the observable signals, not the one that sounds most dramatic. Examples:
+
+- "Mortgage offer expires in 9 days and the survey was booked but not done."
+- "Searches outstanding at day 28; solicitor last contacted day 14."
+- "Vendor unresponsive since day 12; buyer's broker has chased twice."
+
+If no pattern fits, the sentence reads "no clear cause from connectors, manual check recommended". The skill never invents a cause it cannot trace to data.
+
+### Variance paragraphs (used by month-end-close)
+
+Given the period's reconciliation totals and the two comparison periods (prior month, same month last year), produces two paragraphs in plain language with no jargon. Example:
+
+> April was GBP 8,400 down on March because three completions slipped into May, all expected to land. The reconciliation matched cleanly otherwise; the only variance was a GBP 120 referral deduction on the Norton sale.
+>
+> Year-on-year April is 15% up on the same month last year. The increase came from two completions over GBP 8,000 fee value, both new instructions taken in February.
+
+The paragraphs are suitable to paste into a board update, a tax-return cover note, or a conversation with a partner.
+
+## Voice source
+
+Reads the profile's voice samples and the operator's prior narrative paragraphs. Learns from edit-before-approve diffs.
+
+## What it does not do
+
+- It does not write outgoing messages. That is `tone-matched-drafter`.
+- It does not produce numerical totals. The calling workflow passes the numbers in; this skill writes the prose around them.
+- It does not write to the CRM or the accounting platform.
+
+## Connectors
+
+Read: profile (voice samples, narrative voice). No writes.
+
+## Profile keys
+
+- `realagent.voice_samples`
+- `realagent.close.narrative_voice_samples`
+- `realagent.cause_phrases`

package/payload/premium-plugins/real-agency/plugins/loop/skills/vendor-research/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: vendor-research
+description: "Public-record and CRM-history lookup on a vendor, with the profile's privacy line enforced. Used in valuation-prep, in new-instruction AML staging, and in chase-progression when a vendor goes silent. Surfaces useful context; flags sensitive signals separately."
+---
+
+# Vendor research
+
+A cross-cutting building-block skill. Looks the vendor up across the sources the platform has access to and returns a structured summary with the privacy line applied.
+
+## What it looks at
+
+- Land Registry: ownership history, joint owners, transactions
+- The agency's CRM history with this vendor and with the property
+- Council planning portal: planning applications and decisions for the property
+- The portal record if the property has been listed before
+- Public probate registry where relevant
+- Public news sources via the deep-research tool when the brief warrants it
+
+## The privacy line
+
+The profile holds a privacy preference. Default behaviour:
+
+- **Surface.** Ownership and planning history.
+- **Flag-but-suppress.** Deaths registered against the address, ownership changes that correlate with bereavement, planning disputes, anything that the agent could not quote in the appointment without harming their reputation.
+
+The flag-but-suppress signals are not deleted; they are summarised at the top of the output as "n suppressed signals exist on this address, available on request". The operator can say "show me everything you find" to see them, or "drop the sensitive stuff" to remove the heading entirely.
+
+## Output shape
+
+A structured summary with:
+
+- How long the vendor has owned
+- Last purchase price
+- Joint owners on the title
+- Planning history (one-line per material event)
+- Prior listings (agent, asking price, sold or withdrawn)
+- CRM history with this agent
+
+Plus the suppressed-signal heading if any apply.
+
+## What it does not do
+
+- It does not draft anything to send to the vendor. That is `tone-matched-drafter`.
+- It does not produce a valuation. That is `pricing-scenario-builder`.
+- It does not write to the CRM. The calling workflow stores anything it wants kept.
+
+## Connectors
+
+Read: Land Registry, planning portal, CRM, portal data, probate registry, deep-research tool. No writes.
+
+## Profile keys
+
+- `realagent.privacy_line.surface` (list of signal types)
+- `realagent.privacy_line.suppress` (list of signal types)