@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,258 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: email-triage-rollout
|
|
3
|
+
description: >-
|
|
4
|
+
Roll out an AI email-triage assistant into a client's live mailbox as a
|
|
5
|
+
staged program instead of a one-shot deploy — soak (watch, write nothing),
|
|
6
|
+
label-only, organize (noise leaves the inbox), then full (drafts). Covers the
|
|
7
|
+
one thing that makes it a product rather than a build: the exit gate each
|
|
8
|
+
stage must pass before the next one starts, with real numbers and a
|
|
9
|
+
zero-tolerance list, so a technician cannot promote on a hunch. Also covers
|
|
10
|
+
the week-1 soak report (the fixed table set that turns a week of observed
|
|
11
|
+
mail into a taxonomy the client approves), what to say to the client at each
|
|
12
|
+
promotion, the pause switch, and how each promotion lands as one CADENCE
|
|
13
|
+
slice in the client's build repo. Use this WHENEVER an engagement involves
|
|
14
|
+
email triage, inbox cleanup, auto-labeling, or mailbox organization — "set up
|
|
15
|
+
their inbox", "triage their email", "the AI is labeling wrong", "can we turn
|
|
16
|
+
on archiving yet", "week 1 of the email agent", "what stage are they on",
|
|
17
|
+
"write the soak report", "is it safe to enable drafts" — or when deploying
|
|
18
|
+
the `email-gmail-triage` or `email-outlook-triage` banked template. Reach for
|
|
19
|
+
it even if the user never says "skill". It governs the ROLLOUT; each
|
|
20
|
+
template's own `sop.md` in the agents/ bank carries the per-provider detail.
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
# Email triage rollout
|
|
24
|
+
|
|
25
|
+
## What this is for
|
|
26
|
+
|
|
27
|
+
An email triage agent is the highest-trust automation we deploy. It has write
|
|
28
|
+
access to the one system a business owner checks a hundred times a day, and the
|
|
29
|
+
failure mode is not an error message — it is an email that was there and now is
|
|
30
|
+
not. One misfiled message costs more trust than three weeks of correct
|
|
31
|
+
labelling earns.
|
|
32
|
+
|
|
33
|
+
So we never deploy it at full power. It goes in as **four stages**, each one
|
|
34
|
+
selected by a single config value and each gated on evidence from the client's
|
|
35
|
+
own mail.
|
|
36
|
+
|
|
37
|
+
**The stage model, in one line each:**
|
|
38
|
+
|
|
39
|
+
| Stage | Value | What changes in the mailbox |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 1. Soak | `soak` | **Nothing.** It classifies and records, and writes nothing at all |
|
|
42
|
+
| 2. Label only | `label` | Labels/categories appear. Nothing leaves the inbox |
|
|
43
|
+
| 3. Organize | `organize` | Newsletters and noise leave the inbox, always tagged first |
|
|
44
|
+
| 4. Full | `full` | Reply drafts appear in Drafts. Still never sends, never deletes |
|
|
45
|
+
|
|
46
|
+
**There is no calendar.** A stage ends when its gate passes, not on a Monday.
|
|
47
|
+
A busy inbox can reach stage 4 in ten days; a quiet one takes a month, and
|
|
48
|
+
that is correct — the gates need mail to measure.
|
|
49
|
+
|
|
50
|
+
**But the client heard "four weeks".** The kickoff deck (`docs/
|
|
51
|
+
kickoff-presentation.html`, slide 3) shows watch → report → diagrams → first
|
|
52
|
+
build live as four weeks. That is how we set expectations, said out loud as
|
|
53
|
+
the *typical shape* with one hedge ("each step moves when its check passes,
|
|
54
|
+
not on a date"). The gates are the contract. When a gate lags the deck, tell
|
|
55
|
+
the client the number and the likely day — never let the date slip silently.
|
|
56
|
+
|
|
57
|
+
**The client-facing vocabulary is four lanes** — **Critical / Today / Later /
|
|
58
|
+
Noise** — on the deck, in the soak report, and in every Slack message they
|
|
59
|
+
read. The templates' internal dispositions and categories map onto them (the
|
|
60
|
+
table is in each `sop.md` § *Client-facing lanes*; the code is
|
|
61
|
+
`team-tools` `triage-gates.ts`). Never say `archive` or `SalesPitch` to a
|
|
62
|
+
client.
|
|
63
|
+
|
|
64
|
+
## Start here
|
|
65
|
+
|
|
66
|
+
1. **Identify the template.** Gmail → `agents/email-gmail-triage/`. Outlook or
|
|
67
|
+
365 → `agents/email-outlook-triage/`. Never build inbox triage from a blank
|
|
68
|
+
canvas.
|
|
69
|
+
2. **Read that template's `sop.md`.** It is the authority for preconditions,
|
|
70
|
+
the stage table, the gate numbers, and rollback. This skill is the shared
|
|
71
|
+
method; the SOP is the provider-specific contract.
|
|
72
|
+
3. **Set up the record before the first publish.** The classification record
|
|
73
|
+
is the client portal's `triage_classifications` table — one row per
|
|
74
|
+
message, sender domain only — written by the template's record branch
|
|
75
|
+
(`🧺 Batch Record Rows` → `📊 Record to Portal`). There is no sheet to
|
|
76
|
+
create. Register the org + agent (`ia portal create-agent`), bind the two
|
|
77
|
+
credentials in the n8n UI (`IA - portal - agent-ingest`,
|
|
78
|
+
`IA - slack - agent-zero`), then **`ia triage enable <slug>`** — it checks
|
|
79
|
+
the live workflow's record wiring, marks the agent as a triage agent, and
|
|
80
|
+
prints the next steps. Publish only after it passes, then check the first
|
|
81
|
+
execution's `📊 Record to Portal` output (never the `⚙️ Stage` or trigger
|
|
82
|
+
nodes — they hold full email bodies).
|
|
83
|
+
4. **Confirm which stage the client is on.** It is not a memory question — the
|
|
84
|
+
`stage` column in the client's classification record, and the `stage=`
|
|
85
|
+
field in the n8n execution log, both answer it.
|
|
86
|
+
5. **Read the client repo's `CADENCE.md`.** Every promotion is one cadence
|
|
87
|
+
slice, and the surface matrix says what must move in the same commit.
|
|
88
|
+
|
|
89
|
+
## The two rules that carry the whole program
|
|
90
|
+
|
|
91
|
+
**1. Promotion is config, never node surgery.** One value (`TRIAGE_STAGE` in
|
|
92
|
+
the `⚙️ Stage` node), published, re-exported, committed. Never enable a
|
|
93
|
+
disabled node to promote a client. A disabled node leaves no audit trail and
|
|
94
|
+
cannot answer "what stage is this client on?".
|
|
95
|
+
|
|
96
|
+
**2. A gate is a number plus a zero-tolerance list.** "It looks good" is not a
|
|
97
|
+
gate. Neither is a percentage on its own — 95% correct still permits the one
|
|
98
|
+
error that ends the engagement. Every gate names the errors that are never
|
|
99
|
+
acceptable at any percentage.
|
|
100
|
+
|
|
101
|
+
## The soak report
|
|
102
|
+
|
|
103
|
+
Week 1's deliverable is not a working workflow — it is a **taxonomy the client
|
|
104
|
+
approves**. Every soak report uses the same tables, so a technician reading
|
|
105
|
+
their second one already knows the shape.
|
|
106
|
+
|
|
107
|
+
Write it to `evidence/YYYY-MM-DD-email-triage-soak-report.md` in the client's
|
|
108
|
+
build repo, from the classification record — **with the tool, not by
|
|
109
|
+
hand**:
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
ia triage soak-report <slug> # reads the portal record
|
|
113
|
+
ia triage soak-report <slug> --since 2026-10-01T00:00Z # only rows from this instant on
|
|
114
|
+
ia triage soak-report <slug> --lane "Permits=Today" # a client-added category
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
It writes every table below in the fixed order, pre-computes the two numeric
|
|
118
|
+
gate-A checks, adds the lane view (table 3b), and refuses to overwrite a file
|
|
119
|
+
already written today (`--force`). You fill table 6's one-line definitions and
|
|
120
|
+
table 7's answers, then send. Needs `IA_PORTAL_ADMIN_SECRET` on your machine
|
|
121
|
+
(`ia env fill`); the evidence header names the source it read. (A client from
|
|
122
|
+
before the portal move still reads its old sheet — see the `ia-cli` skill's
|
|
123
|
+
source rule.)
|
|
124
|
+
|
|
125
|
+
**Required tables:**
|
|
126
|
+
|
|
127
|
+
1. **Volume** — total messages, messages/day, busiest and quietest day. Sets
|
|
128
|
+
the expectation for how fast the later gates can pass.
|
|
129
|
+
2. **Sender domains** — top 20 by volume, with a share-of-total column, and a
|
|
130
|
+
count of the long tail below them. This is where the taxonomy comes from.
|
|
131
|
+
A domain with 40 messages and no home in the proposed labels is a missing
|
|
132
|
+
category.
|
|
133
|
+
3. **Proposed disposition/category mix** — what the classifier said, as counts
|
|
134
|
+
and shares. Read it as a hypothesis, not a result. **3b. Client-facing
|
|
135
|
+
lanes** — the same mail as Critical / Today / Later / Noise; this is the
|
|
136
|
+
table the client sees first.
|
|
137
|
+
4. **Review-lane rate** — the share the model was not confident about. Above
|
|
138
|
+
~20% at soak means the taxonomy does not fit the mail yet. Fix that before
|
|
139
|
+
stage 2, not by lowering the confidence floor.
|
|
140
|
+
5. **Action-lane load** — how many messages/day would be starred or flagged.
|
|
141
|
+
If it is most of the inbox, the automation gives the owner nothing. This
|
|
142
|
+
number is the one clients feel most directly.
|
|
143
|
+
6. **Proposed taxonomy** — the label/category list, each with a one-line
|
|
144
|
+
definition and its expected volume from table 2. This is the thing the
|
|
145
|
+
client says yes or no to.
|
|
146
|
+
7. **Open questions** — anything the mail could not settle. Sender roster
|
|
147
|
+
gaps, ambiguous categories, mail whose importance depends on business
|
|
148
|
+
context we do not have.
|
|
149
|
+
|
|
150
|
+
**Then ask the client to approve or change the list, and wait for the answer.**
|
|
151
|
+
It is their mailbox and their vocabulary. A taxonomy we chose alone is a
|
|
152
|
+
taxonomy they will not use, and the gate does not pass without their yes in
|
|
153
|
+
writing.
|
|
154
|
+
|
|
155
|
+
## Sampling for the precision gates
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
ia triage sample <slug> --stage label # gate B → evidence/<date>-email-triage-stage2-gate.md
|
|
159
|
+
ia triage sample <slug> --stage organize # gate C → evidence/<date>-email-triage-stage3-gate.md
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The tool draws the sample, computes the review-lane rate over the stage
|
|
163
|
+
window, and writes the judging table with the thresholds and the
|
|
164
|
+
zero-tolerance list pre-filled. It cannot pass or fail the gate — **you open
|
|
165
|
+
every `message_id` and judge**. The building technician judges their own gate
|
|
166
|
+
(decided 2026-09-16); the seed printed in the evidence header lets anyone
|
|
167
|
+
re-draw the identical sample later, which is the check on that call.
|
|
168
|
+
|
|
169
|
+
- **Sample at random across the whole window**, not the most recent N. Recent
|
|
170
|
+
mail is the mail the technician has been staring at all week. The tool does
|
|
171
|
+
this; a spreadsheet sort does not.
|
|
172
|
+
- **Sample size 50** unless the SOP says otherwise. Open each message by its
|
|
173
|
+
`message_id` in the client's own mailbox — that is where the content is
|
|
174
|
+
allowed to live; it never gets copied into the record or the evidence
|
|
175
|
+
file.
|
|
176
|
+
- **A gate can only be sampled from rows written at the current stage.** After
|
|
177
|
+
a promotion the behaviour changed, so earlier rows are a different
|
|
178
|
+
experiment. `--since <promotion instant>` makes that exact, instead of
|
|
179
|
+
trusting the `stage` column alone.
|
|
180
|
+
- **Judge against what the owner would have wanted**, not against what the
|
|
181
|
+
prompt says. The prompt is the thing under test.
|
|
182
|
+
|
|
183
|
+
## What to tell the client
|
|
184
|
+
|
|
185
|
+
Use the `house-voice` skill — the Slack register.
|
|
186
|
+
|
|
187
|
+
- **Before stage 1:** what it reads, that it changes nothing yet, and roughly
|
|
188
|
+
how long. Get the yes.
|
|
189
|
+
- **At the taxonomy gate:** the soak findings in plain language plus the
|
|
190
|
+
proposed list. This is the one place we wait for a reply.
|
|
191
|
+
- **At every promotion:** what changes today, and how they undo it.
|
|
192
|
+
- **When a gate fails:** say so, with the number and what you are changing. A
|
|
193
|
+
client who hears "82%, so I am not moving it forward yet" trusts the next
|
|
194
|
+
promotion. A silent promotion is how a client finds out by noticing a moved
|
|
195
|
+
email — and that conversation costs more than the message you skipped.
|
|
196
|
+
|
|
197
|
+
## Landing a promotion in the client repo
|
|
198
|
+
|
|
199
|
+
One CADENCE slice, one commit:
|
|
200
|
+
|
|
201
|
+
- `evidence/YYYY-MM-DD-email-triage-stageN-gate.md` — the sample, the counts,
|
|
202
|
+
every miss, the verdict.
|
|
203
|
+
- `docs/02-tech-spec.md` — the stage section.
|
|
204
|
+
- `docs/00-delivery-log.md` — an entry, since something shipped.
|
|
205
|
+
- `onboarding.html` — the Workflows status badge.
|
|
206
|
+
- `workflows/*.json` — re-exported from n8n in the same session.
|
|
207
|
+
- The Linear issue → Done, and the next stage's issue unblocked.
|
|
208
|
+
|
|
209
|
+
Track the four stages as a Linear sub-issue tree with `blockedBy` chains (see
|
|
210
|
+
the `linear` skill), so stage 3 cannot open before stage 2 closes. The chain
|
|
211
|
+
is the enforcement; a checklist in a doc is not.
|
|
212
|
+
|
|
213
|
+
## Traps
|
|
214
|
+
|
|
215
|
+
- **A live client on an older version is not automatically retro-fitted.**
|
|
216
|
+
Record the exception in that repo's `AGENT.md` § *Client-specific gotchas*
|
|
217
|
+
and leave the running workflow alone until the next change touches it. That
|
|
218
|
+
includes a client that still records to a Google Sheet: moving it to the
|
|
219
|
+
portal follows the Gmail SOP § *Retro-fit* (double write for 7 days, the
|
|
220
|
+
backfill re-run says 0 new, then the Sheets node goes), one client per
|
|
221
|
+
session.
|
|
222
|
+
Re-cutting a production inbox to tidy up our own consistency is a risk the
|
|
223
|
+
client did not ask for.
|
|
224
|
+
- **The record is the health signal.** No new rows today means the workflow
|
|
225
|
+
is off, the trigger broke, or a credential expired. Nothing in the mailbox
|
|
226
|
+
will tell you — a triage agent that has stopped looks exactly like a quiet
|
|
227
|
+
inbox. The **portal's daily watch** (13:00 UTC) checks every active triage
|
|
228
|
+
agent and alerts `#team-techs` after 24 hours with no row; `ia triage
|
|
229
|
+
health <slug>` is the same check by hand (exit 1 when quiet). The portal
|
|
230
|
+
agent IS the registration — a client that never ran `ia triage enable` has
|
|
231
|
+
no watcher.
|
|
232
|
+
- **A record POST that fails alerts `#team-techs`** with the execution id.
|
|
233
|
+
Recovery: copy that execution's `🧺 Batch Record Rows` output into a file,
|
|
234
|
+
then `ia triage backfill <slug> --rows <file>` (idempotent; it refuses rows
|
|
235
|
+
from a workflow no agent of that client runs). The triage itself never
|
|
236
|
+
waited on the record, so no mail was missed.
|
|
237
|
+
- **The weekly client summary is automatic.** The `Team - Email Triage Weekly
|
|
238
|
+
Digest` workflow on our n8n reads the portal's totals
|
|
239
|
+
(`/api/triage-summary`) and posts, as Agent Zero, a short plain-words
|
|
240
|
+
summary into the client's channel every week (messages sorted, lane split,
|
|
241
|
+
current stage). That is the "weekly summary" the deck promises. It covers a
|
|
242
|
+
client only once its org has a channel: `ia portal set-org-slack-channel`.
|
|
243
|
+
Do not hand-write one; do read it, because a rising review lane there is
|
|
244
|
+
taxonomy drift.
|
|
245
|
+
- **Don't fix a bad taxonomy by lowering the confidence floor.** A rising
|
|
246
|
+
review lane is the system reporting that the categories do not match the
|
|
247
|
+
mail. Lowering the floor converts a visible problem into a silent one.
|
|
248
|
+
- **A failed execution must never silently drop a message.** Both mail
|
|
249
|
+
triggers advance by date, so a message whose run errored is never re-polled:
|
|
250
|
+
not retried, not labelled, and nothing says so. Every enabled write node
|
|
251
|
+
carries `retryOnFail`. If you add a node that writes to the mailbox, it
|
|
252
|
+
needs the same posture.
|
|
253
|
+
- **`soak` is also the pause switch.** Something looks wrong mid-engagement:
|
|
254
|
+
set the stage back to `soak` and publish. Writes stop, recording continues,
|
|
255
|
+
so the data does not stop while you diagnose.
|
|
256
|
+
- **The first reply draft the owner sees must not already be in their Drafts
|
|
257
|
+
folder.** Generate samples in a test run at the previous stage and paste
|
|
258
|
+
them into the channel.
|
|
@@ -43,7 +43,7 @@ you keep that same build folder's `onboarding.html` in sync:
|
|
|
43
43
|
| `01-overview.md` | The client | Plain English, **tech-agnostic** | What we're solving, what we're building, what to expect. The doc you'd send them. |
|
|
44
44
|
| `02-tech-spec.md` | Install Agent engineering | Precise, **names tools** | The implementation: architecture, data shapes, node-by-node, error handling, open questions. This is `onboarding.html`'s source of truth per `client-template/AGENT.md` — if they disagree, fix the page. |
|
|
45
45
|
| `03-client-onboarding.md` | The client's admin/bookkeeper | Plain English, checklist | Access + decisions + info we need, split by "before kickoff" vs "during week 1". This is the **ask**. |
|
|
46
|
-
| `04-access-checklist.md` | Install Agent (internal) |
|
|
46
|
+
| `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING. This is the **tracker**, kept current as access lands. Mirror §1 only into `onboarding.html`'s Access tab. |
|
|
47
47
|
| `onboarding.html` | A technician landing on the build cold | Scannable, tab per topic | Every `REPLACE_WITH_*` token filled from the same source material as `01`–`04` (step 6) — so the tech discovery call happens with real context already on screen, not a blank template. |
|
|
48
48
|
|
|
49
49
|
Look at the canonical exemplars before writing — match their depth and
|
|
@@ -161,35 +161,56 @@ The checklist that unblocks the build. Split by urgency so the client isn't
|
|
|
161
161
|
overwhelmed:
|
|
162
162
|
|
|
163
163
|
- **§1 Access (before kickoff)** — accounts/credentials we need, each with the
|
|
164
|
-
*minimum* role and how they grant it
|
|
165
|
-
|
|
164
|
+
*minimum* role and how they grant it: OAuth/invite where the system
|
|
165
|
+
supports it, or their **portal's Access tab** for a straight login
|
|
166
|
+
(username/password, plus a two-factor setup key if that login uses 2FA) —
|
|
167
|
+
submitted directly, on their own time, into a 1Password vault dedicated to
|
|
168
|
+
their engagement. Reserve a scheduled working session for what the form
|
|
169
|
+
can't cover (an admin-consent flow they have to click through themselves).
|
|
166
170
|
- **§2 Decisions (before kickoff)** — the choices only they can make (e.g.
|
|
167
171
|
confidence threshold, point of contact).
|
|
168
172
|
- **§3 Information (week 1, not blocking)** — exports, lists, edge cases to seed
|
|
169
173
|
rules.
|
|
170
174
|
- **§4 Ongoing** — review cadence, their time commitment, who owns what.
|
|
171
|
-
- **§5 What we are NOT asking for** — explicitly
|
|
172
|
-
|
|
175
|
+
- **§5 What we are NOT asking for** — explicitly: nothing over Slack, email,
|
|
176
|
+
or a shared doc — every credential goes through the portal or 1Password,
|
|
177
|
+
never pasted in a message — and no access beyond the named systems.
|
|
173
178
|
- **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
|
|
174
179
|
|
|
175
180
|
### 5. Draft `04-access-checklist.md` (internal tracker)
|
|
176
181
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
182
|
+
Two tables, never one. **§1 Credentials & grants** — one row per *system* we
|
|
183
|
+
need a credential or an access grant for (a login, an OAuth scope, a share, an
|
|
184
|
+
API key): **System | Access we need (minimum role/scope) | Used by | Status |
|
|
185
|
+
Notes**. Every software the client named on the sales call gets a row, even
|
|
186
|
+
when the ask is still MISSING or it is UNKNOWN whether a credential is needed.
|
|
187
|
+
**§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
|
|
188
|
+
intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
|
|
189
|
+
list, a person or a decision is never a §1 row; that mixing is what turns the
|
|
190
|
+
tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
|
|
191
|
+
UNKNOWN / N/A — set from what the call notes and registry profile actually say
|
|
192
|
+
was granted or promised, never assumed. This is the doc (and the matching
|
|
193
|
+
`onboarding.html` Access tab) a teammate opens to answer "what are we still
|
|
194
|
+
waiting on from this client?" without re-reading the call transcript. Update
|
|
195
|
+
it in the same commit whenever access lands — it decays fast otherwise.
|
|
185
196
|
|
|
186
197
|
- **Capture status, don't invent it.** If a call didn't confirm an item was
|
|
187
198
|
received, it's MISSING or REQUESTED, not HAVE.
|
|
199
|
+
- **When month one is inbox triage, the SOP's preconditions are §2 rows from
|
|
200
|
+
day one** (`agents/email-gmail-triage/sop.md` or `email-outlook-triage/
|
|
201
|
+
sop.md` § *Preconditions*): the client's written OK that every inbound
|
|
202
|
+
message is read; the BAA / DPA position for a regulated client; the VIP
|
|
203
|
+
list and key phrases; the classification record sheet created and shared
|
|
204
|
+
read-only with the tooling accounts; the sensitive categories (wire, legal,
|
|
205
|
+
health) and how they are handled. The mailbox OAuth grant itself is a §1
|
|
206
|
+
row. Mirror the written-OK ask into `03` §2 (Decisions) — it is the one
|
|
207
|
+
thing the client must say, not grant.
|
|
188
208
|
- **No credential values or IDs** — status and the 1Password vault *name*
|
|
189
209
|
only (from `CLIENT.md`), same rule as everywhere else in the repo.
|
|
190
|
-
- Mirror
|
|
191
|
-
|
|
192
|
-
`docs/`.
|
|
210
|
+
- Mirror **§1 only** into `onboarding.html`'s Access tab (its own sidebar
|
|
211
|
+
entry, `#access`) so a developer sees it in one screen without opening
|
|
212
|
+
`docs/`. §2 stays in the doc; the Client tab's status snapshot carries the
|
|
213
|
+
open decisions.
|
|
193
214
|
|
|
194
215
|
### 6. Populate `onboarding.html`
|
|
195
216
|
|
|
@@ -211,6 +232,17 @@ In short:
|
|
|
211
232
|
`<li>` per item, duplicate the template's stub `<li>` as needed. The
|
|
212
233
|
access table (`ITEM`/`SYSTEM`/`REASON`/`NOTE`, one row per item) is the
|
|
213
234
|
`04-access-checklist.md` mirror already required in step 5.
|
|
235
|
+
- **Builds tab** — one *systems-level* block per build in scope, duplicating
|
|
236
|
+
the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
|
|
237
|
+
`SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
|
|
238
|
+
node labels, `BUILD_CAPTION`, and the *under the hood* rows: `INSTANCE`,
|
|
239
|
+
`WORKFLOW_FILE`, `MODEL`, `LEDGER`, `STACK_NOTES`). Add the matching
|
|
240
|
+
`Builds / <name>` sub-link in the sidebar `.subnav` (href = the block's
|
|
241
|
+
`id="build-<slug>"`). Boxes are **client-safe** — the client's own systems
|
|
242
|
+
by name, ours as "Install Agent", no vendor of ours in the SVG; that detail
|
|
243
|
+
goes only in the collapsed *under the hood* table. Anything not yet built
|
|
244
|
+
is drawn dashed (`.ghost`). This is the picture shown on client update
|
|
245
|
+
calls and Looms, so draw it first.
|
|
214
246
|
- **Workflows tab** — one diagram block per automation in scope, duplicating
|
|
215
247
|
the template block (`WORKFLOW_TITLE`, `WORKFLOW_SLUG`, `STATUS`,
|
|
216
248
|
`TRIGGER`/`FILTER`/`AI_STEP`/`N`/`WRITE`/`NOTIFY` node labels, `CAPTION`).
|
|
@@ -259,8 +291,9 @@ tokens or empty bullets.
|
|
|
259
291
|
error table, AI specifics, **open questions**, build sequence.
|
|
260
292
|
- [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
|
|
261
293
|
/ quick-fill; minimum roles; "creds in your vault, never a password".
|
|
262
|
-
- [ ] `04-access-checklist.md`:
|
|
263
|
-
|
|
294
|
+
- [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
|
|
295
|
+
sales-call software has a row) + §2 decisions/information; Status set from
|
|
296
|
+
what's actually confirmed (not assumed); §1 mirrored into the Access tab.
|
|
264
297
|
- [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
|
|
265
298
|
update pass, only the ones the tech-discovery call still hasn't
|
|
266
299
|
answered); Client tab agrees with `02`, not the other way around.
|
|
@@ -119,8 +119,13 @@ write path → exception flow → prod cutover → tuning.>
|
|
|
119
119
|
done; §3 can come in parallel during week 1.>
|
|
120
120
|
|
|
121
121
|
## 1. Access (need before kickoff)
|
|
122
|
-
<Per system: the minimum role, how they grant it
|
|
123
|
-
|
|
122
|
+
<Per system: the minimum role, and how they grant it. For OAuth/invite-based
|
|
123
|
+
access, describe the grant. For a straight login (no API), point them at
|
|
124
|
+
their portal's Access tab to submit the username/password directly — and a
|
|
125
|
+
two-factor setup key too, if that login uses 2FA — themselves, on their own
|
|
126
|
+
time; it goes straight into their own 1Password vault, never through us by
|
|
127
|
+
hand. Reserve a live working session for what the form can't cover, e.g. an
|
|
128
|
+
admin-consent OAuth flow they have to click through.>
|
|
124
129
|
|
|
125
130
|
## 2. Decisions (need before kickoff)
|
|
126
131
|
<Choices only they can make: thresholds, point of contact, channel name.>
|
|
@@ -132,8 +137,9 @@ credentials go into the client's own vault — we never take a password.>
|
|
|
132
137
|
<Review-call cadence, their time on the review queue, who approves changes.>
|
|
133
138
|
|
|
134
139
|
## 5. What we are NOT asking for
|
|
135
|
-
<Explicit list:
|
|
136
|
-
|
|
140
|
+
<Explicit list: nothing over Slack, email, or a shared doc — every credential
|
|
141
|
+
goes through the portal's Access tab or 1Password, never pasted in a message;
|
|
142
|
+
no access beyond the named systems.>
|
|
137
143
|
|
|
138
144
|
## 6. Quick-fill checklist
|
|
139
145
|
- [ ] <access item invited/ready>
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gcloud-cli-setup
|
|
3
|
+
description: >-
|
|
4
|
+
Keep gcloud CLI accounts and configurations straight when more than one
|
|
5
|
+
GCP identity is in play on a machine — one named configuration per
|
|
6
|
+
account/client, and a check of the active account before any command
|
|
7
|
+
that touches a project. Use this WHENEVER someone logs into a new GCP
|
|
8
|
+
account, sets up a machine that will touch more than one client's GCP
|
|
9
|
+
project, asks "how do I add another gcloud account", "how do I switch
|
|
10
|
+
accounts", "which gcloud account am I on", or a GCP command runs against
|
|
11
|
+
the wrong project. Reach for it even if the user never says "skill" —
|
|
12
|
+
any time gcloud auth/config state is being set up or checked.
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# gcloud-cli-setup — one named configuration per account
|
|
16
|
+
|
|
17
|
+
Never run GCP commands off a single unnamed (`default`) configuration once
|
|
18
|
+
more than one account is in play on a machine. A stray command run against
|
|
19
|
+
the wrong active account can touch the wrong client's project.
|
|
20
|
+
|
|
21
|
+
## Core rule
|
|
22
|
+
|
|
23
|
+
One **named gcloud configuration** per account/client, never a bare
|
|
24
|
+
`default`:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
gcloud config configurations create <name>
|
|
28
|
+
gcloud config configurations activate <name>
|
|
29
|
+
gcloud config set account <email>
|
|
30
|
+
gcloud config set project <project-id>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Pick `<name>` to match the client slug or account purpose (e.g.
|
|
34
|
+
`behaviatherapy`, `installagent`), not the tool ("gcp") or the email local
|
|
35
|
+
part alone.
|
|
36
|
+
|
|
37
|
+
## Before running any GCP command
|
|
38
|
+
|
|
39
|
+
Confirm which account and project are active — don't assume:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
gcloud config configurations list
|
|
43
|
+
gcloud auth list
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The row with `IS_ACTIVE = True` (or the `*` in `auth list`) is what every
|
|
47
|
+
subsequent `gcloud` command runs as. If it's not the account/project you
|
|
48
|
+
expect, activate the right configuration first:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
gcloud config configurations activate <name>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Adding a new account
|
|
55
|
+
|
|
56
|
+
1. Check what already exists — don't assume a `default` configuration is
|
|
57
|
+
empty or safe to reuse:
|
|
58
|
+
```
|
|
59
|
+
gcloud config configurations list
|
|
60
|
+
```
|
|
61
|
+
2. Create a configuration named for the new account/client, then log in:
|
|
62
|
+
```
|
|
63
|
+
gcloud config configurations create <name>
|
|
64
|
+
gcloud config configurations activate <name>
|
|
65
|
+
gcloud auth login <email>
|
|
66
|
+
```
|
|
67
|
+
A browser window opens for sign-in. `gcloud` sets the signed-in account
|
|
68
|
+
active on that configuration automatically.
|
|
69
|
+
3. Set the project once you know it:
|
|
70
|
+
```
|
|
71
|
+
gcloud config set project <project-id>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Renaming a configuration
|
|
75
|
+
|
|
76
|
+
`gcloud` has no rename command. Recreate it:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
gcloud config configurations describe <old-name> # note account + project
|
|
80
|
+
gcloud config configurations create <new-name>
|
|
81
|
+
gcloud config configurations activate <new-name>
|
|
82
|
+
gcloud config set account <email-from-above>
|
|
83
|
+
gcloud config set project <project-from-above>
|
|
84
|
+
gcloud config configurations delete <old-name> # account stays logged in
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Switching per-terminal without changing the global active configuration
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
export CLOUDSDK_ACTIVE_CONFIG_NAME=<name>
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Useful when running commands for two accounts in different terminal tabs at
|
|
94
|
+
the same time. Or scope a single command with `--configuration=<name>`
|
|
95
|
+
instead of switching anything.
|
|
96
|
+
|
|
97
|
+
## Related
|
|
98
|
+
|
|
99
|
+
- `ia-cli` — the same "check what's active before you act" discipline
|
|
100
|
+
applies to `ia`'s own client-scoped commands.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: github-profile
|
|
3
|
+
description: >-
|
|
4
|
+
Force every GitHub action (gh CLI commands, git push/pull against a GitHub
|
|
5
|
+
remote, PR creation, gh api calls) to run under THIS MACHINE's Install Agent
|
|
6
|
+
work account — the one that is a member of the InstallAgent GitHub org —
|
|
7
|
+
never a personal account that is also logged into `gh` on the same machine.
|
|
8
|
+
Resolves the work account from the workspace-root `.github-account` file
|
|
9
|
+
(or from org membership when the file is missing), checks the active `gh`
|
|
10
|
+
account, and switches before the action. Use this WHENEVER a task is about
|
|
11
|
+
to run a `gh` command, a git operation against a GitHub remote, or any
|
|
12
|
+
GitHub API call. Reach for it even if the user never says "skill" — any
|
|
13
|
+
GitHub request on any technician machine.
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# github-profile — act as this machine's work account, never the personal one
|
|
17
|
+
|
|
18
|
+
Most technician machines have two GitHub accounts logged into the `gh` CLI:
|
|
19
|
+
the Install Agent work account and a personal one. Only the work account is
|
|
20
|
+
a member of the **InstallAgent** GitHub org. GitHub actions must never run
|
|
21
|
+
under the other one — a PR, an API call or a push under the personal account
|
|
22
|
+
lands on the wrong identity and usually fails with "Repository not found".
|
|
23
|
+
|
|
24
|
+
This skill is bundled into every technician's workspace, so it **never names
|
|
25
|
+
a person or a login**. The login lives in one machine-local file.
|
|
26
|
+
|
|
27
|
+
## Where the work account is recorded
|
|
28
|
+
|
|
29
|
+
`<workspace-root>/.github-account` — one line, the GitHub login of this
|
|
30
|
+
machine's work account. Nothing else. The workspace root is not a git repo
|
|
31
|
+
and the file is not part of the template bundle, so it never travels to
|
|
32
|
+
another machine.
|
|
33
|
+
|
|
34
|
+
## Before any GitHub action
|
|
35
|
+
|
|
36
|
+
1. **Resolve the work account.**
|
|
37
|
+
- If `.github-account` exists at the workspace root, its content is the
|
|
38
|
+
work login. Done.
|
|
39
|
+
- If it does not exist: list the logged-in accounts with
|
|
40
|
+
`gh auth status`, and for each login check org membership:
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
gh api orgs/InstallAgent/memberships/<login> --jq .state
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Exactly one `active` login → that is the work account. Write it to
|
|
47
|
+
`.github-account` so the next task skips this step.
|
|
48
|
+
None → stop and tell the user `gh auth login --hostname github.com`
|
|
49
|
+
is needed for the work account. Do not proceed under the other one.
|
|
50
|
+
More than one → ask the user which one is the work account for this
|
|
51
|
+
machine, then write the file.
|
|
52
|
+
|
|
53
|
+
2. **Check the active account.**
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
gh auth status
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
3. **If the active `github.com` account is not the work login, switch:**
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
gh auth switch --hostname github.com --user <work-login>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
4. Only then run the actual command (`gh pr create`, `gh api …`,
|
|
66
|
+
`git push`, …).
|
|
67
|
+
|
|
68
|
+
Do this check-then-switch every time a GitHub action starts a task — the
|
|
69
|
+
active account drifts whenever the user, another tool or another session
|
|
70
|
+
used the personal account in between.
|
|
71
|
+
|
|
72
|
+
## Git identity
|
|
73
|
+
|
|
74
|
+
Pushes over SSH use the per-repo key (`git config --get core.sshcommand` in
|
|
75
|
+
any InstallAgent clone) and are independent of the `gh` account — a switch
|
|
76
|
+
never fixes or breaks a push. Commits should carry the work account's
|
|
77
|
+
identity so history stays attributable and free of personal addresses:
|
|
78
|
+
|
|
79
|
+
- `user.name` = the work login
|
|
80
|
+
- `user.email` = `<id>+<login>@users.noreply.github.com`
|
|
81
|
+
(`gh api user --jq .id` prints the id while the work account is active)
|
|
82
|
+
|
|
83
|
+
If `git config user.email` in a repo shows something else, **say so and let
|
|
84
|
+
the user decide** — never rewrite their git config unasked.
|
|
85
|
+
|
|
86
|
+
## Token scope
|
|
87
|
+
|
|
88
|
+
The work account's `gh` token normally carries `repo, read:org, gist,
|
|
89
|
+
admin:public_key`. Org administration (removing a member, reading org
|
|
90
|
+
secrets) and writing under `.github/workflows/` need more — tell the user to
|
|
91
|
+
run `gh auth refresh -h github.com -s admin:org` (or `-s workflow`) rather
|
|
92
|
+
than working around it. Pushing workflow files over SSH is not subject to
|
|
93
|
+
the token scope.
|
|
94
|
+
|
|
95
|
+
## Offboarding a technician
|
|
96
|
+
|
|
97
|
+
Removing someone's GitHub access is one call under an org admin's account
|
|
98
|
+
and it also drops every team membership:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
gh api -X DELETE orgs/InstallAgent/members/<login>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Verify with the members list afterwards. Their machine's
|
|
105
|
+
`.github-account` is theirs to delete; nothing in the bundle references
|
|
106
|
+
them.
|