opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/small-business/skills/small-business-brand-style/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: brand-style
+description: >
+  Sets and updates the owner's brand look and output preferences, which every
+  page and document the plugin produces then follows automatically. Captures
+  the brand from a pasted website link or a plain-words description — never a
+  hex code, color picker, or upload — previews it on a sample page, asks how
+  they want their outputs delivered (visual artifacts, Word docs, markdown, Notion pages,
+  Canva Docs, or best-for-the-skill), and saves both to the business profile. Runs inside
+  smb-onboard on first setup and stands alone forever after. Use when the
+  owner says "update my brand," "we rebranded," "change my colors," "make the
+  reports match our new look," "change how you give me reports," "I want Word
+  docs instead," or anything about the look or format of what the plugin
+  hands them.
+allowed-tools: Read, WebFetch
+---
+
+# Brand Style
+
+One place the owner controls how everything looks and how everything is
+delivered. Set once during onboarding, changed any time after with one
+sentence.
+
+## Step 1 — Show what is set now
+
+Read the `## Business context` block. If Brand colors, Logo, or Output
+preference exist, play them back in plain words first: "Right now your pages
+use a deep green and cream with your leaf logo, and you get visual pages.
+What's changing?" An owner updating one thing should not re-answer the rest.
+
+If nothing is stored yet (first run, usually inside `smb-onboard`), skip
+straight to capture.
+
+## Step 2 — Capture the brand, frictionlessly
+
+Two paths, both costing the owner almost nothing:
+
+- **A website link.** Fetch the site (WebFetch) and pull the logo URL,
+  primary brand colors (from the CSS, theme, or social-preview image), and
+  tagline. The owner does nothing but paste the link. Guidance in
+  [`../smb-onboard/reference/website-research.md`](../smb-onboard/reference/website-research.md).
+- **A plain-words description.** "Forest green and cream," "navy and warm
+  gray," "like a modern law firm." Translate the words to real colors
+  yourself.
+
+**Never ask for hex codes, color pickers, or file uploads.** Branding costs
+one pasted link or one spoken sentence, nothing more. "Skip" is always an
+answer and means the clean house default.
+
+## Step 3 — Preview before saving
+
+Render a small sample page as an HTML artifact in the house style
+(`../../shared/artifact-style.md`) with the candidate brand applied — a
+title, one stat tile, a short table, a status pill — so the owner sees the
+look on real components, not a color swatch. Ask one question: "Match?"
+
+If they adjust ("darker green," "less cream"), apply and re-preview. This
+loop is cheap; a wrong brand on every future page is not.
+
+## Step 4 — Ask how outputs should arrive
+
+The six-way choice, as a multiple choice (skip if the owner only came to
+change colors and the preference is already stored):
+
+1. **Visual artifacts** — styled pages viewed right here (the default)
+2. **Word docs** — DOCX files to download
+3. **Markdown** — plain .md files to download
+4. **Notion** — pages created in their Notion workspace (needs the Notion connector; ask where in the workspace they should land)
+5. **Canva** — Canva Docs created in their Canva account (needs the Canva connector; if it is connected, run `list-brand-kits` and ask once which brand kit to apply, or none; if not, the first skill that delivers to Canva asks)
+6. **Best for the skill** — each skill picks what fits its job
+
+Store the answer verbatim as one of: `visual artifacts`, `docx`, `md`,
+`notion`, `canva`, `best for skill`. If they pick Notion or Canva and that
+connector is not connected, store it anyway, say deliverables fall back to
+visual artifacts until it is connected, and offer to help connect it.
+
+## Step 5 — Save, with approval
+
+Show what will be stored — Website, Brand colors, Logo, Output preference,
+and Canva brand kit (name and id) when the preference is Canva — and wait
+for the yes. Then update only those fields in the
+`## Business context` block, using the exact field names in
+[`../smb-onboard/reference/onboard-checklist.md`](../smb-onboard/reference/onboard-checklist.md).
+Never touch the other fields, and never overwrite silently.
+
+Close with the effect, not the mechanics: "Done — every page and document
+from here on uses the new look."
+
+## What not to do
+
+- **Do not ask for hex codes, pickers, or uploads.** One link or one
+  sentence, always.
+- **Do not re-run the whole interview.** This skill changes look and
+  delivery, nothing else — an owner who says "update my brand" is not
+  signing up for onboarding again.
+- **Do not save without the preview and the yes.** A brand applied to every
+  future page deserves one confirmation.
+- **Do not restyle old deliverables.** The change applies from now on;
+  never claim past documents were updated.
+
+## After the update
+
+One line on what changed. The natural next step is seeing it live: offer
+"Monday brief" (`/monday-brief`) or "how's the business doing?"
+(`business-pulse`) so the first branded page arrives immediately. Never more
+than three offers; never repeat one declined this session.

