@installagent/sdk 0.1.0 → 0.3.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-mirror.d.ts +69 -0
- package/dist/agent-mirror.js +275 -0
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/claude-hours.d.ts +118 -0
- package/dist/claude-hours.js +523 -0
- package/dist/client-drive.d.ts +3 -0
- package/dist/client-drive.js +2 -2
- 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 +55 -13
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +29 -0
- package/dist/env-registry.js +123 -9
- package/dist/exec.js +15 -2
- package/dist/git.d.ts +31 -0
- package/dist/git.js +59 -0
- package/dist/google-service-account.d.ts +20 -0
- package/dist/google-service-account.js +49 -0
- package/dist/hours-estimate.d.ts +43 -0
- package/dist/hours-estimate.js +159 -0
- package/dist/hours-export-schedule.d.ts +35 -0
- package/dist/hours-export-schedule.js +188 -0
- package/dist/hours-ledger.d.ts +129 -0
- package/dist/hours-ledger.js +882 -0
- package/dist/index.d.ts +25 -6
- package/dist/index.js +25 -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 +108 -0
- package/dist/portal-admin.js +94 -1
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +54 -0
- package/dist/sync-repos.js +89 -0
- package/dist/template-sync.d.ts +11 -0
- package/dist/template-sync.js +16 -0
- package/dist/triage-backfill.d.ts +37 -0
- package/dist/triage-backfill.js +211 -0
- package/dist/triage-enable.d.ts +90 -0
- package/dist/triage-enable.js +428 -0
- package/dist/triage-gates.d.ts +252 -0
- package/dist/triage-gates.js +951 -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/dist/workspace-push.d.ts +39 -0
- package/dist/workspace-push.js +78 -0
- package/dist/workspace-status.d.ts +37 -0
- package/dist/workspace-status.js +114 -0
- package/package.json +2 -2
- package/templates/env.example +37 -23
- package/templates/workspace-root/.claude/settings.json +12 -1
- 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 +127 -0
- package/templates/workspace-root/skills/CLAUDE.md +29 -6
- package/templates/workspace-root/skills/README.md +171 -0
- package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -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-deliverables/SKILL.md +1 -1
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
- package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/github-profile/SKILL.md +106 -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 +49 -7
- package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
- 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
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: google-chat-app-setup
|
|
3
|
+
description: >-
|
|
4
|
+
Deploy a Google Chat app (backed by an n8n webhook workflow) in a client's
|
|
5
|
+
own Google Workspace, and open it up to their whole domain — not just the
|
|
6
|
+
person who built it. Covers the two things that aren't obvious from
|
|
7
|
+
Google's docs: the Chat API Configuration screen (webhook, visibility,
|
|
8
|
+
triggers) AND the separate Google Workspace Marketplace SDK "publish as
|
|
9
|
+
Private" step that domain-wide visibility actually requires. Also covers
|
|
10
|
+
the request/response contract for a Workspace-add-on-style Chat app, which
|
|
11
|
+
differs from the plain Chat REST API in three ways that all fail silently
|
|
12
|
+
as "app not responding" in the Chat UI. Use this WHENEVER a client asks for
|
|
13
|
+
an internal Q&A/FAQ bot inside Google Chat, or a technician hits "not
|
|
14
|
+
responding" after wiring a Chat webhook to n8n.
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# Google Chat app setup (client Workspace, n8n-backed)
|
|
18
|
+
|
|
19
|
+
Built and proven end-to-end on Behavia Therapy's `behaviatherapy.com`
|
|
20
|
+
Workspace (2026-08-05). Two things Google's own UI doesn't say plainly:
|
|
21
|
+
domain-wide visibility needs a **second** publish step beyond the Chat API
|
|
22
|
+
config, and a Workspace-add-on-style Chat app uses a different request/
|
|
23
|
+
response shape than the plain Chat REST API — get any one of three shapes
|
|
24
|
+
wrong and Chat just says "not responding," no error surfaced anywhere obvious.
|
|
25
|
+
|
|
26
|
+
## Part 1 — Chat API Configuration (single user works after this)
|
|
27
|
+
|
|
28
|
+
In the GCP project's **Chat API → Configuration** page:
|
|
29
|
+
|
|
30
|
+
1. **App details** — name, avatar (host the avatar somewhere durable, not a
|
|
31
|
+
throwaway image host).
|
|
32
|
+
2. **Interactive features** — enable, check "Build this Chat app as a
|
|
33
|
+
Workspace add-on" if you want it usable outside pure 1:1 DMs later (this
|
|
34
|
+
changes the payload shape — see Part 3).
|
|
35
|
+
3. **Connection settings / triggers** — App URL = your n8n **production**
|
|
36
|
+
webhook URL (`https://<host>/webhook/<path>`), same URL for all trigger
|
|
37
|
+
types (message, added-to-space, removed-from-space) unless you need to
|
|
38
|
+
split them.
|
|
39
|
+
4. **Visibility** — checkbox "Make this Chat app available to specific
|
|
40
|
+
people and groups in `<domain>`" is the only option here; the page itself
|
|
41
|
+
tells you domain-wide requires Marketplace (Part 2).
|
|
42
|
+
5. **Logs** — turn on error logging to Cloud Logging; it's the only place
|
|
43
|
+
Google-side failures (bad response shape, auth rejects) show up — n8n's
|
|
44
|
+
own execution log only shows what happened *after* Google delivered the
|
|
45
|
+
request.
|
|
46
|
+
6. Save. Test with the owner account's own Chat DM first before touching
|
|
47
|
+
visibility — confirms the webhook contract (Part 3) before adding the
|
|
48
|
+
domain-wide complexity of Part 2.
|
|
49
|
+
|
|
50
|
+
## Part 2 — Publish as Private (domain-wide visibility)
|
|
51
|
+
|
|
52
|
+
Domain-wide visibility is **not** a setting on the Chat API page — it
|
|
53
|
+
requires publishing through the **Google Workspace Marketplace SDK**, in the
|
|
54
|
+
same GCP project:
|
|
55
|
+
|
|
56
|
+
1. **APIs & Services → Library** → enable **"Google Workspace Marketplace
|
|
57
|
+
SDK."**
|
|
58
|
+
2. **Marketplace SDK → App Configuration**:
|
|
59
|
+
- **App Visibility: Private** ("only available to users in your domain")
|
|
60
|
+
— this is what makes it domain-wide and skips Google's public-app
|
|
61
|
+
review (review only applies to Public). Leave **Unlisted** unchecked
|
|
62
|
+
so staff can find it by browsing/searching, not just via direct link.
|
|
63
|
+
- **Installation Settings: Individual + Admin Install** — lets any staff
|
|
64
|
+
member add it themselves.
|
|
65
|
+
- **App Integrations**: check **Google Workspace add-on** →
|
|
66
|
+
**HTTP or other deployments** → **Standalone Chat App**, then use the
|
|
67
|
+
**"(Configure Chat API)"** link to point it at the *same* Chat API
|
|
68
|
+
config from Part 1 — don't create a second one. The top-level
|
|
69
|
+
"Deployment ID / Select deployment" field is for a *generic* Workspace
|
|
70
|
+
Add-on (Apps Script) deployment; it stays disabled and unused for a
|
|
71
|
+
Standalone Chat App — that's expected, not a bug.
|
|
72
|
+
- **OAuth Scopes**: leave the two defaults (`userinfo.email`,
|
|
73
|
+
`userinfo.profile`). No extra scopes needed — auth is verified from the
|
|
74
|
+
signed JWT already on every request (Part 3), not via a separate OAuth
|
|
75
|
+
grant.
|
|
76
|
+
- **Developer Information**: real name/site/email — Google emails this
|
|
77
|
+
address about the listing.
|
|
78
|
+
3. **Save Draft**, then **Publish** (button label may vary — "Publish" or
|
|
79
|
+
equivalent once required fields are filled).
|
|
80
|
+
4. **Verify with a second person**, not the builder's own account — have
|
|
81
|
+
someone else in the domain find/add the app in Chat. This is the actual
|
|
82
|
+
proof visibility worked; the owner account was already implicitly
|
|
83
|
+
authorized.
|
|
84
|
+
|
|
85
|
+
## Part 3 — The webhook contract (Workspace-add-on shape)
|
|
86
|
+
|
|
87
|
+
If "Build this Chat app as a Workspace add-on" is checked, the request/
|
|
88
|
+
response shapes are **not** the plain Chat REST API's. All three of the
|
|
89
|
+
following look identical from the Chat UI ("app not responding") but have
|
|
90
|
+
different root causes — check them in order:
|
|
91
|
+
|
|
92
|
+
1. **Auth**: the bearer JWT's `email` claim is
|
|
93
|
+
`service-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`
|
|
94
|
+
— **not** the generic `chat@system.gserviceaccount.com` from the plain
|
|
95
|
+
API. `aud` is your exact webhook URL. Decode the JWT payload (base64url)
|
|
96
|
+
to sanity-check `iss`/`email`/`aud`; full JWKS signature verification is a
|
|
97
|
+
separate hardening step, not required to get this working.
|
|
98
|
+
2. **Request body**: everything is nested under `body.chat` —
|
|
99
|
+
`body.chat.messagePayload.message.text` /
|
|
100
|
+
`body.chat.messagePayload.space.name` / `body.chat.user`, and event type
|
|
101
|
+
is inferred from which of `messagePayload` / `addedToSpacePayload` /
|
|
102
|
+
`removedFromSpacePayload` is present. The plain API's flat
|
|
103
|
+
`body.type`/`body.message`/`body.space` shape does not apply here.
|
|
104
|
+
3. **Response body**: must be the nested envelope, not a flat `{"text":
|
|
105
|
+
"..."}`:
|
|
106
|
+
```json
|
|
107
|
+
{"hostAppDataAction":{"chatDataAction":{"createMessageAction":{"message":{"text":"..."}}}}}
|
|
108
|
+
```
|
|
109
|
+
A flat `{"text": "..."}` response is silently ignored by Chat (no error,
|
|
110
|
+
no message, nothing) — this is the single easiest thing to get wrong and
|
|
111
|
+
the hardest to diagnose without capturing real traffic, because the n8n
|
|
112
|
+
execution itself shows `success` right up to a malformed expression.
|
|
113
|
+
|
|
114
|
+
**Fastest way to debug a real "not responding" report**: pull the actual
|
|
115
|
+
trigger-node payload from n8n's execution history for that request (not a
|
|
116
|
+
synthetic test payload) and check these three things directly against what
|
|
117
|
+
was captured, in order. Re-run the fix via the MCP `test_workflow` tool with
|
|
118
|
+
that captured payload pinned to the trigger node — confirms the fix
|
|
119
|
+
end-to-end without needing the reporter to retry in Chat again.
|
|
120
|
+
|
|
121
|
+
## Requirements checklist
|
|
122
|
+
|
|
123
|
+
- [ ] GCP project in the client's own Workspace org (not a personal/InstallAgent project)
|
|
124
|
+
- [ ] Chat API enabled + configured (Part 1), tested against the owner's own DM
|
|
125
|
+
- [ ] Google Workspace Marketplace SDK enabled + published Private (Part 2)
|
|
126
|
+
- [ ] n8n webhook contract matches Part 3 (Workspace-add-on shapes) if that checkbox was ticked
|
|
127
|
+
- [ ] Verified by a second domain user, not just the builder
|
|
128
|
+
- [ ] Cloud Logging error logs turned on for the Chat API
|
|
129
|
+
|
|
130
|
+
## Known gaps to flag, not silently skip
|
|
131
|
+
|
|
132
|
+
- Real `@mention`s in escalation paths need the person's People API
|
|
133
|
+
`resourceName` (`users/xxxxx`) — not derivable from just an email address.
|
|
134
|
+
- JWT verification here is claims-based, not full JWKS signature
|
|
135
|
+
verification — fine for an internal FAQ bot, not sufficient if the app
|
|
136
|
+
ever touches anything sensitive enough to need real request authentication.
|
|
Binary file
|
|
@@ -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.
|
|
@@ -8,7 +8,11 @@ description: >-
|
|
|
8
8
|
(don't grep repos or draft Airtable/Drive/Linear API calls — `ia client`,
|
|
9
9
|
`ia client-build`, `ia client-drive`, `ia client-linear` already do it
|
|
10
10
|
read-only), starting a new client engagement, building an n8n automation
|
|
11
|
-
(check the bank first),
|
|
11
|
+
(check the bank first), running an email-triage gate ("write the soak
|
|
12
|
+
report", "sample for gate B", "is the triage agent still recording?" —
|
|
13
|
+
`ia triage` reads the classification record and writes the evidence file,
|
|
14
|
+
never a hand-built spreadsheet; `ia triage enable` sets a new triage client
|
|
15
|
+
up), minting a credential, administering the portal,
|
|
12
16
|
searching the team docs, or setting up / fixing a technician's
|
|
13
17
|
environment ("set me up", "my env vars are missing", "clone the
|
|
14
18
|
workspace", onboarding a new machine). Reach for it before writing any
|
|
@@ -31,8 +35,11 @@ secrets).
|
|
|
31
35
|
| The task is… | Run |
|
|
32
36
|
|---|---|
|
|
33
37
|
| Set up a machine from nothing / onboard a technician | `ia wizard <dir>` (clones every team repo + root docs + `.env`) |
|
|
34
|
-
|
|
|
35
|
-
|
|
|
38
|
+
| Pull every repo up to date (team **and** client repos) | `ia sync [<dir>]` — ff-only; `--docs` also refreshes root docs/skills/`.env.example` |
|
|
39
|
+
| See which repos are dirty / unpushed / behind, across the whole workspace | `ia status [<dir>]` — read-only: fetches, then reports `clean`/`dirty`/`ahead`/`behind`/`diverged` per repo; never commits or pushes |
|
|
40
|
+
| Push already-committed work across every repo | `ia push [<dir>]` — pushes only repos that are clean and strictly ahead (fast-forward only); a dirty repo is skipped and reported, **never auto-committed** — review the diff and commit it yourself, then re-run |
|
|
41
|
+
| 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-*`) |
|
|
42
|
+
| "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
43
|
| Who is client X / latest calls / what shipped? | `ia client <slug>` |
|
|
37
44
|
| What's in client X's build repo docs? | `ia client-build <slug> [query]` |
|
|
38
45
|
| Find a client's call transcript / Drive deliverable | `ia client-drive <slug> [query]` |
|
|
@@ -42,6 +49,12 @@ secrets).
|
|
|
42
49
|
| Client repos drifted from client-template's lint/CI files | `ia template-sync [--apply]` |
|
|
43
50
|
| Search the team docs site | `ia docs search "<query>"` |
|
|
44
51
|
| Building an n8n automation | `ia agent templates` FIRST (the bank), then `ia agent create <template>`; bank the result back with `ia agent save` |
|
|
52
|
+
| Email triage gate A — "write the soak report" / "can we propose the categories yet?" | `ia triage soak-report <slug>` — the fixed seven-table report + Critical / Today / Later / Noise lane view, ≥200-row and ≤20%-review-lane checks pre-computed, written to `evidence/`; never build it in a spreadsheet by hand |
|
|
53
|
+
| Email triage gates B / C — "sample for the precision gate" / "can we turn on archiving / drafts?" | `ia triage sample <slug> --stage label` (gate B) or `--stage organize` (gate C) — seeded random 50 from the current stage's rows, judging table + zero-tolerance list pre-filled; **you** judge each message_id in the client's mailbox |
|
|
54
|
+
| "Is the triage agent still recording?" / a client's inbox looks quiet | `ia triage health <slug>` — rows in the last N days from the record; exit 1 when quiet (a stopped triage agent looks exactly like a quiet inbox). The portal's daily watch runs the same check for every active triage agent and alerts `#team-techs` |
|
|
55
|
+
| Set up a new email-triage client's record / "the record node is wired, now what?" | `ia portal create-agent …`, bind the two credentials in the n8n UI, then `ia triage enable <slug>` BEFORE the first publish — checks the live workflow's record wiring (read-only, node names + pass/fail only), marks the agent (`ia portal set-agent-triage`), backfills an old sheet if one exists. `--dry-run` checks only; exit 1 on a failed check, with the fix |
|
|
56
|
+
| "Record did not reach the portal" alert in `#team-techs` | copy that execution's `🧺 Batch Record Rows` output into a file → `ia triage backfill <slug> --rows <file>` (idempotent; refuses rows from another client's workflow). `ia triage backfill <slug> [--sheet\|--csv]` copies an old record sheet in; a re-run that says 0 new is the parity check |
|
|
57
|
+
| Weekly triage summary into the client's channel | `ia portal set-org-slack-channel --slug <slug> --channel <C…>` (`none` clears it) — the digest only posts for an org with a channel |
|
|
45
58
|
| Mint a GCP SA key / Gemini key / Fathom webhook | `ia secrets mint <kind> …` |
|
|
46
59
|
| Portal org/agent admin (create org, passwords, run sync) | `ia portal <cmd>` — CLI-only, never via MCP |
|
|
47
60
|
|
|
@@ -55,12 +68,34 @@ list, including this one.
|
|
|
55
68
|
- The `client*` family, `docs search`, `agent templates`, and `linear-*`
|
|
56
69
|
are **read-only**. Nothing in `ia` ever writes to the team-clients
|
|
57
70
|
registry or Airtable.
|
|
71
|
+
- **The record source rule** for `ia triage soak-report|sample|health`: with
|
|
72
|
+
`IA_PORTAL_ADMIN_SECRET` set, the **portal comes first** (the
|
|
73
|
+
`triage_classifications` record of the client's triage agent; `--agent`
|
|
74
|
+
when the org has more than one). A portal 404 (no triage agent) falls back
|
|
75
|
+
to the record sheet, and the evidence header says why. `--sheet <id>` /
|
|
76
|
+
`--csv <file>` force the sheet (a client from before the move; the sheet
|
|
77
|
+
read needs `GOOGLE_SERVICE_ACCOUNT_KEY` as Viewer). `--since <iso>` /
|
|
78
|
+
`--until <iso>` window every source — use `--since` for "rows after the
|
|
79
|
+
promotion".
|
|
80
|
+
- `ia triage soak-report|sample|health` never write to the record or the
|
|
81
|
+
mailbox; their only write is the evidence markdown in
|
|
82
|
+
`clients/client-<slug>/evidence/`, and they refuse to overwrite today's
|
|
83
|
+
file (`--force`). The MCP twins compute the same result and write nothing.
|
|
84
|
+
- `ia triage enable` and `ia triage backfill` write to the portal, so they
|
|
85
|
+
are CLI-only (like `ia portal set-agent-triage` and
|
|
86
|
+
`set-org-slack-channel`). `enable` never prints node parameters — a triage
|
|
87
|
+
workflow's prompts hold client data.
|
|
58
88
|
- `ia secrets mint *` and `ia portal set-password` print the secret **once**
|
|
59
89
|
(stdout is exactly the secret) and store nothing — save it to the client's
|
|
60
90
|
1Password vault immediately.
|
|
61
91
|
- Anything touching existing files skips or refuses; nothing overwrites
|
|
62
92
|
silently. The root `.env` is never overwritten, not even by
|
|
63
|
-
`wizard --update`.
|
|
93
|
+
`wizard --update` or `sync --docs`.
|
|
94
|
+
- `ia env fill` covers the technician var set only. The infra/portal/payments
|
|
95
|
+
vars are withheld as a bare count, never listed by name — don't "helpfully"
|
|
96
|
+
re-add them to a report. `--admin` opts in for whoever holds that grant.
|
|
97
|
+
- Commands are single words. If a new one ever needs two, join them with a
|
|
98
|
+
colon (`family:verb`), never a dash.
|
|
64
99
|
- Portal mutations and `client-intake` are deliberately CLI-only (no MCP
|
|
65
100
|
twin) — don't script agents around that.
|
|
66
101
|
|
|
@@ -73,9 +108,16 @@ list, including this one.
|
|
|
73
108
|
- No `ia` on PATH yet? The CLI lives in `team-tools/`:
|
|
74
109
|
`pnpm install && pnpm -r build`, then `node apps/cli/dist/index.js …`
|
|
75
110
|
(bootstrap order for a from-scratch machine is in root `ONBOARDING.md`).
|
|
76
|
-
- Cloning InstallAgent repos
|
|
77
|
-
|
|
78
|
-
|
|
111
|
+
- Cloning InstallAgent repos works over **HTTPS** using the gh CLI's
|
|
112
|
+
credential helper, so `gh auth login` is sufficient; `ia wizard --ssh`
|
|
113
|
+
switches to SSH URLs. On shared machines the git identity may be
|
|
114
|
+
directory-scoped — if a clone fails with auth errors, say so rather than
|
|
115
|
+
retrying with other credentials.
|
|
116
|
+
- **Windows:** run `op`-touching commands (`ia env fill`, `ia env push`) from
|
|
117
|
+
PowerShell. 1Password supports PowerShell only, so its CLI cannot
|
|
118
|
+
authenticate from Git Bash — the command will look installed and still
|
|
119
|
+
fail. `ia doctor` detects this and adjusts its fix-it text; if you ever see
|
|
120
|
+
`brew` suggested on Windows, that is a bug to report, not to work around.
|
|
79
121
|
|
|
80
122
|
## When NOT to use ia
|
|
81
123
|
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: init_repo
|
|
3
|
+
description: >-
|
|
4
|
+
ONLY invoke when the user explicitly runs the /init_repo command, or
|
|
5
|
+
explicitly asks to invoke it by name. Do NOT trigger this on generic
|
|
6
|
+
mentions of "set up the client repo," "onboard this client," "scaffold the
|
|
7
|
+
repo," or similar — those route to `client-deliverables` / `engagement-spec`
|
|
8
|
+
/ `ia new-client` instead, which handle creating and filling a brand-new
|
|
9
|
+
client-<slug> repo. This skill assumes that repo already exists and has a
|
|
10
|
+
GitHub remote. When explicitly invoked, it scaffolds git/GitHub/Linear
|
|
11
|
+
branch structure on top of an existing client-<slug> build repo: creates
|
|
12
|
+
and pushes a `dev` branch, sets it as the GitHub default branch, reads the
|
|
13
|
+
client's linear_project from CLIENT.md, and creates one GitHub milestone +
|
|
14
|
+
one root branch per qualifying Linear issue. It deliberately does not
|
|
15
|
+
create GitHub issues or per-issue branches — that stays manual.
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
# /init_repo — client repo branch & milestone scaffolding
|
|
19
|
+
|
|
20
|
+
Sets up the git/GitHub/Linear scaffolding a `client-<slug>` build repo needs
|
|
21
|
+
before coding work starts: a `dev` branch as default, and one GitHub
|
|
22
|
+
milestone + one root branch per Linear issue that will eventually need a
|
|
23
|
+
commit. Everything finer-grained than that (individual GitHub issues,
|
|
24
|
+
feature branches inside a milestone) is created by hand afterward — this
|
|
25
|
+
skill is scaffolding, not issue management.
|
|
26
|
+
|
|
27
|
+
**Only runs on explicit invocation** (`/init_repo` or `/init_repo
|
|
28
|
+
client-<slug>`). Never fire this from a generic "set up the repo" request —
|
|
29
|
+
check whether the user actually typed the command or named this skill first.
|
|
30
|
+
|
|
31
|
+
## Scope boundary
|
|
32
|
+
|
|
33
|
+
- **Not this skill:** creating the repo itself, filling `CLIENT.md`, writing
|
|
34
|
+
`docs/01-04`, creating the Linear project. That's `ia new-client
|
|
35
|
+
<slug>` (bare scaffold) followed by the `engagement-spec` skill (fills the
|
|
36
|
+
docs), or the portal's Client scaffold studio, which does both end-to-end.
|
|
37
|
+
If `clients/client-<slug>/` doesn't exist yet, stop and tell the user to
|
|
38
|
+
run that path first.
|
|
39
|
+
- **Not this skill:** creating GitHub issues, or a branch per individual
|
|
40
|
+
Linear issue. The user creates those manually inside each milestone's root
|
|
41
|
+
branch, on purpose — it's how they keep a milestone's branch from growing
|
|
42
|
+
too large before it merges.
|
|
43
|
+
- **This skill:** `dev` branch + default branch, one milestone + one root
|
|
44
|
+
branch per qualifying leaf issue. That's the entire output.
|
|
45
|
+
|
|
46
|
+
Before any GitHub action (branch push, default-branch change, milestone
|
|
47
|
+
creation), follow the `github-profile` skill so it runs under the correct
|
|
48
|
+
account. Branch-naming and Linear conventions below build on the `linear`
|
|
49
|
+
skill — read that first if anything here is unclear.
|
|
50
|
+
|
|
51
|
+
## Step 1 — Resolve the target repo
|
|
52
|
+
|
|
53
|
+
- `/init_repo` with no argument: list the directories under `clients/`
|
|
54
|
+
matching `client-*`, and ask the user to pick one.
|
|
55
|
+
- `/init_repo <arg>`: match `arg` against `clients/client-*` (accept the
|
|
56
|
+
slug with or without the `client-` prefix). If more than one directory
|
|
57
|
+
plausibly matches, or none do, list the candidates and ask the user to
|
|
58
|
+
confirm rather than guessing.
|
|
59
|
+
- Confirm the resolved repo has a GitHub remote: `git -C
|
|
60
|
+
clients/client-<slug> remote -v`. No remote → stop and tell the user; this
|
|
61
|
+
skill assumes one already exists (see `linear` skill's PR-linking section
|
|
62
|
+
for the same check).
|
|
63
|
+
|
|
64
|
+
## Step 2 — `dev` branch + GitHub default branch
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git -C clients/client-<slug> fetch origin
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- If local `dev` doesn't exist yet: `git checkout -b dev main` (or
|
|
71
|
+
`origin/main` if `main` isn't checked out locally). If `dev` already
|
|
72
|
+
exists, just check it out — don't recreate it.
|
|
73
|
+
- Push it: `git push -u origin dev`.
|
|
74
|
+
- Check the current GitHub default branch before changing anything:
|
|
75
|
+
`gh repo view InstallAgent/client-<slug> --json defaultBranchRef -q
|
|
76
|
+
.defaultBranchRef.name`. If it's already `dev`, skip this step (idempotent
|
|
77
|
+
no-op). Otherwise:
|
|
78
|
+
`gh repo edit InstallAgent/client-<slug> --default-branch dev`.
|
|
79
|
+
- This changes what a fresh clone checks out and what PRs target by
|
|
80
|
+
default — tell the user this happened, don't do it silently.
|
|
81
|
+
|
|
82
|
+
## Step 3 — Find the Linear project
|
|
83
|
+
|
|
84
|
+
Read `clients/client-<slug>/CLIENT.md`'s `linear_project` field and resolve
|
|
85
|
+
it via the Linear MCP tools (`get_project` / `list_projects`). This is the
|
|
86
|
+
authoritative pointer per the `linear` skill — never fuzzy-match the project
|
|
87
|
+
by repo name.
|
|
88
|
+
|
|
89
|
+
## Step 4 — Find qualifying "main" issues
|
|
90
|
+
|
|
91
|
+
Pull every issue in that project (`list_issues`, filtered by project,
|
|
92
|
+
including `parentId`). Classify by tree position, not by leaf-vs-parent:
|
|
93
|
+
|
|
94
|
+
- **Root/container**: an issue with no parent that has at least one child
|
|
95
|
+
(e.g. a `Build 1 — ...` umbrella issue). Purely organizational — never
|
|
96
|
+
gets a milestone itself.
|
|
97
|
+
- **Main issue**: either (a) a direct child of a root/container issue — a
|
|
98
|
+
milestone candidate **whether or not it has its own sub-issues** — or (b)
|
|
99
|
+
an issue with no parent and no children (fully standalone). Every
|
|
100
|
+
milestone maps to exactly one main issue.
|
|
101
|
+
- **Sub-issue**: a child of a main issue (any depth below it). Never gets
|
|
102
|
+
its own milestone or branch, no matter how far it's nested — it's folded
|
|
103
|
+
into its main issue's milestone description as a checklist item instead
|
|
104
|
+
(Step 5). This is the case that broke the old "leaf issue" rule: a
|
|
105
|
+
"Blockers" umbrella like `[B]` isn't a leaf (it has children), but it's
|
|
106
|
+
still one main issue and one milestone — its children become the
|
|
107
|
+
checklist, not separate milestones.
|
|
108
|
+
|
|
109
|
+
A main issue qualifies when its status isn't `Done` / `Canceled` /
|
|
110
|
+
`Duplicate`, and it (or something under it) will require a git push at some
|
|
111
|
+
point — code **or** docs. In practice this almost always holds once an
|
|
112
|
+
issue has any sub-issues at all (status changes on the children typically
|
|
113
|
+
get mirrored into a doc somewhere, e.g. `docs/04-access-checklist.md`), so
|
|
114
|
+
the push test mainly matters for filtering *standalone, childless* main
|
|
115
|
+
issues that are pure discussion/decision with no repo artifact ever. If
|
|
116
|
+
it's genuinely unclear, ask the user rather than guessing — skipping is
|
|
117
|
+
cheap, but creating-then-deleting a milestone is noisy.
|
|
118
|
+
|
|
119
|
+
## Step 5 — One GitHub milestone per qualifying main issue
|
|
120
|
+
|
|
121
|
+
- Check for an existing milestone first: `gh api
|
|
122
|
+
repos/InstallAgent/client-<slug>/milestones --paginate` and match on the
|
|
123
|
+
`INS-xxx` prefix in the title. If one already exists for that issue, skip
|
|
124
|
+
it (idempotent — never duplicate).
|
|
125
|
+
- Title: `INS-xxx — <issue title>`.
|
|
126
|
+
- Description: a link back to the Linear issue
|
|
127
|
+
(`https://linear.app/install-agent/issue/INS-xxx`), plus a GitHub-flavored
|
|
128
|
+
checkbox list:
|
|
129
|
+
- If the main issue **has sub-issues**, one checklist line per sub-issue
|
|
130
|
+
— `- [ ] INS-xxx — <title>` (checked if that sub-issue is already
|
|
131
|
+
Done/Canceled) — regardless of how many levels deep they nest. Don't
|
|
132
|
+
create separate milestones or branches for any of them.
|
|
133
|
+
- If the main issue **has no sub-issues** (standalone), pull the
|
|
134
|
+
checklist from its own description/acceptance criteria if it has one,
|
|
135
|
+
otherwise a single unchecked placeholder item for the user to flesh out
|
|
136
|
+
by hand.
|
|
137
|
+
- Create it: `gh api repos/InstallAgent/client-<slug>/milestones -f
|
|
138
|
+
title="INS-xxx — ..." -f description="..." -f state=open`.
|
|
139
|
+
- **Never change the Linear issue's status here.** Creating a milestone is
|
|
140
|
+
organizational structuring, not starting work — it must not trigger the
|
|
141
|
+
`In Progress` transition described in the `linear` skill's status
|
|
142
|
+
discipline.
|
|
143
|
+
|
|
144
|
+
## Step 6 — One root branch per milestone
|
|
145
|
+
|
|
146
|
+
- Get the issue's suggested branch name via `get_issue`
|
|
147
|
+
(`gitBranchName`, e.g. `noahm/ins-264-fix-sftp-upload-path`).
|
|
148
|
+
- Strip the leading `<username>/` segment and prefix with `milestone/`:
|
|
149
|
+
`milestone/ins-264-fix-sftp-upload-path`.
|
|
150
|
+
- Skip if that branch already exists locally or on `origin` — never
|
|
151
|
+
overwrite or duplicate.
|
|
152
|
+
- Otherwise branch off `dev` (not `main`):
|
|
153
|
+
```bash
|
|
154
|
+
git -C clients/client-<slug> checkout -b milestone/<slug> dev
|
|
155
|
+
git -C clients/client-<slug> push -u origin milestone/<slug>
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Step 7 — Summarize and stop
|
|
159
|
+
|
|
160
|
+
Print a short summary: branches created vs. skipped (already existed),
|
|
161
|
+
milestones created vs. skipped, and any issues that were skipped pending a
|
|
162
|
+
judgment call from the user. Stop there — this skill's job ends at the
|
|
163
|
+
scaffolding. Sub-issue creation, feature branches inside a milestone, and
|
|
164
|
+
eventual root-to-`dev` PRs are manual.
|
|
165
|
+
|
|
166
|
+
## Closing a milestone later (not automated by this skill)
|
|
167
|
+
|
|
168
|
+
When the user is ready to fold a milestone's root branch into `dev`, the PR
|
|
169
|
+
body should carry the Linear magic keyword (`Fixes INS-xxx` / `Closes
|
|
170
|
+
INS-xxx` / `Resolves INS-xxx`) for **every** issue that milestone covers,
|
|
171
|
+
batched onto that one PR — not scattered across earlier PRs merged into the
|
|
172
|
+
root branch itself. Two things this ordering protects:
|
|
173
|
+
|
|
174
|
+
- GitHub only auto-closes an issue on merge into the repo's **default**
|
|
175
|
+
branch. Since the root branch (`milestone/...`) isn't the default branch,
|
|
176
|
+
merges into it never auto-close anything — only the final root-to-`dev`
|
|
177
|
+
PR does. Keeping the magic keywords off earlier PRs (into the root
|
|
178
|
+
branch) is what prevents issues from closing early.
|
|
179
|
+
- Once every issue under a milestone is closed, GitHub auto-closes the
|
|
180
|
+
milestone itself — no extra scripting needed for that part.
|
|
181
|
+
|
|
182
|
+
## Re-running
|
|
183
|
+
|
|
184
|
+
Safe to re-run against the same repo at any time — every step above already
|
|
185
|
+
skips existing branches, existing milestones, and closed/canceled/duplicate
|
|
186
|
+
issues rather than duplicating or overwriting. If issues were added to
|
|
187
|
+
Linear well after the first run and it's unclear which ones should now be
|
|
188
|
+
pulled in, ask the user for a scope check before creating anything new.
|
|
@@ -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.
|