client-communication-engine

What this skill does

# Client Communication Engine

This skill handles all outgoing communication from the accounting firm to its clients. It produces professional Greek-language letters, summaries, and notifications — the documents and emails that clients actually receive. Every piece of outgoing communication follows Greek business correspondence conventions, references the correct regulatory terminology, and is drafted for human review before anything is sent.

The skill pairs with `greek-email-processor` (Skill 4), which handles inbound. Together they form the complete communication layer: Skill 4 reads the inbox, Skill 16 writes the outbox.


## Setup

```bash
export OPENCLAW_DATA_DIR="/data"
export SMTP_HOST="smtp.your-provider.com" # e.g. smtp.gmail.com, smtp.outlook.com
export SMTP_USER="[email protected]"
export SMTP_PASSWORD="app-specific-password"
which jq curl || sudo apt install jq curl
```

SMTP credentials are required for sending client correspondence. All communications are drafted locally and require human review and approval before sending. Use app-specific passwords.


## Core Philosophy

- **Draft First, Send Second**: Nothing is sent automatically. Every communication is drafted, shown for review, and requires explicit approval before dispatch. This applies to all communication types without exception
- **Greek Business Standards**: Output matches what a professional Greek accounting firm would send — correct formal register, appropriate regulatory terminology, proper salutations and closings for Greek business correspondence
- **Data-Driven Content**: Letters are generated from real system data — actual submission reference numbers, actual VAT amounts, actual deadlines. Nothing is fabricated or approximated
- **Logged Against Client Record**: Every sent communication is recorded in `/data/clients/{AFM}/correspondence/` with timestamp, type, recipient, and content hash. The firm always knows what was said to whom and when
- **Context-Aware Tone**: Document request letters are polite but clear. Deadline reminders escalate appropriately (informative → reminder → urgent → critical) without being aggressive. Submission confirmations are formal and precise
- **Language Boundary**: Communications to clients are in Greek. Internal summaries and draft previews shown to firm staff are in English. The skill never sends English to a Greek client

---

## OpenClaw Commands

### Drafting Communications
```bash
# Draft a submission confirmation letter
openclaw comms draft --type submission-confirmation --afm EL123456789 --filing-type VAT --period 2026-01
openclaw comms draft --type submission-confirmation --afm EL123456789 --filing-type EFKA --period 2026-01

# Draft a monthly accounting summary
openclaw comms draft --type monthly-summary --afm EL123456789 --period 2026-01
openclaw comms draft --type monthly-summary --afm EL123456789 --period 2026-01 --include-statements

# Draft a document request
openclaw comms draft --type document-request --afm EL123456789 --missing "bank-statements" --period 2026-01
openclaw comms draft --type document-request --afm EL123456789 --missing "october-invoices,payroll-hours" --deadline 2026-02-20
openclaw comms draft --type document-request --afm EL123456789 --from-pending-list  # auto-reads pending.json

# Draft a deadline reminder
openclaw comms draft --type deadline-reminder --afm EL123456789 --deadline-type VAT --due-date 2026-02-25
openclaw comms draft --type deadline-reminder --afm EL123456789 --deadline-type VAT --due-date 2026-02-25 --urgency critical
openclaw comms draft --type deadline-reminder --all-clients --deadline-type VAT --due-within 7-days

# Draft an annual tax summary
openclaw comms draft --type annual-tax-summary --afm EL123456789 --year 2025
openclaw comms draft --type annual-tax-summary --afm EL123456789 --year 2025 --include-e1-status

# Draft a payment reminder (for clients with outstanding fees to the firm)
openclaw comms draft --type payment-reminder --afm EL123456789 --invoice-ref INV-2026-001

# Free-form draft with prompt
openclaw comms draft --type custom --afm EL123456789 --prompt "inform client that their ENFIA property tax instalment is due next month and we need their payment confirmation"
```