package/content/small-business/skills/small-business-build-agent/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: build-agent
+description: >
+  Turns a task the owner keeps doing by hand into a named, reusable skill they
+  can trigger by name or put on a schedule. Watches them do it once or listens
+  to them describe it, works out what varies and what stays fixed, writes the
+  skill with approval checkpoints in the right places, registers it with the
+  router, and shares it with the team. This is how a business gets a workflow
+  nobody shipped for them. Use this whenever the owner describes something
+  repetitive they wish were automatic — including phrasings like "I do this
+  every week," "can you remember how to do this," "make this a thing I can just
+  ask for," "build me an agent," "automate this for me," "turn this into a
+  workflow," or "I want this to happen every Monday." Reach for it when they
+  describe a routine, even without asking for automation.
+allowed-tools: Read, WebFetch
+---
+
+# Build Agent
+
+Turn something the owner does every week into something they ask for by name.
+
+This is what keeps the plugin from having to ship every industry's workflow. No catalog can cover a septic contractor's permit routine or an insurance agency's carrier commission reconciliation. Those owners can build them.
+
+## Step 1 — Watch it happen, or hear it described
+
+Two starting points, and the first is much better.
+
+**Best: they just did it in this conversation.** If the owner has walked through the task with you — pulled the files, made the decisions, corrected you twice — that transcript is the specification. Extract it rather than re-interviewing them. The corrections they made are the most valuable part, because they encode judgment the owner would never have thought to state.
+
+**Otherwise: they describe it.** Ask them to walk through the last time they did it, concretely. Real specifics beat an abstract description every time — "last Tuesday I pulled the carrier file, matched it against what we'd booked, and chased six discrepancies" tells you more than "I reconcile commissions."
+
+Read `reference/capture.md` for how to get a complete picture without an interrogation.
+
+## Step 2 — Separate what varies from what stays fixed
+
+This is the whole craft of the step. A skill that hardcodes last Tuesday's specifics only works on last Tuesday.
+
+For each part of the task, decide:
+
+- **Fixed** — the sequence, the sources, the output format, the rules
+- **Varies** — dates, names, amounts, which file, which customer
+- **Judgment** — the parts where the owner decides, which become approval gates
+
+The corrections the owner made while walking through it usually mark the judgment points. When someone says "no, not that one — we skip anything under USD 50," that is a rule. When they say "hmm, depends," that is an approval gate.
+
+## Step 3 — Find the approval gates
+
+Every step that sends, spends, publishes, or deletes needs a gate. So does every step where the owner hesitated.
+
+Do not gate everything — a skill that asks permission nine times is worse than doing it by hand. Gate the consequential and the ambiguous, and let the rest run.
+
+Read `reference/skill_authoring.md` for where gates belong and how to phrase them.
+
+## Step 4 — Write it
+
+Produce a real skill in the same shape as everything else in this plugin: a `SKILL.md` with frontmatter and numbered steps, plus a `reference/` folder if the detail warrants it.
+
+Requirements it must meet, same as every shipped skill:
+
+- Name and folder match, lowercase with hyphens
+- Description says what it does **and** when to trigger, in third person
+- A real fallback for when a connector is missing
+- Approval gates on anything consequential
+- Never invents a number; missing data is reported as missing
+
+**Write it in the owner's terms, not in generic business language.** If they call it "the carrier file," the skill says carrier file. A skill full of unfamiliar vocabulary is one they will not trust to run unattended.
+
+## Step 5 — Test it on a real case, before they rely on it
+
+Run the new skill against a case the owner already knows the answer to — ideally the exact one they walked through. Show the output next to what they got by hand.
+
+This is the step that determines whether the skill gets used. An owner who has seen it reproduce a known-good result will schedule it. One who hasn't will run it manually and check it every time, which saves nothing.
+
+If it doesn't match, fix the skill and run it again. Do not ask the owner to accept a near-miss.
+
+## Step 6 — Register and set the cadence
+
+Add it to `smb-router` so plain-English requests reach it, and record the trigger phrases the owner actually uses.
+
+If it is a recurring task, offer to schedule it. Scheduling is what converts "a skill I could run" into "something that happens without me," which is the outcome they wanted.
+
+## Step 7 — Share it, with approval
+
+Offer to share with the team. Say what sharing means: who gets it, what data it can reach, and what it can do unattended.
+
+**Be specific about the risk when a skill sends, spends, or writes.** A skill that emails customers, running for someone who did not build it and does not know its assumptions, is a real hazard. Recommend draft-only for shared skills that send anything.
+
+## What not to do
+
+- **Do not re-interview about a task they just walked through.** The transcript is the spec.
+- **Do not hardcode the example.** Names, dates, and amounts vary; the sequence does not.
+- **Do not gate every step.** Nine approvals is worse than doing it by hand.
+- **Do not skip the test run.** An untested skill gets checked manually forever, which saves nothing.
+- **Do not write it in generic business language.** Their words, or they won't trust it.
+- **Do not build something that sends or spends without approval gates.** Ever, regardless of what the owner asks for.
+
+## After the build
+
+The owner now has a named skill they can trigger or schedule. If the new skill hit a tool that isn't connected, "connect to my ERP" (`build-connector`) is the natural next step — it turns the missing system into a working source. Also nearby: "brief me" to fold the new output into the daily picture, and "Monday brief" if the skill should feed the weekly one. Offer at most three, and skip any offer the owner already declined this session.
+
+## Reference files
+
+- `reference/capture.md` — getting a complete picture of the task without an interrogation
+- `reference/skill_authoring.md` — the structure, frontmatter, and where approval gates belong
+- `reference/gotchas.md` — the failure modes that produce a skill nobody uses

