@installagent/sdk 0.4.1 → 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.
- package/dist/agent-mirror.js +22 -10
- package/dist/agent-templates.d.ts +10 -12
- package/dist/agent-templates.js +34 -6
- package/dist/doctor.d.ts +11 -1
- package/dist/doctor.js +24 -22
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/lefthook-hooks.d.ts +36 -0
- package/dist/lefthook-hooks.js +64 -0
- package/dist/n8n-defaults.d.ts +90 -0
- package/dist/n8n-defaults.js +153 -0
- package/dist/portal-admin.d.ts +104 -13
- package/dist/portal-admin.js +113 -28
- package/dist/pr-open.d.ts +45 -0
- package/dist/pr-open.js +98 -0
- package/dist/sync-repos.d.ts +8 -1
- package/dist/sync-repos.js +10 -9
- package/dist/triage-enable.js +20 -7
- package/package.json +1 -1
- package/templates/workspace-root/ONBOARDING.md +9 -7
- package/templates/workspace-root/skills/CLAUDE.md +4 -4
- package/templates/workspace-root/skills/README.md +2 -2
- package/templates/workspace-root/skills/ad-machine/SKILL.md +14 -18
- package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +14 -16
- package/templates/workspace-root/skills/client-latest/SKILL.md +14 -18
- package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +22 -16
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +11 -14
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +9 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +67 -19
- package/templates/workspace-root/skills/ia-cli/SKILL.md +14 -17
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +14 -20
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +2 -2
- package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +13 -15
- package/templates/workspace-root/skills/slack-voice/SKILL.md +50 -31
- package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +14 -15
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +13 -19
- package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +13 -15
package/dist/pr-open.js
ADDED
|
@@ -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
|
+
}
|
package/dist/sync-repos.d.ts
CHANGED
|
@@ -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
|
/**
|
package/dist/sync-repos.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
import { existsSync
|
|
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
|
-
|
|
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
|
}
|
package/dist/triage-enable.js
CHANGED
|
@@ -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-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
300
|
-
`ia portal create-
|
|
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-
|
|
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
|
@@ -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 —
|
|
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`
|
|
63
|
-
|
|
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.
|
|
71
|
-
`LINEAR_API_TOKEN` (Linear → Settings → Security & access)
|
|
72
|
-
`
|
|
73
|
-
|
|
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.
|
|
@@ -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
|
|
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
|
|
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
|
|
64
|
-
| Writing any
|
|
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` |
|
|
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` |
|
|
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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
`meta-video-ads-agent` n8n rail for paused publishing into the client's
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
that
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
6
|
-
label-only, organize (noise leaves the inbox), then full (drafts). Covers
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|