opencode-knowledge-work 0.0.0-stage → 0.1.1

package/content/small-business/skills/small-business-crm-autopilot/reference/gotchas.md

@@ -0,0 +1,110 @@
+# Gotchas
+
+Edge cases where the `crm-autopilot` skill is most likely to produce bad CRM data. Each entry uses the Good / Bad pattern.
+
+---
+
+## Gotcha: Creating a duplicate contact when the email is already in HubSpot under a different case
+
+**Why it matters:** HubSpot dedupes on exact email match. `Sarah.Lin@acme.com` and `sarah.lin@acme.com` are treated as distinct, but an owner who already created one will see a silent duplicate appear. That destroys the owner's trust in the skill.
+
+### ✗ Bad
+
+> Searched HubSpot for `Sarah.Lin@acme.com` — no match. Creating new contact: Sarah Lin (Sarah.Lin@acme.com).
+
+New contact is created; owner's existing `sarah.lin@acme.com` contact now has a duplicate.
+
+### ✓ Good
+
+> Searched HubSpot for `sarah.lin@acme.com` (case-insensitive) — no match. Creating new contact: Sarah Lin (sarah.lin@acme.com). Announcing before write.
+
+Always normalize email to lowercase before lookup. Announce the creation so the owner can catch misses.
+
+---
+
+## Gotcha: Writing the full email thread as the activity body
+
+**Why it matters:** HubSpot activities are signal surfaces for fast scanning, not a transcript archive. A 12-message thread pasted into the activity body is useless; a three-sentence summary of what was agreed is actionable.
+
+### ✗ Bad
+
+> **Activity body:**
+> *From: Sarah Lin — Thu Apr 9…*
+> *Hi! Following up on our call, here are the specs we discussed…*
+> *[1,200 more words]*
+
+Owner scrolls past it every time.
+
+### ✓ Good
+
+> **Activity body:** Sarah confirmed scope for Q2 expansion — 50 seats, USD 18K ACV, start date June 1. She'll send the signed SOW by Friday. No open questions.
+
+Summary names the decisions, the numbers, and the next step.
+
+---
+
+## Gotcha: Auto-creating a deal when the right one can't be resolved
+
+**Why it matters:** Duplicate deals are very hard to untangle in HubSpot — they split activity history, confuse reporting, and the owner usually notices weeks later when a forecast looks wrong.
+
+### ✗ Bad
+
+> No open deal found for Sarah Lin at Acme. Creating new deal: "Acme — new opportunity" and logging the call to it.
+
+Now there are two Acme deals and the owner has no idea which one is real.
+
+### ✓ Good
+
+> No open deal found for Sarah Lin at Acme. Which deal should I log this to? Options: (1) Acme Q2 Expansion (closed-won Feb), (2) Acme Renewal 2027 (open). Or do you want to skip logging for now?
+
+Ask. Never create a deal on behalf of the owner.
+
+---
+
+## Gotcha: Resolving against an empty portal
+
+**Why it matters:** A brand-new HubSpot portal returns zero contacts and zero deals, and every resolution step then "fails" in a way that reads like a data problem. The skill starts proposing contacts to create and deals to log against, and the owner ends up with a CRM seeded by a logging run instead of by their own setup.
+
+### ✗ Bad
+
+> No contact found for sarah@acme.com. Creating contact. No open deal found — which deal should I log this to? (none listed)
+
+The portal has nothing in it. There is no deal to pick.
+
+### ✓ Good
+
+> Your CRM has no contacts or deals yet — it looks brand new. I can keep this call log in the spreadsheet CRM until it is populated (on HubSpot, I can also start its own setup). Which?
+
+Check the counts first (Step 3). An empty portal is a setup question, not a resolution problem. Do not use `get_user_details`' `onboarded` flag as the test: a portal full of contacts can still report `onboarded: false`. The flag says whether HubSpot's guided setup ran, not whether there is data.
+
+---
+
+## Gotcha: Proposing a deal stage change based on email language
+
+**Why it matters:** "We're moving forward" in an email doesn't always mean "advance to closed-won." Customers say it when they're moving forward with evaluation, or with a procurement step. Owners have context the skill doesn't. Auto-advancing stage is destructive to the pipeline.
+
+### ✗ Bad
+
+> Email from Sarah says "we're moving forward." Proposing `dealstage` → Closed Won. Writing now.
+
+### ✓ Good
+
+> Flagging: the Apr 18 email from Sarah ("we're moving forward with the Anthropic evaluation") may indicate stage movement. Current stage is "Proposal Sent." Do you want to advance it? I won't change stage without your explicit go-ahead.
+
+Surface the evidence, hold the write.
+
+---
+
+## Gotcha: Overwriting an owner-set next-step during cleanup
+
+**Why it matters:** The owner may have set a next step that reflects context the skill can't see — a phone call, a Slack thread, a private note. Overwriting it because a recent email suggests something different erases real work.
+
+### ✗ Bad
+
+> `hs_next_step` currently says "wait for legal review." Latest email from Sarah says "let's schedule pricing review." Updating `hs_next_step` to "schedule pricing review."
+
+### ✓ Good
+
+> `hs_next_step` currently reads "wait for legal review" (set by you 3 days ago). The Apr 19 email from Sarah suggests a pricing review is also needed. Propose appending or replacing? Current → Proposed: "wait for legal review" → "wait for legal review; then schedule pricing review." Approve?
+
+Show the current value, propose the change explicitly, wait for approval.

