@installagent/sdk 0.1.0 → 0.2.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 (80) hide show
  1. package/dist/agent-templates.d.ts +36 -2
  2. package/dist/agent-templates.js +173 -3
  3. package/dist/client-linear-create.d.ts +26 -0
  4. package/dist/client-linear-create.js +46 -0
  5. package/dist/client-linear.d.ts +28 -9
  6. package/dist/client-linear.js +36 -14
  7. package/dist/docs-search.d.ts +19 -6
  8. package/dist/docs-search.js +32 -11
  9. package/dist/doctor.d.ts +9 -0
  10. package/dist/doctor.js +126 -23
  11. package/dist/env-fill.d.ts +13 -0
  12. package/dist/env-fill.js +34 -9
  13. package/dist/env-push.d.ts +3 -0
  14. package/dist/env-push.js +11 -6
  15. package/dist/env-registry.d.ts +25 -0
  16. package/dist/env-registry.js +69 -7
  17. package/dist/exec.js +15 -2
  18. package/dist/index.d.ts +14 -6
  19. package/dist/index.js +14 -6
  20. package/dist/linear-project.d.ts +2 -2
  21. package/dist/linear-project.js +2 -2
  22. package/dist/log.d.ts +28 -0
  23. package/dist/log.js +73 -0
  24. package/dist/n8n-executions.d.ts +85 -0
  25. package/dist/n8n-executions.js +259 -0
  26. package/dist/op-cli.d.ts +29 -0
  27. package/dist/op-cli.js +52 -0
  28. package/dist/platform.d.ts +35 -0
  29. package/dist/platform.js +39 -0
  30. package/dist/portal-admin.d.ts +40 -0
  31. package/dist/portal-admin.js +30 -0
  32. package/dist/standup.d.ts +88 -0
  33. package/dist/standup.js +235 -0
  34. package/dist/sync-repos.d.ts +47 -0
  35. package/dist/sync-repos.js +80 -0
  36. package/dist/template-sync.d.ts +10 -0
  37. package/dist/template-sync.js +11 -0
  38. package/dist/wizard.d.ts +15 -0
  39. package/dist/wizard.js +35 -56
  40. package/dist/workspace-docs.d.ts +44 -0
  41. package/dist/workspace-docs.js +73 -0
  42. package/package.json +2 -2
  43. package/templates/env.example +33 -23
  44. package/templates/workspace-root/AGENT.md +7 -5
  45. package/templates/workspace-root/ONBOARDING.md +65 -8
  46. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
  47. package/templates/workspace-root/skills/CLAUDE.md +24 -6
  48. package/templates/workspace-root/skills/README.md +156 -0
  49. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  50. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  51. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  52. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  53. package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
  54. package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
  55. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  56. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
  57. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  58. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  59. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  60. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  61. package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
  62. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  63. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  64. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  65. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  66. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  67. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  68. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  69. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  70. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  71. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  72. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  73. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  74. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  75. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  76. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  77. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  78. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  79. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  80. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -0,0 +1,128 @@