package/content/small-business/skills/small-business-build-agent/reference/capture.md

@@ -0,0 +1,133 @@
+# Capturing the Task
+
+The goal is a complete picture without an interrogation. Owners abandon this halfway through if it feels like filling in a form.
+
+---
+
+## Best case: they just did it
+
+If the task was walked through in this conversation, the transcript is the specification. Do not start over with questions.
+
+Extract:
+
+- **The sequence** — what happened, in order
+- **The sources** — every file, system, or place data came from
+- **The decisions** — every point where a judgment was made
+- **The corrections** — everywhere the owner said "no, actually"
+
+**The corrections are the most valuable part.** They encode rules the owner would never have thought to state, because to them it is obvious. "No, skip anything under USD 50" is a business rule that would not have surfaced in any interview.
+
+Then confirm the shape in one pass rather than many:
+
+```
+Here's what I think this is:
+
+  1. Pull the carrier commission file from the monthly email
+  2. Match each line against what's booked in the CRM
+  3. Flag anything off by more than USD 5
+  4. Draft a chase email per discrepancy, one per carrier
+  5. You review and send
+
+Rules I picked up: skip anything under USD 50. Anything over USD 500 you want to
+look at yourself before it's chased.
+
+Right?
+```
+
+One block, one question.
+
+---
+
+## Otherwise: ask about the last time
+
+An abstract description produces an abstract skill. Anchor to a specific instance:
+
+```
+Walk me through the last time you did this. What did you open first?
+```
+
+Then follow the actual sequence. Ask what happened next, not what usually happens.
+
+The questions that produce the most useful answers:
+
+- What did you open first?
+- Where did that number come from?
+- What would make you stop and think here?
+- What went wrong the last time this went badly?
+- What would you never want this to do on its own?
+
+**The last two matter most.** The failure mode and the hard limit are what turn a fragile automation into one the owner will let run unattended.
+
+---
+
+## What to capture, checklist
+
+```
+Task:        <what the owner calls it>
+Trigger:     <what makes them do it — a date, an email, a request>
+Frequency:   <weekly, monthly, ad hoc>
+Sources:     <every system, file, or inbox involved>
+Sequence:    <steps, in order>
+Rules:       <thresholds, exclusions, exceptions>
+Judgment:    <where they decide, not the process>
+Output:      <what exists at the end, and who sees it>
+Never:       <what it must not do on its own>
+Time:        <how long it takes by hand — this is the ROI number>
+```
+
+The Time line is worth asking for explicitly. "Two hours every Monday" is what the owner will repeat when someone asks whether this was worth it — that number is worth keeping.
+
+---
+
+## How much to ask
+
+Three to five questions, maximum, before showing a draft.
+
+An owner who wanted to save two hours a week will not spend forty minutes specifying a skill. Get to a draft fast — a wrong draft is easier to correct than a blank page, and the correction produces better information than the question would have.
+
+```
+That's enough to build a first version. Let me draft it and you tell me what's
+wrong — faster than me guessing at more questions.
+```
+
+---
+
+## When the task is too big
+
+Some described tasks are really four tasks. "Manage my whole month-end" is not one skill.
+
+Say so, and propose the split:
+
+```
+That's really three things: reconciling the accounts, chasing the gaps, and
+writing the summary. Building it as one skill means it breaks in ways that are
+hard to find.
+
+Want to start with the reconciliation? It's the part that takes longest, and
+the other two get easier once it exists.
+```
+
+Start with the piece that takes the most time by hand. Momentum matters more than completeness here — an owner with one working skill builds three more.
+
+---
+
+## When the task shouldn't be a skill
+
+Sometimes the honest answer is that a shipped skill already covers it, or that the task varies too much to automate.
+
+Say so plainly:
+
+```
+This is close to what `invoice-chase` already does. Want me to look at whether
+it covers your case before we build something new?
+```
+
+Or:
+
+```
+Every one of these seems to go differently. I could build something that
+handles the common shape, but you'd still review each one — which is most of
+the work. Worth it, or would a checklist serve you better?
+```
+
+Building an unnecessary skill costs the owner trust when it fails, and it clutters the router for every future request.

