@installagent/sdk 0.1.0 → 0.2.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.
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/client-linear-create.d.ts +26 -0
- package/dist/client-linear-create.js +46 -0
- package/dist/client-linear.d.ts +28 -9
- package/dist/client-linear.js +36 -14
- package/dist/docs-search.d.ts +19 -6
- package/dist/docs-search.js +32 -11
- package/dist/doctor.d.ts +9 -0
- package/dist/doctor.js +126 -23
- package/dist/env-fill.d.ts +13 -0
- package/dist/env-fill.js +34 -9
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +25 -0
- package/dist/env-registry.js +69 -7
- package/dist/exec.js +15 -2
- package/dist/index.d.ts +14 -6
- package/dist/index.js +14 -6
- package/dist/linear-project.d.ts +2 -2
- package/dist/linear-project.js +2 -2
- package/dist/log.d.ts +28 -0
- package/dist/log.js +73 -0
- package/dist/n8n-executions.d.ts +85 -0
- package/dist/n8n-executions.js +259 -0
- package/dist/op-cli.d.ts +29 -0
- package/dist/op-cli.js +52 -0
- package/dist/platform.d.ts +35 -0
- package/dist/platform.js +39 -0
- package/dist/portal-admin.d.ts +40 -0
- package/dist/portal-admin.js +30 -0
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +47 -0
- package/dist/sync-repos.js +80 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +11 -0
- package/dist/wizard.d.ts +15 -0
- package/dist/wizard.js +35 -56
- package/dist/workspace-docs.d.ts +44 -0
- package/dist/workspace-docs.js +73 -0
- package/package.json +2 -2
- package/templates/env.example +33 -23
- package/templates/workspace-root/AGENT.md +7 -5
- package/templates/workspace-root/ONBOARDING.md +65 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
- package/templates/workspace-root/skills/CLAUDE.md +24 -6
- package/templates/workspace-root/skills/README.md +156 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
- package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
- package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
- package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
- package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
|
@@ -8,7 +8,11 @@ description: >-
|
|
|
8
8
|
jargon, confident on value but honestly hedged on numbers, the
|
|
9
9
|
name-the-objection-then-contrast structure, a one-word-verdict-then-explain
|
|
10
10
|
FAQ pattern, and a short list of signature phrases to reuse rather than
|
|
11
|
-
paraphrase.
|
|
11
|
+
paraphrase. Includes a dedicated SLACK section pulled from the account
|
|
12
|
+
owner's real client messages — greeting/bullets/ask/enthusiasm skeleton,
|
|
13
|
+
his signature phrases, hyphens-not-em-dashes, and emoji as status markers —
|
|
14
|
+
which takes precedence over the marketing register when drafting a client
|
|
15
|
+
Slack reply. Use this WHENEVER writing or reviewing client-facing sentences,
|
|
12
16
|
or someone says "make this sound like us", "in our voice", "match the
|
|
13
17
|
website tone", "does this read on-brand", "tighten this copy", "too
|
|
14
18
|
jargon-y". Reach for it even without the word "skill". Position-agnostic —
|
|
@@ -105,6 +109,69 @@ references to an AI system itself.)
|
|
|
105
109
|
automation builds." A number or a named institution always beats an
|
|
106
110
|
adjective like "world-class" used alone.
|
|
107
111
|
|
|
112
|
+
## Slack, specifically — how the account owner actually writes
|
|
113
|
+
|
|
114
|
+
The landing page is the *marketing* register. Day-to-day client Slack is a
|
|
115
|
+
different, warmer register, and it has its own consistent shape. Pulled from
|
|
116
|
+
Angello's real messages across `#client-jared-tomseth`,
|
|
117
|
+
`#client-behaviatherapy-team`, `#client-carvision` and `#client-iloveanthonys`,
|
|
118
|
+
July 2026. When drafting a Slack message for a client, match **this** section
|
|
119
|
+
first and the landing-page pillars second.
|
|
120
|
+
|
|
121
|
+
> **Client only.** This register is for a message a client reads. For an
|
|
122
|
+
> internal message — a teammate DM, `#team-techs`, a status post — use
|
|
123
|
+
> `slack-voice` instead: no greeting, no warmth, lead with the link or the
|
|
124
|
+
> number. Applying this section internally is what produced the DM that got
|
|
125
|
+
> "Bro, can we please use english" on 2026-08-11.
|
|
126
|
+
|
|
127
|
+
**The reliable skeleton of a substantive message:**
|
|
128
|
+
|
|
129
|
+
1. Warm one-line greeting with the person's @name
|
|
130
|
+
2. One line of gratitude or momentum — *"thank you for taking the time"*,
|
|
131
|
+
*"Really enjoyed the call today"*, *"thank you for sending everything over
|
|
132
|
+
quickly"*
|
|
133
|
+
3. The substance, as **bullets** (`•`, sub-bullets `◦`) or a numbered list —
|
|
134
|
+
never long paragraphs
|
|
135
|
+
4. An explicit, short ask — often literally headed *"Two questions for you:"*
|
|
136
|
+
5. Close on next step + genuine enthusiasm — *"Excited to get going on this"*
|
|
137
|
+
|
|
138
|
+
**Openers actually used:** "Morning [name] -", "Good morning!", "Hi [name]!!",
|
|
139
|
+
"Hey [name]!", "Heyo", "Gm!", "Thanks for taking the time to speak today".
|
|
140
|
+
|
|
141
|
+
**Signature phrases — reuse verbatim:**
|
|
142
|
+
|
|
143
|
+
- "let me know if you have any questions" / "As always, let me know if any
|
|
144
|
+
questions or concerns"
|
|
145
|
+
- "please don't hesitate to reach out"
|
|
146
|
+
- "I'll reach out if I find I missed anything"
|
|
147
|
+
- "thank you for taking the time"
|
|
148
|
+
- "Excited to get going on this" / "excited to start tackling all this"
|
|
149
|
+
- "With that said, ..." · "Regarding [X], ..." · "As for [X], ..." · "Lastly, ..."
|
|
150
|
+
- "worth noting ..."
|
|
151
|
+
- "I prefer giving conservative timelines so I estimate [date]"
|
|
152
|
+
|
|
153
|
+
**Mechanics that make it sound like him and not like a bot:**
|
|
154
|
+
|
|
155
|
+
- **Hyphens, not em dashes.** He writes " - " where a writer would use "—".
|
|
156
|
+
This is the single most recognisable tell. Do not "upgrade" his dashes.
|
|
157
|
+
- **Emoji, used as punctuation and as status markers.** 🫡 is his most frequent
|
|
158
|
+
sign-off beat; also 🙂 🙏 🎉 ⚡ 👀. In update lists he uses ✅ (done), ✍️ (in
|
|
159
|
+
progress), 🏁 (queued), 🟡 (deferred) as row markers.
|
|
160
|
+
- **"We" for the company's work, "I" for his own actions.** "We'll get to work"
|
|
161
|
+
but "I'll send over everything we spoke about tonight."
|
|
162
|
+
- **Light informality is on-voice**, including the occasional lowercase start
|
|
163
|
+
and clipped line ("awesome, thank you -"). Don't over-polish it into
|
|
164
|
+
corporate register.
|
|
165
|
+
- **Conservative on dates, by explicit policy.** He says he prefers
|
|
166
|
+
conservative timelines and then names one — this is the Slack form of the
|
|
167
|
+
landing page's hedging pillar.
|
|
168
|
+
- **Asks for an explicit ack** when something matters: *"Give me a ✅ once
|
|
169
|
+
you've read the message"*.
|
|
170
|
+
|
|
171
|
+
**What he does not do:** long unbroken paragraphs, headers inside a Slack
|
|
172
|
+
message, bold-heavy formatting, hedging apologies, or hype adjectives. Bad
|
|
173
|
+
news is delivered plainly and immediately, then followed by the plan.
|
|
174
|
+
|
|
108
175
|
## Quick before/after
|
|
109
176
|
|
|
110
177
|
> Jargon draft: "Our AI-powered platform leverages seamless automation to
|
|
@@ -148,11 +215,20 @@ references to an AI system itself.)
|
|
|
148
215
|
("most," "typically," a range) rather than promised outright.
|
|
149
216
|
- [ ] Signature phrases ("at a fraction of the cost of a full-time hire")
|
|
150
217
|
reused verbatim, not paraphrased.
|
|
218
|
+
- [ ] **If it's a client Slack message**: greeting → bullets → explicit ask →
|
|
219
|
+
next step + enthusiasm; hyphens not em dashes; no headers or heavy bold;
|
|
220
|
+
at least one of his signature closers.
|
|
151
221
|
- [ ] If this is going somewhere permanent, spot-check
|
|
152
222
|
`references/source-copy.md` (or the live page) hasn't drifted.
|
|
153
223
|
|
|
154
224
|
## Keeping it in sync
|
|
155
225
|
|
|
156
|
-
The landing page is the source of truth, not this
|
|
157
|
-
`installagent.com/get-started` copy changes materially, re-pull it
|
|
158
|
-
`references/source-copy.md` and update the patterns above in the same pass.
|
|
226
|
+
The landing page is the source of truth for the marketing register, not this
|
|
227
|
+
skill. If `installagent.com/get-started` copy changes materially, re-pull it
|
|
228
|
+
into `references/source-copy.md` and update the patterns above in the same pass.
|
|
229
|
+
|
|
230
|
+
The **Slack section** has a different source of truth: the account owner's own
|
|
231
|
+
messages in the live `#client-*` channels. It was last pulled 2026-07-31. If his
|
|
232
|
+
writing drifts — or if someone else starts owning client channels — re-sample a
|
|
233
|
+
few recent substantive messages per channel and update that section rather than
|
|
234
|
+
letting the two diverge silently.
|
|
@@ -31,8 +31,9 @@ secrets).
|
|
|
31
31
|
| The task is… | Run |
|
|
32
32
|
|---|---|
|
|
33
33
|
| Set up a machine from nothing / onboard a technician | `ia wizard <dir>` (clones every team repo + root docs + `.env`) |
|
|
34
|
-
|
|
|
35
|
-
|
|
|
34
|
+
| Pull every repo up to date (team **and** client repos) | `ia sync [<dir>]` — ff-only; `--docs` also refreshes root docs/skills/`.env.example` |
|
|
35
|
+
| Converge an existing workspace with the canonical one | `ia wizard <dir> --update` (ff-only pulls + refresh drifted root docs; prefer `ia sync`, which also covers `clients/client-*`) |
|
|
36
|
+
| "Is my environment OK?" / missing env vars / broken setup | `ia doctor [-w <dir>]` — every gap comes with a fix-it line; `--all` for every check |
|
|
36
37
|
| Who is client X / latest calls / what shipped? | `ia client <slug>` |
|
|
37
38
|
| What's in client X's build repo docs? | `ia client-build <slug> [query]` |
|
|
38
39
|
| Find a client's call transcript / Drive deliverable | `ia client-drive <slug> [query]` |
|
|
@@ -60,7 +61,12 @@ list, including this one.
|
|
|
60
61
|
1Password vault immediately.
|
|
61
62
|
- Anything touching existing files skips or refuses; nothing overwrites
|
|
62
63
|
silently. The root `.env` is never overwritten, not even by
|
|
63
|
-
`wizard --update`.
|
|
64
|
+
`wizard --update` or `sync --docs`.
|
|
65
|
+
- `ia env fill` covers the technician var set only. The infra/portal/payments
|
|
66
|
+
vars are withheld as a bare count, never listed by name — don't "helpfully"
|
|
67
|
+
re-add them to a report. `--admin` opts in for whoever holds that grant.
|
|
68
|
+
- Commands are single words. If a new one ever needs two, join them with a
|
|
69
|
+
colon (`family:verb`), never a dash.
|
|
64
70
|
- Portal mutations and `client-intake` are deliberately CLI-only (no MCP
|
|
65
71
|
twin) — don't script agents around that.
|
|
66
72
|
|
|
@@ -73,9 +79,16 @@ list, including this one.
|
|
|
73
79
|
- No `ia` on PATH yet? The CLI lives in `team-tools/`:
|
|
74
80
|
`pnpm install && pnpm -r build`, then `node apps/cli/dist/index.js …`
|
|
75
81
|
(bootstrap order for a from-scratch machine is in root `ONBOARDING.md`).
|
|
76
|
-
- Cloning InstallAgent repos
|
|
77
|
-
|
|
78
|
-
|
|
82
|
+
- Cloning InstallAgent repos works over **HTTPS** using the gh CLI's
|
|
83
|
+
credential helper, so `gh auth login` is sufficient; `ia wizard --ssh`
|
|
84
|
+
switches to SSH URLs. On shared machines the git identity may be
|
|
85
|
+
directory-scoped — if a clone fails with auth errors, say so rather than
|
|
86
|
+
retrying with other credentials.
|
|
87
|
+
- **Windows:** run `op`-touching commands (`ia env fill`, `ia env push`) from
|
|
88
|
+
PowerShell. 1Password supports PowerShell only, so its CLI cannot
|
|
89
|
+
authenticate from Git Bash — the command will look installed and still
|
|
90
|
+
fail. `ia doctor` detects this and adjusts its fix-it text; if you ever see
|
|
91
|
+
`brew` suggested on Windows, that is a bug to report, not to work around.
|
|
79
92
|
|
|
80
93
|
## When NOT to use ia
|
|
81
94
|
|
|
@@ -4,16 +4,23 @@ description: >-
|
|
|
4
4
|
The official Install Agent brand kit for deliverables — the canonical palette
|
|
5
5
|
(deep red #d11a1a on white / signal red #ff2d2d, white foreground), the official logo
|
|
6
6
|
assets, and copy-paste recipes that apply them to Excalidraw diagrams (house
|
|
7
|
-
RED theme)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
7
|
+
RED theme), client PDFs (SOW, proposal, overview, onboarding, one-pagers), and
|
|
8
|
+
**client decks / Google Slides presentations** (scripts/deck.py + a
|
|
9
|
+
duplicate-me assets/installagent-deck-template.pptx + scripts/deck_lint.py,
|
|
10
|
+
the gate that fails a deck on any off-brand colour, typeface, unresolvable
|
|
11
|
+
glyph or out-of-bounds shape and renders every slide so you can actually look
|
|
12
|
+
at it). Use this WHENEVER a diagram, document, deck or presentation needs to
|
|
13
|
+
look on-brand — triggers include "make it on-brand", "use our brand
|
|
14
|
+
color/red", "add our logo", "official logo not a generic one", "branded PDF",
|
|
15
|
+
"SOW/proposal PDF", "red excalidraw", "match our theme", "build a deck",
|
|
16
|
+
"client presentation", "Google Slides", "slide deck for the call", "deck
|
|
17
|
+
template", or any client-facing visual. Reach for it even if the user never
|
|
18
|
+
says "skill". It mirrors the single brand source
|
|
13
19
|
(team-web/packages/ui/theme.css) and ships scripts/brand.py so generators
|
|
14
20
|
never hard-code a hex or re-draw the logo. Pairs with client-workflow-diagram,
|
|
15
|
-
engagement-spec,
|
|
16
|
-
govern
|
|
21
|
+
engagement-spec, tech-call-prep (the deck's content comes from the call
|
|
22
|
+
agenda), and contract-tech-agnostic — this one governs BRAND, those govern
|
|
23
|
+
content/layout.
|
|
17
24
|
---
|
|
18
25
|
|
|
19
26
|
# Install Agent brand kit — branded diagrams & PDFs
|
|
@@ -47,10 +54,16 @@ generator imports one module and is automatically on-brand.
|
|
|
47
54
|
|---|---|---|
|
|
48
55
|
| **Branded Excalidraw** (red theme) | [`references/excalidraw-red-theme.md`](references/excalidraw-red-theme.md) | editable `.excalidraw` in the house red theme |
|
|
49
56
|
| **Branded PDF** (SOW, proposal, overview, one-pager) | [`references/branded-pdf.md`](references/branded-pdf.md) | client PDF with the official logo + brand red |
|
|
57
|
+
| **Client deck / Google Slides** | [`references/deck-guide.md`](references/deck-guide.md) | `.pptx` that converts to native Slides on Drive upload |
|
|
50
58
|
|
|
51
|
-
|
|
59
|
+
All are driven by [`scripts/brand.py`](scripts/brand.py) — palette constants,
|
|
52
60
|
`logo_svg()`, an `Excalidraw` builder, and `pdf_css()` / `pdf_hero()` /
|
|
53
|
-
`render_pdf()` for WeasyPrint.
|
|
61
|
+
`render_pdf()` for WeasyPrint. Decks add
|
|
62
|
+
[`scripts/deck.py`](scripts/deck.py) (builder),
|
|
63
|
+
[`scripts/deck_lint.py`](scripts/deck_lint.py) (the gate),
|
|
64
|
+
[`scripts/logo_raster.py`](scripts/logo_raster.py) (SVG → PNG, since pptx can't
|
|
65
|
+
embed SVG), and a duplicate-me template at
|
|
66
|
+
`assets/installagent-deck-template.pptx`.
|
|
54
67
|
|
|
55
68
|
## How to use it
|
|
56
69
|
|
|
@@ -73,6 +86,25 @@ numbers. Then `brand.render_pdf(body, out)` rasterizes via WeasyPrint. Content
|
|
|
73
86
|
discipline stays with `engagement-spec` (overviews/onboarding) and
|
|
74
87
|
`contract-tech-agnostic` (SOWs) — this skill only guarantees the brand.
|
|
75
88
|
|
|
89
|
+
### Client deck (Google Slides)
|
|
90
|
+
|
|
91
|
+
Two paths, one gate — full detail in
|
|
92
|
+
[`references/deck-guide.md`](references/deck-guide.md).
|
|
93
|
+
|
|
94
|
+
- **By hand:** upload `assets/installagent-deck-template.pptx` to Drive (it
|
|
95
|
+
converts to native Slides), then **duplicate** the slide whose *shape* fits
|
|
96
|
+
your point and type over it. Its OOXML theme is branded, so a text box added
|
|
97
|
+
by hand inherits Hanken Grotesk and deep red rather than Calibri and Office
|
|
98
|
+
blue. Delete the read-me slide and every unused archetype before sharing.
|
|
99
|
+
- **In code:** `from deck import Deck` and compose the archetypes — `cover`,
|
|
100
|
+
`pipeline`, `ladder`, `cards`, `flow` (struck-out cut step), `gantt`,
|
|
101
|
+
`tiles`, `decisions`, `chat`, `kanban`, plus `table` / `callout` /
|
|
102
|
+
`question_band` / `panel`. A deck is ~80 lines of content and no geometry.
|
|
103
|
+
|
|
104
|
+
**A deck is presented, not read.** Every slide carries a picture of the idea
|
|
105
|
+
and only the words that anchor it; prose belongs in the speaker's mouth or in
|
|
106
|
+
`docs/05-call-agenda.md`. The linter warns past 180 words on a slide.
|
|
107
|
+
|
|
76
108
|
### Verify before shipping
|
|
77
109
|
|
|
78
110
|
- Excalidraw: `python -m json.tool file.excalidraw` parses; opens at
|
|
@@ -80,6 +112,15 @@ discipline stays with `engagement-spec` (overviews/onboarding) and
|
|
|
80
112
|
- PDF: render pages to PNG (`pdftoppm -png -r 110 out.pdf page`) and eyeball —
|
|
81
113
|
the official logo renders, the accent is brand red (not a stray blue), nothing
|
|
82
114
|
spills onto a near-empty page.
|
|
115
|
+
- Deck: `python scripts/deck_lint.py mydeck.pptx --render`. It reads the raw
|
|
116
|
+
OOXML (off-brand hex, off-brand typeface, hard line breaks, unresolvable
|
|
117
|
+
glyphs, out-of-bounds shapes, invisible hairlines, wrong slide size) **and**
|
|
118
|
+
renders every slide to PNG so you can actually look at it. `--render` is the
|
|
119
|
+
step people skip: there is no LibreOffice on most of our machines, so Quick
|
|
120
|
+
Look via `qlmanage` is the only local preview — and it only ever previews
|
|
121
|
+
slide 1, which is why the linter splits the deck one slide per file first.
|
|
122
|
+
Geometry checks pass on decks with eight visible defects; looking is not
|
|
123
|
+
optional.
|
|
83
124
|
|
|
84
125
|
## Quality rules
|
|
85
126
|
|
|
@@ -109,4 +150,12 @@ images. The logo assets here are copies of
|
|
|
109
150
|
- [ ] Official logo used (PDF hero + running header); no generic glyph.
|
|
110
151
|
- [ ] Generator imports `scripts/brand.py` — no hard-coded hexes.
|
|
111
152
|
- [ ] Excalidraw validates / opens; PDF previewed as PNG.
|
|
153
|
+
- [ ] Deck: `deck_lint.py --render` clean **and every slide looked at** — a
|
|
154
|
+
clean geometry pass is not a clean deck.
|
|
155
|
+
- [ ] Deck: white surfaces, not the dark marketing palette; the logo is the
|
|
156
|
+
official asset (lockup on the cover, mark on every other slide).
|
|
112
157
|
- [ ] No secrets or customer data in labels; branding says Install Agent.
|
|
158
|
+
- [ ] **Not this skill's job, but check it anyway:** every number and status
|
|
159
|
+
word on a deliverable traces to a source file. The linter cannot tell
|
|
160
|
+
"passing 25/25" from an unrun test set — see `deck-guide.md` § mistakes
|
|
161
|
+
12–15 for the four that reached a draft.
|
|
Binary file
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# Client decks — the template, the builder, and the mistakes not to repeat
|
|
2
|
+
|
|
3
|
+
Two paths to an on-brand deck. Both end in the same linter.
|
|
4
|
+
|
|
5
|
+
| You are… | Use | Then |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| Writing a deck by hand | `assets/installagent-deck-template.pptx` | Upload to Drive → it converts to native Google Slides → duplicate the slide whose *shape* fits your point |
|
|
8
|
+
| Generating a deck in code | `scripts/deck.py` | `python scripts/deck_lint.py yourdeck.pptx --render` before you hand it over |
|
|
9
|
+
|
|
10
|
+
Both are generated from `scripts/brand.py`, which mirrors the single brand
|
|
11
|
+
source (`team-web/packages/ui/theme.css`). **Nothing here contains a hex
|
|
12
|
+
literal, and neither should your deck script.**
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## The hand-built path
|
|
17
|
+
|
|
18
|
+
1. Upload `assets/installagent-deck-template.pptx` to the client's Drive
|
|
19
|
+
folder — or to your own and copy it. Drive converts `.pptx` to native
|
|
20
|
+
Slides on upload, keeping the layout.
|
|
21
|
+
2. Slide 2 is the read-me. Read it, then delete it before sharing.
|
|
22
|
+
3. **Duplicate, don't create.** Right-click a slide → Duplicate, then type over
|
|
23
|
+
it. A slide you add from scratch loses the type stack and the spacing.
|
|
24
|
+
4. Delete every archetype you didn't use. A ten-slide template is not a
|
|
25
|
+
ten-slide deck.
|
|
26
|
+
5. Fix the footer date and the `n/N` page numbers — they are text, not fields.
|
|
27
|
+
|
|
28
|
+
The file's **OOXML theme** is patched too, so Slides reports the theme as
|
|
29
|
+
"Install Agent" and a text box you add by hand inherits Hanken Grotesk and
|
|
30
|
+
deep red instead of Calibri and Office blue.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## The generated path
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
import sys
|
|
38
|
+
sys.path.append("/Users/…/skills/installagent-brand-kit/scripts")
|
|
39
|
+
from deck import Deck, RED, RED_SIG, MUTED
|
|
40
|
+
|
|
41
|
+
d = Deck(client="Acme Co", date="14 Sep 2026", total=4)
|
|
42
|
+
|
|
43
|
+
d.cover("ACME CO", "Where we are, and what we need to decide today",
|
|
44
|
+
"Attendees 14 September 2026 · 60 minutes",
|
|
45
|
+
outcomes=[("A priority order", "we all agree on"),
|
|
46
|
+
("A timeline", "you can plan against"),
|
|
47
|
+
("A short list", "of what we need from you")])
|
|
48
|
+
|
|
49
|
+
s = d.slide("01 · already working", "One thing is live",
|
|
50
|
+
"And it has been for two weeks.")
|
|
51
|
+
d.pipeline(s, [("inbox", "Mail arrives", "Any hour"),
|
|
52
|
+
("read", "Classified", "Understood, not matched"),
|
|
53
|
+
("file", "Filed", "Your own labels"),
|
|
54
|
+
("act", "Archived", "By itself")], accent=3)
|
|
55
|
+
d.callout(s, "The sentence you want repeated back to you.", "One clause more.")
|
|
56
|
+
|
|
57
|
+
s = d.slide("02 · what we need", "From your side",
|
|
58
|
+
"None of this is engineering time.")
|
|
59
|
+
d.tiles(s, [("⚠", "The blocker", "What it unlocks.", "OWNER — VERB", True),
|
|
60
|
+
("→", "A question", "Asked, not answered.", "OWNER", False)], cols=4)
|
|
61
|
+
|
|
62
|
+
s = d.slide("03 · next steps", "The next seven days")
|
|
63
|
+
d.kanban(s, [("TODAY", RED, [(1, "Thing", "US", False)]),
|
|
64
|
+
("THIS WEEK", RED_SIG, [(2, "Their thing", "THEM", True)]),
|
|
65
|
+
("LATER", MUTED, [(3, "Dated thing", "US", False)])])
|
|
66
|
+
|
|
67
|
+
d.save("acme-deck.pptx")
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Archetypes** (all take the `Slide` returned by `d.slide()` and advance its
|
|
71
|
+
cursor, so you can stack two on one page):
|
|
72
|
+
|
|
73
|
+
`cover` · `pipeline` · `ladder` · `cards` · `flow` (with a struck-out cut step)
|
|
74
|
+
· `gantt` · `tiles` · `decisions` · `chat` · `kanban` · plus `table`,
|
|
75
|
+
`callout`, `question_band`, `panel`, `stat`.
|
|
76
|
+
|
|
77
|
+
For a bespoke diagram — a map, a topology — use `panel()` for the left-hand
|
|
78
|
+
narrative card; it returns the x where the free area starts. Draw into that
|
|
79
|
+
area with the primitives (`card`, `bar`, `badge`, `pill`, `arrow`, `rule`) so
|
|
80
|
+
the diagram stays on-palette.
|
|
81
|
+
|
|
82
|
+
`d.save()` refuses to write if the slide count doesn't match `total=` — the
|
|
83
|
+
footer page numbers would otherwise lie.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## The mistakes this exists to prevent
|
|
88
|
+
|
|
89
|
+
Every one of these reached a draft. Ordered by how badly it would have landed.
|
|
90
|
+
|
|
91
|
+
### Brand
|
|
92
|
+
|
|
93
|
+
1. **Building a client deck on the marketing site's dark palette.** The site is
|
|
94
|
+
always-dark; **documents live on white with `#d11a1a`**. `brand-tokens.md`
|
|
95
|
+
is explicit: the dark `theme.css` neutrals are *"for the always-dark
|
|
96
|
+
marketing site — do not use them for client PDFs or diagrams."*
|
|
97
|
+
2. **Introducing a second hue for semantics** — blue "client" pins, amber
|
|
98
|
+
"stale" markers. **Red is the only hue.** Meaning rides on glyphs
|
|
99
|
+
(`✓ → ⚠ ✕`), fill weight, and dashed-vs-solid outlines. `deck_lint.py`
|
|
100
|
+
fails the build on any hex not in `brand.py`.
|
|
101
|
+
3. **Using signal red `#ff2d2d` as decoration.** It means attention. Deep red
|
|
102
|
+
`#d11a1a` is the primary; if everything is bright red, nothing is urgent.
|
|
103
|
+
4. **Re-creating the logo**, or screenshotting it. `logo_raster.py` rasterises
|
|
104
|
+
the official SVGs — full lockup on the cover, icon mark in every running
|
|
105
|
+
header. `deck_lint.py` fails a slide with no logo at all.
|
|
106
|
+
|
|
107
|
+
### Rendering — things that look fine locally and break on the projector
|
|
108
|
+
|
|
109
|
+
5. **1px rules.** A `GRID`-coloured shape 9525 EMU thick is invisible
|
|
110
|
+
projected. The gantt gridlines shipped this way. Floor is **12700 EMU**;
|
|
111
|
+
`deck.HAIRLINE` is that value.
|
|
112
|
+
6. **Glyphs that don't resolve.** `▮`/`▯` rendered as tiny boxes and a missing
|
|
113
|
+
glyph. Draw swatch shapes instead. The linter has a denylist; `✓ → ⚠ ✕ ● ★
|
|
114
|
+
◌` are safe.
|
|
115
|
+
7. **`\n` inside a run.** Renderers disagree on whether it breaks. `deck.py`
|
|
116
|
+
strips it; add a second paragraph, or let `word_wrap` do the work.
|
|
117
|
+
8. **`Inches(13.333)` for a 16:9 width.** That is 12191695 EMU — 305 short of
|
|
118
|
+
true 16:9 against 7.5in, so Slides rescales on import. Use
|
|
119
|
+
`Emu(12192000)`, which `deck.py` does.
|
|
120
|
+
9. **Text frames overhanging the footer.** `deck.tb()` clamps every frame to
|
|
121
|
+
`BOTTOM_SAFE`; the linter fails on any shape past the slide edge.
|
|
122
|
+
10. **A "radius" stretched into an ellipse.** If your diagram's coordinate
|
|
123
|
+
space isn't square, a circle sized in *units* comes out oval. Size radial
|
|
124
|
+
things in **inches**, not canvas units.
|
|
125
|
+
11. **Labels colliding with the thing they label.** Only visible by looking.
|
|
126
|
+
|
|
127
|
+
### Content — not enforceable, but the expensive kind
|
|
128
|
+
|
|
129
|
+
12. **An unrun test quoted as a passing score.** A `25/25` reached a
|
|
130
|
+
client-facing slide while the workplan said the set had *"not yet [been]
|
|
131
|
+
run."* Every number on a slide needs a source file; if there is no
|
|
132
|
+
evidence file, say what you actually have.
|
|
133
|
+
13. **A status word doing more work than the repo supports.** "Finished",
|
|
134
|
+
"the only thing left", "it tracks his edits" — each was one phase ahead of
|
|
135
|
+
reality. Grep the workplan before you write a status word.
|
|
136
|
+
14. **A claim that undercuts your own ask.** "Carries no patient data" two
|
|
137
|
+
slides before asking them to sign a data-handling agreement.
|
|
138
|
+
15. **Contradicting a stakeholder who will be in the room.** A slide said
|
|
139
|
+
"read-only" about a tool whose owner had explicitly required it be
|
|
140
|
+
editable. Read the last call's notes before you write the roadmap slide.
|
|
141
|
+
|
|
142
|
+
The linter cannot catch 12–15. The client repo's `CADENCE.md` § surface matrix
|
|
143
|
+
is the process that does: every claim traces to `docs/`, and `docs/` traces to
|
|
144
|
+
a call note.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Verifying a deck before you send it
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
python scripts/deck_lint.py mydeck.pptx --render
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Errors block; warnings are advisory (word count over 180, hairlines).
|
|
155
|
+
|
|
156
|
+
**`--render` is the step people skip and shouldn't.** There is no LibreOffice
|
|
157
|
+
on most of our machines, so the only local way to *see* a `.pptx` is macOS
|
|
158
|
+
Quick Look — and `qlmanage` previews only slide 1. The linter works around that
|
|
159
|
+
by splitting the deck into one file per slide and rendering each. It is the
|
|
160
|
+
only check that catches composition: collisions, dead whitespace, a shape
|
|
161
|
+
covering half the page. On the deck this guide came from, geometry was clean
|
|
162
|
+
and **eight defects were still visible**.
|
|
163
|
+
|
|
164
|
+
Then: upload to Drive, and confirm after conversion that Hanken Grotesk and
|
|
165
|
+
JetBrains Mono resolved (both are Google Fonts and normally do) and that any
|
|
166
|
+
hand-drawn diagram survived.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Regenerating the template
|
|
171
|
+
|
|
172
|
+
After any change to `theme.css`, `brand.py`, or `deck.py`:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
cd scripts
|
|
176
|
+
python make_deck_template.py
|
|
177
|
+
python deck_lint.py ../assets/installagent-deck-template.pptx --render
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Never hand-edit the `.pptx` in `assets/` — it is a build artifact, and a manual
|
|
181
|
+
edit is how it drifts from the brand source.
|