---
name: new-instruction
description: "Run the post-win onboarding sequence after a valuation is won. Drafts terms of business, books photographer and floorplan supplier, drafts listing copy and PDF particulars, schedules portal launch, and drafts the vendor welcome. Each write action is individually gated. Triggers when the operator says 'set up <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 CRM marks a property as instructed."
---

# New instruction

The master workflow that takes a property from "instruction won" to "on the portal" inside 72 hours. Owned jointly by the valuer (until terms are signed) and the negotiator (from photography onward).

Done well, this workflow is the second-highest-value moment in the agent's week after winning the instruction itself. The speed compounds: faster on-market means more viewings in the first weekend, which is when offers happen.

## Inputs

- The property address.
- The vendor name and contact details (read from the CRM record created at the appointment).
- The fee structure agreed at the appointment, captured verbally by the operator or read from the diary notes.
- The customisation profile.

If any input is missing, the workflow asks once and then proceeds with the rest staged.

## Architecture principles encoded here

- Read before write. The workflow opens by reading the property's CRM state and the calendar. It writes nothing until the operator approves each individual stage.
- Stage, don't send. Every write action is staged, not fired. Eight gates in total, each individually approved.
- One screen of output. The sequenced checklist is one screen even when every item is staged. Each item collapses to a status line.
- Cite the source. Every populated field in the terms of business, the listing copy, and the particulars traces to a CRM record, a profile entry, or a connector read.
- Teach the profile. Learning hooks below.
- Reversible. Every staged item can be cancelled before approval. Approved items create CRM activity records the operator can rescind.

## Sequence and approval gates

The workflow presents the seven steps in order. The operator can approve them one at a time, approve everything ("ship everything"), or pause and return later. State is preserved between sessions.

1. **Terms of business.** Drafted by `terms-of-business-drafter` from the agency template, populated with property, vendor, fee structure, sole or multi agency, marketing period, withdrawal fee. Staged in DocuSign with the vendor as recipient. *Gate: approve before send.*
2. **Photographer booking.** `supplier-booker` drafts a booking request to the agent's preferred photographer with the property address, vendor contact, and the agent's standard brief. *Gate: approve before send.*
3. **Floorplan booking.** Same as photography. Combined into a single booking request if the same supplier handles both. *Gate: approve before send.*
4. **Listing copy.** Drafted by `listing-copy-writer` in the agent's voice, length, and structure from the profile. Headline, key features bullets, full description, location paragraph. Optimised for the profile's portals. *Gate: approve before any portal upload.*
5. **Particulars.** PDF brochure built by `particulars-builder`. The skill chains into the Maxy `content-producer` for the PDF render so the agency brand is applied consistently. Staged for the agent's review and the vendor's review before any wider distribution. *Gate: approve distribution before send.*
6. **Portal launch schedule.** `portal-launch-scheduler` proposes the launch sequence (Rightmove premium on a Friday by default; learns). Staged, not fired. *Gate: approve schedule before any portal upload happens.*
7. **Vendor welcome email.** Drafted by `tone-matched-drafter` explaining what happens next, what to expect, when to expect photos, who will be in touch. *Gate: approve before send.*

## AML and material information

AML on the vendor must be passed 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, and the rest of the DMCCA 2024 fields) is gathered into the listing copy. Missing items are flagged before the operator approves the copy. `compliance-flag-checker` runs against every output of this workflow before approval.

## Continuous learning hooks

- Supplier preferences. If the operator routinely overrides the suggested photographer, EPC supplier, floorplan supplier, or AML provider, the new preferred supplier is learned.
- Copy voice and length. Edit-before-send diffs on the listing copy feed `listing-copy-writer`. Within a month, drafts should need minimal editing.
- Launch timing. Friday morning is a heuristic default. If the agent consistently launches on a different day, around school holidays, around area events, or around a sale calendar, the scheduler picks that up.
- Particulars structure. Section order, photo count, whether the floorplan goes early or late, whether the location paragraph leads or trails, all adapt.
- Fee structure drift. A single override is a one-off. Three same-direction overrides in a month update the profile's default fee logic.

All writes go through `profile-writer`.

## Connectors

Read: CRM, calendar, profile.
Write: DocuSign (terms), email (vendor welcome, supplier bookings), portal upload APIs (Rightmove, Zoopla, OnTheMarket, staged only).

## Profile keys

- `realagent.fee_structure.default` (sole or multi, percentage, minimum)
- `realagent.fee_structure.withdrawal_fee`
- `realagent.fee_structure.marketing_period_weeks`
- `realagent.suppliers.photographer`
- `realagent.suppliers.floorplan`
- `realagent.suppliers.epc`
- `realagent.suppliers.aml_provider`
- `realagent.listing_copy.length_words` (target word count, learned)
- `realagent.listing_copy.section_order`
- `realagent.particulars.template_path`
- `realagent.portal_launch.preferred_day` (default Friday)
- `realagent.portal_launch.preferred_time`
- `realagent.portal_launch.rightmove_tier` ("standard" | "premium" | "premium_listing")
