@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
|
@@ -43,7 +43,7 @@ you keep that same build folder's `onboarding.html` in sync:
|
|
|
43
43
|
| `01-overview.md` | The client | Plain English, **tech-agnostic** | What we're solving, what we're building, what to expect. The doc you'd send them. |
|
|
44
44
|
| `02-tech-spec.md` | Install Agent engineering | Precise, **names tools** | The implementation: architecture, data shapes, node-by-node, error handling, open questions. This is `onboarding.html`'s source of truth per `client-template/AGENT.md` — if they disagree, fix the page. |
|
|
45
45
|
| `03-client-onboarding.md` | The client's admin/bookkeeper | Plain English, checklist | Access + decisions + info we need, split by "before kickoff" vs "during week 1". This is the **ask**. |
|
|
46
|
-
| `04-access-checklist.md` | Install Agent (internal) |
|
|
46
|
+
| `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING. This is the **tracker**, kept current as access lands. Mirror §1 only into `onboarding.html`'s Access tab. |
|
|
47
47
|
| `onboarding.html` | A technician landing on the build cold | Scannable, tab per topic | Every `REPLACE_WITH_*` token filled from the same source material as `01`–`04` (step 6) — so the tech discovery call happens with real context already on screen, not a blank template. |
|
|
48
48
|
|
|
49
49
|
Look at the canonical exemplars before writing — match their depth and
|
|
@@ -161,35 +161,56 @@ The checklist that unblocks the build. Split by urgency so the client isn't
|
|
|
161
161
|
overwhelmed:
|
|
162
162
|
|
|
163
163
|
- **§1 Access (before kickoff)** — accounts/credentials we need, each with the
|
|
164
|
-
*minimum* role and how they grant it
|
|
165
|
-
|
|
164
|
+
*minimum* role and how they grant it: OAuth/invite where the system
|
|
165
|
+
supports it, or their **portal's Access tab** for a straight login
|
|
166
|
+
(username/password, plus a two-factor setup key if that login uses 2FA) —
|
|
167
|
+
submitted directly, on their own time, into a 1Password vault dedicated to
|
|
168
|
+
their engagement. Reserve a scheduled working session for what the form
|
|
169
|
+
can't cover (an admin-consent flow they have to click through themselves).
|
|
166
170
|
- **§2 Decisions (before kickoff)** — the choices only they can make (e.g.
|
|
167
171
|
confidence threshold, point of contact).
|
|
168
172
|
- **§3 Information (week 1, not blocking)** — exports, lists, edge cases to seed
|
|
169
173
|
rules.
|
|
170
174
|
- **§4 Ongoing** — review cadence, their time commitment, who owns what.
|
|
171
|
-
- **§5 What we are NOT asking for** — explicitly
|
|
172
|
-
|
|
175
|
+
- **§5 What we are NOT asking for** — explicitly: nothing over Slack, email,
|
|
176
|
+
or a shared doc — every credential goes through the portal or 1Password,
|
|
177
|
+
never pasted in a message — and no access beyond the named systems.
|
|
173
178
|
- **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
|
|
174
179
|
|
|
175
180
|
### 5. Draft `04-access-checklist.md` (internal tracker)
|
|
176
181
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
182
|
+
Two tables, never one. **§1 Credentials & grants** — one row per *system* we
|
|
183
|
+
need a credential or an access grant for (a login, an OAuth scope, a share, an
|
|
184
|
+
API key): **System | Access we need (minimum role/scope) | Used by | Status |
|
|
185
|
+
Notes**. Every software the client named on the sales call gets a row, even
|
|
186
|
+
when the ask is still MISSING or it is UNKNOWN whether a credential is needed.
|
|
187
|
+
**§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
|
|
188
|
+
intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
|
|
189
|
+
list, a person or a decision is never a §1 row; that mixing is what turns the
|
|
190
|
+
tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
|
|
191
|
+
UNKNOWN / N/A — set from what the call notes and registry profile actually say
|
|
192
|
+
was granted or promised, never assumed. This is the doc (and the matching
|
|
193
|
+
`onboarding.html` Access tab) a teammate opens to answer "what are we still
|
|
194
|
+
waiting on from this client?" without re-reading the call transcript. Update
|
|
195
|
+
it in the same commit whenever access lands — it decays fast otherwise.
|
|
185
196
|
|
|
186
197
|
- **Capture status, don't invent it.** If a call didn't confirm an item was
|
|
187
198
|
received, it's MISSING or REQUESTED, not HAVE.
|
|
199
|
+
- **When month one is inbox triage, the SOP's preconditions are §2 rows from
|
|
200
|
+
day one** (`agents/email-gmail-triage/sop.md` or `email-outlook-triage/
|
|
201
|
+
sop.md` § *Preconditions*): the client's written OK that every inbound
|
|
202
|
+
message is read; the BAA / DPA position for a regulated client; the VIP
|
|
203
|
+
list and key phrases; the classification record sheet created and shared
|
|
204
|
+
read-only with the tooling accounts; the sensitive categories (wire, legal,
|
|
205
|
+
health) and how they are handled. The mailbox OAuth grant itself is a §1
|
|
206
|
+
row. Mirror the written-OK ask into `03` §2 (Decisions) — it is the one
|
|
207
|
+
thing the client must say, not grant.
|
|
188
208
|
- **No credential values or IDs** — status and the 1Password vault *name*
|
|
189
209
|
only (from `CLIENT.md`), same rule as everywhere else in the repo.
|
|
190
|
-
- Mirror
|
|
191
|
-
|
|
192
|
-
`docs/`.
|
|
210
|
+
- Mirror **§1 only** into `onboarding.html`'s Access tab (its own sidebar
|
|
211
|
+
entry, `#access`) so a developer sees it in one screen without opening
|
|
212
|
+
`docs/`. §2 stays in the doc; the Client tab's status snapshot carries the
|
|
213
|
+
open decisions.
|
|
193
214
|
|
|
194
215
|
### 6. Populate `onboarding.html`
|
|
195
216
|
|
|
@@ -211,6 +232,17 @@ In short:
|
|
|
211
232
|
`<li>` per item, duplicate the template's stub `<li>` as needed. The
|
|
212
233
|
access table (`ITEM`/`SYSTEM`/`REASON`/`NOTE`, one row per item) is the
|
|
213
234
|
`04-access-checklist.md` mirror already required in step 5.
|
|
235
|
+
- **Builds tab** — one *systems-level* block per build in scope, duplicating
|
|
236
|
+
the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
|
|
237
|
+
`SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
|
|
238
|
+
node labels, `BUILD_CAPTION`, and the *under the hood* rows: `INSTANCE`,
|
|
239
|
+
`WORKFLOW_FILE`, `MODEL`, `LEDGER`, `STACK_NOTES`). Add the matching
|
|
240
|
+
`Builds / <name>` sub-link in the sidebar `.subnav` (href = the block's
|
|
241
|
+
`id="build-<slug>"`). Boxes are **client-safe** — the client's own systems
|
|
242
|
+
by name, ours as "Install Agent", no vendor of ours in the SVG; that detail
|
|
243
|
+
goes only in the collapsed *under the hood* table. Anything not yet built
|
|
244
|
+
is drawn dashed (`.ghost`). This is the picture shown on client update
|
|
245
|
+
calls and Looms, so draw it first.
|
|
214
246
|
- **Workflows tab** — one diagram block per automation in scope, duplicating
|
|
215
247
|
the template block (`WORKFLOW_TITLE`, `WORKFLOW_SLUG`, `STATUS`,
|
|
216
248
|
`TRIGGER`/`FILTER`/`AI_STEP`/`N`/`WRITE`/`NOTIFY` node labels, `CAPTION`).
|
|
@@ -259,8 +291,9 @@ tokens or empty bullets.
|
|
|
259
291
|
error table, AI specifics, **open questions**, build sequence.
|
|
260
292
|
- [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
|
|
261
293
|
/ quick-fill; minimum roles; "creds in your vault, never a password".
|
|
262
|
-
- [ ] `04-access-checklist.md`:
|
|
263
|
-
|
|
294
|
+
- [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
|
|
295
|
+
sales-call software has a row) + §2 decisions/information; Status set from
|
|
296
|
+
what's actually confirmed (not assumed); §1 mirrored into the Access tab.
|
|
264
297
|
- [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
|
|
265
298
|
update pass, only the ones the tech-discovery call still hasn't
|
|
266
299
|
answered); Client tab agrees with `02`, not the other way around.
|
|
@@ -119,8 +119,13 @@ write path → exception flow → prod cutover → tuning.>
|
|
|
119
119
|
done; §3 can come in parallel during week 1.>
|
|
120
120
|
|
|
121
121
|
## 1. Access (need before kickoff)
|
|
122
|
-
<Per system: the minimum role, how they grant it
|
|
123
|
-
|
|
122
|
+
<Per system: the minimum role, and how they grant it. For OAuth/invite-based
|
|
123
|
+
access, describe the grant. For a straight login (no API), point them at
|
|
124
|
+
their portal's Access tab to submit the username/password directly — and a
|
|
125
|
+
two-factor setup key too, if that login uses 2FA — themselves, on their own
|
|
126
|
+
time; it goes straight into their own 1Password vault, never through us by
|
|
127
|
+
hand. Reserve a live working session for what the form can't cover, e.g. an
|
|
128
|
+
admin-consent OAuth flow they have to click through.>
|
|
124
129
|
|
|
125
130
|
## 2. Decisions (need before kickoff)
|
|
126
131
|
<Choices only they can make: thresholds, point of contact, channel name.>
|
|
@@ -132,8 +137,9 @@ credentials go into the client's own vault — we never take a password.>
|
|
|
132
137
|
<Review-call cadence, their time on the review queue, who approves changes.>
|
|
133
138
|
|
|
134
139
|
## 5. What we are NOT asking for
|
|
135
|
-
<Explicit list:
|
|
136
|
-
|
|
140
|
+
<Explicit list: nothing over Slack, email, or a shared doc — every credential
|
|
141
|
+
goes through the portal's Access tab or 1Password, never pasted in a message;
|
|
142
|
+
no access beyond the named systems.>
|
|
137
143
|
|
|
138
144
|
## 6. Quick-fill checklist
|
|
139
145
|
- [ ] <access item invited/ready>
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: github-profile
|
|
3
|
+
description: >-
|
|
4
|
+
Force every GitHub action (gh CLI commands, git push/pull against a GitHub
|
|
5
|
+
remote, PR creation, gh api calls) to run under THIS MACHINE's Install Agent
|
|
6
|
+
work account — the one that is a member of the InstallAgent GitHub org —
|
|
7
|
+
never a personal account that is also logged into `gh` on the same machine.
|
|
8
|
+
Resolves the work account from the workspace-root `.github-account` file
|
|
9
|
+
(or from org membership when the file is missing), checks the active `gh`
|
|
10
|
+
account, and switches before the action. Use this WHENEVER a task is about
|
|
11
|
+
to run a `gh` command, a git operation against a GitHub remote, or any
|
|
12
|
+
GitHub API call. Reach for it even if the user never says "skill" — any
|
|
13
|
+
GitHub request on any technician machine.
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# github-profile — act as this machine's work account, never the personal one
|
|
17
|
+
|
|
18
|
+
Most technician machines have two GitHub accounts logged into the `gh` CLI:
|
|
19
|
+
the Install Agent work account and a personal one. Only the work account is
|
|
20
|
+
a member of the **InstallAgent** GitHub org. GitHub actions must never run
|
|
21
|
+
under the other one — a PR, an API call or a push under the personal account
|
|
22
|
+
lands on the wrong identity and usually fails with "Repository not found".
|
|
23
|
+
|
|
24
|
+
This skill is bundled into every technician's workspace, so it **never names
|
|
25
|
+
a person or a login**. The login lives in one machine-local file.
|
|
26
|
+
|
|
27
|
+
## Where the work account is recorded
|
|
28
|
+
|
|
29
|
+
`<workspace-root>/.github-account` — one line, the GitHub login of this
|
|
30
|
+
machine's work account. Nothing else. The workspace root is not a git repo
|
|
31
|
+
and the file is not part of the template bundle, so it never travels to
|
|
32
|
+
another machine.
|
|
33
|
+
|
|
34
|
+
## Before any GitHub action
|
|
35
|
+
|
|
36
|
+
1. **Resolve the work account.**
|
|
37
|
+
- If `.github-account` exists at the workspace root, its content is the
|
|
38
|
+
work login. Done.
|
|
39
|
+
- If it does not exist: list the logged-in accounts with
|
|
40
|
+
`gh auth status`, and for each login check org membership:
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
gh api orgs/InstallAgent/memberships/<login> --jq .state
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Exactly one `active` login → that is the work account. Write it to
|
|
47
|
+
`.github-account` so the next task skips this step.
|
|
48
|
+
None → stop and tell the user `gh auth login --hostname github.com`
|
|
49
|
+
is needed for the work account. Do not proceed under the other one.
|
|
50
|
+
More than one → ask the user which one is the work account for this
|
|
51
|
+
machine, then write the file.
|
|
52
|
+
|
|
53
|
+
2. **Check the active account.**
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
gh auth status
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
3. **If the active `github.com` account is not the work login, switch:**
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
gh auth switch --hostname github.com --user <work-login>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
4. Only then run the actual command (`gh pr create`, `gh api …`,
|
|
66
|
+
`git push`, …).
|
|
67
|
+
|
|
68
|
+
Do this check-then-switch every time a GitHub action starts a task — the
|
|
69
|
+
active account drifts whenever the user, another tool or another session
|
|
70
|
+
used the personal account in between.
|
|
71
|
+
|
|
72
|
+
## Git identity
|
|
73
|
+
|
|
74
|
+
Pushes over SSH use the per-repo key (`git config --get core.sshcommand` in
|
|
75
|
+
any InstallAgent clone) and are independent of the `gh` account — a switch
|
|
76
|
+
never fixes or breaks a push. Commits should carry the work account's
|
|
77
|
+
identity so history stays attributable and free of personal addresses:
|
|
78
|
+
|
|
79
|
+
- `user.name` = the work login
|
|
80
|
+
- `user.email` = `<id>+<login>@users.noreply.github.com`
|
|
81
|
+
(`gh api user --jq .id` prints the id while the work account is active)
|
|
82
|
+
|
|
83
|
+
If `git config user.email` in a repo shows something else, **say so and let
|
|
84
|
+
the user decide** — never rewrite their git config unasked.
|
|
85
|
+
|
|
86
|
+
## Token scope
|
|
87
|
+
|
|
88
|
+
The work account's `gh` token normally carries `repo, read:org, gist,
|
|
89
|
+
admin:public_key`. Org administration (removing a member, reading org
|
|
90
|
+
secrets) and writing under `.github/workflows/` need more — tell the user to
|
|
91
|
+
run `gh auth refresh -h github.com -s admin:org` (or `-s workflow`) rather
|
|
92
|
+
than working around it. Pushing workflow files over SSH is not subject to
|
|
93
|
+
the token scope.
|
|
94
|
+
|
|
95
|
+
## Offboarding a technician
|
|
96
|
+
|
|
97
|
+
Removing someone's GitHub access is one call under an org admin's account
|
|
98
|
+
and it also drops every team membership:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
gh api -X DELETE orgs/InstallAgent/members/<login>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Verify with the members list afterwards. Their machine's
|
|
105
|
+
`.github-account` is theirs to delete; nothing in the bundle references
|
|
106
|
+
them.
|
|
@@ -8,7 +8,11 @@ description: >-
|
|
|
8
8
|
(don't grep repos or draft Airtable/Drive/Linear API calls — `ia client`,
|
|
9
9
|
`ia client-build`, `ia client-drive`, `ia client-linear` already do it
|
|
10
10
|
read-only), starting a new client engagement, building an n8n automation
|
|
11
|
-
(check the bank first),
|
|
11
|
+
(check the bank first), running an email-triage gate ("write the soak
|
|
12
|
+
report", "sample for gate B", "is the triage agent still recording?" —
|
|
13
|
+
`ia triage` reads the classification record and writes the evidence file,
|
|
14
|
+
never a hand-built spreadsheet; `ia triage enable` sets a new triage client
|
|
15
|
+
up), minting a credential, administering the portal,
|
|
12
16
|
searching the team docs, or setting up / fixing a technician's
|
|
13
17
|
environment ("set me up", "my env vars are missing", "clone the
|
|
14
18
|
workspace", onboarding a new machine). Reach for it before writing any
|
|
@@ -32,6 +36,8 @@ secrets).
|
|
|
32
36
|
|---|---|
|
|
33
37
|
| Set up a machine from nothing / onboard a technician | `ia wizard <dir>` (clones every team repo + root docs + `.env`) |
|
|
34
38
|
| Pull every repo up to date (team **and** client repos) | `ia sync [<dir>]` — ff-only; `--docs` also refreshes root docs/skills/`.env.example` |
|
|
39
|
+
| See which repos are dirty / unpushed / behind, across the whole workspace | `ia status [<dir>]` — read-only: fetches, then reports `clean`/`dirty`/`ahead`/`behind`/`diverged` per repo; never commits or pushes |
|
|
40
|
+
| Push already-committed work across every repo | `ia push [<dir>]` — pushes only repos that are clean and strictly ahead (fast-forward only); a dirty repo is skipped and reported, **never auto-committed** — review the diff and commit it yourself, then re-run |
|
|
35
41
|
| Converge an existing workspace with the canonical one | `ia wizard <dir> --update` (ff-only pulls + refresh drifted root docs; prefer `ia sync`, which also covers `clients/client-*`) |
|
|
36
42
|
| "Is my environment OK?" / missing env vars / broken setup | `ia doctor [-w <dir>]` — every gap comes with a fix-it line; `--all` for every check |
|
|
37
43
|
| Who is client X / latest calls / what shipped? | `ia client <slug>` |
|
|
@@ -43,6 +49,12 @@ secrets).
|
|
|
43
49
|
| Client repos drifted from client-template's lint/CI files | `ia template-sync [--apply]` |
|
|
44
50
|
| Search the team docs site | `ia docs search "<query>"` |
|
|
45
51
|
| Building an n8n automation | `ia agent templates` FIRST (the bank), then `ia agent create <template>`; bank the result back with `ia agent save` |
|
|
52
|
+
| Email triage gate A — "write the soak report" / "can we propose the categories yet?" | `ia triage soak-report <slug>` — the fixed seven-table report + Critical / Today / Later / Noise lane view, ≥200-row and ≤20%-review-lane checks pre-computed, written to `evidence/`; never build it in a spreadsheet by hand |
|
|
53
|
+
| Email triage gates B / C — "sample for the precision gate" / "can we turn on archiving / drafts?" | `ia triage sample <slug> --stage label` (gate B) or `--stage organize` (gate C) — seeded random 50 from the current stage's rows, judging table + zero-tolerance list pre-filled; **you** judge each message_id in the client's mailbox |
|
|
54
|
+
| "Is the triage agent still recording?" / a client's inbox looks quiet | `ia triage health <slug>` — rows in the last N days from the record; exit 1 when quiet (a stopped triage agent looks exactly like a quiet inbox). The portal's daily watch runs the same check for every active triage agent and alerts `#team-techs` |
|
|
55
|
+
| Set up a new email-triage client's record / "the record node is wired, now what?" | `ia portal create-agent …`, bind the two credentials in the n8n UI, then `ia triage enable <slug>` BEFORE the first publish — checks the live workflow's record wiring (read-only, node names + pass/fail only), marks the agent (`ia portal set-agent-triage`), backfills an old sheet if one exists. `--dry-run` checks only; exit 1 on a failed check, with the fix |
|
|
56
|
+
| "Record did not reach the portal" alert in `#team-techs` | copy that execution's `🧺 Batch Record Rows` output into a file → `ia triage backfill <slug> --rows <file>` (idempotent; refuses rows from another client's workflow). `ia triage backfill <slug> [--sheet\|--csv]` copies an old record sheet in; a re-run that says 0 new is the parity check |
|
|
57
|
+
| Weekly triage summary into the client's channel | `ia portal set-org-slack-channel --slug <slug> --channel <C…>` (`none` clears it) — the digest only posts for an org with a channel |
|
|
46
58
|
| Mint a GCP SA key / Gemini key / Fathom webhook | `ia secrets mint <kind> …` |
|
|
47
59
|
| Portal org/agent admin (create org, passwords, run sync) | `ia portal <cmd>` — CLI-only, never via MCP |
|
|
48
60
|
|
|
@@ -56,6 +68,23 @@ list, including this one.
|
|
|
56
68
|
- The `client*` family, `docs search`, `agent templates`, and `linear-*`
|
|
57
69
|
are **read-only**. Nothing in `ia` ever writes to the team-clients
|
|
58
70
|
registry or Airtable.
|
|
71
|
+
- **The record source rule** for `ia triage soak-report|sample|health`: with
|
|
72
|
+
`IA_PORTAL_ADMIN_SECRET` set, the **portal comes first** (the
|
|
73
|
+
`triage_classifications` record of the client's triage agent; `--agent`
|
|
74
|
+
when the org has more than one). A portal 404 (no triage agent) falls back
|
|
75
|
+
to the record sheet, and the evidence header says why. `--sheet <id>` /
|
|
76
|
+
`--csv <file>` force the sheet (a client from before the move; the sheet
|
|
77
|
+
read needs `GOOGLE_SERVICE_ACCOUNT_KEY` as Viewer). `--since <iso>` /
|
|
78
|
+
`--until <iso>` window every source — use `--since` for "rows after the
|
|
79
|
+
promotion".
|
|
80
|
+
- `ia triage soak-report|sample|health` never write to the record or the
|
|
81
|
+
mailbox; their only write is the evidence markdown in
|
|
82
|
+
`clients/client-<slug>/evidence/`, and they refuse to overwrite today's
|
|
83
|
+
file (`--force`). The MCP twins compute the same result and write nothing.
|
|
84
|
+
- `ia triage enable` and `ia triage backfill` write to the portal, so they
|
|
85
|
+
are CLI-only (like `ia portal set-agent-triage` and
|
|
86
|
+
`set-org-slack-channel`). `enable` never prints node parameters — a triage
|
|
87
|
+
workflow's prompts hold client data.
|
|
59
88
|
- `ia secrets mint *` and `ia portal set-password` print the secret **once**
|
|
60
89
|
(stdout is exactly the secret) and store nothing — save it to the client's
|
|
61
90
|
1Password vault immediately.
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: init_repo
|
|
3
|
+
description: >-
|
|
4
|
+
ONLY invoke when the user explicitly runs the /init_repo command, or
|
|
5
|
+
explicitly asks to invoke it by name. Do NOT trigger this on generic
|
|
6
|
+
mentions of "set up the client repo," "onboard this client," "scaffold the
|
|
7
|
+
repo," or similar — those route to `client-deliverables` / `engagement-spec`
|
|
8
|
+
/ `ia new-client` instead, which handle creating and filling a brand-new
|
|
9
|
+
client-<slug> repo. This skill assumes that repo already exists and has a
|
|
10
|
+
GitHub remote. When explicitly invoked, it scaffolds git/GitHub/Linear
|
|
11
|
+
branch structure on top of an existing client-<slug> build repo: creates
|
|
12
|
+
and pushes a `dev` branch, sets it as the GitHub default branch, reads the
|
|
13
|
+
client's linear_project from CLIENT.md, and creates one GitHub milestone +
|
|
14
|
+
one root branch per qualifying Linear issue. It deliberately does not
|
|
15
|
+
create GitHub issues or per-issue branches — that stays manual.
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
# /init_repo — client repo branch & milestone scaffolding
|
|
19
|
+
|
|
20
|
+
Sets up the git/GitHub/Linear scaffolding a `client-<slug>` build repo needs
|
|
21
|
+
before coding work starts: a `dev` branch as default, and one GitHub
|
|
22
|
+
milestone + one root branch per Linear issue that will eventually need a
|
|
23
|
+
commit. Everything finer-grained than that (individual GitHub issues,
|
|
24
|
+
feature branches inside a milestone) is created by hand afterward — this
|
|
25
|
+
skill is scaffolding, not issue management.
|
|
26
|
+
|
|
27
|
+
**Only runs on explicit invocation** (`/init_repo` or `/init_repo
|
|
28
|
+
client-<slug>`). Never fire this from a generic "set up the repo" request —
|
|
29
|
+
check whether the user actually typed the command or named this skill first.
|
|
30
|
+
|
|
31
|
+
## Scope boundary
|
|
32
|
+
|
|
33
|
+
- **Not this skill:** creating the repo itself, filling `CLIENT.md`, writing
|
|
34
|
+
`docs/01-04`, creating the Linear project. That's `ia new-client
|
|
35
|
+
<slug>` (bare scaffold) followed by the `engagement-spec` skill (fills the
|
|
36
|
+
docs), or the portal's Client scaffold studio, which does both end-to-end.
|
|
37
|
+
If `clients/client-<slug>/` doesn't exist yet, stop and tell the user to
|
|
38
|
+
run that path first.
|
|
39
|
+
- **Not this skill:** creating GitHub issues, or a branch per individual
|
|
40
|
+
Linear issue. The user creates those manually inside each milestone's root
|
|
41
|
+
branch, on purpose — it's how they keep a milestone's branch from growing
|
|
42
|
+
too large before it merges.
|
|
43
|
+
- **This skill:** `dev` branch + default branch, one milestone + one root
|
|
44
|
+
branch per qualifying leaf issue. That's the entire output.
|
|
45
|
+
|
|
46
|
+
Before any GitHub action (branch push, default-branch change, milestone
|
|
47
|
+
creation), follow the `github-profile` skill so it runs under the correct
|
|
48
|
+
account. Branch-naming and Linear conventions below build on the `linear`
|
|
49
|
+
skill — read that first if anything here is unclear.
|
|
50
|
+
|
|
51
|
+
## Step 1 — Resolve the target repo
|
|
52
|
+
|
|
53
|
+
- `/init_repo` with no argument: list the directories under `clients/`
|
|
54
|
+
matching `client-*`, and ask the user to pick one.
|
|
55
|
+
- `/init_repo <arg>`: match `arg` against `clients/client-*` (accept the
|
|
56
|
+
slug with or without the `client-` prefix). If more than one directory
|
|
57
|
+
plausibly matches, or none do, list the candidates and ask the user to
|
|
58
|
+
confirm rather than guessing.
|
|
59
|
+
- Confirm the resolved repo has a GitHub remote: `git -C
|
|
60
|
+
clients/client-<slug> remote -v`. No remote → stop and tell the user; this
|
|
61
|
+
skill assumes one already exists (see `linear` skill's PR-linking section
|
|
62
|
+
for the same check).
|
|
63
|
+
|
|
64
|
+
## Step 2 — `dev` branch + GitHub default branch
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git -C clients/client-<slug> fetch origin
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- If local `dev` doesn't exist yet: `git checkout -b dev main` (or
|
|
71
|
+
`origin/main` if `main` isn't checked out locally). If `dev` already
|
|
72
|
+
exists, just check it out — don't recreate it.
|
|
73
|
+
- Push it: `git push -u origin dev`.
|
|
74
|
+
- Check the current GitHub default branch before changing anything:
|
|
75
|
+
`gh repo view InstallAgent/client-<slug> --json defaultBranchRef -q
|
|
76
|
+
.defaultBranchRef.name`. If it's already `dev`, skip this step (idempotent
|
|
77
|
+
no-op). Otherwise:
|
|
78
|
+
`gh repo edit InstallAgent/client-<slug> --default-branch dev`.
|
|
79
|
+
- This changes what a fresh clone checks out and what PRs target by
|
|
80
|
+
default — tell the user this happened, don't do it silently.
|
|
81
|
+
|
|
82
|
+
## Step 3 — Find the Linear project
|
|
83
|
+
|
|
84
|
+
Read `clients/client-<slug>/CLIENT.md`'s `linear_project` field and resolve
|
|
85
|
+
it via the Linear MCP tools (`get_project` / `list_projects`). This is the
|
|
86
|
+
authoritative pointer per the `linear` skill — never fuzzy-match the project
|
|
87
|
+
by repo name.
|
|
88
|
+
|
|
89
|
+
## Step 4 — Find qualifying "main" issues
|
|
90
|
+
|
|
91
|
+
Pull every issue in that project (`list_issues`, filtered by project,
|
|
92
|
+
including `parentId`). Classify by tree position, not by leaf-vs-parent:
|
|
93
|
+
|
|
94
|
+
- **Root/container**: an issue with no parent that has at least one child
|
|
95
|
+
(e.g. a `Build 1 — ...` umbrella issue). Purely organizational — never
|
|
96
|
+
gets a milestone itself.
|
|
97
|
+
- **Main issue**: either (a) a direct child of a root/container issue — a
|
|
98
|
+
milestone candidate **whether or not it has its own sub-issues** — or (b)
|
|
99
|
+
an issue with no parent and no children (fully standalone). Every
|
|
100
|
+
milestone maps to exactly one main issue.
|
|
101
|
+
- **Sub-issue**: a child of a main issue (any depth below it). Never gets
|
|
102
|
+
its own milestone or branch, no matter how far it's nested — it's folded
|
|
103
|
+
into its main issue's milestone description as a checklist item instead
|
|
104
|
+
(Step 5). This is the case that broke the old "leaf issue" rule: a
|
|
105
|
+
"Blockers" umbrella like `[B]` isn't a leaf (it has children), but it's
|
|
106
|
+
still one main issue and one milestone — its children become the
|
|
107
|
+
checklist, not separate milestones.
|
|
108
|
+
|
|
109
|
+
A main issue qualifies when its status isn't `Done` / `Canceled` /
|
|
110
|
+
`Duplicate`, and it (or something under it) will require a git push at some
|
|
111
|
+
point — code **or** docs. In practice this almost always holds once an
|
|
112
|
+
issue has any sub-issues at all (status changes on the children typically
|
|
113
|
+
get mirrored into a doc somewhere, e.g. `docs/04-access-checklist.md`), so
|
|
114
|
+
the push test mainly matters for filtering *standalone, childless* main
|
|
115
|
+
issues that are pure discussion/decision with no repo artifact ever. If
|
|
116
|
+
it's genuinely unclear, ask the user rather than guessing — skipping is
|
|
117
|
+
cheap, but creating-then-deleting a milestone is noisy.
|
|
118
|
+
|
|
119
|
+
## Step 5 — One GitHub milestone per qualifying main issue
|
|
120
|
+
|
|
121
|
+
- Check for an existing milestone first: `gh api
|
|
122
|
+
repos/InstallAgent/client-<slug>/milestones --paginate` and match on the
|
|
123
|
+
`INS-xxx` prefix in the title. If one already exists for that issue, skip
|
|
124
|
+
it (idempotent — never duplicate).
|
|
125
|
+
- Title: `INS-xxx — <issue title>`.
|
|
126
|
+
- Description: a link back to the Linear issue
|
|
127
|
+
(`https://linear.app/install-agent/issue/INS-xxx`), plus a GitHub-flavored
|
|
128
|
+
checkbox list:
|
|
129
|
+
- If the main issue **has sub-issues**, one checklist line per sub-issue
|
|
130
|
+
— `- [ ] INS-xxx — <title>` (checked if that sub-issue is already
|
|
131
|
+
Done/Canceled) — regardless of how many levels deep they nest. Don't
|
|
132
|
+
create separate milestones or branches for any of them.
|
|
133
|
+
- If the main issue **has no sub-issues** (standalone), pull the
|
|
134
|
+
checklist from its own description/acceptance criteria if it has one,
|
|
135
|
+
otherwise a single unchecked placeholder item for the user to flesh out
|
|
136
|
+
by hand.
|
|
137
|
+
- Create it: `gh api repos/InstallAgent/client-<slug>/milestones -f
|
|
138
|
+
title="INS-xxx — ..." -f description="..." -f state=open`.
|
|
139
|
+
- **Never change the Linear issue's status here.** Creating a milestone is
|
|
140
|
+
organizational structuring, not starting work — it must not trigger the
|
|
141
|
+
`In Progress` transition described in the `linear` skill's status
|
|
142
|
+
discipline.
|
|
143
|
+
|
|
144
|
+
## Step 6 — One root branch per milestone
|
|
145
|
+
|
|
146
|
+
- Get the issue's suggested branch name via `get_issue`
|
|
147
|
+
(`gitBranchName`, e.g. `noahm/ins-264-fix-sftp-upload-path`).
|
|
148
|
+
- Strip the leading `<username>/` segment and prefix with `milestone/`:
|
|
149
|
+
`milestone/ins-264-fix-sftp-upload-path`.
|
|
150
|
+
- Skip if that branch already exists locally or on `origin` — never
|
|
151
|
+
overwrite or duplicate.
|
|
152
|
+
- Otherwise branch off `dev` (not `main`):
|
|
153
|
+
```bash
|
|
154
|
+
git -C clients/client-<slug> checkout -b milestone/<slug> dev
|
|
155
|
+
git -C clients/client-<slug> push -u origin milestone/<slug>
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Step 7 — Summarize and stop
|
|
159
|
+
|
|
160
|
+
Print a short summary: branches created vs. skipped (already existed),
|
|
161
|
+
milestones created vs. skipped, and any issues that were skipped pending a
|
|
162
|
+
judgment call from the user. Stop there — this skill's job ends at the
|
|
163
|
+
scaffolding. Sub-issue creation, feature branches inside a milestone, and
|
|
164
|
+
eventual root-to-`dev` PRs are manual.
|
|
165
|
+
|
|
166
|
+
## Closing a milestone later (not automated by this skill)
|
|
167
|
+
|
|
168
|
+
When the user is ready to fold a milestone's root branch into `dev`, the PR
|
|
169
|
+
body should carry the Linear magic keyword (`Fixes INS-xxx` / `Closes
|
|
170
|
+
INS-xxx` / `Resolves INS-xxx`) for **every** issue that milestone covers,
|
|
171
|
+
batched onto that one PR — not scattered across earlier PRs merged into the
|
|
172
|
+
root branch itself. Two things this ordering protects:
|
|
173
|
+
|
|
174
|
+
- GitHub only auto-closes an issue on merge into the repo's **default**
|
|
175
|
+
branch. Since the root branch (`milestone/...`) isn't the default branch,
|
|
176
|
+
merges into it never auto-close anything — only the final root-to-`dev`
|
|
177
|
+
PR does. Keeping the magic keywords off earlier PRs (into the root
|
|
178
|
+
branch) is what prevents issues from closing early.
|
|
179
|
+
- Once every issue under a milestone is closed, GitHub auto-closes the
|
|
180
|
+
milestone itself — no extra scripting needed for that part.
|
|
181
|
+
|
|
182
|
+
## Re-running
|
|
183
|
+
|
|
184
|
+
Safe to re-run against the same repo at any time — every step above already
|
|
185
|
+
skips existing branches, existing milestones, and closed/canceled/duplicate
|
|
186
|
+
issues rather than duplicating or overwriting. If issues were added to
|
|
187
|
+
Linear well after the first run and it's unclear which ones should now be
|
|
188
|
+
pulled in, ask the user for a scope check before creating anything new.
|