### Reviewing Drafts
```bash
# List all pending drafts
openclaw comms drafts-list --all
openclaw comms drafts-list --afm EL123456789
openclaw comms drafts-list --type document-request --pending-approval

# Preview a draft (English summary of Greek content)
openclaw comms preview --draft-id D20260218-001
openclaw comms preview --draft-id D20260218-001 --language el  # Show full Greek text

# Edit a draft before approval
openclaw comms edit --draft-id D20260218-001 --field body --instruction "add mention of the EFKA deadline also due this month"
openclaw comms edit --draft-id D20260218-001 --field tone --value formal  # formal / professional / urgent
```

### Approving and Sending
```bash
# Approve and send a single draft
openclaw comms send --draft-id D20260218-001 --approved-by "yannis.k"

# Approve and send all drafts for a client
openclaw comms send --afm EL123456789 --all-pending --approved-by "yannis.k"

# Send via email (default)
openclaw comms send --draft-id D20260218-001 --via email --approved-by "yannis.k"

# Export as PDF for manual sending (no email integration configured)
openclaw comms send --draft-id D20260218-001 --via pdf-export --approved-by "yannis.k"

# Batch send — e.g. deadline reminders to all affected clients
openclaw comms batch-send --type deadline-reminder --deadline-type VAT --due-within 7-days --approved-by "yannis.k"
```

### Correspondence History
```bash
# View sent communications for a client
openclaw comms history --afm EL123456789 --last 30-days
openclaw comms history --afm EL123456789 --type document-request --year 2026
openclaw comms history --afm EL123456789 --full  # All time

# Firm-wide communication log
openclaw comms log --period 2026-01 --type all --format table
openclaw comms log --period 2026-01 --unsent-drafts  # Drafts that were created but never sent

# Check if a specific type of communication has been sent recently
openclaw comms check-sent --afm EL123456789 --type submission-confirmation --filing-type VAT --period 2026-01
```

### Template Management
```bash
# List available templates
openclaw comms templates-list
openclaw comms templates-list --type document-request

# Preview a template
openclaw comms template-preview --name "vat-submission-confirmation"

# Customise a template for a specific client (client-level override)
openclaw comms template-override --afm EL123456789 --template "monthly-summary" --field salutation --value "Αγαπητέ κ. Παπαδόπουλε,"
```

---

## Communication Templates

### 1. Submission Confirmation Letter

Sent after every successful government filing. References the actual AADE submission receipt.

```
[GREEK TEXT — rendered in Greek in the actual letter]

[Firm letterhead]
[Date in DD/MM/YYYY format]

Αγαπητέ / Αγαπητή [Client contact name],
[or: Αγαπητοί κύριοι, for company-addressed]

Σας ενημερώνουμε ότι ολοκληρώθηκε επιτυχώς η υποβολή της παρακάτω
φορολογικής δήλωσης για λογαριασμό σας:

Τύπος δήλωσης:   [e.g. Δήλωση ΦΠΑ]
Περίοδος:        [e.g. Θανουάριος 2026]
ΑΦΜ:             [EL123456789]
Αριθμός υποβολής: [AADE reference number]
Δμερομηνία υποβολής: [DD/MM/YYYY]
Ποσό πληρωτέο:   [€X,XXX.XX] (εάν υφίσταται)
Προθεσμία πληρωμής: [DD/MM/YYYY]

Για οποιαδήποτε απορία, παρακαλώ επικοινωνήστε μαζί μας.

Με εκτίμηση,
[Accountant name]
[Firm name]
[Contact details]
```

```yaml
English_Preview_Fields:
  type: "VAT Return Submission Confirmation"
  client: "Alpha Trading AE (EL123456789)"
  period: "January 2026"
  reference: "AAD-2026-001234"
  submitted: "24/01/2026"
  amount_due: "EUR 3,340.00"
  payment_deadline: "25/02/2026"
```

---

### 2. Monthly Accounting Summary

Sent at month-end. Provides the client with a plain-language overview of what happened to their accounts that month.

```yaml
Monthly_