@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.
- package/dist/agent-mirror.d.ts +69 -0
- package/dist/agent-mirror.js +275 -0
- package/dist/claude-hours.d.ts +134 -0
- package/dist/claude-hours.js +638 -0
- package/dist/client-drive.d.ts +3 -0
- package/dist/client-drive.js +2 -2
- package/dist/client-linear-create.d.ts +10 -0
- package/dist/client-linear-create.js +30 -3
- package/dist/env-fill.js +21 -4
- package/dist/env-registry.d.ts +4 -0
- package/dist/env-registry.js +54 -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 +137 -0
- package/dist/hours-ledger.js +926 -0
- package/dist/index.d.ts +14 -3
- package/dist/index.js +14 -3
- package/dist/portal-admin.d.ts +68 -0
- package/dist/portal-admin.js +64 -1
- package/dist/sync-repos.d.ts +7 -0
- package/dist/sync-repos.js +10 -1
- package/dist/template-sync.d.ts +10 -9
- package/dist/template-sync.js +14 -9
- 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/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 +1 -1
- package/templates/env.example +6 -2
- package/templates/workspace-root/.claude/settings.json +12 -1
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
- package/templates/workspace-root/skills/CLAUDE.md +6 -1
- package/templates/workspace-root/skills/README.md +17 -2
- package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -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 +124 -82
- package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
- 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/github-profile/SKILL.md +106 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
- 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
|
|
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
|
-
|
|
7
|
-
(CLIENT.md, docs/00-delivery-log.md,
|
|
8
|
-
AGENT.md gotchas), the local git state
|
|
9
|
-
stray worktrees), the read-only
|
|
10
|
-
commands, the calendar (the one date a
|
|
11
|
-
client's Slack channel, and n8n run
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
[client]", "
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
|
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
|
|
95
|
-
it
|
|
96
|
-
|
|
97
|
-
|
|
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
|
|
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 —
|
|
201
|
+
## Output — state, then one ranked table
|
|
191
202
|
|
|
192
|
-
Print exactly this shape.
|
|
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
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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
|
-
|
|
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
|
|
226
|
-
credential that blocks a checkpoint beats a
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
-
|
|
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
|
-
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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
|
|
246
|
-
| 2 | **Start the top
|
|
247
|
-
| 3 | **Pick a different
|
|
248
|
-
|
|
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
|
|
261
|
-
|
|
262
|
-
- **
|
|
263
|
-
|
|
264
|
-
|
|
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
|
|
269
|
-
stop. Mechanical means the fact is not in dispute: a stale date, a
|
|
270
|
-
snapshot that contradicts the delivery log, a missing evidence
|
|
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
|
|
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
|
|
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
|
|
14
|
-
shape, and then the
|
|
15
|
-
|
|
16
|
-
|
|
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. **
|
|
59
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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.
|