@installagent/sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/dist/agent-templates.d.ts +90 -0
  2. package/dist/agent-templates.js +211 -0
  3. package/dist/client-build.d.ts +50 -0
  4. package/dist/client-build.js +155 -0
  5. package/dist/client-context.d.ts +40 -0
  6. package/dist/client-context.js +70 -0
  7. package/dist/client-drive.d.ts +67 -0
  8. package/dist/client-drive.js +278 -0
  9. package/dist/client-intake.d.ts +68 -0
  10. package/dist/client-intake.js +189 -0
  11. package/dist/client-linear.d.ts +30 -0
  12. package/dist/client-linear.js +85 -0
  13. package/dist/docs-search.d.ts +44 -0
  14. package/dist/docs-search.js +187 -0
  15. package/dist/doctor.d.ts +43 -0
  16. package/dist/doctor.js +425 -0
  17. package/dist/env-file.d.ts +25 -0
  18. package/dist/env-file.js +69 -0
  19. package/dist/env-fill.d.ts +43 -0
  20. package/dist/env-fill.js +161 -0
  21. package/dist/env-push.d.ts +37 -0
  22. package/dist/env-push.js +137 -0
  23. package/dist/env-registry.d.ts +49 -0
  24. package/dist/env-registry.js +230 -0
  25. package/dist/exec.d.ts +14 -0
  26. package/dist/exec.js +16 -0
  27. package/dist/fathom-webhook.d.ts +44 -0
  28. package/dist/fathom-webhook.js +123 -0
  29. package/dist/fs-utils.d.ts +9 -0
  30. package/dist/fs-utils.js +34 -0
  31. package/dist/gcp-service-account-key.d.ts +37 -0
  32. package/dist/gcp-service-account-key.js +66 -0
  33. package/dist/gemini-api-key.d.ts +47 -0
  34. package/dist/gemini-api-key.js +132 -0
  35. package/dist/git.d.ts +16 -0
  36. package/dist/git.js +29 -0
  37. package/dist/github-token.d.ts +24 -0
  38. package/dist/github-token.js +30 -0
  39. package/dist/index.d.ts +25 -0
  40. package/dist/index.js +28 -0
  41. package/dist/init.d.ts +47 -0
  42. package/dist/init.js +101 -0
  43. package/dist/linear-project.d.ts +81 -0
  44. package/dist/linear-project.js +192 -0
  45. package/dist/new-client.d.ts +32 -0
  46. package/dist/new-client.js +89 -0
  47. package/dist/ping.d.ts +6 -0
  48. package/dist/ping.js +7 -0
  49. package/dist/portal-admin.d.ts +133 -0
  50. package/dist/portal-admin.js +144 -0
  51. package/dist/sync-templates.d.ts +58 -0
  52. package/dist/sync-templates.js +109 -0
  53. package/dist/template-sync.d.ts +55 -0
  54. package/dist/template-sync.js +90 -0
  55. package/dist/templates.d.ts +19 -0
  56. package/dist/templates.js +24 -0
  57. package/dist/wizard.d.ts +78 -0
  58. package/dist/wizard.js +213 -0
  59. package/package.json +30 -0
  60. package/templates/env.example +60 -0
  61. package/templates/workspace-root/.claude/settings.json +39 -0
  62. package/templates/workspace-root/AGENT.md +205 -0
  63. package/templates/workspace-root/AGENTS.md +11 -0
  64. package/templates/workspace-root/CLAUDE.md +63 -0
  65. package/templates/workspace-root/GEMINI.md +24 -0
  66. package/templates/workspace-root/ONBOARDING.md +164 -0
  67. package/templates/workspace-root/README.md +67 -0
  68. package/templates/workspace-root/skills/CLAUDE.md +79 -0
  69. package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
  70. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
  71. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
  72. package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
  73. package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
  74. package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
  75. package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
  76. package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
  77. package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
  78. package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
  79. package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
  80. package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
  81. package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
  82. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
  83. package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
  84. package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
  85. package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
  86. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
  87. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
  88. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
  89. package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
  90. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
  91. package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
  92. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
  93. package/templates/workspace-root/skills/linear/SKILL.md +186 -0
  94. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
