@installagent/sdk 0.2.0 → 0.3.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 (54) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/claude-hours.d.ts +118 -0
  4. package/dist/claude-hours.js +523 -0
  5. package/dist/client-drive.d.ts +3 -0
  6. package/dist/client-drive.js +2 -2
  7. package/dist/env-fill.js +21 -4
  8. package/dist/env-registry.d.ts +4 -0
  9. package/dist/env-registry.js +54 -2
  10. package/dist/git.d.ts +31 -0
  11. package/dist/git.js +59 -0
  12. package/dist/google-service-account.d.ts +20 -0
  13. package/dist/google-service-account.js +49 -0
  14. package/dist/hours-estimate.d.ts +43 -0
  15. package/dist/hours-estimate.js +159 -0
  16. package/dist/hours-export-schedule.d.ts +35 -0
  17. package/dist/hours-export-schedule.js +188 -0
  18. package/dist/hours-ledger.d.ts +129 -0
  19. package/dist/hours-ledger.js +882 -0
  20. package/dist/index.d.ts +13 -2
  21. package/dist/index.js +13 -2
  22. package/dist/portal-admin.d.ts +68 -0
  23. package/dist/portal-admin.js +64 -1
  24. package/dist/sync-repos.d.ts +7 -0
  25. package/dist/sync-repos.js +10 -1
  26. package/dist/template-sync.d.ts +10 -9
  27. package/dist/template-sync.js +14 -9
  28. package/dist/triage-backfill.d.ts +37 -0
  29. package/dist/triage-backfill.js +211 -0
  30. package/dist/triage-enable.d.ts +90 -0
  31. package/dist/triage-enable.js +428 -0
  32. package/dist/triage-gates.d.ts +252 -0
  33. package/dist/triage-gates.js +951 -0
  34. package/dist/workspace-push.d.ts +39 -0
  35. package/dist/workspace-push.js +78 -0
  36. package/dist/workspace-status.d.ts +37 -0
  37. package/dist/workspace-status.js +114 -0
  38. package/package.json +1 -1
  39. package/templates/env.example +6 -2
  40. package/templates/workspace-root/.claude/settings.json +12 -1
  41. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +53 -28
  42. package/templates/workspace-root/skills/CLAUDE.md +6 -1
  43. package/templates/workspace-root/skills/README.md +17 -2
  44. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  45. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  46. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  47. package/templates/workspace-root/skills/client-latest/SKILL.md +124 -82
  48. package/templates/workspace-root/skills/client-latest/catchup.command.md +5 -4
  49. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +90 -13
  50. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  51. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  52. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  53. package/templates/workspace-root/skills/ia-cli/SKILL.md +30 -1
  54. 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) | Terse status table | Same items as `03`, plus a Status column (HAVE/REQUESTED/MISSING) — the fast answer to "what are we still waiting on?" This is the **tracker**, kept current as access lands. Mirror it into `onboarding.html`'s Client tab. |
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 (OAuth, invite). State that credentials
165
- go into *their* vault and we never take a password.
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. Builds trust, prevents the
172
- "why do you need my bank password" panic. (We never do.)
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
- Same items as `03-client-onboarding.md`'s §1 Access and §2 Decisions, reshaped
178
- into one status table: **Item | System | Why we need it | Status | Notes**.
179
- Status is one of HAVE / REQUESTED / MISSING / N/A — set it from what the call
180
- notes and registry profile actually say was granted or promised, never
181
- assumed. This is the doc (and the matching `onboarding.html` section) a
182
- teammate opens to answer "what are we still waiting on from this client?"
183
- without re-reading the call transcript. Update it in the same commit whenever
184
- access lands — it decays fast otherwise.
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 the table into `onboarding.html`'s Client tab (a new "Access &
191
- credentials checklist" section) so a developer sees it without opening
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`: same items as `03`, Status column set from
263
- what's actually confirmed (not assumed); mirrored into `onboarding.html`.
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 (OAuth/invite), and that
123
- credentials go into the client's own vault — we never take a password.>
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: no bank passwords ever, no system password (OAuth only), no
136
- access beyond the named systems.>
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), minting a credential, administering the portal,
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.