@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.
- package/dist/agent-templates.d.ts +36 -2
- package/dist/agent-templates.js +173 -3
- package/dist/client-linear-create.d.ts +26 -0
- package/dist/client-linear-create.js +46 -0
- package/dist/client-linear.d.ts +28 -9
- package/dist/client-linear.js +36 -14
- package/dist/docs-search.d.ts +19 -6
- package/dist/docs-search.js +32 -11
- package/dist/doctor.d.ts +9 -0
- package/dist/doctor.js +126 -23
- package/dist/env-fill.d.ts +13 -0
- package/dist/env-fill.js +34 -9
- package/dist/env-push.d.ts +3 -0
- package/dist/env-push.js +11 -6
- package/dist/env-registry.d.ts +25 -0
- package/dist/env-registry.js +69 -7
- package/dist/exec.js +15 -2
- package/dist/index.d.ts +14 -6
- package/dist/index.js +14 -6
- package/dist/linear-project.d.ts +2 -2
- package/dist/linear-project.js +2 -2
- package/dist/log.d.ts +28 -0
- package/dist/log.js +73 -0
- package/dist/n8n-executions.d.ts +85 -0
- package/dist/n8n-executions.js +259 -0
- package/dist/op-cli.d.ts +29 -0
- package/dist/op-cli.js +52 -0
- package/dist/platform.d.ts +35 -0
- package/dist/platform.js +39 -0
- package/dist/portal-admin.d.ts +40 -0
- package/dist/portal-admin.js +30 -0
- package/dist/standup.d.ts +88 -0
- package/dist/standup.js +235 -0
- package/dist/sync-repos.d.ts +47 -0
- package/dist/sync-repos.js +80 -0
- package/dist/template-sync.d.ts +10 -0
- package/dist/template-sync.js +11 -0
- package/dist/wizard.d.ts +15 -0
- package/dist/wizard.js +35 -56
- package/dist/workspace-docs.d.ts +44 -0
- package/dist/workspace-docs.js +73 -0
- package/package.json +2 -2
- package/templates/env.example +33 -23
- package/templates/workspace-root/AGENT.md +7 -5
- package/templates/workspace-root/ONBOARDING.md +65 -8
- package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +102 -0
- package/templates/workspace-root/skills/CLAUDE.md +24 -6
- package/templates/workspace-root/skills/README.md +156 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
- package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
- package/templates/workspace-root/skills/client-latest/SKILL.md +301 -0
- package/templates/workspace-root/skills/client-latest/catchup.command.md +17 -0
- package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +181 -0
- package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
- package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
- package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
- package/templates/workspace-root/skills/ia-cli/SKILL.md +19 -6
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
- package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
- package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
- package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
|
@@ -0,0 +1,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.
|
package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md
ADDED
|
@@ -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.
|