@@ -0,0 +1,272 @@
1
+ ---
2
+ name: engagement-spec
3
+ description: >-
4
+ Turn a discovery call into the four engagement documents Install Agent
5
+ writes at the start of every build (client-facing overview, internal tech
6
+ spec, client-onboarding checklist, internal access-checklist tracker) AND
7
+ the matching onboarding.html for that client's build repo — pulling the
8
+ call itself via `ia client <slug>` rather than requiring a pasted
9
+ transcript. Runs twice per engagement: once after the sales discovery call
10
+ (first-pass fill, so a technician walks into the tech discovery call with
11
+ real context already on screen) and again after the tech discovery call
12
+ (update pass — fills remaining open questions, doesn't rewrite what's
13
+ already accurate). Use this WHENEVER you've just had or read a
14
+ discovery/scoping or tech-discovery call, or someone says "spec this out",
15
+ "write the overview", "draft the tech spec", "what do we need from the
16
+ client", "turn these call notes into a plan", "populate onboarding.html",
17
+ "scaffold the client repo from the call", or you're populating the docs/
18
+ folder inside a client-[slug]/ build folder. Reach for it even if the user
19
+ never says "skill". Client-facing language stays tech-agnostic; internal
20
+ docs name tools.
21
+ ---
22
+
23
+ # Discovery → engagement spec
24
+
25
+ Turn a discovery conversation into the three documents that start a build. The
26
+ input is messy (a transcript, bullet notes, a Slack hand-off from sales). The
27
+ output is a `docs/` folder a teammate — or the client — can read cold and know
28
+ exactly what we're building, how, and what we need to start.
29
+
30
+ This is the repeatable version of the write-up an engineer does after every
31
+ scoping call. The goal isn't to invent scope; it's to capture what was agreed,
32
+ make the implicit explicit, and surface the open questions before code is
33
+ written.
34
+
35
+ ## Output contract (read this first)
36
+
37
+ You produce up to four files inside the client's **build folder**
38
+ (`client-<slug>/docs/`, created per the client-project-kickoff cadence), and
39
+ you keep that same build folder's `onboarding.html` in sync:
40
+
41
+ | File | Audience | Tone | Purpose |
42
+ |---|---|---|---|
43
+ | `01-overview.md` | The client | Plain English, **tech-agnostic** | What we're solving, what we're building, what to expect. The doc you'd send them. |
44
+ | `02-tech-spec.md` | Install Agent engineering | Precise, **names tools** | The implementation: architecture, data shapes, node-by-node, error handling, open questions. This is `onboarding.html`'s source of truth per `client-template/AGENT.md` — if they disagree, fix the page. |
45
+ | `03-client-onboarding.md` | The client's admin/bookkeeper | Plain English, checklist | Access + decisions + info we need, split by "before kickoff" vs "during week 1". This is the **ask**. |
46
+ | `04-access-checklist.md` | Install Agent (internal) | Terse status table | Same items as `03`, plus a Status column (HAVE/REQUESTED/MISSING) — the fast answer to "what are we still waiting on?" This is the **tracker**, kept current as access lands. Mirror it into `onboarding.html`'s Client tab. |
47
+ | `onboarding.html` | A technician landing on the build cold | Scannable, tab per topic | Every `REPLACE_WITH_*` token filled from the same source material as `01`–`04` (step 6) — so the tech discovery call happens with real context already on screen, not a blank template. |
48
+
49
+ Look at the canonical exemplars before writing — match their depth and
50
+ structure, not their specific domain:
51
+
52
+ - `client-kingdom/docs/01-overview.md` — problem → what we're building (numbered
53
+ pipeline in plain words) → what the diagram shows → what to expect (with
54
+ measurable outcomes).
55
+ - `client-kingdom/docs/02-tech-spec.md` — architecture summary, normalized
56
+ schema, node-by-node, idempotency/reversal, error-handling table, security,
57
+ observability, **open questions for the build**, build sequence.
58
+ - `client-kingdom/docs/03-client-onboarding.md` — §1 Access (need before
59
+ kickoff), §2 Decisions (need before kickoff), §3 Information (week 1, not
60
+ blocking), §4 ongoing, §5 what we are NOT asking for, §6 quick-fill checklist.
61
+ - `04-access-checklist.md` has no Kingdom exemplar yet (added 2026-07) — follow
62
+ the template in `references/spec-templates.md`.
63
+
64
+ Templates you can paste from:
65
+ [`references/spec-templates.md`](references/spec-templates.md).
66
+
67
+ ## Before you start
68
+
69
+ - [ ] You have the raw material. Don't ask the human to paste a transcript —
70
+ pull it: `ia client <slug>` (the `ia-cli` skill) returns the registry
71
+ profile plus recent call notes read-only from `team-clients/`, newest
72
+ first. Each call file's frontmatter has a `type` (`discovery`,
73
+ `tech-discovery`, …) — use that to pick the right call for this pass
74
+ (see "Two passes" below). If there's no call on record yet, run the
75
+ **automation-design** skill first to scope it — this skill writes up a
76
+ scope, it doesn't invent one.
77
+ - [ ] You know the client slug and that a `client-<slug>/` build folder
78
+ exists — if not, `ia new-client <slug>` creates it from
79
+ `client-template` (empty, template tokens only; this skill fills them).
80
+ - [ ] You've skimmed the industry playbook for their vertical
81
+ (`team-web/apps/docs/content/docs/sales/industry-playbooks/<vertical>.mdx`) so
82
+ the overview speaks their language and the pain points ring true.
83
+
84
+ ### Two passes: discovery call vs. tech-discovery call
85
+
86
+ This skill runs **twice** per engagement, against two different calls in
87
+ `team-clients/clients/<slug>/calls/`:
88
+
89
+ 1. **After the sales discovery call** (`type: discovery`), run this skill
90
+ fresh against a just-scaffolded, empty build folder. Every doc and every
91
+ `onboarding.html` token gets its first, best-effort value — this is what
92
+ the technician sees walking into the tech discovery call.
93
+ 2. **After the tech discovery call** (`type: tech-discovery`), run this
94
+ skill again, against the *same* build folder, now already populated. This
95
+ is an **update, not a rewrite**:
96
+ - Fill anything still literally `REPLACE_WITH_*` — those are open
97
+ questions the first pass couldn't answer.
98
+ - For content already filled, update only what the tech call firms up,
99
+ corrects, or adds (a confirmed trigger, a newly-scoped item, a
100
+ resolved open question) — don't regenerate prose that's already
101
+ accurate just because you're touching the file.
102
+ - Leave anything a human has clearly hand-edited since the first pass
103
+ alone unless the tech call directly contradicts it.
104
+ - Move resolved items out of `02-tech-spec.md`'s open-questions list
105
+ rather than deleting the section.
106
+
107
+ ## Workflow
108
+
109
+ ### 1. Extract the five scoping answers
110
+
111
+ From the raw material, pin down the five questions from the **automation-design**
112
+ skill. If the call didn't answer one, it becomes an open question (don't guess
113
+ it into the spec):
114
+
115
+ 1. **Trigger** — what event starts the automation?
116
+ 2. **Success outcome** — the specific end state ("a categorized entry posted",
117
+ "a reply draft in the inbox").
118
+ 3. **Failure mode** — what's the worst case if it runs twice / mis-classifies /
119
+ times out? This drives the idempotency and error-handling sections.
120
+ 4. **Human in the loop** — what we automate vs. what we route for approval.
121
+ 5. **Volume** — items/day; decides polling-vs-webhook and per-item LLM cost.
122
+
123
+ ### 2. Draft `01-overview.md` (client-facing)
124
+
125
+ Structure: **the problem we're solving** (their words, their pain — quantify the
126
+ cost) → **what we're building** (a numbered pipeline in plain English) → **what
127
+ the diagram shows** (if a diagram exists; see the client-workflow-diagram skill)
128
+ → **what you can expect** (measurable outcomes, honestly hedged).
129
+
130
+ - **Stay tech-agnostic in body prose.** Name a tool only with a plain-language
131
+ gloss the first time, the way the Kingdom overview does: "**Plaid** (a
132
+ bank-data service)", "an **automation layer** (n8n)", "**Claude** (an AI
133
+ model)". The client cares about outcomes, not the stack.
134
+ - **Lead with outcomes, hedge honestly.** "After two-to-three weeks of pattern
135
+ learning, we'd expect 80%+ auto-filed" — a range with a ramp, not a promise.
136
+ - This is the doc you'd actually send. Read it back as the client.
137
+
138
+ ### 3. Draft `02-tech-spec.md` (internal)
139
+
140
+ Audience is Install Agent engineering — **name the tools, be precise.** Mirror
141
+ the Kingdom tech-spec sections that apply:
142
+
143
+ - **Architecture summary** + a small ASCII flow.
144
+ - **Normalized data schema** — the one shape every downstream node consumes
145
+ (define it once; nothing downstream touches the raw payload).
146
+ - **Node-by-node** walk of the workflow.
147
+ - **Idempotency** — both halves (filter at trigger + mark at end). Non-negotiable;
148
+ see the n8n-workflow and automation-design skills.
149
+ - **Error-handling table** — failure → behavior, per the three categories
150
+ (transient → retry, bad input → safe default, bug → fail loud).
151
+ - **AI specifics** — model id pinned, strict-JSON prompt, confidence threshold,
152
+ defensive parser fallback.
153
+ - **Security** — where credentials live, what gets scrubbed from logs.
154
+ - **Open questions for the build** — the things the call left unresolved. This
155
+ section is the most valuable; it prevents building on an assumption.
156
+ - **Build sequence** — the order you'll actually implement in.
157
+
158
+ ### 4. Draft `03-client-onboarding.md` (what we need from them)
159
+
160
+ The checklist that unblocks the build. Split by urgency so the client isn't
161
+ overwhelmed:
162
+
163
+ - **§1 Access (before kickoff)** — accounts/credentials we need, each with the
164
+ *minimum* role and how they grant it (OAuth, invite). State that credentials
165
+ go into *their* vault and we never take a password.
166
+ - **§2 Decisions (before kickoff)** — the choices only they can make (e.g.
167
+ confidence threshold, point of contact).
168
+ - **§3 Information (week 1, not blocking)** — exports, lists, edge cases to seed
169
+ rules.
170
+ - **§4 Ongoing** — review cadence, their time commitment, who owns what.
171
+ - **§5 What we are NOT asking for** — explicitly. Builds trust, prevents the
172
+ "why do you need my bank password" panic. (We never do.)
173
+ - **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
174
+
175
+ ### 5. Draft `04-access-checklist.md` (internal tracker)
176
+
177
+ Same items as `03-client-onboarding.md`'s §1 Access and §2 Decisions, reshaped
178
+ into one status table: **Item | System | Why we need it | Status | Notes**.
179
+ Status is one of HAVE / REQUESTED / MISSING / N/A — set it from what the call
180
+ notes and registry profile actually say was granted or promised, never
181
+ assumed. This is the doc (and the matching `onboarding.html` section) a
182
+ teammate opens to answer "what are we still waiting on from this client?"
183
+ without re-reading the call transcript. Update it in the same commit whenever
184
+ access lands — it decays fast otherwise.
185
+
186
+ - **Capture status, don't invent it.** If a call didn't confirm an item was
187
+ received, it's MISSING or REQUESTED, not HAVE.
188
+ - **No credential values or IDs** — status and the 1Password vault *name*
189
+ only (from `CLIENT.md`), same rule as everywhere else in the repo.
190
+ - Mirror the table into `onboarding.html`'s Client tab (a new "Access &
191
+ credentials checklist" section) so a developer sees it without opening
192
+ `docs/`.
193
+
194
+ ### 6. Populate `onboarding.html`
195
+
196
+ Fill every `REPLACE_WITH_*` token in the build folder's `onboarding.html`
197
+ from the same material you just used for `01`–`04` — don't leave it as the
198
+ bare template. The full token list (grouped by section, with which ones
199
+ repeat per list item) is in
200
+ [`references/spec-templates.md`](references/spec-templates.md#onboardinghtml-token-contract).
201
+ In short:
202
+
203
+ - **Overview/hero** (`CLIENT_NAME`, `SLUG`, `ENGAGEMENT_TITLE`,
204
+ `ONE_PARAGRAPH`, `PHASE`, `TZ`) — one line each, same facts as `01`'s
205
+ opening.
206
+ - **Client tab** (`BUSINESS`, `PROBLEM`, `OUTCOME`, the architecture-node
207
+ tokens, `TRIGGER`, `THRESHOLD`, `IDEMPOTENCY`, `INSTANCE`,
208
+ `STACK_NOTES`) — pulled straight from `02-tech-spec.md`'s architecture
209
+ summary and idempotency section. Repeating list tokens
210
+ (`SCOPE_ITEM`, `PARKED_ITEM`, `STEP`, `DONE_ITEM`, `NEXT_ITEM`) — one
211
+ `<li>` per item, duplicate the template's stub `<li>` as needed. The
212
+ access table (`ITEM`/`SYSTEM`/`REASON`/`NOTE`, one row per item) is the
213
+ `04-access-checklist.md` mirror already required in step 5.
214
+ - **Workflows tab** — one diagram block per automation in scope, duplicating
215
+ the template block (`WORKFLOW_TITLE`, `WORKFLOW_SLUG`, `STATUS`,
216
+ `TRIGGER`/`FILTER`/`AI_STEP`/`N`/`WRITE`/`NOTIFY` node labels, `CAPTION`).
217
+ Hand off to **client-workflow-diagram** if the SVG itself needs redrawing,
218
+ not just labels filled.
219
+ - **Proposals tab** — one row per proposal (`PROPOSAL_TITLE`, `STATUS`,
220
+ `DATE`, `CALL_FILE`, `FILENAME`), plus `COMMITMENT`/`EXCLUSION` list items
221
+ from the SOW.
222
+ - **Public tab** — the client-safe rewrite: tech-agnostic
223
+ `PUBLIC_SUMMARY`/`TODAY`/`AFTER`/`METRIC`, `PLAIN_STEP`+`PLAIN_DETAIL`
224
+ pairs (same pipeline as the Client tab's architecture nodes, no tool
225
+ names), `PUBLIC_DONE_ITEM`/`PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
226
+
227
+ If a list section has more real items than the template's stub `<li>`s,
228
+ duplicate the stub; if fewer, delete the extras — don't leave unfilled
229
+ tokens or empty bullets.
230
+
231
+ ### 7. Wire it together and check scope
232
+
233
+ - Confirm the docs agree (the overview's promises match the spec's build;
234
+ `04`'s items match `03`'s asks).
235
+ - Cross-check the **SOW**: the spec must not exceed what was sold. If it does,
236
+ flag it — that's a change order, not a build (per technician operations).
237
+ - If the overview or a pitch references a diagram, hand off to the
238
+ **client-workflow-diagram** skill.
239
+
240
+ ## Quality rules
241
+
242
+ - **Client-facing = tech-agnostic; internal = specific.** The split between
243
+ `01`/`03` (plain) and `02` (named tools) is the whole discipline. For
244
+ contracts/SOWs specifically, the **contract-tech-agnostic** skill governs.
245
+ - **Capture, don't invent.** Anything not said on the call is an *open question*
246
+ in the tech spec, not an assumed fact. Label inferences.
247
+ - **Measurable outcomes, honestly hedged.** Ranges and ramps, never guarantees.
248
+ - **Name the human in the loop.** Every spec states what is automated vs.
249
+ approved. Default to "suggest, don't act" for anything hard to undo.
250
+ - **No secrets, no client customer data** in committed docs (root AGENT.md). The
251
+ build folder holds the plan, not credentials.
252
+ - **Client-facing says Install Agent, never Rebar.**
253
+
254
+ ## Before you finish — checklist
255
+
256
+ - [ ] `01-overview.md`: problem → build (plain) → expectations (measurable,
257
+ hedged); no bare tool names without a gloss.
258
+ - [ ] `02-tech-spec.md`: schema, node-by-node, idempotency (both halves),
259
+ error table, AI specifics, **open questions**, build sequence.
260
+ - [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
261
+ / quick-fill; minimum roles; "creds in your vault, never a password".
262
+ - [ ] `04-access-checklist.md`: same items as `03`, Status column set from
263
+ what's actually confirmed (not assumed); mirrored into `onboarding.html`.
264
+ - [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
265
+ update pass, only the ones the tech-discovery call still hasn't
266
+ answered); Client tab agrees with `02`, not the other way around.
267
+ - [ ] If this is the update pass (post tech-discovery call): resolved open
268
+ questions moved out of `02`'s list, nothing already-accurate silently
269
+ regenerated, no hand-edited content overwritten without contradiction.
270
+ - [ ] Spec ⊆ SOW. Anything beyond scope is flagged, not silently built.
271
+ - [ ] Diagram handed off to client-workflow-diagram if referenced.
272
+ - [ ] No secrets / client customer data; client-facing branding is Install Agent.
@@ -0,0 +1,220 @@
1
+ # Engagement spec — paste-from templates
2
+
3
+ Skeletons for the three engagement docs. Fill the `<…>` placeholders. Delete
4
+ sections that don't apply; don't invent content to fill them. Match the depth of
5
+ the `client-kingdom/docs/` exemplars.
6
+
7
+ ---
8
+
9
+ ## `01-overview.md` (client-facing — tech-agnostic)
10
+
11
+ ```markdown
12
+ # <Project name> — Project Overview
13
+
14
+ **Prepared for:** <Client legal/dba name>
15
+ **Prepared by:** Install Agent
16
+ **Status:** Proposal, post-discovery
17
+
18
+ ---
19
+
20
+ ## The problem we're solving
21
+
22
+ <2–3 sentences in the client's own terms. Name the manual work, the cost of it,
23
+ and what gets worse under load (season, growth, volume spikes).>
24
+
25
+ ## What we're building
26
+
27
+ <One-paragraph plain-English summary, then a numbered pipeline. Name tools only
28
+ with a gloss: "Plaid (a bank-data service)", "an automation layer (n8n)",
29
+ "Claude (an AI model)".>
30
+
31
+ 1. <Trigger, in plain words>
32
+ 2. <Step>
33
+ 3. <Decision / the "have we seen this?" gate>
34
+ 4. <AI step, with a confidence idea>
35
+ 5. <Success outcome — what lands where>
36
+ 6. <Exception path — where unsure items go for a human>
37
+
38
+ <One sentence on the guarantee: nothing happens without matching a rule or
39
+ clearing a confidence bar; everything is logged.>
40
+
41
+ ## What the diagram shows <!-- if a diagram exists -->
42
+
43
+ <Name the stages the diagram lays out, left to right.>
44
+
45
+ ## What you can expect
46
+
47
+ <Measurable outcomes with a ramp and a range — never a guarantee. E.g. "After
48
+ 2–3 weeks of pattern learning, we'd expect 80%+ auto-filed, with the rest in a
49
+ daily review queue that shrinks as the system learns."><br/>
50
+ <Timeline to first value. What success looks like at day 30.>
51
+ ```
52
+
53
+ ---
54
+
55
+ ## `02-tech-spec.md` (internal — names tools)
56
+
57
+ ```markdown
58
+ # Tech Spec — <short system name>
59
+
60
+ **Audience:** Install Agent engineering. Internal.
61
+ **Status:** Pre-implementation, ready for build kickoff.
62
+ **Source diagram:** docs/<name>-diagram.html
63
+
64
+ ---
65
+
66
+ ## 1. Architecture summary
67
+ <Source of truth → orchestration → destination. Name every system + model id.
68
+ Small ASCII flow.>
69
+
70
+ ## 2. Normalized schema
71
+ <The single flattened shape every downstream node consumes. Define once. State
72
+ the sign/units conventions.>
73
+
74
+ ## 3. Workflow — node by node
75
+ <Trigger → normalize → dedup/idempotency → rules → AI fallback → write →
76
+ audit/log → exception. One short subsection per node.>
77
+
78
+ ## 4. Idempotency & replay
79
+ <Half 1: filter at trigger. Half 2: mark processed at end. Replay behavior.
80
+ Reversal/correction path if the source revises an item.>
81
+
82
+ ## 5. Exception review
83
+ <Where low-confidence / failed items go (alert channel + review queue). How a
84
+ human decision feeds back into the rules.>
85
+
86
+ ## 6. AI specifics
87
+ <Pinned model id, strict-JSON prompt location, confidence threshold, defensive
88
+ parser fallback, retry policy, rough per-call cost at expected volume.>
89
+
90
+ ## 7. Error handling
91
+ | Failure | Behavior |
92
+ |---|---|
93
+ | <transient: timeout/5xx/429> | retry next poll / backoff |
94
+ | <bad input: invalid JSON> | safe default, log, continue |
95
+ | <bug: config parse error> | halt + alert |
96
+
97
+ ## 8. Security
98
+ <Where credentials live; what's scrubbed from logs; transport; sharing scope.>
99
+
100
+ ## 9. Observability
101
+ <Audit log of record; daily/weekly digest; native dashboards.>
102
+
103
+ ## 10. Open questions for the build
104
+ <Everything the discovery call left unresolved. Resolve before coding.>
105
+
106
+ ## 11. Build sequence
107
+ <The order you'll implement: infra → fixtures → core nodes → rules → AI shadow →
108
+ write path → exception flow → prod cutover → tuning.>
109
+ ```
110
+
111
+ ---
112
+
113
+ ## `03-client-onboarding.md` (client-facing checklist)
114
+
115
+ ```markdown
116
+ # Client Onboarding Checklist — <Client name>
117
+
118
+ <One line: plan on a ~45-min working session; build can start once §1 + §2 are
119
+ done; §3 can come in parallel during week 1.>
120
+
121
+ ## 1. Access (need before kickoff)
122
+ <Per system: the minimum role, how they grant it (OAuth/invite), and that
123
+ credentials go into the client's own vault — we never take a password.>
124
+
125
+ ## 2. Decisions (need before kickoff)
126
+ <Choices only they can make: thresholds, point of contact, channel name.>
127
+
128
+ ## 3. Information (week 1 — not blocking)
129
+ <Exports, top-N lists, 30 days of history for shadow mode, edge-case examples.>
130
+
131
+ ## 4. During build — ongoing
132
+ <Review-call cadence, their time on the review queue, who approves changes.>
133
+
134
+ ## 5. What we are NOT asking for
135
+ <Explicit list: no bank passwords ever, no system password (OAuth only), no
136
+ access beyond the named systems.>
137
+
138
+ ## 6. Quick-fill checklist
139
+ - [ ] <access item invited/ready>
140
+ - [ ] <decision made>
141
+ - [ ] <contact + handle>
142
+ - [ ] <person available for live linking>
143
+ ```
144
+
145
+ ---
146
+
147
+ ## `04-access-checklist.md` (internal — status tracker)
148
+
149
+ ```markdown
150
+ # Access & Credentials Checklist — <slug>
151
+
152
+ Internal tracker: same items as `03-client-onboarding.md`'s §1 Access and §2
153
+ Decisions, plus what we actually have. `03` is the **ask** we send the
154
+ client; this file is the **tracker** — update it the moment access lands or a
155
+ decision gets made, so anyone can answer "what are we still waiting on?"
156
+ without re-reading the call notes. Mirror this table into `onboarding.html`'s
157
+ Client tab in the same commit.
158
+
159
+ No real credential values or IDs here — status and the 1Password vault
160
+ *name* only (see `CLIENT.md`).
161
+
162
+ Status legend: **HAVE** · **REQUESTED** (asked, not yet received) ·
163
+ **MISSING** (not yet asked, or blocking) · **N/A**
164
+
165
+ | Item | System | Why we need it | Status | Notes |
166
+ |---|---|---|---|---|
167
+ | <e.g. Portal login> | <e.g. Catalyte> | <what it unblocks> | MISSING | <who's chasing it, by when> |
168
+ | <e.g. EHR admin user> | <e.g. Lumary> | <what it unblocks> | REQUESTED | <date asked> |
169
+ | <e.g. Notification space> | <e.g. Google Chat> | <what it unblocks> | HAVE | <date confirmed> |
170
+ | <e.g. Data-handling agreement> | <BAA / DPA> | <legal gate before real data flows> | MISSING | <blocking real-data cutover> |
171
+
172
+ _Last updated: <date> — update in the same commit as any access change._
173
+ ```
174
+
175
+ ---
176
+
177
+ ## `onboarding.html` token contract
178
+
179
+ Every `REPLACE_WITH_*` token in `client-template/onboarding.html`, by
180
+ section. Tokens marked **(repeat)** are list items or table rows — duplicate
181
+ the template's stub markup once per real item; tokens with no mark appear
182
+ once (even if the same value is reused verbatim in more than one spot, e.g.
183
+ `SLUG` and `CLIENT_NAME`).
184
+
185
+ **Overview / hero** — `CLIENT_NAME`, `SLUG`, `ENGAGEMENT_TITLE`,
186
+ `ONE_PARAGRAPH`, `PHASE`, `TZ`.
187
+
188
+ **Client tab**
189
+ - Single: `BUSINESS`, `PROBLEM`, `OUTCOME`, `SOURCE`+`DETAIL` (source node),
190
+ `PIPELINE_STEP`+`DETAIL` (orchestration node), `DESTINATION`+`DETAIL`
191
+ (destination node), `EXCEPTION_PATH`, `TRIGGER`, `THRESHOLD`,
192
+ `IDEMPOTENCY`, `INSTANCE`, `STACK_NOTES`, `CLIENT_SPECIFIC_RULE`, `DATE`
193
+ (status-snapshot "as of").
194
+ - **(repeat)** `SCOPE_ITEM` (Phase 1 scope), `PARKED_ITEM`, `STEP` (build
195
+ order, numbered), `DONE_ITEM`, `NEXT_ITEM`.
196
+ - **(repeat, one row)** access table: `ITEM`, `SYSTEM`, `REASON`, `NOTE` —
197
+ the `04-access-checklist.md` mirror; Status is a badge class, not a token.
198
+
199
+ **Workflows tab** — one whole diagram block duplicated per automation in
200
+ scope:
201
+ - Single per block: `WORKFLOW_TITLE`, `STATUS`, `WORKFLOW_SLUG`, `CAPTION`.
202
+ - Single per node, inside the SVG: `TRIGGER`, `FILTER`, `AI_STEP`, `N`
203
+ (confidence number), `WRITE`, `NOTIFY`.
204
+
205
+ **Proposals tab**
206
+ - **(repeat, one row)** `PROPOSAL_TITLE`, `STATUS`, `DATE`, `CALL_FILE`
207
+ (paired with `SLUG`), `FILENAME`.
208
+ - **(repeat)** `COMMITMENT` (commitments card), `EXCLUSION` (exclusions
209
+ card).
210
+
211
+ **Public tab** (tech-agnostic — no tool names)
212
+ - Single: `CLIENT_NAME` (reused), `PUBLIC_SUMMARY`, `TODAY`, `AFTER`,
213
+ `METRIC`, `DATE` (reused, progress "as of").
214
+ - **(repeat, paired)** `PLAIN_STEP`+`PLAIN_DETAIL` — same pipeline as the
215
+ Client tab's architecture nodes, described without tool names.
216
+ - **(repeat)** `PUBLIC_DONE_ITEM`, `PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
217
+
218
+ If a repeating section has more real items than the template's stub
219
+ elements, duplicate the stub; if fewer, delete the extras. Never leave a
220
+ literal `REPLACE_WITH_*` string in a shipped page.
@@ -0,0 +1,158 @@
1
+ ---
2
+ name: house-voice
3
+ description: >-
4
+ Install Agent's house voice for anything client-facing — proposals, emails,
5
+ onboarding/leave-behind guides, web copy, ad copy, Slack replies to a
6
+ client. Patterns are pulled verbatim from the installagent.com landing
7
+ page, not invented: direct "you/your" address, plain concrete words over
8
+ jargon, confident on value but honestly hedged on numbers, the
9
+ name-the-objection-then-contrast structure, a one-word-verdict-then-explain
10
+ FAQ pattern, and a short list of signature phrases to reuse rather than
11
+ paraphrase. Use this WHENEVER writing or reviewing client-facing sentences,
12
+ or someone says "make this sound like us", "in our voice", "match the
13
+ website tone", "does this read on-brand", "tighten this copy", "too
14
+ jargon-y". Reach for it even without the word "skill". Position-agnostic —
15
+ sales, ops, and techs all write client-facing copy. Governs WORDS;
16
+ installagent-brand-kit governs visual brand; design-system governs screens.
17
+ ---
18
+
19
+ # House voice
20
+
21
+ How Install Agent sounds in writing, anywhere a client reads it. Pulled
22
+ directly from the copy on `installagent.com/get-started` — the fullest,
23
+ most deliberate expression of the voice we have — rather than guessed at.
24
+ The raw corpus with every quote in context is
25
+ [`references/source-copy.md`](references/source-copy.md); this file is the
26
+ distilled set of patterns to reuse.
27
+
28
+ This is the **words** layer. `installagent-brand-kit` governs color/logo on
29
+ documents, `design-system` governs color/type on screens — this skill
30
+ governs what the sentences themselves sound like, on either surface.
31
+
32
+ ## The five pillars
33
+
34
+ 1. **Direct address, second person.** Nearly every sentence talks to "you" —
35
+ your hours, your payroll, your business, your team. Never "the client" or
36
+ "users" in client-facing text.
37
+ 2. **Plain, concrete words over jargon.** "Automate your busywork," "hours
38
+ back every week," "inbox load," "response delays." Nothing is
39
+ "leveraged," "unlocked," or "seamless." See the word list below.
40
+ 3. **Confident on value, honestly hedged on specifics.** The value claims are
41
+ bold ("The result: hours back every week..."). The numbers and timelines
42
+ are ranged and qualified: "**Most clients** have their first automations
43
+ live **within the first several weeks**." Never a bare guarantee on a
44
+ number.
45
+ 4. **Name the objection, then contrast it.** "Why not just hire in-house?"
46
+ followed by a two-column comparison — the whole "Common Question"
47
+ section is this move. Don't argue around an objection; put it in the
48
+ reader's own words, then answer it point by point.
49
+ 5. **Short lists of three or four concrete items**, not sprawling bullet
50
+ dumps: "Inbox volume grows. Follow-ups slip. Invoices, updates, and
51
+ approvals pile up. Manual processes never get rebuilt."
52
+
53
+ ## Sentence-level moves worth reusing
54
+
55
+ - **The triple negative-then-positive**: "Not software you configure
56
+ yourself. Not a ticket queue. One qualified technician who..." Names what
57
+ you're *not*, twice, before landing the positive claim — it pre-empts the
58
+ reader's assumption.
59
+ - **Cause/effect pairs, stated flat**: "Revenue increases. Complexity
60
+ increases." Two short declaratives, no connective tissue, let the reader
61
+ draw the line between them.
62
+ - **Colon-led payoff**: "The result: hours back every week, work that
63
+ finishes itself, and expert AI help without the six-figure salary."
64
+ State the setup, colon, then the concrete payoff list.
65
+ - **FAQ = one-word verdict, then explain.** Every FAQ answer opens with
66
+ "Yes." or "No." before the explanation — never buries the verdict in the
67
+ middle of a paragraph.
68
+ - **Reuse signature phrases verbatim.** "At a fraction of the cost of a
69
+ full-time hire" appears (in some form) at least three times across the
70
+ page. That's deliberate repetition, not a rough draft — when a phrase like
71
+ this fits, reuse it exactly rather than inventing a synonym.
72
+ - **CTA specificity lowers friction.** "Watch what we do. **2 min.**" — give
73
+ the reader the actual cost (time, steps) of the next click, not just an
74
+ imperative verb.
75
+
76
+ ## Words we use / words we avoid
77
+
78
+ | Avoid (hype/jargon) | Use instead |
79
+ |---|---|
80
+ | leverage, utilize | use, run, put to work |
81
+ | seamless, frictionless | (usually just cut it — show the result instead) |
82
+ | synergy, ecosystem | — describe the actual connection |
83
+ | cutting-edge, revolutionary, game-changing | — let the concrete claim carry it |
84
+ | unlock, empower, supercharge, elevate | build, save, automate, run |
85
+ | turnkey, best-in-class, world-class (alone) | pair "world-class" with the concrete proof (IBM/Amazon/Google/Meta, hundreds of builds) — never let it stand alone |
86
+ | disrupt, paradigm shift | — say what actually changes for the reader |
87
+ | "AI-powered" as a selling point on its own | say what it *does* ("automates your busywork," "trained on your SOPs") |
88
+
89
+ Role vocabulary: the human-facing role is always **"technician"** — never
90
+ "agent," "bot," or "assistant" when describing who does the work for the
91
+ client. ("Agent" is fine as our company name and for internal/technical
92
+ references to an AI system itself.)
93
+
94
+ ## Structural devices worth stealing
95
+
96
+ - **Objection-as-question, then a compare table** — the "Why not just hire
97
+ in-house?" pattern. Use it whenever the copy needs to address a real
98
+ hesitation instead of ignoring it.
99
+ - **Named "layers"** — "Communication Layer," "Scheduling & Follow-Up
100
+ Layer," "Knowledge & Delegation Layer" — turning a list of automations
101
+ into named categories makes an amorphous "we automate stuff" concrete and
102
+ scannable.
103
+ - **Trust proof as facts, not adjectives** — "Trusted by 150+ business
104
+ owners," "worked at IBM, Amazon, Google, and Meta," "hundreds of
105
+ automation builds." A number or a named institution always beats an
106
+ adjective like "world-class" used alone.
107
+
108
+ ## Quick before/after
109
+
110
+ > Jargon draft: "Our AI-powered platform leverages seamless automation to
111
+ > unlock operational efficiency and empower your team."
112
+
113
+ > House voice: "We automate the busywork slowing your team down — inside
114
+ > the tools you already use."
115
+
116
+ ## Where this applies vs. where it doesn't
117
+
118
+ - **Applies**: proposals, executive overviews, onboarding checklists, the
119
+ client LLM-setup leave-behind guide, web/funnel copy, ad copy, client
120
+ emails and Slack messages.
121
+ - **Doesn't override**: `contract-tech-agnostic` (SOWs still describe
122
+ deliverables by function, not tool — house voice governs *tone*, not that
123
+ rule) or the plain-English/tech-agnostic split in `engagement-spec`
124
+ (house voice is the tone *within* whichever register — client-facing or
125
+ internal — that skill calls for).
126
+
127
+ ## Quality rules
128
+
129
+ - **Every pattern here traces to an actual quote in
130
+ `references/source-copy.md`.** If you're not sure a phrase fits the
131
+ voice, check whether something like it exists on the live page before
132
+ inventing new house phrasing.
133
+ - **No bare guarantees on numbers or timelines** — ranges and honest
134
+ qualifiers ("most clients," "within the first several weeks"), matching
135
+ the source's own hedging.
136
+ - **No hype-adjective stacking** — one strong claim, stated plainly, beats
137
+ three vague ones.
138
+ - **Second person throughout** in anything a client reads.
139
+ - **Reuse the signature phrases verbatim** rather than drafting
140
+ near-equivalents — consistency across every artifact is the point.
141
+
142
+ ## Before you finish — checklist
143
+
144
+ - [ ] Reads like a person talking to the reader, not a deck abstract.
145
+ - [ ] No banned hype word from the table above.
146
+ - [ ] At least one claim is backed by a concrete number, name, or example.
147
+ - [ ] Any bold number/timeline claim is hedged the way the source hedges
148
+ ("most," "typically," a range) rather than promised outright.
149
+ - [ ] Signature phrases ("at a fraction of the cost of a full-time hire")
150
+ reused verbatim, not paraphrased.
151
+ - [ ] If this is going somewhere permanent, spot-check
152
+ `references/source-copy.md` (or the live page) hasn't drifted.
153
+
154
+ ## Keeping it in sync
155
+
156
+ The landing page is the source of truth, not this skill. If
157
+ `installagent.com/get-started` copy changes materially, re-pull it into
158
+ `references/source-copy.md` and update the patterns above in the same pass.