@installagent/sdk 0.2.0 → 0.4.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 (56) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/claude-hours.d.ts +134 -0
  4. package/dist/claude-hours.js +638 -0
  5. package/dist/client-drive.d.ts +3 -0
  6. package/dist/client-drive.js +2 -2
  7. package/dist/client-linear-create.d.ts +10 -0
  8. package/dist/client-linear-create.js +30 -3
  9. package/dist/env-fill.js +21 -4
  10. package/dist/env-registry.d.ts +4 -0
  11. package/dist/env-registry.js +54 -2
  12. package/dist/git.d.ts +31 -0
  13. package/dist/git.js +59 -0
  14. package/dist/google-service-account.d.ts +20 -0
  15. package/dist/google-service-account.js +49 -0
  16. package/dist/hours-estimate.d.ts +43 -0
  17. package/dist/hours-estimate.js +159 -0
  18. package/dist/hours-export-schedule.d.ts +35 -0
  19. package/dist/hours-export-schedule.js +188 -0
  20. package/dist/hours-ledger.d.ts +137 -0
  21. package/dist/hours-ledger.js +926 -0
  22. package/dist/index.d.ts +14 -3
  23. package/dist/index.js +14 -3
  24. package/dist/portal-admin.d.ts +68 -0
  25. package/dist/portal-admin.js +64 -1
  26. package/dist/sync-repos.d.ts +7 -0
  27. package/dist/sync-repos.js +10 -1
  28. package/dist/template-sync.d.ts +10 -9
  29. package/dist/template-sync.js +14 -9
  30. package/dist/triage-backfill.d.ts +37 -0
  31. package/dist/triage-backfill.js +211 -0
  32. package/dist/triage-enable.d.ts +90 -0
  33. package/dist/triage-enable.js +428 -0
  34. package/dist/triage-gates.d.ts +252 -0
  35. package/dist/triage-gates.js +951 -0
  36. package/dist/workspace-push.d.ts +39 -0
  37. package/dist/workspace-push.js +78 -0
  38. package/dist/workspace-status.d.ts +37 -0
  39. package/dist/workspace-status.js +114 -0
  40. package/package.json +1 -1
  41. package/templates/env.example +6 -2
  42. package/templates/workspace-root/.claude/settings.json +12 -1
  43. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
  44. package/templates/workspace-root/skills/CLAUDE.md +6 -1
  45. package/templates/workspace-root/skills/README.md +17 -2
  46. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  47. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  48. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  49. package/templates/workspace-root/skills/client-latest/SKILL.md +124 -82
  50. package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
  51. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
  52. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  53. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  54. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  55. package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
  56. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
