@installagent/sdk 0.4.0 → 0.5.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 (39) hide show
  1. package/dist/agent-mirror.js +22 -10
  2. package/dist/agent-templates.d.ts +10 -12
  3. package/dist/agent-templates.js +34 -6
  4. package/dist/doctor.d.ts +11 -1
  5. package/dist/doctor.js +24 -22
  6. package/dist/index.d.ts +4 -1
  7. package/dist/index.js +4 -1
  8. package/dist/lefthook-hooks.d.ts +36 -0
  9. package/dist/lefthook-hooks.js +64 -0
  10. package/dist/n8n-defaults.d.ts +90 -0
  11. package/dist/n8n-defaults.js +153 -0
  12. package/dist/portal-admin.d.ts +104 -13
  13. package/dist/portal-admin.js +113 -28
  14. package/dist/pr-open.d.ts +45 -0
  15. package/dist/pr-open.js +98 -0
  16. package/dist/sync-repos.d.ts +8 -1
  17. package/dist/sync-repos.js +10 -9
  18. package/dist/triage-enable.js +20 -7
  19. package/package.json +1 -1
  20. package/templates/workspace-root/AGENT.md +2 -1
  21. package/templates/workspace-root/ONBOARDING.md +10 -8
  22. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +7 -2
  23. package/templates/workspace-root/skills/CLAUDE.md +4 -4
  24. package/templates/workspace-root/skills/README.md +2 -2
  25. package/templates/workspace-root/skills/ad-machine/SKILL.md +14 -18
  26. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +14 -16
  27. package/templates/workspace-root/skills/client-latest/SKILL.md +14 -18
  28. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +22 -16
  29. package/templates/workspace-root/skills/engagement-spec/SKILL.md +11 -14
  30. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +9 -0
  31. package/templates/workspace-root/skills/house-voice/SKILL.md +67 -19
  32. package/templates/workspace-root/skills/ia-cli/SKILL.md +14 -17
  33. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +14 -20
  34. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +2 -2
  35. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +13 -15
  36. package/templates/workspace-root/skills/slack-voice/SKILL.md +50 -31
  37. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +14 -15
  38. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +13 -19
  39. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +13 -15
@@ -0,0 +1,98 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { findWorkspaceRoot } from "./env-file.js";
4
+ import { execFailureDetail, execFileAsync } from "./exec.js";
5
+ /** `owner/repo` from a GitHub remote URL (ssh or https). */
6
+ export function parseGithubRemote(url) {
7
+ const m = url.trim().match(/github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/);
8
+ return m ? `${m[1]}/${m[2]}` : undefined;
9
+ }
10
+ export function expectedGithubAccount(workspaceDir) {
11
+ if (!workspaceDir)
12
+ return undefined;
13
+ const file = join(workspaceDir, ".github-account");
14
+ if (!existsSync(file))
15
+ return undefined;
16
+ const login = readFileSync(file, "utf8").trim();
17
+ return login || undefined;
18
+ }
19
+ export async function prOpen(options = {}) {
20
+ const exec = options.execFileImpl ?? execFileAsync;
21
+ const repoDir = options.repoDir ?? ".";
22
+ const base = options.base ?? "main";
23
+ const run = async (file, args) => {
24
+ try {
25
+ return (await exec(file, args)).stdout.trim();
26
+ }
27
+ catch (error) {
28
+ throw new Error(`${file} ${args.slice(0, 3).join(" ")} failed: ${execFailureDetail(error).detail}`);
29
+ }
30
+ };
31
+ const git = (...args) => run("git", ["-C", repoDir, ...args]);
32
+ // 1. Right account.
33
+ const account = await run("gh", ["api", "user", "--jq", ".login"]);
34
+ const expected = expectedGithubAccount(options.workspaceDir ?? findWorkspaceRoot(repoDir));
35
+ if (expected && account !== expected) {
36
+ throw new Error(`gh is logged in as "${account}", but this workspace uses "${expected}" (.github-account). ` +
37
+ `Run: gh auth switch --hostname github.com --user ${expected}`);
38
+ }
39
+ const branch = await git("rev-parse", "--abbrev-ref", "HEAD");
40
+ if (branch === "HEAD")
41
+ throw new Error("Detached HEAD — check out a branch first.");
42
+ if (branch === base) {
43
+ throw new Error(`You are on ${base}. Create a branch first: git switch -c <name>`);
44
+ }
45
+ const repo = parseGithubRemote(await git("remote", "get-url", "origin"));
46
+ if (!repo)
47
+ throw new Error("origin is not a GitHub remote.");
48
+ // 2 + 3. No merged or open PR from this branch.
49
+ const prs = JSON.parse(await run("gh", [
50
+ "pr",
51
+ "list",
52
+ "--repo",
53
+ repo,
54
+ "--head",
55
+ branch,
56
+ "--state",
57
+ "all",
58
+ "--json",
59
+ "number,state,url",
60
+ ]));
61
+ const merged = prs.find((p) => p.state === "MERGED");
62
+ if (merged) {
63
+ throw new Error(`PR #${merged.number} from ${branch} is already merged (${merged.url}). A push to this branch ` +
64
+ `would be lost. Put the new commits on a fresh branch from ${base}: ` +
65
+ `git switch -c ${branch}-2 origin/${base}, then cherry-pick them.`);
66
+ }
67
+ const open = prs.find((p) => p.state === "OPEN");
68
+ if (open) {
69
+ throw new Error(`PR #${open.number} from ${branch} is still open (${open.url}). Do not add commits to it: ` +
70
+ "the Merge button squashes the head as it is. Open a new branch for the next slice.");
71
+ }
72
+ const result = {
73
+ repo,
74
+ branch,
75
+ base,
76
+ account,
77
+ draft: !options.ready,
78
+ dryRun: Boolean(options.dryRun),
79
+ };
80
+ if (options.dryRun)
81
+ return result;
82
+ try {
83
+ await git("push", "-u", "origin", "HEAD");
84
+ }
85
+ catch (error) {
86
+ // A pre-push hook prints its reason on stdout, which the error does not carry.
87
+ throw new Error(`${error instanceof Error ? error.message : String(error)} — run \`git -C ${repoDir} push -u origin HEAD\` to see the hook output, fix it, then re-run \`ia pr open\`.`);
88
+ }
89
+ const args = ["pr", "create", "--repo", repo, "--base", base, "--head", branch];
90
+ if (options.title)
91
+ args.push("--title", options.title, "--body", options.body ?? "");
92
+ else
93
+ args.push("--fill");
94
+ if (!options.ready)
95
+ args.push("--draft");
96
+ const url = (await run("gh", args)).split("\n").pop()?.trim();
97
+ return { ...result, url };
98
+ }
@@ -1,4 +1,5 @@
1
1
  import { type PullFn } from "./git.js";
