# The Engagement System — How It Works A plain-language guide to Claude Cabinet's engagement module for managing ongoing client relationships. **Don't know where to start?** Run **`/engagement-help`** — it detects whether you're the consultant or the client, shows you exactly what you can do right now, and offers to run the next step for you. No need to memorize skill names. --- ## What is it? The engagement system turns your pib-db work backlog into a communication layer with your clients. Instead of emailing status updates manually or hoping the client remembers what you discussed on a call, you run one command (`/engagement-sync`) and each person on the engagement gets a personalized update showing exactly what needs their attention, what's in progress, and what's done — formatted for their role. It grew out of the handoff module (which handled one-time credential collection) into something broader: an ongoing engagement loop where work flows out as updates, and client feedback flows back as events on a timeline you can review at your own pace. --- ## Getting started Run **`/engagement-help`**. It detects your role automatically — you don't need to know which of the 9 skills to use. It reads the engagement config, checks what state things are in (fresh? mid-flight? feedback waiting?), and tells you exactly what's relevant right now. It also offers to run the next step for you, so it works as a launchpad. --- ## How the pieces fit together ### Who sees what An engagement has **recipients** — the people you're working with. Each has a **role**: - A **principal** sees everything: all client-visible work items, the billing running total, and all messages. They get the full picture. - A **delegate** sees only the items specifically assigned to them. No billing, no items outside their scope. They get a focused, relevant view — usually as a plain email rather than the full interactive experience. You control what appears in anyone's view using **tags** on your pib-db actions: | Tag | What it does | |-----|-------------| | `client-visible` | Opt-in. Without this, the action is internal and invisible to everyone. | | `audience:ed` | Only the named recipient(s) can see it — narrows even a principal. | | `scope:marketing` | Only recipients whose scope includes this topic (or the wildcard "all"). | | `assignee:sydney` | The sole basis for what a delegate sees. | | `needs:decision` | This item requires the client to choose from options. | | `needs:credential` | This item requires a secure credential capture. | Each client-visible action also carries a **client-facing copy block** — a title and explanation written for the client, separate from your internal notes. The client never sees the raw action text or your working notes. ### The trust boundary The client never sees your internal identifiers. Every item in a client's update is referenced by an opaque code (a hash). The mapping back to your real action IDs stays on your machine in a gitignored file that's never transmitted. When a client responds, their feedback comes back keyed by the opaque code — you resolve it locally. The system enforces this structurally. The update your client receives is built from scratch without internal IDs ever being added to it. A separate invariant check runs on every update before it can leave your machine — if anything leaked through, it throws and the update doesn't send. ### Previewing before sending `/engagement-sync` shows you a summary of what each recipient is about to receive **before** anything is dispatched: ``` Ready to send: Ed (principal, has Claude Code) — 2 need response, 4 in progress, 7 done, $4,417.50 billed Sydney (delegate, no Claude Code) — 1 assigned item (marketing) Blocked (not client-ready): 1 — "DNS cutover" (no client-facing copy) ``` You can drill into any recipient's full packet to read exactly what they'll see, then send, or cancel. Nothing goes out without your explicit confirmation. `/engagement-status` serves as a separate dry-run preview anytime — it renders what each recipient *would* receive right now, without dispatching anything. ### The feedback loop Client feedback flows back as events on the engagement timeline. When a client approves a decision, you see it and are *offered* (never forced) the option to update the action's status. When they object or ask a question, it shows up in your inbox. Neutral acknowledgment receipts are queued for your review before they reach the client. ### Billing If enabled, the engagement tracks billable hours from a markdown timelog. The running total appears only in a principal's update — never in a delegate's. Billing can be scoped by period: the full engagement total, the current month, or only hours since the last sync. **Invoicing.** `/collab-consultant invoice [YYYY-MM]` renders a clean invoice document from a month's tracked hours (defaults to the last full calendar month; `--itemized` for one line per timelog row instead of a single consolidated line). The document is built for upload to the operator's bank (Relay), whose "Create Invoice → Autofill from document" extracts the customer, line items, and total — so the document carries no invoice number and no From/bank block (Relay supplies those). It's written to `invoices/.html` with a best-effort PDF conversion. Relay defaults the due date to today, so the skill reminds you to set the Net-30 due date by hand after autofill. ### Credential handoff When a client needs to provide a secret (API key, token, password): 1. A secure OS dialog appears on their screen (not in the conversation). 2. They type it — it's encrypted immediately with the consultant's public key. 3. The encrypted envelope is sent back. 4. The consultant decrypts it on their machine via `/engagement-status`, which writes the plaintext to a private file they open in their own terminal. The decrypted value never enters Claude's context. --- ## All 9 skills at a glance | Skill | Who runs it | What it does | |-------|------------|-------------| | `/engagement-help` | Either | Detects your role and shows you what to do next | | `/engagement-create` | Consultant | Set up a new engagement (recipients, roles, billing, credentials, deploy) | | `/engagement-edit` | Consultant | Fix or update the config after creation | | `/engagement-add` | Consultant | Add a client-visible work item with tags + client-facing copy | | `/engagement-message` | Consultant | Send a free-text note to a recipient | | `/engagement-sync` | Consultant | Push updates to recipients (with preview + confirm) + pull feedback | | `/engagement-status` | Consultant | Dashboard: previews, feedback inbox, billing, tag warnings | | `/collab-consultant invoice` | Consultant | Render a month's invoice document for upload to Relay's autofill | | `/engagement` | Client | Review the latest update and respond | | `/engagement-progress` | Client | Quick glance — what's new, counts, read-only | --- ## Known limitations - **Single machine.** The engagement store (pib.db + the `engagement-packets/` archive) is local. Running sync from two different machines without syncing those files can produce inconsistent updates. - **No terminal state.** An engagement never "completes" — a credential checklist can finish without ending the engagement. Sync is re-runnable indefinitely. - **Credential decryption requires a desktop.** On Linux without `zenity`, the secure dialog can't appear and the system refuses rather than showing the secret on screen.