package/content/small-business/skills/small-business-crm-autopilot/reference/hubspot-fields.md

@@ -0,0 +1,62 @@
+# HubSpot fields and activity types
+
+The specific HubSpot objects, properties, and activity types the `crm-autopilot` skill reads from and writes to. Only the fields listed here are in-scope for this skill — everything else in HubSpot is untouched.
+
+## Contacts — write
+
+| Field         | Usage                                                                                  |
+|---------------|----------------------------------------------------------------------------------------|
+| `email`       | Primary identifier for lookup + dedupe. Always set on creation.                        |
+| `firstname`   | Set from email signature or calendar invite if available. Leave blank if unknown.      |
+| `lastname`    | Set from email signature or calendar invite if available. Leave blank if unknown.      |
+| `company`     | Set from email signature domain or calendar organization if available.                 |
+
+Do not write any other contact properties. Owner, lifecycle stage, and lead source are user-managed fields — never overwrite.
+
+## Contacts — read (for lookup)
+
+| Field         | Usage                                                              |
+|---------------|--------------------------------------------------------------------|
+| `email`       | Search key. Case-insensitive exact match.                          |
+| `firstname` · `lastname` · `company` | Displayed to the user during ambiguity resolution. |
+| `hs_object_id`| Used for association with deals and activities.                    |
+
+## Deals — read (all cleanup + resolution paths)
+
+| Field                       | Usage                                                    |
+|-----------------------------|----------------------------------------------------------|
+| `dealname`                  | Displayed to the user; used for fuzzy match against email/meeting topic |
+| `dealstage`                 | Read-only during cleanup — flag discrepancies, never change |
+| `amount`                    | Read during cleanup; flag if recent email/meeting implies change |
+| `closedate`                 | Read during cleanup; flag if outdated                    |
+| `hs_next_step`              | Read + propose updates during cleanup                    |
+| `hubspot_owner_id`          | Displayed to the user; never changed                     |
+| `notes_last_updated`        | Used to detect stale deals. This is HubSpot's "Last Activity Date" on the deal object. There is no `hs_lastactivitydate` property — do not look for one |
+| Associated contacts         | Used to determine whether recent email/meeting participants are on the deal |
+
+## Deals — write (cleanup path only, with approval)
+
+| Field           | Rule                                                             |
+|-----------------|------------------------------------------------------------------|
+| `hs_next_step`  | Propose updates; write only with explicit user approval          |
+| `closedate`     | Propose updates; write only with explicit user approval          |
+| `amount`        | Propose updates; write only with explicit user approval          |
+| Contact assoc.  | Propose adding missing deal participants; write only with approval |
+
+**Never write** `dealstage`, `pipeline`, `hubspot_owner_id`, or any custom property during cleanup. Those are owner-managed.
+
+## Activities — write
+
+| Activity type                  | Used by        | Fields set                                                               |
+|--------------------------------|----------------|--------------------------------------------------------------------------|
+| Email engagement (`EMAIL`)     | Email path     | `hs_email_subject` (thread subject), `hs_email_text` (summary, not full thread), `hs_timestamp` (latest message time), associated contact(s) + deal |
+| Call engagement (`CALL`)       | Call path      | `hs_call_title` (event title), `hs_call_body` (summary), `hs_call_duration` (from calendar), `hs_timestamp` (event start), associated contact(s) + deal |
+| Note (`NOTE`)                  | Cleanup path   | `hs_note_body` (when flagging something for future review that doesn't fit a field update) |
+
+Use HubSpot's standard engagement vocabulary. Do not invent custom activity types.
+
+## Association rules
+
+- Every activity must associate to the deal AND to at least one contact.
+- If a contact is created on-the-fly during activity logging, associate it to the deal in the same operation so the activity shows up on both the contact and deal timelines.
+- Do not associate a contact to a deal during an activity-logging flow unless the contact is actually a participant in that email thread or meeting.

package/content/small-business/skills/small-business-crm-autopilot/reference/lightweight_crm.md

@@ -0,0 +1,125 @@
+# The Lightweight CRM
+
+For owners with no CRM at all — a large share of this segment. Telling them to go buy HubSpot is not an answer, and it is the point where the skill would otherwise stop being useful.
+
+Build them one in a spreadsheet or Notion and maintain it exactly the same way.
+
+---
+
+## Where it lives
+
+**Google Sheets or Excel** — the default. Every owner can open it, share it, and take it with them.
+
+**Notion** — when they already use it. Better for notes, worse for anything numeric.
+
+**Monday.com** — when they already use it, and the strongest of these three. Board items act
+as records, per-column updates work, and the contact timeline already holds emails, calls,
+meetings and notes. Read and write both. If the owner is in Monday.com daily, maintaining
+their boards beats building a sheet they will forget to open.
+
+**A local file** — when nothing is connected. Still works.
+
+Ask once, then stop asking.
+
+---
+
+## Structure
+
+Four tabs. Resist adding more — every extra field is one that goes stale and makes the sheet feel like homework.
+
+### Contacts
+
+| Column | Notes |
+|---|---|
+| Name | |
+| Company | |
+| Email | |
+| Phone | |
+| Role | |
+| First seen | Date |
+| Last contact | Auto-updated on every logged activity |
+| Notes | |
+
+### Deals
+
+| Column | Notes |
+|---|---|
+| Deal | Short name the owner recognizes |
+| Company | |
+| Contact | |
+| Value | |
+| Stage | Keep it to four: New, Quoted, Won, Lost |
+| Next step | The single most important column |
+| Next step date | |
+| Last activity | Auto-updated |
+| Source | How they found the business |
+| Notes | |
+
+**Four stages, not eight.** Owners without a CRM do not need a pipeline taxonomy; they need to know what to do next. More stages means more records sitting in the wrong one.
+
+### Activity
+
+| Column | Notes |
+|---|---|
+| Date | When it happened, not when it was logged |
+| Type | Email, call, meeting, note |
+| Contact | |
+| Deal | |
+| Summary | Three to five lines |
+| Next step set | Yes or no |
+
+Append only. Never edit history — this tab is the record the owner relies on when they cannot remember what was agreed.
+
+### Queue
+
+A filtered view, not a fourth data set: every open deal with no next step, or with a next-step date in the past. This is the tab the owner actually opens.
+
+---
+
+## Maintaining it
+
+Identical to the HubSpot path. Same modes, same approval gates, same rules.
+
+- Log activity from email, calendar, and transcripts
+- Update Last contact and Last activity automatically
+- Propose field changes, never write stage or value without approval
+- Draft follow-ups on quiet deals
+- Keep the queue current
+
+The only real difference is that resolving a contact means matching a row rather than searching an API. Match on email address first, then on name and company — and when it's ambiguous, ask rather than guessing. A wrongly merged row is harder to unpick in a spreadsheet than in a CRM.
+
+---
+
+## Introducing it
+
+Do not present this as a downgrade. For most of these owners it is the first time their pipeline has existed anywhere but their head.
+
+```
+You don't have a CRM connected, so I'll build you one in Sheets. Four tabs —
+contacts, deals, activity, and a queue of what needs a next step.
+
+It's not a toy. I'll keep it current the same way I would HubSpot: log your
+calls and emails automatically, draft follow-ups when a deal goes quiet, and
+flag anything with no next step. And it exports cleanly if you ever move to
+a real CRM.
+```
+
+The last sentence matters. Owners avoid spreadsheet systems because they fear being stuck in one.
+
+---
+
+## When to suggest they upgrade
+
+Only when the data says so, and only once:
+
+- More than about 150 open deals
+- More than one person needing to edit at the same time
+- They start asking for reporting the sheet cannot do
+
+```
+You're at 180 open deals and Teri's editing this too. That's about where a
+spreadsheet starts costing you more than it saves. Worth a look at HubSpot —
+everything here exports straight in.
+```
+
+Say it once. Do not repeat it. An owner who has decided against a CRM has usually decided for a reason, and nagging is how a useful skill becomes an annoying one.

package/content/small-business/skills/small-business-crm-autopilot/reference/salesforce-fields.md

@@ -0,0 +1,122 @@
+# Salesforce objects, fields, and activity types
+
+The Salesforce objects and fields the `crm-autopilot` skill reads and writes,
+and how it reaches them. Only the fields listed here are in scope; everything
+else in the org is left alone.
+
+**Source of these names.** Standard-object API names, plus the Headless 360
+tool contract Salesforce published. Any operation name `discover` returns is
+the truth over this file.
+
+---
+
+## How the connector works
+
+Salesforce is reached through the Headless 360 server, which the owner adds
+as a custom connector (it has a per-org address and its own OAuth client, so
+it is not in the plugin manifest). It exposes four tools, and every step in
+this skill is the same three-beat flow:
+
+1. `discover` — say what you need in plain words ("find a contact by email",
+   "open opportunities with no recent activity", "log a completed call").
+   It returns ranked operations.
+2. `describe` — the one you pick. Read its parameters and any ordered steps
+   before calling. Never skip this: parameter names are the operation's,
+   not this file's.
+3. `dispatch_readonly` for any read; `dispatch` only for the one write the
+   owner approved. `dispatch` runs as the signed-in user with that user's
+   access, and there is no delete operation, which matches this skill's
+   first gate.
+
+Shape notes are in `../../../shared/connector-call-shapes.md`.
+
+---
+
+## Contacts — write (`Contact`)
+
+| Field | Usage |
+|---|---|
+| `Email` | Primary identifier for lookup and dedupe. Always set on creation. |
+| `FirstName` | From the email signature or calendar invite if available. |
+| `LastName` | Required by Salesforce. From the signature or invite; if unknown, ask before creating — do not invent one. |
+| `AccountId` | Set only when the company is unambiguous (an existing Account matching the email domain). Otherwise leave blank and say so. |
+
+Do not write any other contact field. `OwnerId`, `LeadSource`, and any custom
+field are user-managed.
+
+## Contacts — read (for lookup)
+
+| Field | Usage |
+|---|---|
+| `Email` | Search key. Salesforce email matching is case-insensitive. |
+| `FirstName` · `LastName` · `Account.Name` | Shown to the owner during ambiguity resolution. |
+| `Id` | The `WhoId` on any activity logged against this person. |
+
+A person may exist as a `Lead` rather than a `Contact` (unconverted). Search
+both by email, with `IsConverted = false` on the Lead side — a converted lead's
+row persists and would otherwise match beside the Contact it became. A match
+on an unconverted `Lead` is reported as a lead, and the activity is
+logged with `WhoId` = the lead's `Id` **and no `WhatId`** — Salesforce
+rejects an activity that names a Lead and an Opportunity together. Say the
+deal is unset and that it attaches once the lead is converted.
+
+## Opportunities — read (all cleanup and resolution paths)
+
+| Field | Usage |
+|---|---|
+| `Name` | Shown to the owner; fuzzy-matched against the email subject or meeting title |
+| `StageName` | Read-only during cleanup — flag discrepancies, never change |
+| `Amount` | Read during cleanup; flag if a recent email or meeting implies a change |
+| `CloseDate` | Read during cleanup; flag if in the past on an open opportunity |
+| `NextStep` | Read, and propose updates during cleanup |
+| `OwnerId` → `Owner.Name` | Shown to the owner; never changed |
+| `IsClosed` | Open-pipeline filter |
+| `LastActivityDate` | Stale-deal detection. Set by completed Tasks and Events; **null on a record with no logged activity ever** — treat null as the quietest deal, not as "no data" |
+| `OpportunityContactRoles` (subquery) | Whether the email or meeting participants are on the opportunity. A child object, not a column: `SELECT Id, (SELECT ContactId, Role FROM OpportunityContactRoles) FROM Opportunity WHERE Id = ...` |
+
+## Opportunities — write (cleanup path only, with approval)
+
+| Field | Rule |
+|---|---|
+| `NextStep` | Proposed from the extracted next step; written only on approval |
+| `CloseDate` | Proposed when the evidence names a date; written only on approval |
+| `StageName`, `Amount` | **Never written by this skill.** Flag and defer; stage drives the forecast the owner reports to other people |
+
+Never create an Opportunity unprompted. Never close one.
+
+## Activities — write
+
+| Activity | Object | Fields |
+|---|---|---|
+| Call | `Task` | `Subject`, `Description` (the summary, never the transcript), `ActivityDate` (the real date), `Status` = Completed, `TaskSubtype` = Call, `WhoId` (contact or lead), `WhatId` (opportunity) |
+| Email | `Task` | Same, `TaskSubtype` = Email |
+| Meeting | `Event` | `Subject`, `Description`, `StartDateTime` and `EndDateTime` (the real times), `WhoId`, `WhatId` |
+
+`WhoId` takes a Contact or Lead `Id`; `WhatId` takes an Opportunity or Account
+`Id`. Either may stand alone: a deal-only activity (`WhatId` set, no `WhoId`) is
+valid, and so is a contact-only one. The single constraint is that a Lead
+`WhoId` requires an empty `WhatId`. An activity with neither is orphaned and
+invisible from the deal; if the deal cannot be resolved, log against the
+contact and say the deal is unset.
+
+## Association rules
+
+- A contact joins an opportunity through `OpportunityContactRole`; propose
+  adding a participant who is on the email or meeting but not on the
+  opportunity, never add silently.
+- A contact's company is `AccountId`. If the email domain matches exactly one
+  Account, propose it; if it matches none or several, leave it blank and say
+  so.
+
+---
+
+## What the Salesforce path cannot do here
+
+- **Delete.** No operation exists; the skill never wanted one.
+- **Arbitrary joins in one read.** SOQL covers parent lookups (contact →
+  account, opportunity → account) and one level of child subquery (an
+  opportunity's contact roles); anything wider is two reads, and the report
+  says so.
+- **Bypass the user's own access.** `dispatch` runs as the signed-in owner.
+  A field they cannot edit in Salesforce cannot be edited from here either,
+  and the error is reported as that, not as a plugin failure.

package/content/small-business/skills/small-business-crm-autopilot/reference/standing_mode.md

@@ -0,0 +1,144 @@
+# Standing Mode
+
+The scheduled sweep. This is what turns the skill from a tool the owner remembers to use into one that keeps the CRM current on its own.
+
+---
+
+## What a run does
+
+1. Pull everything since the last run — sent and received mail with external contacts, completed calendar events, new call transcripts
+2. Resolve each to a contact and a deal
+3. Log the activity
+4. Extract structured fields and propose updates
+5. Find deals that have gone quiet and draft the next touch
+6. Refresh the next-step queue
+7. Report what needs the owner
+
+Record the run timestamp so the next sweep knows where to start. Re-logging the same meeting twice is a visible error and it clutters the record the owner relies on.
+
+---
+
+## Extracting from a call transcript
+
+The highest-value input in this whole skill. A recorded sales call contains everything the owner would otherwise type from memory three days later, badly.
+
+Pull these:
+
+| Field | What to look for |
+|---|---|
+| Next step | What was agreed, and by when. Usually said in the last two minutes |
+| Owner of the next step | Whether it's on the owner or the customer |
+| Budget signal | Any number mentioned, even in passing |
+| Timeline | Dates, seasons, "before the end of the quarter" |
+| Objection | What they pushed back on. Often the most useful field |
+| Other people | Anyone named who wasn't on the call — they're usually a decision-maker |
+| Competitor mentioned | Who else they're talking to |
+
+**Quote the objection verbatim.** A paraphrase loses the thing that made it useful. "It's not the price, it's that we'd have to shut down the floor for two days" is a specific problem the owner can solve. "Had concerns about implementation" is not.
+
+Write the summary in three to five lines. The transcript stays available; the summary is what gets read.
+
+```
+Call summary — Ridgeline, Jul 27, 34 min
+
+Dana confirmed all six buildings, wants one plan not per-building. Budget
+signal: "we paid around 8 last time" (that was 2 units, not 6).
+
+Objection, her words: "the part I can't sell upstairs is another vendor
+changeover — last one was a mess."
+
+Next step: Ray sends the proposal by Wed. Dana loops in Priya (facilities
+director, wasn't on the call) before they decide.
+```
+
+Everything in that summary either changes what the owner does next or explains why the deal might not close.
+
+---
+
+## Finding quiet deals
+
+A deal is quiet when it has no activity in 14+ days, or its close date has passed and it's still open.
+
+Rank by what's at stake — value first, then how long it's been silent. An owner will act on three quiet deals and ignore a list of twenty.
+
+**Draft the next touch, don't just flag it.** A flag creates work. A draft removes it.
+
+Ground each draft in what actually happened last: the last exchange, what was promised, what was left open. "Following up on our conversation" is the generic version and it converts poorly. "You were going to check with Priya on the changeover timing — any word?" is a real message.
+
+Read [the shared voice profile](../../../shared/voice-profile.md) so drafts sound like the owner. Every one waits for approval.
+
+---
+
+## The next-step queue
+
+Every open deal needs three things: an owner, a next action, and a date. Deals missing any of them are the ones that quietly die.
+
+Surfacing them is most of the value in a standing run:
+
+```
+No next step set — these are the ones that go quiet:
+  Fairmount Commercial   USD 9,400   last activity Jul 11
+  Delta Park             USD 22,000  last activity Jul 19
+```
+
+Two lines, and the owner can fix both in a minute.
+
+---
+
+## The standing-run report
+
+Lead with what needs the owner. Never open with a list of everything logged — that reads as noise and trains them to skip it.
+
+```
+## CRM — since Monday
+
+### Needs you
+
+  3 follow-ups drafted on quiet deals — Ridgeline, Corwin & Bay, Delta Park.
+  Review and send?
+
+  Fairmount close date passed Jul 18 and it's still open. Push the date, or
+  mark it lost?
+
+### Logged automatically
+
+  11 emails · 4 meetings · 2 call transcripts across 9 deals
+
+### Proposed field updates
+
+  Ridgeline    next step: proposal by Wed (from Thursday's call)
+  Corwin & Bay budget: ~USD 9,400 mentioned (from Tuesday's email)
+
+### No next step set
+
+  Fairmount USD 9,400 · Delta Park USD 22,000
+```
+
+The owner reads the first section and acts. Everything below it is there for when they want to check.
+
+---
+
+## Cadence
+
+Daily is usually too often — there isn't enough new activity and the report becomes noise the owner stops opening.
+
+Twice a week or weekly fits most businesses. Match it to how often they actually talk to customers.
+
+Ask once at setup, then leave it alone:
+
+```
+Weekly on Monday, or twice a week? Weekly works for most people — daily
+ends up being a lot of empty reports.
+```
+
+---
+
+## What standing mode must never do on its own
+
+- Change a deal stage. It drives forecasts the owner reports to other people.
+- Close or mark a deal lost.
+- Create a deal.
+- Send a follow-up.
+- Delete anything.
+
+Everything on that list gets proposed and waits. The point of a standing run is that the owner can ignore it for a week without anything irreversible happening.