@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.
Files changed (114) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/agent-templates.d.ts +36 -2
  4. package/dist/agent-templates.js +173 -3
  5. package/dist/claude-hours.d.ts +118 -0
  6. package/dist/claude-hours.js +523 -0
  7. package/dist/client-drive.d.ts +3 -0
  8. package/dist/client-drive.js +2 -2
  9. package/dist/client-linear-create.d.ts +26 -0
  10. package/dist/client-linear-create.js +46 -0
  11. package/dist/client-linear.d.ts +28 -9
  12. package/dist/client-linear.js +36 -14
  13. package/dist/docs-search.d.ts +19 -6
  14. package/dist/docs-search.js +32 -11
  15. package/dist/doctor.d.ts +9 -0
  16. package/dist/doctor.js +126 -23
  17. package/dist/env-fill.d.ts +13 -0
  18. package/dist/env-fill.js +55 -13
  19. package/dist/env-push.d.ts +3 -0
  20. package/dist/env-push.js +11 -6
  21. package/dist/env-registry.d.ts +29 -0
  22. package/dist/env-registry.js +123 -9
  23. package/dist/exec.js +15 -2
  24. package/dist/git.d.ts +31 -0
  25. package/dist/git.js +59 -0
  26. package/dist/google-service-account.d.ts +20 -0
  27. package/dist/google-service-account.js +49 -0
  28. package/dist/hours-estimate.d.ts +43 -0
  29. package/dist/hours-estimate.js +159 -0
  30. package/dist/hours-export-schedule.d.ts +35 -0
  31. package/dist/hours-export-schedule.js +188 -0
  32. package/dist/hours-ledger.d.ts +129 -0
  33. package/dist/hours-ledger.js +882 -0
  34. package/dist/index.d.ts +25 -6
  35. package/dist/index.js +25 -6
  36. package/dist/linear-project.d.ts +2 -2
  37. package/dist/linear-project.js +2 -2
  38. package/dist/log.d.ts +28 -0
  39. package/dist/log.js +73 -0
  40. package/dist/n8n-executions.d.ts +85 -0
  41. package/dist/n8n-executions.js +259 -0
  42. package/dist/op-cli.d.ts +29 -0
  43. package/dist/op-cli.js +52 -0
  44. package/dist/platform.d.ts +35 -0
  45. package/dist/platform.js +39 -0
  46. package/dist/portal-admin.d.ts +108 -0
  47. package/dist/portal-admin.js +94 -1
  48. package/dist/standup.d.ts +88 -0
  49. package/dist/standup.js +235 -0
  50. package/dist/sync-repos.d.ts +54 -0
  51. package/dist/sync-repos.js +89 -0
  52. package/dist/template-sync.d.ts +11 -0
  53. package/dist/template-sync.js +16 -0
  54. package/dist/triage-backfill.d.ts +37 -0
  55. package/dist/triage-backfill.js +211 -0
  56. package/dist/triage-enable.d.ts +90 -0
  57. package/dist/triage-enable.js +428 -0
  58. package/dist/triage-gates.d.ts +252 -0
  59. package/dist/triage-gates.js +951 -0
  60. package/dist/wizard.d.ts +15 -0
  61. package/dist/wizard.js +35 -56
  62. package/dist/workspace-docs.d.ts +44 -0
  63. package/dist/workspace-docs.js +73 -0
  64. package/dist/workspace-push.d.ts +39 -0
  65. package/dist/workspace-push.js +78 -0
  66. package/dist/workspace-status.d.ts +37 -0
  67. package/dist/workspace-status.js +114 -0
  68. package/package.json +2 -2
  69. package/templates/env.example +37 -23
  70. package/templates/workspace-root/.claude/settings.json +12 -1
  71. package/templates/workspace-root/AGENT.md +7 -5
  72. package/templates/workspace-root/ONBOARDING.md +65 -8
  73. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +127 -0
  74. package/templates/workspace-root/skills/CLAUDE.md +29 -6
  75. package/templates/workspace-root/skills/README.md +171 -0
  76. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  77. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  78. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  79. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  80. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  81. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  82. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  83. package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
  84. package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
  85. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  86. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
  87. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  88. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  89. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  90. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  91. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  92. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  93. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  94. package/templates/workspace-root/skills/ia-cli/SKILL.md +49 -7
  95. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
  96. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  97. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  98. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  99. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  100. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  101. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  102. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  103. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  104. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  105. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  106. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  107. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  108. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  109. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  110. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  111. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  112. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  113. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  114. 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.
@@ -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. Use this WHENEVER writing or reviewing client-facing sentences,
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 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.
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), minting a credential, administering the portal,
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
- | Converge an existing workspace with the canonical one | `ia wizard <dir> --update` (ff-only pulls + refresh drifted root docs) |
35
- | "Is my environment OK?" / missing env vars / broken setup | `ia doctor [-w <dir>]` — every gap comes with a fix-it line |
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 requires GitHub SSH access; on shared machines
77
- the identity may be directory-scoped — if a clone fails with auth errors,
78
- say so rather than retrying with other credentials.
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) and client PDFs (SOW, proposal, overview, onboarding, one-pagers).
8
- Use this WHENEVER a diagram or document needs to look on-brand — triggers
9
- include "make it on-brand", "use our brand color/red", "add our logo",
10
- "official logo not a generic one", "branded PDF", "SOW/proposal PDF", "red
11
- excalidraw", "match our theme", or any client-facing visual. Reach for it even
12
- if the user never says "skill". It mirrors the single brand source
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, and contract-tech-agnostic — this one governs BRAND, those
16
- govern content/layout.
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
- Both are driven by [`scripts/brand.py`](scripts/brand.py) — palette constants,
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.