2
+ import { type HookInstallFn, type InstallClientHooksResult } from "./lefthook-hooks.js";
2
3
  import { type EnvExampleStatus, type WorkspaceDocsResult } from "./workspace-docs.js";
3
4
  /**
4
5
  * `ia sync` — bring every repo in the workspace up to date in one command.
@@ -12,7 +13,9 @@ import { type EnvExampleStatus, type WorkspaceDocsResult } from "./workspace-doc
12
13
  * Never merges. Every pull is fast-forward-only, so a repo with local commits
13
14
  * or a dirty tree fails loudly and keeps its work — losing a technician's
14
15
  * uncommitted client changes to a convenience command would be unforgivable.
15
- * `.env` is never read or written here.
16
+ * `.env` is never read or written here. The one other write: a client clone
17
+ * with no lefthook hook gets `npx lefthook install`, so its repo-lint and
18
+ * secret-scan gates run (see lefthook-hooks.ts).
16
19
  */
17
20
  export interface SyncReposOptions {
18
21
  /** installagent/ workspace root. Defaults to the current dir. */
@@ -25,6 +28,8 @@ export interface SyncReposOptions {
25
28
  docs?: boolean;
26
29
  /** Injectable for tests; defaults to real `git pull --ff-only`. */
27
30
  pull?: PullFn;
31
+ /** Injectable for tests; defaults to a real `npx --yes lefthook install`. */
32
+ installHooks?: HookInstallFn;
28
33
  }
29
34
  export type SyncRepoStatus = "updated" | "absent" | "failed";
30
35
  export interface SyncRepoResult {
@@ -42,6 +47,8 @@ export interface SyncReposResult {
42
47
  docs?: WorkspaceDocsResult;
43
48
  /** Present only when `docs` was set. `.env` itself is never touched. */
44
49
  envExample?: EnvExampleStatus;
50
+ /** Client clones that had no lefthook hook, and what installing it did. */
51
+ hooks: InstallClientHooksResult;
45
52
  nextSteps: string[];
46
53
  }
47
54
  /**
@@ -1,6 +1,7 @@
1
- import { existsSync, readdirSync } from "node:fs";
1
+ import { existsSync } from "node:fs";
2
2
  import { join, resolve } from "node:path";
3
3
  import { gitPullFfOnly } from "./git.js";
4
+ import { clientCloneNames, installClientHooks, } from "./lefthook-hooks.js";
4
5
  import { WIZARD_REPO_NAMES } from "./wizard.js";
5
6
  import { refreshEnvExample, refreshWorkspaceDocs, } from "./workspace-docs.js";
6
7
  /**
@@ -12,14 +13,7 @@ import { refreshEnvExample, refreshWorkspaceDocs, } from "./workspace-docs.js";
12
13
  * Windows. Only the filesystem probe below uses platform separators.
13
14
  */
14
15
  function clientRepoPaths(workspaceDir) {
15
- const clientsDir = join(workspaceDir, "clients");
16
- if (!existsSync(clientsDir))
17
- return [];
18
- return readdirSync(clientsDir, { withFileTypes: true })
19
- .filter((entry) => entry.isDirectory() && entry.name.startsWith("client-"))
20
- .map((entry) => `clients/${entry.name}`)
21
- .filter((rel) => existsSync(join(workspaceDir, ...rel.split("/"), ".git")))
22
- .sort();
16
+ return clientCloneNames(workspaceDir).map((name) => `clients/${name}`);
23
17
  }
24
18
  /**
25
19
  * Every repo `ia sync`/`ia status`/`ia push` operate on: the team repos plus
@@ -63,6 +57,7 @@ export async function syncRepos(options = {}) {
63
57
  });
64
58
  }
65
59
  }
60
+ const hooks = await installClientHooks(dir, options.installHooks);
66
61
  const docs = withDocs ? await refreshWorkspaceDocs(dir, { overwrite: true }) : undefined;
67
62
  const envExample = withDocs ? await refreshEnvExample(dir, { overwrite: true }) : undefined;
68
63
  const failed = repos.filter((repo) => repo.status === "failed");
@@ -72,6 +67,11 @@ export async function syncRepos(options = {}) {
72
67
  .map((repo) => repo.name)
73
68
  .join(", ")}, then re-run \`ia sync\` (nothing was merged or discarded)`);
74
69
  }
70
+ if (hooks.failed.length > 0) {
71
+ nextSteps.push(`lefthook install failed in ${hooks.failed
72
+ .map((repo) => `clients/${repo.name}`)
73
+ .join(", ")} — run \`npx lefthook install\` inside each one`);
74
+ }
75
75
  if (!withDocs) {
76
76
  nextSteps.push("`ia sync --docs` also refreshes the root docs, skills/ and .env.example");
77
77
  }
@@ -84,6 +84,7 @@ export async function syncRepos(options = {}) {
84
84
  repos,
85
85
  ...(docs ? { docs } : {}),
86
86
  ...(envExample ? { envExample } : {}),
87
+ hooks,
87
88
  nextSteps,
88
89
  };
89
90
  }
@@ -1,7 +1,7 @@
1
1
  import { readdir, readFile } from "node:fs/promises";
2
2
  import { join } from "node:path";
3
3
  import { N8N_API_KEY_ENV, N8N_API_URL_ENV, N8nAuthError } from "./agent-templates.js";
4
- import { DEFAULT_PORTAL_URL, PORTAL_URL_ENV, portalListAgents, portalSetAgentTriage, } from "./portal-admin.js";
4
+ import { DEFAULT_PORTAL_URL, PORTAL_URL_ENV, portalBuildType, portalBuildWorkflowId, portalListAgents, portalSetAgentTriage, } from "./portal-admin.js";
5
5
  import { triageBackfill } from "./triage-backfill.js";
6
6
  import { resolveRecordSheetId } from "./triage-gates.js";
7
7
  // `ia triage enable <slug>`: turn a registered agent into a portal triage
@@ -277,12 +277,16 @@ async function fetchWorkflow(workflowId, agentLabel, options) {
277
277
  }
278
278
  if (res.status === 404) {
279
279
  throw new Error(`n8n has no workflow ${workflowId} (the workflow of ${agentLabel}). If the agent now runs ` +
280
- "another workflow, repoint it: ia portal set-agent-workflow");
280
+ "another workflow, repoint it: ia portal set-build-workflow");
281
281
  }
282
282
  if (!res.ok)
283
283
  throw new Error(`n8n API ${res.status} reading workflow ${workflowId}`);
284
284
  return res.json();
285
285
  }
286
+ function asRunnable(build) {
287
+ const workflowId = portalBuildWorkflowId(build);
288
+ return workflowId ? { ...build, workflowId } : null;
289
+ }
286
290
  function pickAgent(slug, agents, wanted) {
287
291
  if (wanted) {
288
292
  const found = agents.find((a) => a.slug === wanted);
@@ -292,12 +296,21 @@ function pickAgent(slug, agents, wanted) {
292
296
  if (found.status === "retired") {
293
297
  throw new Error(`${slug}/${wanted} is retired — a retired agent does not record`);
294
298
  }
295
- return found;
299
+ const runnable = asRunnable(found);
300
+ if (!runnable) {
301
+ throw new Error(`${slug}/${wanted} is an ${portalBuildType(found)} build with no n8n workflow — only an ` +
302
+ "agent build can be a triage agent");
303
+ }
304
+ return runnable;
296
305
  }
297
- const active = agents.filter((a) => a.status === "active");
306
+ // App builds (and any agent row with no workflow id) never record — skip them.
307
+ const active = agents
308
+ .filter((a) => a.status === "active")
309
+ .map(asRunnable)
310
+ .filter((a) => a !== null);
298
311
  if (active.length === 0) {
299
- throw new Error(`${slug} has no active agent in the portal — register the triage workflow first: ` +
300
- `ia portal create-agent --slug ${slug} --agent <agentSlug> --workflow <n8nId> …`);
312
+ throw new Error(`${slug} has no active agent build with an n8n workflow in the portal — register the triage ` +
313
+ `workflow first: ia portal create-build --slug ${slug} --build <slug> --type agent --workflow <n8nId> …`);
301
314
  }
302
315
  if (active.length > 1) {
303
316
  throw new Error(`${slug} has ${active.length} active agents — pass --agent with one of: ` +
@@ -345,7 +358,7 @@ export async function triageEnable(slug, options = {}) {
345
358
  if (agent.triageProvider && agent.triageProvider !== provider) {
346
359
  throw new Error(`${label} is already an ${agent.triageProvider} triage agent, but the ${providerSource === "flag" ? "--provider flag" : "workflow"} ` +
347
360
  `says ${provider}. If the mailbox really changed, clear it first: ` +
348
- `ia portal set-agent-triage --slug ${slug} --agent ${agent.slug} --provider none`);
361
+ `ia portal set-build-triage --slug ${slug} --build ${agent.slug} --provider none`);
349
362
  }
350
363
  const portalUrl = options.portal?.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL;
351
364
  const wiring = checkTriageRecordWiring(workflow, { portalUrl, provider });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@installagent/sdk",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -29,7 +29,7 @@ installagent/
29
29
  │ ├── client-template/ # THE baseline — every client repo is created from this
30
30
  │ └── client-<slug>/ # e.g. client-carvision, client-kingdom, …
31
31
  ├── team-clients/ # Client REGISTRY (CRM-as-code): who each client is + call history (PRIVATE, PII allowed)
32
- ├── team-infra/ # AWS CDK hosting (n8n, SFTP), the n8n workflow library, shared automation skills
32
+ ├── team-infra/ # AWS CDK hosting (n8n, SFTP), the n8n workflow library, shared automation skills, the pdf compress service
33
33
  ├── team-web/ # Public web: installagent.com (apps/web) + team hub (apps/docs)
34
34
  ├── team-design/ # Install Agent design system source (tokens, components, guidelines)
35
35
  ├── team-branding/ # Logo files (static assets only)
@@ -49,6 +49,7 @@ installagent/
49
49
  | Answer "what did we ship for X / does it work?" | `clients/client-<slug>/docs/00-delivery-log.md` + `evidence/` | same |
50
50
  | Check or change deal status | **Airtable (`Clients - Master`)** — never a file in git | — |
51
51
  | Build or edit an n8n workflow (ours or a client's) | **check `agents/` (the bank) first**, then the client repo's `workflows/` or `team-infra/n8n-workflows/` | `agents/README.md` + `team-infra/skills/n8n-workflow.md` |
52
+ | An n8n workflow sends a PDF on to a size-capped step (a Vercel app, an email, an LLM, a vendor upload) | the **`pdf` compress service** on the n8n box (`http://pdf:8080`): compress first, keep the size gate, keep the original on any error | `team-infra/skills/n8n-workflow.md` § 3 + `team-infra/pdf-service/README.md` |
52
53
  | See what automations we can redeploy / scope a deal against them | `agents/` — catalog table in its README, plain-language `template.md` per template | `agents/README.md` |
53
54
  | Reuse or bank a workflow template (`ia agent save\|templates\|create`) | `agents/` | `agents/AGENT.md` |
54
55
  | Infra (n8n hosting, SFTP, AWS) | `team-infra/` | `team-infra/AGENT.md` |
@@ -55,22 +55,24 @@ you're set up. They boil down to:
55
55
  **On Windows, run anything that touches `op` from PowerShell.** 1Password
56
56
  supports PowerShell only, so the desktop-app integration cannot
57
57
  authenticate `op` from Git Bash at all — see the Windows section below.
58
- Shared team secrets live in the **team-techs** vault — 8 items,
58
+ Shared team secrets live in the **team-techs** vault — 12 items,
59
59
  and that one grant is all a technician needs (`AIRTABLE_API_TOKEN`,
60
60
  `GOOGLE_SERVICE_ACCOUNT_KEY`, `N8N_API_URL`, `N8N_API_KEY`,
61
61
  `LINEAR_CLIENT_TEAM_ID`, `FATHOM_API_KEY`, `IA_PORTAL_ADMIN_SECRET`,
62
- `GEMINI_API_KEY`). If you think you need more, you probably don't — ask
63
- before requesting `team-admin`.
62
+ `GEMINI_API_KEY`, `IA_DOCS_SEARCH_TOKEN`, `HOURS_EXPORT_SECRET`,
63
+ `x-relay-secret`, `n8n Install Agent Callback URL`). The full list lives
64
+ in `team-tools/docs/1password-vaults.md`. If you think you need more, you
65
+ probably don't — ask before requesting `team-admin`.
64
66
  3. `ia env fill` — fills the empty vars in the root `.env` straight from
65
67
  1Password. No copy-pasting secrets, nothing goes through a chat window.
66
68
  It only touches your own technician var set. The infra, portal and
67
69
  payments vars ship commented out in `.env.example` and are reported as a
68
70
  count, not by name — if you actually need one, ask, then
69
71
  `ia env fill --admin`.
70
- 4. Two personal values you set by hand in `.env`: your own
71
- `LINEAR_API_TOKEN` (Linear → Settings → Security & access) and
72
- `IA_DOCS_SESSION` (session cookie from a logged-in team.installagent.com
73
- tab).
72
+ 4. One personal value you set by hand in `.env`: your own
73
+ `LINEAR_API_TOKEN` (Linear → Settings → Security & access). Docs search
74
+ needs nothing from you — `ia env fill` sets the shared
75
+ `IA_DOCS_SEARCH_TOKEN`.
74
76
  5. `ia doctor -w ~/installagent` — repeat until everything required is green.
75
77
  It prints only what still needs doing; `ia doctor --all` shows every check,
76
78
  passing ones included.
@@ -128,7 +130,7 @@ installagent/
128
130
  ├── agents/ # the WORKFLOW BANK — reusable n8n templates + plain-language manifests
129
131
  ├── clients/ # one build repo per client + client-template (the baseline)
130
132
  ├── team-clients/ # client REGISTRY: who each client is + call history (private, PII allowed)
131
- ├── team-infra/ # AWS hosting (n8n, SFTP), n8n workflow library, automation skills
133
+ ├── team-infra/ # AWS hosting (n8n, SFTP), n8n workflow library, automation skills, pdf compress service
132
134
  ├── team-web/ # installagent.com + team hub (Next.js pnpm workspace)
133
135
  ├── team-design/ # Install Agent design system source
134
136
  ├── team-branding/ # logo files
@@ -1,7 +1,8 @@
1
1
  name: PR → Slack (approve / close)
2
2
 
3
3
  # Posts every new PR to Slack (as @Agent Zero) with "Merge" and "Close"
4
- # buttons. This workflow only POSTS (it is read-only). The button clicks are
4
+ # buttons — except new-lead `add-client/*` PRs (see the job's `if:`).
5
+ # This workflow only POSTS (it is read-only). The button clicks are
5
6
  # handled by @Agent Zero itself — team-tools/apps/slack-agent, Bolt Socket
6
7
  # Mode, the `pr_merge`/`pr_close` action handlers in src/app.ts — which
7
8
  # squash-merges (or closes) via the GitHub API using its own write-scoped
@@ -38,7 +39,11 @@ jobs:
38
39
  notify:
39
40
  # Drafts are not ready to review, and skipping them also stops the
40
41
  # duplicate post a draft would otherwise make on opened + ready_for_review.
41
- if: github.event.pull_request.draft == false
42
+ # `add-client/*` branches are new-lead PRs (n8n "New lead v3" opens them
43
+ # in team-clients). Their Merge/Close buttons live on the lead card in
44
+ # #notify-leads (`lead_pr_merge`/`lead_pr_close`), so they skip
45
+ # #notify-prs. Every other branch, `add-call/*` included, still posts.
46
+ if: github.event.pull_request.draft == false && !startsWith(github.event.pull_request.head.ref, 'add-client/')
42
47
  runs-on: ubuntu-latest
43
48
  steps:
44
49
  - name: Post PR to Slack with action buttons
@@ -29,12 +29,12 @@ skills/
29
29
  ├── backtest-acceptance-gates/ # prove an automation works before the client trusts it (ground truth, evidence, gates)
30
30
  ├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw/decks (logo + brand red #d11a1a)
31
31
  ├── design-system/ # the Install Agent Design System (screens/UI)
32
- ├── house-voice/ # house voice for client-facing writing, pulled from installagent.com/get-started
32
+ ├── house-voice/ # house voice for client-facing writing + the ~150-word client message budget
33
33
  ├── contract-tech-agnostic/ # contracts/SOWs by FUNCTION and OUTCOME, never tech (+ SOW template in references/)
34
34
  ├── linear/ # Linear issue workflow for client build work (status discipline, sub-issue trees, PR linking)
35
35
  ├── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails
36
36
  ├── gcloud-cli-setup/ # one named gcloud configuration per account/client + check-before-you-run discipline
37
- ├── slack-voice/ # INTERNAL Slack: terse bullets, hard numbers, no adjectives (client Slack → house-voice)
37
+ ├── slack-voice/ # INTERNAL messages (Slack, email, chat): ~100 words, terse bullets, hard numbers (client → house-voice)
38
38
  ├── github-profile/ # force gh CLI + git commits onto the noahm-ia account before any GitHub action
39
39
  └── init_repo/ # explicit-only /init_repo — dev branch + default branch + one milestone/root-branch per leaf issue
40
40
  ```
@@ -60,8 +60,8 @@ Each is `skills/<name>/SKILL.md`, with bulky tables in `references/`.
60
60
  | Proving accuracy / hitting an acceptance gate / writing up a validation run | `backtest-acceptance-gates` |
61
61
  | Branding a print/PDF/Excalidraw deliverable, or building a client deck | `installagent-brand-kit` |
62
62
  | Building or reviewing any UI / web page / funnel / component | `design-system` |
63
- | Writing or reviewing any client-facing copy (proposal, email, guide, web/ad copy) | `house-voice` |
64
- | Writing any Slack message to a teammate or internal channel | `slack-voice` |
63
+ | Writing, reviewing, or cutting down any client-facing copy (proposal, email, Slack, guide, web/ad copy) | `house-voice` |
64
+ | Writing any message to a teammate or internal channel (Slack, email, chat) | `slack-voice` |
65
65
  | Drafting/reviewing any contract, SOW, MSA, or proposal | `contract-tech-agnostic` |
66
66
  | Working an `INS-xxx` issue / a client's Linear project | `linear` |
67
67
  | Any task an `ia` command covers (client context, intake, agent bank, secrets, setup/doctor) | `ia-cli` |
@@ -135,13 +135,13 @@ skills also ship a rendered PDF guide for handing to a technician.
135
135
  | `gcloud-cli-setup` | 100 | — |
136
136
  | `github-profile` | 56 | — |
137
137
  | `google-chat-app-setup` | 136 | PDF guide |
138
- | `house-voice` | 228 | `references/source-copy.md` |
138
+ | `house-voice` | 288 | `references/source-copy.md` |
139
139
  | `ia-cli` | 87 | — |
140
140
  | `init_repo` | 188 | — |
141
141
  | `installagent-brand-kit` | 161 | 4 `references/`, 5 `scripts/` (brand, deck, deck_lint, logo_raster, make_deck_template), logo SVGs + deck template |
142
142
  | `linear` | 186 | — |
143
143
  | `salesforce-api-snapshot` | 379 | `references/` schema-discovery SOQL, snapshot storage · PDF guide |
144
- | `slack-voice` | 158 | — |
144
+ | `slack-voice` | 180 | — |
145
145
  | `sso-gated-client-app` | 337 | PDF guide |
146
146
  | `tech-call-prep` | 240 | — |
147
147
  | `vendor-feed-ingestion` | 323 | `references/` delivery contract, feed guards · PDF guide |
@@ -1,24 +1,20 @@
1
1
  ---
2
2
  name: ad-machine
3
3
  description: >-
4
- The Install Agent Meta ads machine — the creative engine that turns a
5
- script, a prompt/brief, OR a client's existing asset library into a batch
6
- of human-realistic video ads, then hands the batch to the banked
7
- `meta-video-ads-agent` n8n rail for paused publishing into the client's
8
- Meta ad account. Two modes: BRIEF (script or prompt → new UGC-style /
9
- product video ads generated via the connected media-generation MCP's ad
10
- workflows) and RECYCLE (mine the client's Drive folder of past ads, raw
11
- footage, and product photos — ad-multiplier variations of a winning ad,
12
- recuts of real footage, image-to-video from product stills — so the
13
- client never has to film again and creatives keep coming). Use this
14
- WHENEVER someone says "make ads for [client]", "new ad batch", "turn this
15
- script into ads", "multiply the winner", "we need more creatives",
16
- "generate ads from their footage/assets", "Meta ads for [client]", or the
17
- weekly ad digest names a winner to feed back. Reach for it even if the
18
- user never says "skill". Output is always the same contract: a Drive
19
- batch folder (videos + thumbnails + batch.json) that the n8n rail
20
- validates — this skill never touches the Meta API itself, and nothing it
21
- makes goes live without a human in Ads Manager.
4
+ The Install Agent Meta ads machine: the creative engine that turns a script,
5
+ a prompt/brief, OR a client's existing asset library into a batch of
6
+ human-realistic video ads, then hands the batch to the banked
7
+ `meta-video-ads-agent` n8n rail for paused publishing into the client's Meta
8
+ ad account. Two modes: BRIEF (script or prompt → new UGC-style / product
9
+ video ads via the connected media-generation MCP's ad workflows) and RECYCLE
10
+ (mine the client's Drive folder of past ads, raw footage and product photos:
11
+ variations of a winner, recuts of real footage, image-to-video from product
12
+ stills). Use this WHENEVER someone says "make ads for [client]", "new ad
13
+ batch", "turn this script into ads", "multiply the winner", "we need more
14
+ creatives", "Meta ads for [client]", or the weekly ad digest names a winner.
15
+ Output is a Drive batch folder (videos + thumbnails + batch.json) that the
16
+ n8n rail validates. Never touches the Meta API; nothing goes live without a
17
+ human in Ads Manager.
22
18
  ---
23
19
 
24
20
  # ad-machine — the Meta ads creative engine
@@ -1,22 +1,20 @@
1
1
  ---
2
2
  name: backtest-acceptance-gates
3
3
  description: >-
4
- Prove an automation actually works before a client is asked to trust it —
5
- and before we invoice against an acceptance gate. Covers reading the gate
6
- definition off the signed SOW rather than from memory, pinning down which
7
- metric the gate means when several plausible ones disagree by 18 points,
8
- reconstructing ground truth from a client's own historical behaviour
9
- (including the bimodal-signal problem, no-look-ahead scoring, and
10
- right-censoring), excluding contaminated events legitimately instead of
11
- conveniently, segmenting to tell a data gap from a logic gap, discovering
12
- that ground truth itself is only 79% complete, the evidence-record
13
- discipline that keeps a months-long build honest about which of its own
14
- numbers are void, and why a green test suite can mask the exact bug it was
15
- written to catch. Use this WHENEVER an engagement has an accuracy or
16
- acceptance criterion — "backtest it", "how accurate is it", "prove it works",
17
- "we need to hit the gate", "run it against history", "the client wants
18
- evidence", "is it ready for go-live" — or when an existing accuracy number
19
- needs re-checking.
4
+ Prove an automation works before a client is asked to trust it, and before
5
+ we invoice against an acceptance gate. Covers reading the gate definition
6
+ off the signed SOW rather than memory, pinning down which metric the gate
7
+ means when several plausible ones disagree by 18 points, reconstructing
8
+ ground truth from a client's own historical behaviour (the bimodal-signal
9
+ problem, no-look-ahead scoring, right-censoring), excluding contaminated
10
+ events legitimately instead of conveniently, segmenting to tell a data gap
11
+ from a logic gap, finding that ground truth itself is only 79% complete,
12
+ evidence-record discipline that tracks which of a build's numbers are void,
13
+ and why a green test suite can mask the exact bug it was written to catch.
14
+ Use this WHENEVER an engagement has an accuracy or acceptance criterion:
15
+ "backtest it", "how accurate is it", "prove it works", "we need to hit the
16
+ gate", "run it against history", "is it ready for go-live", or an existing
17
+ accuracy number needs re-checking.
20
18
  ---
21
19
 
22
20
  # Backtesting & acceptance gates
@@ -1,24 +1,20 @@
1
1
  ---
2
2
  name: client-latest
3
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
- (bulleted, by system), then one ranked table of what's wrong and what to
7
- do about it. Reads the build repo (CLIENT.md, docs/00-delivery-log.md,
8
- evidence/, onboarding.html, AGENT.md gotchas), the local git state
9
- (uncommitted, unpushed, open PRs, stray worktrees), the read-only
10
- `ia client` / `ia client-linear` commands, the calendar (the one date a
11
- repo cannot be trusted for), the client's Slack channel, and n8n run
12
- health via `ia agent executions`. Use this WHENEVER someone says "what's
13
- the latest on [client]", "catch me up on [client]", "where did we leave
14
- off", "resume the [client] build", "status of [client]", "what's blocked
15
- on [client]", "did anything drift", "am I missing anything before I
16
- start", or opens a `clients/client-[slug]/` repo cold. Reach for it even
17
- if the user never says "skill". The brief itself is a pure read; if the
18
- ranked table has anything in it, it then asks how you want to move
19
- forward (fix the drift, or start one of the ranked items) and acts on the
20
- answer — in the working tree only, never a commit, never a push. Not call
21
- prep: an upcoming client call goes to `tech-call-prep` instead.
4
+ Catch a technician up on one client engagement so they can resume the build:
5
+ a two-part terminal brief, where it stands now (by system), then one ranked
6
+ table of what is wrong and what to do about it. Reads the build repo
7
+ (CLIENT.md, docs/00-delivery-log.md, evidence/, onboarding.html, AGENT.md
8
+ gotchas), local git state (uncommitted, unpushed, open PRs, stray
9
+ worktrees), the read-only `ia client` / `ia client-linear` commands, the
10
+ calendar, the client's Slack channel, and n8n run health via `ia agent
11
+ executions`. Use this WHENEVER someone says "what's the latest on [client]",
12
+ "catch me up on [client]", "where did we leave off", "resume the [client]
13
+ build", "status of [client]", "what's blocked on [client]", "did anything
14
+ drift", or opens a `clients/client-[slug]/` repo cold. The brief is a pure
15
+ read; if the table has items it asks how to proceed and acts in the working
16
+ tree only, never a commit or push. Not call prep: an upcoming client call
17
+ goes to `tech-call-prep`.
22
18
  ---
23
19
 
24
20
  # client-latest — resume-the-build brief for one client
@@ -2,22 +2,19 @@
2
2
  name: email-triage-rollout
3
3
  description: >-
4
4
  Roll out an AI email-triage assistant into a client's live mailbox as a
5
- staged program instead of a one-shot deploy — soak (watch, write nothing),
6
- label-only, organize (noise leaves the inbox), then full (drafts). Covers the
7
- one thing that makes it a product rather than a build: the exit gate each
8
- stage must pass before the next one starts, with real numbers and a
9
- zero-tolerance list, so a technician cannot promote on a hunch. Also covers
10
- the week-1 soak report (the fixed table set that turns a week of observed
11
- mail into a taxonomy the client approves), what to say to the client at each
12
- promotion, the pause switch, and how each promotion lands as one CADENCE
13
- slice in the client's build repo. Use this WHENEVER an engagement involves
14
- email triage, inbox cleanup, auto-labeling, or mailbox organization — "set up
15
- their inbox", "triage their email", "the AI is labeling wrong", "can we turn
16
- on archiving yet", "week 1 of the email agent", "what stage are they on",
17
- "write the soak report", "is it safe to enable drafts" — or when deploying
18
- the `email-gmail-triage` or `email-outlook-triage` banked template. Reach for
19
- it even if the user never says "skill". It governs the ROLLOUT; each
20
- template's own `sop.md` in the agents/ bank carries the per-provider detail.
5
+ staged program, not a one-shot deploy: soak (watch, write nothing),
6
+ label-only, organize (noise leaves the inbox), then full (drafts). Covers
7
+ the exit gate each stage must pass before the next one starts, with real
8
+ numbers and a zero-tolerance list, so nobody promotes on a hunch; the week-1
9
+ soak report (the fixed tables that turn a week of mail into a
10
+ client-approved taxonomy); what to say to the client at each promotion; the
11
+ pause switch; and how each promotion lands as one CADENCE slice in the build
12
+ repo. Use this WHENEVER an engagement involves email triage, inbox cleanup,
13
+ auto-labeling, or mailbox organization: "the AI is labeling wrong", "can we
14
+ turn on archiving yet", "week 1 of the email agent", "write the soak
15
+ report", "is it safe to enable drafts", or when deploying the
16
+ `email-gmail-triage` / `email-outlook-triage` template. Governs the ROLLOUT;
17
+ each template's `sop.md` has the per-provider detail.
21
18
  ---
22
19
 
23
20
  # Email triage rollout
@@ -69,6 +66,15 @@ client.
69
66
  2. **Read that template's `sop.md`.** It is the authority for preconditions,
70
67
  the stage table, the gate numbers, and rollback. This skill is the shared
71
68
  method; the SOP is the provider-specific contract.
69
+
70
+ > **Before the first token (Gmail).** Publish the Google Cloud OAuth consent screen to
71
+ > **Production** before anyone signs in (APIs & Services → OAuth consent screen
72
+ > → Publish app). A consent screen left in *Testing* issues refresh tokens that
73
+ > expire after 7 days; the Gmail poll trigger then shows zero executions and no
74
+ > error — it looks exactly like a quiet inbox. Fix: publish the app, then open
75
+ > the credential in n8n and sign in again. `ia triage health <slug>` is the
76
+ > check. This hit 3 live workflows in 09-2026.
77
+
72
78
  3. **Set up the record before the first publish.** The classification record
73
79
  is the client portal's `triage_classifications` table — one row per
74
80
  message, sender domain only — written by the template's record branch
@@ -4,20 +4,17 @@ description: >-
4
4
  Turn a discovery call into the four engagement documents Install Agent
5
5
  writes at the start of every build (client-facing overview, internal tech
6
6
  spec, client-onboarding checklist, internal access-checklist tracker) AND
7
- the matching onboarding.html for that client's build repo — pulling the
8
- call itself via `ia client <slug>` rather than requiring a pasted
9
- transcript. Runs twice per engagement: once after the sales discovery call
10
- (first-pass fill, so a technician walks into the tech discovery call with
11
- real context already on screen) and again after the tech discovery call
12
- (update pass — fills remaining open questions, doesn't rewrite what's
13
- already accurate). Use this WHENEVER you've just had or read a
14
- discovery/scoping or tech-discovery call, or someone says "spec this out",
15
- "write the overview", "draft the tech spec", "what do we need from the
16
- client", "turn these call notes into a plan", "populate onboarding.html",
17
- "scaffold the client repo from the call", or you're populating the docs/
18
- folder inside a client-[slug]/ build folder. Reach for it even if the user
19
- never says "skill". Client-facing language stays tech-agnostic; internal
20
- docs name tools.
7
+ the matching onboarding.html for the client's build repo, pulling the call
8
+ via `ia client <slug>` rather than a pasted transcript. Runs twice per
9
+ engagement: after the sales discovery call (first-pass fill, so a technician
10
+ enters the tech call with real context) and after the tech discovery call
11
+ (update pass: fills open questions, keeps what is already accurate). Use
12
+ this WHENEVER you have just had or read a discovery/scoping or
13
+ tech-discovery call, or someone says "spec this out", "write the overview",
14
+ "draft the tech spec", "what do we need from the client", "turn these call
15
+ notes into a plan", "populate onboarding.html", or you are populating the
16
+ docs/ folder in a client-[slug]/ build folder. Client-facing language stays
17
+ tech-agnostic; internal docs name tools.
21
18
  ---
22
19
 
23
20
  # Discovery → engagement spec
@@ -220,6 +220,15 @@ scope:
220
220
  - **(repeat, paired)** `PLAIN_STEP`+`PLAIN_DETAIL` — same pipeline as the
221
221
  Client tab's architecture nodes, described without tool names.
222
222
  - **(repeat)** `PUBLIC_DONE_ITEM`, `PUBLIC_NEXT_ITEM`, `CLIENT_ASK`.
223
+ - **`portal-overview` JSON block** (the client portal's Onboarding tab):
224
+ not tokens you replace one by one — fill the whole JSON (`asOf`,
225
+ `summary` — one plain paragraph ≤ 280 chars that opens the page —,
226
+ `phases` done → now → next, `today`/`next`/`goal` ≤ 90 chars, `signIn`,
227
+ `progress` ≤ 40 rows), keeping the limits in the comment above it. The scaffold
228
+ studio fills it from the `OVERVIEW_*` placeholders; one bad value makes
229
+ the portal fall back to the raw section.
230
+ - **`#public-proposals` section**: every client-safe flow diagram goes
231
+ inside it — it is the client portal's Proposals tab.
223
232
 
224
233
  If a repeating section has more real items than the template's stub
225
234
  elements, duplicate the stub; if fewer, delete the extras. Never leave a