# 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.