1
+ # Evidence record — convention and template
2
+
3
+ Every backtest or validation run gets one dated, self-contained `.md` file in
4
+ the build repo's `evidence/`. These are the shareable trail — the client-facing
5
+ ones get imported to their Google Drive, so a reader with no repo access has to
6
+ be able to follow them.
7
+
8
+ Live exemplar set: `clients/client-carvision/evidence/`.
9
+
10
+ ---
11
+
12
+ ## Convention
13
+
14
+ - **One file per run**: `YYYY-MM-DD-<agent>-<what>.md`
15
+ - **~1 page.** What we tested, on what data, the headline number, the honest
16
+ read. One small table. No code — link to the reproduce-it doc instead.
17
+ - **No raw identifiers or personal data.** Aggregates only. Raw inputs stay in
18
+ the gitignored data folder.
19
+ - **Mark internal-only records explicitly** (🔒) so nobody exports one to a
20
+ client Drive by accident.
21
+ - **Index it** in `evidence/README.md`, newest first, with the headline.
22
+
23
+ ---
24
+
25
+ ## Template
26
+
27
+ ```markdown
28
+ # <Agent> — <what was tested> (<YYYY-MM-DD>)
29
+
30
+ **Status:** [client-shareable | 🔒 internal, not for Drive]
31
+ **Supersedes:** [prior record, or —]
32
+
33
+ ## What we tested
34
+
35
+ One paragraph. The question this run answers, and the metric definition being
36
+ used — in the SOW's own words if it maps to an acceptance gate.
37
+
38
+ ## Data
39
+
40
+ - Source, date range, row/entity counts.
41
+ - Known limitations of the sample (sparse periods, single-snapshot inputs,
42
+ missing columns) — stated here, not discovered in the read.
43
+ - Exclusions applied, each with its reason and the constant that encodes it.
44
+
45
+ ## Result
46
+
47
+ | Metric | Result | Bar |
48
+ |---|---:|---:|
49
+ | <the pinned gate metric> | xx.x% | xx% |
50
+ | <the stricter reading> | xx.x% | — |
51
+ | <the looser reading> | xx.x% | — |
52
+
53
+ Segmented:
54
+
55
+ | Segment | n | Result |
56
+ |---|---:|---:|
57
+ | <arm A> | | |
58
+ | <arm B> | | |
59
+ | <high data density> | | |
60
+ | <low data density> | | |
61
+
62
+ ## The honest read
63
+
64
+ Two to four sentences. What this does and does not establish. If the number is
65
+ below the bar, say what the lever is — data completeness or logic — and what
66
+ evidence supports that attribution. If the number is above the bar, say what
67
+ would make it stop being true.
68
+
69
+ ## Reproduce
70
+
71
+ `node scripts/<harness>.js --<args>`
72
+
73
+ Technical detail: `<path to the build-folder doc>`
74
+ ```
75
+
76
+ ---
77
+
78
+ ## Superseding a record
79
+
80
+ When a later run contradicts an earlier one, **edit the old record in place**;
81
+ never delete it.
82
+
83
+ - Strike through the wrong conclusion: `~~Ingestion faithful; counts correct~~`
84
+ - Immediately after it: `**⚠️ SUPERSEDED YYYY-MM-DD — the conclusion was
85
+ wrong.** <one sentence on why.>`
86
+ - **Keep what was right.** If the record raised a hypothesis that later proved
87
+ correct, say so — "the back-truncation hypothesis it raised was right; 'no
88
+ fix needed' was not."
89
+ - Update the index line to match.
90
+
91
+ When something invalidates a whole class of prior figures, put a **standing
92
+ caveat block above the index table**, not in a footnote:
93
+
94
+ ```markdown
95
+ > **Every gate figure in this folder is now provisional.** All were computed on
96
+ > lead data that the YYYY-MM-DD reconciliation showed to be ~79% of ground
97
+ > truth, and the raise arm depends on those counts almost entirely.
98
+ ```
99
+
100
+ That block is what stops a stale headline being quoted into a client
101
+ conversation six weeks later.
102
+
103
+ ---
104
+
105
+ ## Publishing a run to the client
106
+
107
+ Two surfaces, and they're separate steps:
108
+
109
+ 1. **The Drive copy** — the client-shareable records only, imported to their
110
+ engagement folder.
111
+ 2. **A dated tab in the client's working spreadsheet** — a summary block, then
112
+ one row per decision, so they can inspect individual cases rather than
113
+ taking a percentage on faith. CarVision does this via a generator script
114
+ plus a deliberately **inactive** publisher workflow driven by its test
115
+ webhook, so no permanent public endpoint lingers.
116
+
117
+ Keep the publishing secret on the workflow's own credential, never in the repo.
118
+ If one was ever committed, treat it as burned and rotate it.
119
+
120
+ ---
121
+
122
+ ## What belongs in the delivery log instead
123
+
124
+ The evidence record is the *finding*. The build repo's
125
+ `docs/00-delivery-log.md` gets a short dated entry that says what shipped,
126
+ where it runs, links the evidence file, and lists the follow-ups. Schema
127
+ spikes, audits and investigations with no pass/fail verdict belong in the
128
+ delivery log and the tech spec — `evidence/` is for runs with a verdict.
@@ -0,0 +1,90 @@
1
+ # Backtest harness — how to build one that stays trustworthy
2
+
3
+ Every number we quote should be reproducible by a colleague with one command.
4
+ Shape drawn from `clients/client-carvision/agent-pricing/scripts/`.
5
+
6
+ ---
7
+
8
+ ## The scripts you end up needing
9
+
10
+ | Script | Job |
11
+ |---|---|
12
+ | `build-<x>-history.js` | Reconstruct ground truth from raw history. Where exclusion constants live. |
13
+ | `backtest.js` | Score the pinned gate metric. Takes the history file as input. |
14
+ | `<x>-analysis.js` | Segmentation — the *why* behind the headline. |
15
+ | `reconcile-<x>.js` | Compare our inputs against an independent export (Part 5 of the skill). |
16
+ | `replay-coverage.js` | Replay a real historical run end to end and diff against what production produced. |
17
+ | `test-<component>.js` | Unit-level assertions on the scoring logic. |
18
+ | `value-of-fields.js` | What each input field is actually worth to the output — kills debates about which upstream ask matters. |
19
+
20
+ Separate **reconstruct** from **score**. When the ground-truth definition
21
+ changes you re-run one script, and the diff shows exactly what moved.
22
+
23
+ ## Rules
24
+
25
+ **One command line per number.** Every figure in an evidence record carries the
26
+ invocation that produced it:
27
+
28
+ ```
29
+ node scripts/backtest.js --history data/outcome-history.json
30
+ ```
31
+
32
+ **Exclusions are dated constants in the harness**, never a hand-edited dataset.
33
+ `const TEST_EVENT_DATE = "…"` shows up in a diff; a filtered CSV doesn't.
34
+
35
+ **Thresholds live in one config file**, with the calibration rationale in
36
+ comments next to the values, and are read by both production and the harness
37
+ from the same place. If the harness and production can drift apart on a
38
+ threshold, they will, and the backtest stops describing the thing you shipped.
39
+
40
+ **Raw inputs stay out of git.** Client data goes in a gitignored data folder;
41
+ only summaries are committed.
42
+
43
+ **Deterministic.** Same inputs, same outputs, every run. No wall-clock, no
44
+ unseeded randomness — an `asOf` is a parameter, not `now()`.
45
+
46
+ **Print the sample size next to every percentage.** Always. A percentage
47
+ without an n is not a result.
48
+
49
+ ## Tests that actually catch things
50
+
51
+ The failure to design against: a 144-assertion suite passing green while a
52
+ data-joining layer contributed zero records for three days, because the parity
53
+ test applied the missing conversion itself before comparing.
54
+
55
+ - **Feed the seam production's own input shape.** If the test normalizes the
56
+ input first, it is testing the normalizer, not the seam.
57
+ - **Assert non-zero contribution**, not only equality. `joined.length > 0` and
58
+ `contributedRecords >= N` catch silent-empty; `expect(a).toEqual(b)` does not.
59
+ - **Round-trip the real artifact.** Read the actual stored shape (the sheet
60
+ tab, the S3 object) and assert the consumer can read it — not a
61
+ hand-constructed fixture of what you believe it contains.
62
+ - **Red-then-green.** Write the failing assertion against the live bug first,
63
+ watch it fail, then fix. A test written after the fix proves nothing about
64
+ whether it would have caught it.
65
+ - **Replay a known run.** Reproducing a historical run exactly (all N records,
66
+ not most) is what lets you attribute a later delta to a single cause instead
67
+ of arguing about it.
68
+
69
+ ## When a fix moves the numbers
70
+
71
+ 1. Re-run every harness that depended on the fixed component.
72
+ 2. Diff the headline figures and record both sides.
73
+ 3. Mark every prior evidence record whose numbers are now void — in place, with
74
+ a strike-through and a pointer.
75
+ 4. Update the standing caveat block in `evidence/README.md`.
76
+ 5. Only then quote the new number to anyone.
77
+
78
+ Steps 3 and 4 are the ones that get skipped, and they are the ones that stop a
79
+ void figure resurfacing in a client conversation weeks later.
80
+
81
+ ## Before quoting any number externally
82
+
83
+ - [ ] Produced by a committed script, from committed inputs, with the command line recorded
84
+ - [ ] Sample size stated
85
+ - [ ] Metric definition stated, in the SOW's wording if it maps to a gate
86
+ - [ ] Competing metric readings computed, and reported if materially different
87
+ - [ ] Exclusions named and justified; control arm shown unchanged
88
+ - [ ] Inputs reconciled against an independent source
89
+ - [ ] No prior evidence record contradicts it un-superseded
90
+ - [ ] Qualifiers travel with the count (e.g. "half of these were already at a floor")
@@ -0,0 +1,301 @@
1
+ ---
2
+ name: client-latest
3
+ description: >-
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.
21
+ ---
22
+
23
+ # client-latest — resume-the-build brief for one client
24
+
25
+ One engagement is described in four places that nothing keeps in step:
26
+ Linear, `docs/`, `onboarding.html`, and the live systems. This skill reads
27
+ all of them in one pass and prints what is true, then what disagrees.
28
+
29
+ **The brief is a read.** Print it in the terminal. Write no status file —
30
+ one would itself go stale and become another drift source, which is the
31
+ exact failure `CADENCE.md` exists to stop.
32
+
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.
37
+
38
+ ## Inputs
39
+
40
+ - **Client slug** — from the argument (`jared-tomseth`), a repo path
41
+ (`clients/client-jared-tomseth/`), or the current directory when you are
42
+ already inside a client repo. A company name that is not a slug
43
+ (`Medearis`) resolves through `team-clients/clients/*/PROFILE.md`; if two
44
+ match, ask — never guess which client you are reporting on.
45
+ - **Nothing else.** No pasted context needed. If a source cannot be read,
46
+ the brief says so; it does not infer.
47
+
48
+ ## The window
49
+
50
+ Two anchors, and you take the **wider** of them:
51
+
52
+ 1. the date of the newest entry in `docs/00-delivery-log.md`;
53
+ 2. today minus 7 days.
54
+
55
+ So a busy client always gets at least 7 days, and a quiet client gets
56
+ everything back to the last thing anyone wrote down. State the window and
57
+ both anchors in the header — a log entry from three weeks ago is itself a
58
+ finding.
59
+
60
+ ## The read order — one pass, no subagents
61
+
62
+ Run it in this order. Each step is cheap and narrows the next.
63
+
64
+ ### 1. The manifest
65
+
66
+ `cat clients/client-<slug>/CLIENT.md`. It maps every external system.
67
+ Note any key that is still a placeholder (`<...>`, or a literal
68
+ `client-<slug>`) — an unfilled key is a drift finding, not a detail.
69
+
70
+ ### 2. The repo, in the window
71
+
72
+ - `docs/00-delivery-log.md` — entries in the window. Newest first. This is
73
+ the "what shipped, does it work" record.
74
+ - `evidence/` — files dated in the window. An accuracy or go-live claim
75
+ with no evidence file is a risk, not a fact.
76
+ - `onboarding.html` — find the status snapshot and its **`AS OF` date**.
77
+ Compare that date to the newest log entry.
78
+ - `AGENT.md` § *Client-specific gotchas* — the traps for this repo. Carry
79
+ any that still apply into the RISKS block.
80
+ - `docs/` index — a high-numbered handoff or decision-log doc
81
+ (`NN-...-handoff.md`) is usually the freshest single page. Read it.
82
+
83
+ ### 3. Git state — where work goes missing
84
+
85
+ ```bash
86
+ cd clients/client-<slug>
87
+ git status --porcelain # uncommitted work
88
+ git log --oneline @{u}..HEAD # committed but never pushed
89
+ git log --oneline --since=<window-start>
90
+ gh pr list --state open # if the repo pushes to GitHub
91
+ git worktree list
92
+ ```
93
+
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.
98
+
99
+ Never commit, never push, never force-push to undo something you find.
100
+
101
+ ### 4. The `ia` read-only commands
102
+
103
+ ```bash
104
+ ia client <slug> # registry profile + recent calls + delivery log
105
+ ia client-linear <slug> # OPEN issues in the client's Linear project
106
+ ```
107
+
108
+ `ia client-build` and `ia client-drive` are for when the local repo is thin
109
+ or a referenced doc is missing locally. Do not hand-roll GitHub, Airtable,
110
+ Linear, or Drive calls — see the `ia-cli` skill.
111
+
112
+ ### 5. The calendar — the one date the repo cannot be trusted for
113
+
114
+ One query: `angello@installagent.com`'s calendar across the surrounding
115
+ week. Take the client's **next** and **last** meeting from it. Match the
116
+ client by attendee email domain (the registry `PROFILE.md` has the
117
+ addresses), never by the event title.
118
+
119
+ Then **date-check the repo against it.** Every date the docs state for a
120
+ call is a claim, and it goes stale in silence. One build repo carried "the
121
+ 08-20 call" in 14 live places — tech spec, contract, handoff page, a
122
+ client-facing page, even a source comment — while the calendar said 08-21.
123
+ It survived nine days, a delivery-log entry, and a status refresh. Nothing
124
+ inside the repo can catch that. Only the calendar can.
125
+
126
+ - Put the next meeting, with its time zone, in the brief's first block.
127
+ - **Fathom cannot replace this.** It shows only calls that were held *and*
128
+ recorded, so it can never prove what is booked.
129
+ - An attendee who appears nowhere in the registry is a finding, not a
130
+ detail — that is a stakeholder someone is about to meet cold.
131
+ - **Never rewrite history to match.** A dated delivery-log entry records
132
+ what was believed then; correct it with a new entry, not an edit.
133
+
134
+ ### 6. Slack — the client's own words
135
+
136
+ Read `slack_channel` from `CLIENT.md`. Read the channel back to the window
137
+ start. The convention is `#client-<slug>`, but real names vary (one has a
138
+ trailing hyphen; one client has both `#client-<slug>` and a `-team`
139
+ channel), so **use the key, do not build the name**. If the key says
140
+ `none`, print "no Slack channel" and move on. If the key is absent — or the channel it names
141
+ cannot be found — search once, then say in the brief which channel you
142
+ actually read. `ia client-intake` fills this key from the convention, so
143
+ a brand-new repo's value may still be a guess.
144
+
145
+ What matters here: a client ask that never reached Linear or the docs, an
146
+ unanswered question, and a promise we made.
147
+
148
+ **Credentials in the channel.** Clients paste passwords and keys into
149
+ Slack. If you see one, report *that it happened* and that it needs
150
+ rotating and deleting. Never echo the value into the brief, a file, a
151
+ commit message, or a Linear issue.
152
+
153
+ ### 7. n8n run health
154
+
155
+ Workflow IDs are **not** in the repo's `workflows/*.json` — those exports
156
+ are sanitized, so the `id` field is stripped. They live in the docs:
157
+
158
+ ```bash
159
+ grep -rIoh '`[A-Za-z0-9]\{16\}`' docs/ evidence/ AGENT.md | sort | uniq -c | sort -rn
160
+ ia agent executions <workflowId> -n 20
161
+ ```
162
+
163
+ A 16-character backticked string is an n8n workflow id. The most-cited one
164
+ is usually the live workflow, but confirm it against the tech spec before
165
+ you report on it — never guess an id from the client name.
166
+
167
+ Report last run, last error, and silence (a workflow that should run daily
168
+ and has not run). Flag "built but never published" — an inactive or draft
169
+ workflow while the docs or Linear call it live.
170
+
171
+ Do **not** pass `--data`: run data holds full client payloads. Do not
172
+ manually execute a client workflow to "see if it works".
173
+
174
+ ## The drift checks
175
+
176
+ Run every one. Report each as a pair of surfaces that disagree, with file
177
+ and line.
178
+
179
+ | Check | Drift looks like |
180
+ |---|---|
181
+ | Linear vs delivery log | Issue is Done, no log entry exists — or the log says shipped while the issue sits In Progress |
182
+ | `onboarding.html` vs delivery log | The `AS OF` snapshot date is older than the newest log entry |
183
+ | 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 |
185
+ | `CLIENT.md` | A key still holds a placeholder, so every tool that resolves through it is guessing |
186
+ | n8n vs docs | Workflow inactive or draft while docs, Linear, or the client believe it is live |
187
+ | Evidence | A log entry links `evidence/<file>.md` that does not exist, or an evidence file no entry mentions |
188
+ | Worktrees | A `.claude/worktrees/` copy of `docs/` is newer than the tracked one |
189
+
190
+ ## Output — two parts, state then risks
191
+
192
+ Print exactly this shape. Plain text, no preamble.
193
+
194
+ ```
195
+ <CLIENT NAME> (<slug>) — build repo clean? YES|NO
196
+ Window: <start> → today (log anchor <date> · 7-day anchor <date>)
197
+
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>
219
+ ```
220
+
221
+ Then ask the CTA question below. The brief is never the end of the run.
222
+
223
+ Rules for the output:
224
+
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
230
+ unauthenticated MCP session, a missing token, no Linear project. A brief
231
+ that silently skips Slack reads as "Slack was quiet".
232
+ - **Never print a secret, key, password, or client PII**, and never a
233
+ client's dollar amount into anything shared. Point at the system that
234
+ 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.
242
+
243
+ | Slot | Option | Build it from |
244
+ |---|---|---|
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 |
249
+
250
+ Rules:
251
+
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
+ - **Mark work a person must do** with `[HUMAN STEPS FIRST]` and say which
257
+ step is theirs. A lost credential, a Vercel redeploy, an `op` login, a
258
+ new OAuth credential in n8n — offering to "start" these without the
259
+ 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.
265
+
266
+ ### If they choose "fix the drift"
267
+
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.
272
+
273
+ - **Repo files only.** A change to Linear, n8n, Airtable, Drive, or Slack
274
+ is a write to a **shared** surface, and discarding a diff cannot undo it.
275
+ List those instead, with the exact command or issue id, under
276
+ `YOUR CALL — SHARED SURFACES`. Then stop.
277
+ - **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
279
+ why in one line.
280
+ - **`CADENCE.md` still governs.** A drift fix that moves the shape of a
281
+ flow needs the diagram and the tech spec in the same change. If the fix
282
+ reaches that far, stop and say so — that is a slice, not a tidy-up.
283
+ - **Stop in the working tree.** Print `git status --porcelain` and hand the
284
+ commit to the reader. Never commit, never push, never force-push.
285
+
286
+ ### If they choose the top risk or another next step
287
+
288
+ Restate the item as a one-line contract before touching anything — the
289
+ trigger, the inputs, the outputs, the failure behavior. That is CADENCE
290
+ stage 1, and it is where the reader corrects you cheaply. Then work the
291
+ item, and stop in the working tree as above.
292
+
293
+ ## What this skill is not
294
+
295
+ | If the task is… | Use |
296
+ |---|---|
297
+ | Prepping for an upcoming client call | `tech-call-prep` |
298
+ | Writing a call up into build docs | `engagement-spec` |
299
+ | Fixing the drift this brief found | `CADENCE.md` in that repo — the five stages, one commit per slice |
300
+ | Proving an accuracy number | `backtest-acceptance-gates` |
301
+ | Any other `ia` operation | `ia-cli` |
@@ -0,0 +1,17 @@
1
+ ---
2
+ description: Catch up on one client — build state, then risks and drift worst-first, then how to move forward
3
+ argument-hint: <client-slug> (or blank inside a clients/client-<slug>/ repo)
4
+ ---
5
+
6
+ Run the `client-latest` skill for: **$ARGUMENTS**
7
+
8
+ If `$ARGUMENTS` is empty, resolve the client from the current directory. If
9
+ it is a company name rather than a slug, resolve it through
10
+ `team-clients/clients/*/PROFILE.md` and ask when two clients match.
11
+
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,
17
+ Airtable, Drive, Slack) are proposed, never changed.