@@ -0,0 +1,140 @@
1
+ ---
2
+ name: ad-machine
3
+ description: >-
4
+ The Install Agent Meta ads machine — the creative engine that turns a
5
+ script, a prompt/brief, OR a client's existing asset library into a batch
6
+ of human-realistic video ads, then hands the batch to the banked
7
+ `meta-video-ads-agent` n8n rail for paused publishing into the client's
8
+ Meta ad account. Two modes: BRIEF (script or prompt → new UGC-style /
9
+ product video ads generated via the connected media-generation MCP's ad
10
+ workflows) and RECYCLE (mine the client's Drive folder of past ads, raw
11
+ footage, and product photos — ad-multiplier variations of a winning ad,
12
+ recuts of real footage, image-to-video from product stills — so the
13
+ client never has to film again and creatives keep coming). Use this
14
+ WHENEVER someone says "make ads for [client]", "new ad batch", "turn this
15
+ script into ads", "multiply the winner", "we need more creatives",
16
+ "generate ads from their footage/assets", "Meta ads for [client]", or the
17
+ weekly ad digest names a winner to feed back. Reach for it even if the
18
+ user never says "skill". Output is always the same contract: a Drive
19
+ batch folder (videos + thumbnails + batch.json) that the n8n rail
20
+ validates — this skill never touches the Meta API itself, and nothing it
21
+ makes goes live without a human in Ads Manager.
22
+ ---
23
+
24
+ # ad-machine — the Meta ads creative engine
25
+
26
+ The two-layer split, and why it exists: **this skill is the creative
27
+ engine** (taste, brand, hooks, generation — a technician runs it in Claude
28
+ Code, quality stays human-supervised); **the banked
29
+ `agents/meta-video-ads-agent/` workflow is the delivery rail** (validation,
30
+ paused publishing, ledger, weekly insights). The seam between them is one
31
+ file: `batch.json`. This skill writes it; the rail enforces it. The
32
+ manifest schema and every hard rule (PAUSED-only, budget cap, cross-client
33
+ guard, special ad categories) live in
34
+ `agents/meta-video-ads-agent/template.md` — **that file is the source of
35
+ truth for the contract; do not restate or fork it here.**
36
+
37
+ ## Preconditions
38
+
39
+ - The media-generation MCP (Higgsfield) is connected in this session — the
40
+ `generate_*` tools and `get_workflow_instructions` are available. If not,
41
+ stop and say so; there is no fallback generator.
42
+ - Client brand facts are reachable: `team-clients/clients/<slug>/` (who
43
+ they are, offer, review themes) and the build repo's `CLIENT.md`.
44
+ Client-facing copy follows the `house-voice` skill.
45
+ - The client's ad config is known (from the rail's deployment): client
46
+ slug, landing URLs, special-ad-category decision, budget cap. If the
47
+ rail isn't deployed yet, you can still produce the batch folder — the
48
+ creatives are usable manually (stage 1 of the SOP).
49
+
50
+ ## Mode selection
51
+
52
+ | Input you were given | Mode | Generation route |
53
+ |---|---|---|
54
+ | A script (voiceover / talking-head copy) | BRIEF | `ugc-review-video` (talking head) or `ugc-product-video` (voiceover only) |
55
+ | A prompt / offer brief, no script | BRIEF | Write the scripts first (below), then as above |
56
+ | A product/store/site URL to feature on screen | BRIEF | `ugc-website-video` |
57
+ | A winning past ad (4–30s) + "more like this" | RECYCLE | `ad-multiplier` |
58
+ | Raw client footage (jobs, before/after, walkthroughs) | RECYCLE | `video-editing` recuts: hook title + cut + captions |
59
+ | Product/service photos only | RECYCLE | `product-photoshoot` stills → image-to-video where motion helps |
60
+
61
+ Always load the matching workflow with `get_workflow_instructions` before
62
+ generating — never call `generate_video` cold for an ad. The workflow
63
+ catalog changes; check it rather than assuming.
64
+
65
+ ## BRIEF mode
66
+
67
+ 1. **Ingest.** Script or prompt + brand facts + landing URL + objective.
68
+ One batch = one angle tested several ways: default **3 variants, one
69
+ hook each** (e.g. price-anchor / social-proof / question). Hooks differ
70
+ in the first 3 seconds; bodies may share 80%.
71
+ 2. **Scripts.** If given a prompt, draft the variant scripts in the
72
+ client's register (house-voice: plain concrete words, name the
73
+ objection then contrast, honest hedges on numbers). 15–30s each.
74
+ **Truth guard:** no fabricated testimonials, invented statistics,
75
+ undocumented offers, or fake urgency — the same lines the GBP posts
76
+ agent enforces. A creator in a UGC ad is a presenter delivering the
77
+ client's message, never a fake customer with a fake experience. Claims
78
+ must trace to something the client actually said or documented.
79
+ 3. **Generate** via the loaded workflow (consistent creator per batch,
80
+ client's product/branding as references where available). Then a
81
+ thumbnail per variant (`thumbnail-generation` workflow) — the rail
82
+ requires one.
83
+ 4. **Package + approve** (below).
84
+
85
+ ## RECYCLE mode — creatives keep coming without new filming
86
+
87
+ The client's Drive folder gets an asset library, one-time setup:
88
+
89
+ ```
90
+ <client Drive root>/ad-assets/
91
+ past-ads/ # every finished ad we've run (winners get re-multiplied)
92
+ raw/ # phone footage: jobs, before/after, team, workspace
93
+ product/ # product & result photos, logos already in brand kit
94
+ ```
95
+
96
+ Ask the client once, in their channel, for a phone dump into `raw/` — 20
97
+ clips of real work beats a shoot. After that the machine self-feeds:
98
+
99
+ 1. **Inventory** the library (list the folder; note durations, subjects,
100
+ what's fresh since last batch).
101
+ 2. **Pick the seam:**
102
+ - A proven winner (from the rail's Monday digest) that's 4–30s →
103
+ `ad-multiplier`: N independently edited versions (swap people,
104
+ background, on-screen text; keep the motion and timing that won).
105
+ This is the highest-yield route — prefer it when a winner exists.
106
+ - Good raw footage → `video-editing`: hook title card, tight cut,
107
+ burned captions, CTA end-card. Real footage reads as the most
108
+ "human" ad of all — spend the effort on the first 3 seconds.
109
+ - Stills only → `product-photoshoot` restyles and image-to-video.
110
+ 3. **Rights check:** only client-supplied or client-approved footage; any
111
+ recognizable person in `raw/` needs the client's confirmation they're
112
+ ok appearing in ads (record the answer in the client repo). Never pull
113
+ media from anywhere but their library and our generations.
114
+ 4. **Package + approve** (below).
115
+
116
+ ## Package + approve (both modes)
117
+
118
+ 1. Batch folder in the client's Drive: `ad-batches/<batch_id>/` with
119
+ `v1.mp4`, `v1-thumb.jpg`, …, and `batch.json` per the rail's schema
120
+ (`agents/meta-video-ads-agent/template.md`). `batch_id` =
121
+ `YYYY-MM-DD-<angle>`; variant names `v1…`; `hook_label` is the real
122
+ hook, kebab-case — it becomes the ad name and the insights join key.
123
+ 2. Post the videos + copy to the client's Slack channel for approval
124
+ (house-voice). **Wait for the yes.** This is the same gate the SOP's
125
+ stage 1 formalizes — no batch is submitted unapproved.
126
+ 3. Submit the Drive folder ID to the rail's Batch Intake form. The rail
127
+ takes it from there: validated, published PAUSED, ledgered. Activation
128
+ is a human in Ads Manager, always.
129
+ 4. Log the batch in the client repo's delivery log (one CADENCE slice:
130
+ scripts/angle chosen, approval permalink, batch id).
131
+
132
+ ## Cost + cadence
133
+
134
+ - Generation burns media-MCP credits — usage-based, passed through at cost
135
+ per our standard commercial model. Note the batch's credit spend in the
136
+ delivery log so the pass-through is honest.
137
+ - Steady state is pull, not push: the Monday digest names a winner → next
138
+ batch multiplies it; no winner → next batch tests a new angle. One batch
139
+ a week per client is plenty; ten mediocre variants lose to three sharp
140
+ ones.
@@ -55,7 +55,7 @@ by its `ci/repo-lint.mjs`:
55
55
  ```
56
56
  client-<slug>/
57
57
  ├── AGENT.md / CLAUDE.md / CLIENT.md
58
- ├── onboarding.html # tabbed open-me-first page: Architecture/Client/Proposals/Public
58
+ ├── onboarding.html # tabbed open-me-first page: Architecture/Client/Access/Builds/Workflows/Proposals/Public
59
59
  ├── docs/ # internal markdown (engagement-spec): 01-overview, 02-tech-spec,
60
60
  │ # 03-client-onboarding, ① the in-depth internal HTML (tabbed),
61
61
  │ # plus ③ diagrams as self-contained HTML (<system>-<audience>-diagram.html)
@@ -19,8 +19,9 @@ client-<slug>/
19
19
  │ ├── 02-tech-spec.md # internal: names tools, the decision model
20
20
  │ ├── 03-client-onboarding.md # what we need from the client
21
21
  │ └── <system>-overview.html # ① in-depth INTERNAL html (tabbed), if built
22
- ├── onboarding.html # tabbed open-me-first page (Architecture/Client/
23
- │ # Proposals/Public — Public is client-presentable)
22
+ ├── onboarding.html # tabbed open-me-first page (Architecture/Client/Access/
23
+ │ # Builds/Workflows/Proposals/Public — Public and the
24
+ │ # Builds diagrams are client-presentable)
24
25
  ├── workflows/ # n8n JSON exports, credential IDs scrubbed
25
26
  ├── data/ # client-sent raw data — gitignored (README tracked)
26
27
  ├── evidence/ # ④ dated backtest/validation records — required,
@@ -2,22 +2,23 @@
2
2
  name: client-latest
3
3
  description: >-
4
4
  Catch a technician (or an agent) up on one client engagement so they can
5
- resume the build — a two-part terminal brief: where it stands right now,
6
- then the risks and surface drift ranked worst-first. Reads the build repo
7
- (CLIENT.md, docs/00-delivery-log.md, evidence/, onboarding.html,
8
- AGENT.md gotchas), the local git state (uncommitted, unpushed, open PRs,
9
- stray worktrees), the read-only `ia client` / `ia client-linear`
10
- commands, the calendar (the one date a repo cannot be trusted for), the
11
- client's Slack channel, and n8n run health via `ia agent executions`. Use this WHENEVER someone says "what's the latest
12
- on [client]", "catch me up on [client]", "where did we leave off",
13
- "resume the [client] build", "status of [client]", "what's blocked on
14
- [client]", "did anything drift", "am I missing anything before I start",
15
- or opens a `clients/client-[slug]/` repo cold. Reach for it even if the
16
- user never says "skill". The brief itself is a pure read; it then asks how
17
- you want to move forward (fix the drift, start the top risk, pick another
18
- next step, or stop) and acts on the answer — in the working tree only,
19
- never a commit, never a push. Not call prep: an upcoming client call goes
20
- to `tech-call-prep` instead.
5
+ resume the build — a two-part terminal brief: where it stands right now
6
+ (bulleted, by system), then one ranked table of what's wrong and what to
7
+ do about it. Reads the build repo (CLIENT.md, docs/00-delivery-log.md,
8
+ evidence/, onboarding.html, AGENT.md gotchas), the local git state
9
+ (uncommitted, unpushed, open PRs, stray worktrees), the read-only
10
+ `ia client` / `ia client-linear` commands, the calendar (the one date a
11
+ repo cannot be trusted for), the client's Slack channel, and n8n run
12
+ health via `ia agent executions`. Use this WHENEVER someone says "what's
13
+ the latest on [client]", "catch me up on [client]", "where did we leave
14
+ off", "resume the [client] build", "status of [client]", "what's blocked
15
+ on [client]", "did anything drift", "am I missing anything before I
16
+ start", or opens a `clients/client-[slug]/` repo cold. Reach for it even
17
+ if the user never says "skill". The brief itself is a pure read; if the
18
+ ranked table has anything in it, it then asks how you want to move
19
+ forward (fix the drift, or start one of the ranked items) and acts on the
20
+ answer — in the working tree only, never a commit, never a push. Not call
21
+ prep: an upcoming client call goes to `tech-call-prep` instead.
21
22
  ---
22
23
 
23
24
  # client-latest — resume-the-build brief for one client
@@ -30,10 +31,11 @@ all of them in one pass and prints what is true, then what disagrees.
30
31
  one would itself go stale and become another drift source, which is the
31
32
  exact failure `CADENCE.md` exists to stop.
32
33
 
33
- Then ask how the reader wants to move forward, and act on the answer. The
34
- gathering steps never write. Only an explicit choice in the CTA does, and
35
- even then the work **stops in the working tree**: no commit, no push, no
36
- PR.
34
+ **If the ranked table (see Output below) has anything in it**, ask how the
35
+ reader wants to move forward, and act on the answer. If it's empty, say so
36
+ and stop — don't ask a question with no real options. The gathering steps
37
+ never write. Only an explicit choice in the CTA does, and even then the
38
+ work **stops in the working tree**: no commit, no push, no PR.
37
39
 
38
40
  ## Inputs
39
41
 
@@ -76,7 +78,7 @@ Note any key that is still a placeholder (`<...>`, or a literal
76
78
  - `onboarding.html` — find the status snapshot and its **`AS OF` date**.
77
79
  Compare that date to the newest log entry.
78
80
  - `AGENT.md` § *Client-specific gotchas* — the traps for this repo. Carry
79
- any that still apply into the RISKS block.
81
+ any that still apply into the risks/next table.
80
82
  - `docs/` index — a high-numbered handoff or decision-log doc
81
83
  (`NN-...-handoff.md`) is usually the freshest single page. Read it.
82
84
 
@@ -91,10 +93,19 @@ gh pr list --state open # if the repo pushes to GitHub
91
93
  git worktree list
92
94
  ```
93
95
 
94
- Built-but-unlanded work is the most common real risk in this workspace, so
95
- it gets its own line in the brief even when the count is zero. Also check
96
- `.claude/worktrees/` — a stale worktree holds a full duplicate `docs/`
97
- tree, and reading the wrong copy produces a confidently wrong brief.
96
+ Built-but-unlanded work is the most common real risk in this workspace —
97
+ it's the "Git vs reality" row in the drift table below, and it belongs
98
+ there even when the count is zero (say "clean" in the row rather than
99
+ omitting it). Also check `.claude/worktrees/` — a stale worktree holds a
100
+ full duplicate `docs/` tree, and reading the wrong copy produces a
101
+ confidently wrong brief.
102
+
103
+ **A PR that's green and ready to merge is not a passive fact — put it in
104
+ the ranked table as an action**, not just a count in the drift row. The
105
+ distinction: "3 unpushed commits" is drift (something disagrees with
106
+ reality); "PR #25 is green, waiting on a merge click" is a one-line fix,
107
+ so it belongs in NEXT-worthy rows even though nothing is technically
108
+ wrong yet.
98
109
 
99
110
  Never commit, never push, never force-push to undo something you find.
100
111
 
@@ -181,101 +192,132 @@ and line.
181
192
  | Linear vs delivery log | Issue is Done, no log entry exists — or the log says shipped while the issue sits In Progress |
182
193
  | `onboarding.html` vs delivery log | The `AS OF` snapshot date is older than the newest log entry |
183
194
  | Log vs git | An entry claims a deploy or merge with no matching commit in the window |
184
- | Git vs reality | Uncommitted or unpushed work that a log entry already describes as shipped |
195
+ | Git vs reality | Uncommitted files, unpushed commits, or an open PR — whether or not a log entry claims it shipped. State "clean" here explicitly when there's nothing, rather than omitting the row |
185
196
  | `CLIENT.md` | A key still holds a placeholder, so every tool that resolves through it is guessing |
186
197
  | n8n vs docs | Workflow inactive or draft while docs, Linear, or the client believe it is live |
187
198
  | Evidence | A log entry links `evidence/<file>.md` that does not exist, or an evidence file no entry mentions |
188
199
  | Worktrees | A `.claude/worktrees/` copy of `docs/` is newer than the tracked one |
189
200
 
190
- ## Output — two parts, state then risks
201
+ ## Output — state, then one ranked table
191
202
 
192
- Print exactly this shape. Plain text, no preamble.
203
+ Print exactly this shape. Markdown, no preamble, no restating the inputs.
204
+ Tables over prose wherever there's more than one column of facts — a reader
205
+ should be able to scan the whole brief in the time it takes to read one
206
+ screen, not parse paragraphs. **This is a terminal brief, not the delivery
207
+ log** — one line per fact, cite the source instead of narrating how you
208
+ found it, and leave the "why" and the history in the repo files the source
209
+ column points at.
193
210
 
194
211
  ```
195
- <CLIENT NAME> (<slug>) — build repo clean? YES|NO
212
+ ## <CLIENT NAME> (<slug>) — build repo clean? YES|NO
196
213
  Window: <start> → today (log anchor <date> · 7-day anchor <date>)
197
214
 
198
- WHERE IT STANDS
199
- <3-6 sentences. Present tense, only what is true now. What runs in
200
- production, in what mode, and what is still a draft. Name the surface each
201
- fact came from.>
202
-
203
- RISKS, WORST FIRST
204
- 1 <risk> → <what it blocks> (<INS-xxx / file:line>)
205
- 2 ...
206
-
207
- DRIFT
208
- - <surface A> says X · <surface B> says Y (<file:line>)
209
-
210
- UNLANDED
211
- - <n> uncommitted files in <path> · <n> unpushed commits · PR #<n> open
212
-
213
- NEXT
214
- 1. <the first concrete action>
215
- 2. ...
216
-
217
- COULD NOT READ
218
- - <source> — <why>
215
+ ### Where it stands
216
+ - **<system/component>:** <state, present tense, ≤12 words> (<source>)
217
+ - **<system/component>:** <state, present tense, ≤12 words> (<source>)
218
+ ...max 6 bullets — one per production system, workflow, or track, not
219
+ per event. Merge same-system updates into the one bullet that matters now.
220
+
221
+ ### Drift
222
+ | Surface A | Surface B | Disagreement | Location |
223
+ |---|---|---|---|
224
+ | <e.g. onboarding.html> | <e.g. delivery log> | <what they disagree on, ≤12 words> | <file:line> |
225
+ | Git vs reality | — | <clean, or n uncommitted / n unpushed / PR #n open+state> | <path> |
226
+ ...max 5 rows, ranked by what's at stake. If more exist, add one line below
227
+ the table: "+n more drift rows not shown."
228
+
229
+ ### Risks & next steps, worst first
230
+ | # | Risk / gap | Blocks | Fix | Source |
231
+ |---|---|---|---|---|
232
+ | 1 | <the problem, ≤12 words> | <what it blocks, or "—"> | <the concrete next step, ≤12 words> | <INS-xxx / file:line> |
233
+ | 2 | ... | | | |
234
+ ...max 5 rows. If more exist, add one line below the table: "+n more rows
235
+ not shown" — the CTA's slot 3 is how the reader sees them.
236
+
237
+ ### Could not read
238
+ - <source> — <why, ≤10 words>
219
239
  ```
220
240
 
221
- Then ask the CTA question below. The brief is never the end of the run.
241
+ One table, not two. A row doesn't have to be a live threat to belong here
242
+ — "PR #25 is green, needs a merge click" earns a row with `Blocks: —` and
243
+ `Fix: merge it`, same as a lost credential earns a row with `Blocks:
244
+ cutover`. Ranking still runs by what's actually at stake: a blocked
245
+ checkpoint outranks a one-click merge, which outranks a stale sentence in
246
+ a doc.
222
247
 
223
248
  Rules for the output:
224
249
 
225
- - **Rank risks by what they block**, not by how recent they are. A lost
226
- credential that blocks a checkpoint beats a stale sentence in a doc.
227
- - **Every claim carries its source.** `docs/00-delivery-log.md:41`,
228
- `INS-218`, `#client-<slug> 08-19`. A claim with no source does not go in.
229
- - **`COULD NOT READ` is required** whenever a source failed — an
250
+ - **Rank by what's at stake**, not by how recent it is or whether it's
251
+ "technically" a risk. A lost credential that blocks a checkpoint beats a
252
+ green PR waiting on a click, which beats a stale sentence in a doc.
253
+ - **Every row carries a source.** `docs/00-delivery-log.md:41`, `INS-218`,
254
+ `#client-<slug> 08-19`. A row with no source does not go in.
255
+ - **No separate "unlanded" bucket.** Uncommitted files, unpushed commits,
256
+ and open PRs are the "Git vs reality" drift row (state "clean" rather
257
+ than omitting it); anything actionable in there (a mergeable PR) also
258
+ gets its own row in the risks/next table so it isn't just reported and
259
+ forgotten.
260
+ - **`Could not read` is required** whenever a source failed — an
230
261
  unauthenticated MCP session, a missing token, no Linear project. A brief
231
262
  that silently skips Slack reads as "Slack was quiet".
232
263
  - **Never print a secret, key, password, or client PII**, and never a
233
264
  client's dollar amount into anything shared. Point at the system that
234
265
  holds the value.
235
- - Keep it short enough to read before you start work. If the brief runs
236
- past a screen, cut history, not risks.
237
-
238
- ## The CTA — always ask how to move forward
239
-
240
- After the brief, ask **one** question with these four options, in this
241
- order, every time. The shape never changes, so the reader learns it once.
266
+ - **Hard caps, not suggestions:** ≤6 bullets in "Where it stands", ≤5 rows
267
+ each in Drift and Risks/next, every cell one line. Ranking already decides
268
+ what survives — cut the lowest-stakes rows, not the formatting. If
269
+ something doesn't fit in one line, that's a sign it belongs in the repo
270
+ file the source column points at, not in the brief.
271
+ - One line of history per bullet/row max — a fact and its source, not the
272
+ story of how it was found. If the brief still runs past a screen with the
273
+ caps applied, cut adjectives and context clauses before cutting rows.
274
+
275
+ ## The CTA — ask only if there's something to act on
276
+
277
+ After the brief, check the drift table and the risks/next table. **If both
278
+ are empty, say "nothing open — repo's clean" and stop. Don't ask a
279
+ question with no real options** — a reader who wants nothing further will
280
+ just stop reading or move on; forcing a "nothing, thanks" choice on them
281
+ every time is friction, not care.
282
+
283
+ If either table has rows, ask **one** question with up to three options,
284
+ in this order:
242
285
 
243
286
  | Slot | Option | Build it from |
244
287
  |---|---|---|
245
- | 1 | **Fix the drift** — name the count and the items | the DRIFT block |
246
- | 2 | **Start the top risk** — name it and its issue | RISKS line 1 |
247
- | 3 | **Pick a different next step** — name how many exist | the NEXT block |
248
- | 4 | **Nothing — I only wanted the brief** | always present |
288
+ | 1 | **Fix the drift** — name the count and the items | the Drift table |
289
+ | 2 | **Start the top item** — name it | row 1 of the risks/next table |
290
+ | 3 | **Pick a different row** — name how many exist | the other rows |
291
+
292
+ Omit a slot if its source table is empty (e.g. no drift → only offer 2 and
293
+ 3). Never pad the list back to three with a "do nothing" option — that's
294
+ what silence is for.
249
295
 
250
296
  Rules:
251
297
 
252
- - **Ask even when the client is clean.** Slots 1 and 2 then say "no drift
253
- found" and "no open risk", and slot 4 is the obvious answer. A run whose
254
- shape changes with the findings is harder to trust than one that always
255
- ends the same way.
256
298
  - **Mark work a person must do** with `[HUMAN STEPS FIRST]` and say which
257
299
  step is theirs. A lost credential, a Vercel redeploy, an `op` login, a
258
300
  new OAuth credential in n8n — offering to "start" these without the
259
301
  marker wastes the reader's time.
260
- - **Slot 3 opens a second question** listing up to four NEXT items. Say in
261
- it how many items exist and how many are not shown.
262
- - **Nothing can answer in an unattended run** (a `/loop`, a cron, a
263
- subagent). Print the four options as plain text and stop there. Never
264
- pick on the reader's behalf.
302
+ - **Slot 3 opens a second question** listing up to four rows. Say in it how
303
+ many rows exist and how many are not shown.
304
+ - **In an unattended run** (a `/loop`, a cron, a subagent), print the
305
+ available options as plain text and stop there. Never pick on the
306
+ reader's behalf.
265
307
 
266
308
  ### If they choose "fix the drift"
267
309
 
268
- Fix **every mechanical drift in one pass**, then show one combined diff and
269
- stop. Mechanical means the fact is not in dispute: a stale date, a status
270
- snapshot that contradicts the delivery log, a missing evidence link, an
271
- unfilled `CLIENT.md` key whose real value is in the repo.
310
+ Fix **every mechanical drift row in one pass**, then show one combined diff
311
+ and stop. Mechanical means the fact is not in dispute: a stale date, a
312
+ status snapshot that contradicts the delivery log, a missing evidence
313
+ link, an unfilled `CLIENT.md` key whose real value is in the repo.
272
314
 
273
315
  - **Repo files only.** A change to Linear, n8n, Airtable, Drive, or Slack
274
316
  is a write to a **shared** surface, and discarding a diff cannot undo it.
275
317
  List those instead, with the exact command or issue id, under
276
318
  `YOUR CALL — SHARED SURFACES`. Then stop.
277
319
  - **Never invent the fixed value.** If two surfaces disagree and the repo
278
- cannot say which is right, that item is not mechanical. Leave it, and say
320
+ cannot say which is right, that row is not mechanical. Leave it, and say
279
321
  why in one line.
280
322
  - **`CADENCE.md` still governs.** A drift fix that moves the shape of a
281
323
  flow needs the diagram and the tech spec in the same change. If the fix
@@ -283,7 +325,7 @@ unfilled `CLIENT.md` key whose real value is in the repo.
283
325
  - **Stop in the working tree.** Print `git status --porcelain` and hand the
284
326
  commit to the reader. Never commit, never push, never force-push.
285
327
 
286
- ### If they choose the top risk or another next step
328
+ ### If they choose a row from the risks/next table
287
329
 
288
330
  Restate the item as a one-line contract before touching anything — the
289
331
  trigger, the inputs, the outputs, the failure behavior. That is CADENCE
@@ -10,8 +10,9 @@ it is a company name rather than a slug, resolve it through
10
10
  `team-clients/clients/*/PROFILE.md` and ask when two clients match.
11
11
 
12
12
  Follow `skills/client-latest/SKILL.md` exactly: the wider of the two window
13
- anchors, the seven read steps in order, every drift check, the two-part output
14
- shape, and then the four-option CTA — every time, even when the client is
15
- clean. Gathering the brief writes nothing. Acting on a CTA choice stops in
16
- the working tree: no commit, no push, and shared surfaces (Linear, n8n,
13
+ anchors, the seven read steps in order, every drift check, the bulleted
14
+ state + ranked-table output shape, and then the CTA — asked only when the
15
+ drift or risks/next table actually has rows; say the repo's clean and stop
16
+ otherwise. Gathering the brief writes nothing. Acting on a CTA choice stops
17
+ in the working tree: no commit, no push, and shared surfaces (Linear, n8n,
17
18
  Airtable, Drive, Slack) are proposed, never changed.
@@ -47,6 +47,20 @@ own mail.
47
47
  A busy inbox can reach stage 4 in ten days; a quiet one takes a month, and
48
48
  that is correct — the gates need mail to measure.
49
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
+
50
64
  ## Start here
51
65
 
52
66
  1. **Identify the template.** Gmail → `agents/email-gmail-triage/`. Outlook or
@@ -55,10 +69,21 @@ that is correct — the gates need mail to measure.
55
69
  2. **Read that template's `sop.md`.** It is the authority for preconditions,
56
70
  the stage table, the gate numbers, and rollback. This skill is the shared
57
71
  method; the SOP is the provider-specific contract.
58
- 3. **Confirm which stage the client is on.** It is not a memory question — the
59
- `stage` column in the client's classification record sheet, and the `stage=`
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=`
60
85
  field in the n8n execution log, both answer it.
61
- 4. **Read the client repo's `CADENCE.md`.** Every promotion is one cadence
86
+ 5. **Read the client repo's `CADENCE.md`.** Every promotion is one cadence
62
87
  slice, and the surface matrix says what must move in the same commit.
63
88
 
64
89
  ## The two rules that carry the whole program
@@ -80,7 +105,22 @@ approves**. Every soak report uses the same tables, so a technician reading
80
105
  their second one already knows the shape.
81
106
 
82
107
  Write it to `evidence/YYYY-MM-DD-email-triage-soak-report.md` in the client's
83
- build repo, from the classification record sheet.
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.)
84
124
 
85
125
  **Required tables:**
86
126
 
@@ -91,7 +131,9 @@ build repo, from the classification record sheet.
91
131
  A domain with 40 messages and no home in the proposed labels is a missing
92
132
  category.
93
133
  3. **Proposed disposition/category mix** — what the classifier said, as counts
94
- and shares. Read it as a hypothesis, not a result.
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.
95
137
  4. **Review-lane rate** — the share the model was not confident about. Above
96
138
  ~20% at soak means the taxonomy does not fit the mail yet. Fix that before
97
139
  stage 2, not by lowering the confidence floor.
@@ -112,15 +154,29 @@ writing.
112
154
 
113
155
  ## Sampling for the precision gates
114
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
+
115
169
  - **Sample at random across the whole window**, not the most recent N. Recent
116
- mail is the mail the technician has been staring at all week.
170
+ mail is the mail the technician has been staring at all week. The tool does
171
+ this; a spreadsheet sort does not.
117
172
  - **Sample size 50** unless the SOP says otherwise. Open each message by its
118
173
  `message_id` in the client's own mailbox — that is where the content is
119
- allowed to live; it never gets copied into the record sheet or the evidence
174
+ allowed to live; it never gets copied into the record or the evidence
120
175
  file.
121
176
  - **A gate can only be sampled from rows written at the current stage.** After
122
177
  a promotion the behaviour changed, so earlier rows are a different
123
- experiment.
178
+ experiment. `--since <promotion instant>` makes that exact, instead of
179
+ trusting the `stage` column alone.
124
180
  - **Judge against what the owner would have wanted**, not against what the
125
181
  prompt says. The prompt is the thing under test.
126
182
 
@@ -158,13 +214,34 @@ is the enforcement; a checklist in a doc is not.
158
214
 
159
215
  - **A live client on an older version is not automatically retro-fitted.**
160
216
  Record the exception in that repo's `AGENT.md` § *Client-specific gotchas*
161
- and leave the running workflow alone until the next change touches it.
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.
162
222
  Re-cutting a production inbox to tidy up our own consistency is a risk the
163
223
  client did not ask for.
164
- - **The record sheet is the health signal.** No new rows today means the
165
- workflow is off, the trigger broke, or a credential expired. Nothing in the
166
- mailbox will tell you — a triage agent that has stopped looks exactly like a
167
- quiet inbox.
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.
168
245
  - **Don't fix a bad taxonomy by lowering the confidence floor.** A rising
169
246
  review lane is the system reporting that the categories do not match the
170
247
  mail. Lowering the floor converts a visible problem into a silent one.