package/content/small-business/skills/small-business-build-agent/reference/gotchas.md

@@ -0,0 +1,204 @@
+# Gotchas
+
+Failure modes that produce a skill nobody uses, or one that does damage unattended.
+
+---
+
+## Gotcha: re-interviewing about a task they just walked through
+
+**Why it matters:** The owner spent twenty minutes doing the task with you. Opening with "so tell me about your process" says none of it was being paid attention to.
+
+### Bad
+
+```
+Owner: "That was great — can you remember how to do that?"
+Claude: "Sure! Let's start by understanding your workflow. What systems do
+        you use for commission data?"
+```
+
+### Good
+
+```
+Claude: "Here's what I think this is: [the sequence, the rules picked up from
+        the corrections]. Right?"
+```
+
+The transcript is the specification. The corrections are the business rules.
+
+---
+
+## Gotcha: hardcoding the example
+
+**Why it matters:** A skill built around last Tuesday works exactly once. The owner runs it next month, gets nonsense, and never opens it again.
+
+### Bad
+
+```
+Pull the Continental commission file for June and match against the
+34 policies booked.
+```
+
+### Good
+
+```
+Pull the current month's carrier commission file from the statement email.
+Match every line against policies booked in the CRM for that period.
+```
+
+Fixed: the sequence, the sources, the rules. Varies: the month, the carrier, the counts.
+
+---
+
+## Gotcha: gating every step
+
+**Why it matters:** A skill that asks nine times is slower than doing the task manually. The owner stops running it and cannot articulate why.
+
+### Bad
+
+Approval before pulling the file, before matching, before flagging, before drafting, before each email.
+
+### Good
+
+Gate the sends and the ambiguous judgment calls. Let reading, matching, computing, and drafting run:
+
+```
+6 chase emails, one per carrier, USD 2,340 in discrepancies, from your address.
+Send them?
+```
+
+One gate, at the consequential moment.
+
+---
+
+## Gotcha: a vague gate
+
+**Why it matters:** "Ready to proceed?" asks the owner to approve something invisible. The first time it goes wrong, every gate in the plugin loses credibility.
+
+### Bad
+
+```
+I've prepared the emails. Ready to proceed?
+```
+
+### Good
+
+State the count, the recipients, the amounts, and the account it sends from. Consent needs to be informed to be worth anything.
+
+---
+
+## Gotcha: skipping the test run
+
+**Why it matters:** An owner who hasn't seen the skill reproduce a known-good answer will check its output manually every time. That saves nothing, and eventually they stop running it.
+
+### Bad
+
+Build it, register it, tell them it's ready.
+
+### Good
+
+Run it against the case they walked through, and show both:
+
+```
+Ran it on June's file — the one you just did by hand.
+
+Found the same 6 discrepancies, same amounts. It also flagged a 7th at USD 61
+on the Meridian file that you skipped. Was that deliberate, or worth adding
+to the rules?
+```
+
+That last question is how the skill gets a rule it was missing.
+
+---
+
+## Gotcha: generic business language
+
+**Why it matters:** A skill written in vocabulary the owner doesn't use feels like it belongs to someone else. They won't trust it to run unattended, which was the whole point.
+
+### Bad
+
+```
+Reconcile revenue recognition variances against booked commitments.
+```
+
+### Good
+
+```
+Match the carrier file against what's booked and flag anything off by more
+than USD 5.
+```
+
+---
+
+## Gotcha: a shared skill that sends
+
+**Why it matters:** A skill that emails customers, run by someone who didn't build it and doesn't know its assumptions, is a genuine hazard. The owner sharing it is not thinking about that.
+
+### Bad
+
+```
+Shared with your team.
+```
+
+### Good
+
+```
+Sharing this with Teri and Marcus. Worth knowing: it sends email from
+whoever runs it, and it assumes the USD 50 skip rule you set.
+
+Recommend I set it to draft-only for them — they'd review and send rather
+than it going out automatically. Your call.
+```
+
+---
+
+## Gotcha: building a skill that already exists
+
+**Why it matters:** A duplicate clutters the router, competes for triggers with the shipped skill, and will be maintained by nobody.
+
+### Bad
+
+Build "chase unpaid invoices" from scratch.
+
+### Good
+
+```
+This is close to what `invoice-chase` already does. Want me to check whether
+it covers your case before we build something new?
+```
+
+---
+
+## Gotcha: one skill that's really four
+
+**Why it matters:** A skill covering an entire month-end process breaks in ways that are hard to isolate, and a skill the owner can't debug is one they abandon.
+
+### Bad
+
+Accept "automate my month-end" as a single skill.
+
+### Good
+
+Name the split and start with the heaviest piece:
+
+```
+That's three things: reconciling, chasing the gaps, and writing the summary.
+Want to start with the reconciliation? It's the part that takes longest, and
+the others get easier once it exists.
+```
+
+---
+
+## Gotcha: no fallback
+
+**Why it matters:** A skill that requires a connector the owner might lose access to is a skill that breaks silently. This audience changes tools constantly.
+
+### Bad
+
+The skill assumes the carrier portal connector exists.
+
+### Good
+
+```
+No connector for your carrier portal. Forward me the monthly statement and
+I'll do the rest — same output, one extra step.
+```