@installagent/sdk 0.1.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 (114) hide show
  1. package/dist/agent-mirror.d.ts +69 -0
  2. package/dist/agent-mirror.js +275 -0
  3. package/dist/agent-templates.d.ts +36 -2
  4. package/dist/agent-templates.js +173 -3
  5. package/dist/claude-hours.d.ts +118 -0
  6. package/dist/claude-hours.js +523 -0
  7. package/dist/client-drive.d.ts +3 -0
  8. package/dist/client-drive.js +2 -2
  9. package/dist/client-linear-create.d.ts +26 -0
  10. package/dist/client-linear-create.js +46 -0
  11. package/dist/client-linear.d.ts +28 -9
  12. package/dist/client-linear.js +36 -14
  13. package/dist/docs-search.d.ts +19 -6
  14. package/dist/docs-search.js +32 -11
  15. package/dist/doctor.d.ts +9 -0
  16. package/dist/doctor.js +126 -23
  17. package/dist/env-fill.d.ts +13 -0
  18. package/dist/env-fill.js +55 -13
  19. package/dist/env-push.d.ts +3 -0
  20. package/dist/env-push.js +11 -6
  21. package/dist/env-registry.d.ts +29 -0
  22. package/dist/env-registry.js +123 -9
  23. package/dist/exec.js +15 -2
  24. package/dist/git.d.ts +31 -0
  25. package/dist/git.js +59 -0
  26. package/dist/google-service-account.d.ts +20 -0
  27. package/dist/google-service-account.js +49 -0
  28. package/dist/hours-estimate.d.ts +43 -0
  29. package/dist/hours-estimate.js +159 -0
  30. package/dist/hours-export-schedule.d.ts +35 -0
  31. package/dist/hours-export-schedule.js +188 -0
  32. package/dist/hours-ledger.d.ts +129 -0
  33. package/dist/hours-ledger.js +882 -0
  34. package/dist/index.d.ts +25 -6
  35. package/dist/index.js +25 -6
  36. package/dist/linear-project.d.ts +2 -2
  37. package/dist/linear-project.js +2 -2
  38. package/dist/log.d.ts +28 -0
  39. package/dist/log.js +73 -0
  40. package/dist/n8n-executions.d.ts +85 -0
  41. package/dist/n8n-executions.js +259 -0
  42. package/dist/op-cli.d.ts +29 -0
  43. package/dist/op-cli.js +52 -0
  44. package/dist/platform.d.ts +35 -0
  45. package/dist/platform.js +39 -0
  46. package/dist/portal-admin.d.ts +108 -0
  47. package/dist/portal-admin.js +94 -1
  48. package/dist/standup.d.ts +88 -0
  49. package/dist/standup.js +235 -0
  50. package/dist/sync-repos.d.ts +54 -0
  51. package/dist/sync-repos.js +89 -0
  52. package/dist/template-sync.d.ts +11 -0
  53. package/dist/template-sync.js +16 -0
  54. package/dist/triage-backfill.d.ts +37 -0
  55. package/dist/triage-backfill.js +211 -0
  56. package/dist/triage-enable.d.ts +90 -0
  57. package/dist/triage-enable.js +428 -0
  58. package/dist/triage-gates.d.ts +252 -0
  59. package/dist/triage-gates.js +951 -0
  60. package/dist/wizard.d.ts +15 -0
  61. package/dist/wizard.js +35 -56
  62. package/dist/workspace-docs.d.ts +44 -0
  63. package/dist/workspace-docs.js +73 -0
  64. package/dist/workspace-push.d.ts +39 -0
  65. package/dist/workspace-push.js +78 -0
  66. package/dist/workspace-status.d.ts +37 -0
  67. package/dist/workspace-status.js +114 -0
  68. package/package.json +2 -2
  69. package/templates/env.example +37 -23
  70. package/templates/workspace-root/.claude/settings.json +12 -1
  71. package/templates/workspace-root/AGENT.md +7 -5
  72. package/templates/workspace-root/ONBOARDING.md +65 -8
  73. package/templates/workspace-root/skills/.github/workflows/pr-to-slack.yml +127 -0
  74. package/templates/workspace-root/skills/CLAUDE.md +29 -6
  75. package/templates/workspace-root/skills/README.md +171 -0
  76. package/templates/workspace-root/skills/ad-machine/SKILL.md +140 -0
  77. package/templates/workspace-root/skills/backtest-acceptance-gates/SKILL.md +293 -0
  78. package/templates/workspace-root/skills/backtest-acceptance-gates/backtest-acceptance-gates-guide.pdf +0 -0
  79. package/templates/workspace-root/skills/backtest-acceptance-gates/references/evidence-record-template.md +128 -0
  80. package/templates/workspace-root/skills/backtest-acceptance-gates/references/harness-checklist.md +90 -0
  81. package/templates/workspace-root/skills/client-deliverables/SKILL.md +1 -1
  82. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +3 -2
  83. package/templates/workspace-root/skills/client-latest/SKILL.md +343 -0
  84. package/templates/workspace-root/skills/client-latest/catchup.command.md +18 -0
  85. package/templates/workspace-root/skills/cloud-devops/SKILL.md +235 -0
  86. package/templates/workspace-root/skills/email-triage-rollout/SKILL.md +258 -0
  87. package/templates/workspace-root/skills/engagement-spec/SKILL.md +51 -18
  88. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +10 -4
  89. package/templates/workspace-root/skills/gcloud-cli-setup/SKILL.md +100 -0
  90. package/templates/workspace-root/skills/github-profile/SKILL.md +106 -0
  91. package/templates/workspace-root/skills/google-chat-app-setup/SKILL.md +136 -0
  92. package/templates/workspace-root/skills/google-chat-app-setup/google-chat-app-setup-guide.pdf +0 -0
  93. package/templates/workspace-root/skills/house-voice/SKILL.md +80 -4
  94. package/templates/workspace-root/skills/ia-cli/SKILL.md +49 -7
  95. package/templates/workspace-root/skills/init_repo/SKILL.md +188 -0
  96. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +59 -10
  97. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-deck-template.pptx +0 -0
  98. package/templates/workspace-root/skills/installagent-brand-kit/references/deck-guide.md +181 -0
  99. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck.py +652 -0
  100. package/templates/workspace-root/skills/installagent-brand-kit/scripts/deck_lint.py +201 -0
  101. package/templates/workspace-root/skills/installagent-brand-kit/scripts/logo_raster.py +102 -0
  102. package/templates/workspace-root/skills/installagent-brand-kit/scripts/make_deck_template.py +290 -0
  103. package/templates/workspace-root/skills/salesforce-api-snapshot/SKILL.md +379 -0
  104. package/templates/workspace-root/skills/salesforce-api-snapshot/references/schema-discovery-soql.md +153 -0
  105. package/templates/workspace-root/skills/salesforce-api-snapshot/references/snapshot-storage.md +122 -0
  106. package/templates/workspace-root/skills/salesforce-api-snapshot/salesforce-api-snapshot-guide.pdf +0 -0
  107. package/templates/workspace-root/skills/slack-voice/SKILL.md +158 -0
  108. package/templates/workspace-root/skills/sso-gated-client-app/SKILL.md +337 -0
  109. package/templates/workspace-root/skills/sso-gated-client-app/sso-gated-client-app-guide.pdf +0 -0
  110. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +146 -47
  111. package/templates/workspace-root/skills/vendor-feed-ingestion/SKILL.md +323 -0
  112. package/templates/workspace-root/skills/vendor-feed-ingestion/references/delivery-contract-template.md +110 -0
  113. package/templates/workspace-root/skills/vendor-feed-ingestion/references/feed-guards.md +134 -0
  114. package/templates/workspace-root/skills/vendor-feed-ingestion/vendor-feed-ingestion-guide.pdf +0 -0
@@ -2,7 +2,8 @@
2
2
  #
3
3
  # - `ia` commands load this automatically (vars already set in your shell win).
4
4
  # - Shell scripts in any repo can use it too: set -a; source ../.env; set +a
5
- # - Shared values come from 1Password: run `ia env fill` (needs `op signin`).
5
+ # - Shared values come from 1Password: run `ia env fill` (needs the op CLI
6
+ # authenticated via the 1Password app's CLI integration — `ia doctor` checks it).
6
7
  # Personal values (marked below) you fill by hand. NEVER commit this file
7
8
  # anywhere — the root is not a git repo, and no repo may ever contain it.
8
9
  # Only env.example (this placeholder layout, no values) is shareable.
@@ -16,8 +17,11 @@ LINEAR_API_TOKEN=
16
17
  # your personal Linear API key — Linear → Settings → Security & access
17
18
  LINEAR_CLIENT_TEAM_ID=
18
19
  # the fixed Linear client team's ID — filled by `ia env fill`
20
+ IA_DOCS_SEARCH_TOKEN=
21
+ # shared docs-search API bearer (never expires; preferred over the cookie below) — `ia env fill`
19
22
  IA_DOCS_SESSION=
20
- # team.installagent.com __Secure-authjs.session-token cookie (expires periodically)
23
+ # team.installagent.com __Secure-authjs.session-token cookie (expires periodically);
24
+ # only needed when IA_DOCS_SEARCH_TOKEN is unset
21
25
  IA_PORTAL_ADMIN_SECRET=
22
26
  # portal.installagent.com admin API bearer — filled by `ia env fill`
23
27
  AIRTABLE_API_TOKEN=
@@ -30,31 +34,41 @@ N8N_API_URL=
30
34
  # n8n API base INCLUDING /api/v1, e.g. https://n8n.installagent.com/api/v1
31
35
  N8N_API_KEY=
32
36
  # n8n → Settings → API — filled by `ia env fill`
37
+ HOURS_EXPORT_SECRET=
38
+ # lets `ia hours-export` send your file to the ledger keeper — filled by `ia env fill`
33
39
  GEMINI_API_KEY=
34
40
 
35
41
  # ── shared infra (n8n workflows, team-infra scripts) ─────────────────────────
36
- AIRTABLE_BASE_ID=
37
- AIRTABLE_CLIENTS_TABLE_ID=
38
- N8N_WEBHOOK_URL=
39
- N8N_WEBHOOK_SECRET=
40
- AGENT_INGEST_SECRET=
41
- CRON_SECRET=
42
+ SLACK_RELAY_SECRET=
43
+ # Agent Zero relay secret (x-relay-secret header) — filled by `ia env fill`
44
+ N8N_OAUTH_CALLBACK_URL=
45
+ # n8n OAuth redirect URL (paste into a provider's OAuth app) — filled by `ia env fill`
46
+ # AIRTABLE_BASE_ID=
47
+ # AIRTABLE_CLIENTS_TABLE_ID=
48
+ # N8N_WEBHOOK_URL=
49
+ # N8N_WEBHOOK_SECRET=
50
+ # AGENT_INGEST_SECRET=
51
+ # CRON_SECRET=
42
52
 
43
53
  # ── portal / team-web local dev (prod values live in Vercel, never here) ─────
44
- DATABASE_URL=
45
- DATABASE_USER=
46
- DATABASE_PASS=
47
- AUTH_SECRET=
48
- AUTH_GOOGLE_ID=
49
- AUTH_GOOGLE_SECRET=
50
- PORTAL_ADMIN_EMAILS=
54
+ # Commented out — granted case-by-case from the team-admin vault. If you
55
+ # have the grant, uncomment the line you need, then run `ia env fill --admin`.
56
+ # DATABASE_URL=
57
+ # DATABASE_USER=
58
+ # DATABASE_PASS=
59
+ # AUTH_SECRET=
60
+ # AUTH_GOOGLE_ID=
61
+ # AUTH_GOOGLE_SECRET=
62
+ # PORTAL_ADMIN_EMAILS=
51
63
 
52
64
  # ── payments (Stripe / Plaid) ────────────────────────────────────────────────
53
- STRIPE_SECRET_KEY=
54
- STRIPE_WEBHOOK_SECRET=
55
- STRIPE_WEBHOOK_URL=
56
- STRIPE_BASE_URL=
57
- PLAID_CLIENT_ID=
58
- PLAID_SECRET=
59
- PLAID_ACCESS_TOKEN=
60
- PLAID_BASE_URL=
65
+ # Commented out — granted case-by-case from the team-admin vault. If you
66
+ # have the grant, uncomment the line you need, then run `ia env fill --admin`.
67
+ # STRIPE_SECRET_KEY=
68
+ # STRIPE_WEBHOOK_SECRET=
69
+ # STRIPE_WEBHOOK_URL=
70
+ # STRIPE_BASE_URL=
71
+ # PLAID_CLIENT_ID=
72
+ # PLAID_SECRET=
73
+ # PLAID_ACCESS_TOKEN=
74
+ # PLAID_BASE_URL=
@@ -24,7 +24,18 @@
24
24
  "Bash(find * -type f*)",
25
25
  "Bash(pnpm test*)",
26
26
  "Bash(pnpm check*)",
27
- "Bash(pnpm type-check*)"
27
+ "Bash(pnpm type-check*)",
28
+ "Bash(pnpm --filter * test*)",
29
+ "Bash(pnpm vitest run *)",
30
+ "Bash(curl -s -o /dev/null -w *)",
31
+ "Bash(curl -s -w *)",
32
+ "Bash(set -a*)",
33
+ "Bash(set +a*)",
34
+ "Bash(export PATH=*google-cloud-sdk*)",
35
+ "mcp__claude-in-chrome__get_page_text",
36
+ "mcp__Claude_Browser__navigate",
37
+ "mcp__claude-in-chrome__navigate",
38
+ "mcp__claude-in-chrome__tabs_context_mcp"
28
39
  ],
29
40
  "deny": [
30
41
  "Read(.env)",
@@ -43,7 +43,7 @@ installagent/
43
43
  | Task | Go to | Read first |
44
44
  |---|---|---|
45
45
  | Understand who a client/lead is, prep a call | `team-clients/clients/<slug>/` | `team-clients/AGENT.md` |
46
- | Prep a tech discovery / scoping call (call sheet, proposals ready) | `clients/client-<slug>/` via the `tech-call-prep` skill | team hub → Techs → Discovery call |
46
+ | Prep a tech discovery / scoping call (call agenda, proposals ready) | `clients/client-<slug>/` via the `tech-call-prep` skill | team hub → Techs → Discovery call |
47
47
  | Build/edit anything *for* a client (spec, workflow, diagram, PDF, site, agent) | `clients/client-<slug>/` | that repo's `CADENCE.md` (how to ship it) + `AGENT.md` + `CLIENT.md` |
48
48
  | Ship a change into a client repo without causing drift (feature, fix, scope change) | `clients/client-<slug>/CADENCE.md` | it *is* the read — five stages + the surface matrix |
49
49
  | Answer "what did we ship for X / does it work?" | `clients/client-<slug>/docs/00-delivery-log.md` + `evidence/` | same |
@@ -150,7 +150,7 @@ repo; don't invent a per-client process.
150
150
  client-<slug>/
151
151
  ├── CADENCE.md # how work ships: five stages + the anti-drift surface matrix
152
152
  ├── CLIENT.md # context manifest → Airtable record, Drive folder, Linear project, registry profile, n8n tag, 1Password vault
153
- ├── onboarding.html # tabbed open-me-first page: Architecture / Client / Proposals / Public
153
+ ├── onboarding.html # open-me-first page, six sections: Overview / Architecture / Client / Workflows / Proposals / Public
154
154
  ├── docs/ # engagement-spec output + 00-delivery-log.md + diagrams as self-contained HTML
155
155
  ├── workflows/ # n8n JSON exports (credential IDs scrubbed)
156
156
  ├── data/ # client-sent raw data — gitignored (only its README is tracked)
@@ -166,14 +166,16 @@ no `legal/` (signed documents live in the client's Google Drive folder), no
166
166
  files (Airtable owns deal status). No `diagrams/` or `client-facing/` since
167
167
  2026-07: diagrams are HTML files in `docs/`; branded deliverables ship via
168
168
  the client's Drive folder, and the client-presentable view is the Public
169
- tab of `onboarding.html`.
169
+ section of `onboarding.html`.
170
170
 
171
171
  Skills that produce the deliverables: **`client-deliverables`** (orchestrator),
172
172
  **`engagement-spec`** (internal docs), **`client-facing-docs`** (branded PDFs),
173
173
  **`client-workflow-diagram`** (diagrams), **`installagent-brand-kit`** (brand —
174
- official logo + brand red `#9b0506`), **`contract-tech-agnostic`** (contracts
174
+ official logo + brand red `#d11a1a` on white, signal red `#ff2d2d` for
175
+ attention; also the client-deck builder and template),
176
+ **`contract-tech-agnostic`** (contracts
175
177
  by function and outcome, never tech), **`tech-call-prep`** (per-client call
176
- sheet before any client call), **`client-llm-setup`** (the client's own Claude
178
+ agenda before any client call), **`client-llm-setup`** (the client's own Claude
177
179
  workspace guide). All live in `skills/`. The engagement playbook the skills
178
180
  plug into — lifecycle, discovery-call script, LLM-setup runbook — lives on the
179
181
  team hub (`team-web/apps/docs` → Techs).
@@ -16,14 +16,25 @@ One command clones the whole environment (all team repos, an empty
16
16
  `clients/` with `client-template`, these root docs, and `skills/`):
17
17
 
18
18
  ```bash
19
- ia wizard ~/installagent # first-time setup (needs GitHub SSH access)
20
- ia wizard ~/installagent --update # later: pull every repo + refresh root docs/skills
19
+ ia wizard ~/installagent # first-time setup
20
+ ia sync ~/installagent # later: pull every repo, client repos included
21
+ ia sync ~/installagent --docs # ...and refresh root docs/skills/.env.example
21
22
  ```
22
23
 
23
- The `ia` CLI lives in `team-tools/` — for the very first run, clone that repo
24
- alone, `pnpm install && pnpm -r build`, and run `node apps/cli/dist/index.js
25
- wizard …` (or link it). `--update` is how everyone stays on the same
26
- environment: fast-forward-only pulls, root docs refreshed only where drifted.
24
+ `ia wizard` clones over **HTTPS**, so `gh auth login` (step 1 below) is all the
25
+ GitHub access you need — no SSH key to generate, no agent to configure. Pass
26
+ `--ssh` if you prefer SSH URLs.
27
+
28
+ Use `ia sync` day to day, not `ia wizard --update`: sync also pulls your
29
+ `clients/client-<slug>` repos, which the wizard never touched, and it leaves
30
+ your root docs alone unless you ask. Every pull is fast-forward only, so a repo
31
+ with local commits fails loudly instead of being merged over.
32
+
33
+ The `ia` CLI ships as a public npm package —
34
+ [`@installagent/cli`](https://www.npmjs.com/package/@installagent/cli):
35
+ `npm install -g @installagent/cli`, then `ia --version` to confirm.
36
+ `--update` is how everyone stays on the same environment: fast-forward-only
37
+ pulls, root docs refreshed only where drifted.
27
38
 
28
39
  The wizard ends with a **numbered next-steps list** — do those in order and
29
40
  you're set up. They boil down to:
@@ -31,15 +42,61 @@ you're set up. They boil down to:
31
42
  1. `gh auth login` — GitHub auth via one-time OAuth in the browser.
32
43
  **No personal access token, no admin-approval wait.** Every `ia` command
33
44
  that talks to GitHub uses the gh CLI's token automatically.
34
- 2. `op signin` — the 1Password CLI (`brew install 1password-cli` first if
35
- needed). Shared team secrets live in the **team-techs** vault.
45
+ 2. **1Password CLI** — `brew install 1password-cli` on macOS,
46
+ `winget install 1password-cli` on Windows. Before you sign in, open the
47
+ **1Password 8 desktop app → Settings → Developer** and tick
48
+ **"Integrate with 1Password CLI"** (Settings → Security → Touch ID or
49
+ Windows Hello unlock makes it seamless). You need **version 8** — the Mac
50
+ App Store still ships v7, which has no Developer tab. Then `op whoami`
51
+ should work in any terminal.
52
+ Do not skip this: `eval $(op signin)` puts the session in one shell only,
53
+ so `ia env fill` then reports `not-in-vault` in every other window — which
54
+ looks exactly like a missing vault grant.
55
+ **On Windows, run anything that touches `op` from PowerShell.** 1Password
56
+ supports PowerShell only, so the desktop-app integration cannot
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,
59
+ and that one grant is all a technician needs (`AIRTABLE_API_TOKEN`,
60
+ `GOOGLE_SERVICE_ACCOUNT_KEY`, `N8N_API_URL`, `N8N_API_KEY`,
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`.
36
64
  3. `ia env fill` — fills the empty vars in the root `.env` straight from
37
65
  1Password. No copy-pasting secrets, nothing goes through a chat window.
66
+ It only touches your own technician var set. The infra, portal and
67
+ payments vars ship commented out in `.env.example` and are reported as a
68
+ count, not by name — if you actually need one, ask, then
69
+ `ia env fill --admin`.
38
70
  4. Two personal values you set by hand in `.env`: your own
39
71
  `LINEAR_API_TOKEN` (Linear → Settings → Security & access) and
40
72
  `IA_DOCS_SESSION` (session cookie from a logged-in team.installagent.com
41
73
  tab).
42
74
  5. `ia doctor -w ~/installagent` — repeat until everything required is green.
75
+ It prints only what still needs doing; `ia doctor --all` shows every check,
76
+ passing ones included.
77
+
78
+ ## On Windows
79
+
80
+ Everything works on native Windows, with three things worth knowing up front.
81
+ Run your terminal as **PowerShell** (Windows Terminal's default profile is
82
+ fine) rather than Git Bash.
83
+
84
+ 1. **`op` does not work in Git Bash.** 1Password documents PowerShell as its
85
+ only supported Windows shell, so the desktop-app integration cannot
86
+ authenticate the CLI from an MSYS shell. `op` will look installed and still
87
+ fail. Run `ia env fill` (and anything else touching `op`) in PowerShell.
88
+ `ia doctor` detects Git Bash and says so instead of printing macOS advice.
89
+ 2. **Prerequisites:** Node 20+, `pnpm`, `git`, and the GitHub CLI
90
+ (`winget install GitHub.cli`). `npm install -g @installagent/cli` gets you
91
+ `ia` itself.
92
+ 3. **git hooks are per-clone.** Inside each client repo you clone, run
93
+ `npx lefthook install` once — client repos carry no `package.json`, so
94
+ there is no local lefthook to call. Without it the repo-lint pre-commit
95
+ gate silently never runs. `ia doctor` warns when a cloned client repo is
96
+ missing it.
97
+
98
+ If something prints advice that is wrong for Windows, that is a bug in the
99
+ CLI — say so, don't work around it quietly.
43
100
 
44
101
  The root `.env` is the ONE env file for the whole workspace: every `ia`
45
102
  command auto-loads it, and shell scripts can `set -a; source .env; set +a`.
@@ -0,0 +1,127 @@
1
+ name: PR → Slack (approve / close)
2
+
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
5
+ # handled by @Agent Zero itself — team-tools/apps/slack-agent, Bolt Socket
6
+ # Mode, the `pr_merge`/`pr_close` action handlers in src/app.ts — which
7
+ # squash-merges (or closes) via the GitHub API using its own write-scoped
8
+ # token. Only an authorized Install Agent team member's click is honored
9
+ # (same permission check the bot uses everywhere else). The button's `value`
10
+ # carries the owner/repo + PR number as JSON, so this workflow stays
11
+ # repo-agnostic — no regex over the posted message, no per-repo config.
12
+ #
13
+ # Required secrets (both ORGANIZATION secrets, visibility "all repositories",
14
+ # set once so every current and future repo is covered with no per-repo
15
+ # setup — a repo-level secret of the same name also works and takes
16
+ # precedence):
17
+ # SLACK_PR_BOT_TOKEN — @Agent Zero's Slack bot token (xoxb-), needs the
18
+ # chat:write scope. Same token value as the
19
+ # slack-agent deploy's SLACK_BOT_TOKEN
20
+ # (team-infra/agent-hosting) — Agent Zero's Socket
21
+ # Mode connection is what receives the button
22
+ # clicks, so the posting identity and the
23
+ # interactivity receiver have to be the same app.
24
+ # SLACK_PR_CHANNEL_ID — the Slack channel ID (#notify-prs) to post into.
25
+ #
26
+ # If either secret is absent the job logs a notice and exits green, so this
27
+ # file is safe to land in a repo before the secrets exist.
28
+
29
+ on:
30
+ pull_request:
31
+ types: [opened, reopened, ready_for_review]
32
+
33
+ permissions:
34
+ contents: read
35
+ pull-requests: read
36
+
37
+ jobs:
38
+ notify:
39
+ # Drafts are not ready to review, and skipping them also stops the
40
+ # duplicate post a draft would otherwise make on opened + ready_for_review.
41
+ if: github.event.pull_request.draft == false
42
+ runs-on: ubuntu-latest
43
+ steps:
44
+ - name: Post PR to Slack with action buttons
45
+ env:
46
+ SLACK_BOT_TOKEN: ${{ secrets.SLACK_PR_BOT_TOKEN }}
47
+ SLACK_CHANNEL_ID: ${{ secrets.SLACK_PR_CHANNEL_ID }}
48
+ PR_REPO: ${{ github.event.repository.name }}
49
+ PR_REPO_FULL: ${{ github.event.repository.full_name }}
50
+ PR_NUMBER: ${{ github.event.pull_request.number }}
51
+ PR_TITLE: ${{ github.event.pull_request.title }}
52
+ PR_URL: ${{ github.event.pull_request.html_url }}
53
+ PR_AUTHOR: ${{ github.event.pull_request.user.login }}
54
+ PR_BASE: ${{ github.event.pull_request.base.ref }}
55
+ PR_HEAD: ${{ github.event.pull_request.head.ref }}
56
+ PR_ADDITIONS: ${{ github.event.pull_request.additions }}
57
+ PR_DELETIONS: ${{ github.event.pull_request.deletions }}
58
+ PR_CHANGED: ${{ github.event.pull_request.changed_files }}
59
+ run: |
60
+ set -euo pipefail
61
+ if [ -z "${SLACK_BOT_TOKEN:-}" ] || [ -z "${SLACK_CHANNEL_ID:-}" ]; then
62
+ echo "::notice::SLACK_PR_BOT_TOKEN / SLACK_PR_CHANNEL_ID not set (org or repo secret) — skipping the Slack post."
63
+ exit 0
64
+ fi
65
+ # Build the Block Kit payload with jq so PR titles/branches that
66
+ # contain quotes or other JSON-breaking characters are escaped
67
+ # safely. Each button's value is itself a JSON object
68
+ # ({"repo":"owner/repo","pr":N}) — Agent Zero parses that directly,
69
+ # so it never has to regex the rendered Slack message to figure out
70
+ # which PR a click was for.
71
+ payload=$(jq -n \
72
+ --arg channel "$SLACK_CHANNEL_ID" \
73
+ --arg repo "$PR_REPO" \
74
+ --arg repoFull "$PR_REPO_FULL" \
75
+ --arg num "$PR_NUMBER" \
76
+ --arg title "$PR_TITLE" \
77
+ --arg url "$PR_URL" \
78
+ --arg author "$PR_AUTHOR" \
79
+ --arg base "$PR_BASE" \
80
+ --arg head "$PR_HEAD" \
81
+ --arg stats "+$PR_ADDITIONS / -$PR_DELETIONS · $PR_CHANGED files" \
82
+ '{
83
+ channel: $channel,
84
+ text: ("New PR in " + $repo + " #" + $num + ": " + $title),
85
+ blocks: [
86
+ { type: "header",
87
+ text: { type: "plain_text", text: ("🔀 " + $repo + " · PR #" + $num) } },
88
+ { type: "section",
89
+ text: { type: "mrkdwn",
90
+ text: ( "*<" + $url + "|" + $title + ">*\n"
91
+ + "by `" + $author + "` • `" + $head + "` → `" + $base + "`\n"
92
+ + $stats ) } },
93
+ { type: "actions",
94
+ block_id: ("pr_" + $num),
95
+ elements: [
96
+ { type: "button", style: "primary", action_id: "pr_merge",
97
+ text: { type: "plain_text", text: "✅ Merge" },
98
+ value: ({ repo: $repoFull, pr: ($num | tonumber) } | tojson),
99
+ confirm: {
100
+ title: { type: "plain_text", text: "Merge this PR?" },
101
+ text: { type: "mrkdwn", text: ("Squash-merge *" + $repo + "* PR #" + $num + " into `" + $base + "` and delete `" + $head + "`.") },
102
+ confirm: { type: "plain_text", text: "Merge" },
103
+ deny: { type: "plain_text", text: "Cancel" } } },
104
+ { type: "button", style: "danger", action_id: "pr_close",
105
+ text: { type: "plain_text", text: "🗑️ Close" },
106
+ value: ({ repo: $repoFull, pr: ($num | tonumber) } | tojson),
107
+ confirm: {
108
+ title: { type: "plain_text", text: "Close this PR?" },
109
+ text: { type: "mrkdwn", text: ("Close *" + $repo + "* PR #" + $num + " without merging.") },
110
+ confirm: { type: "plain_text", text: "Close" },
111
+ deny: { type: "plain_text", text: "Cancel" } } }
112
+ ] }
113
+ ]
114
+ }')
115
+ # chat.postMessage returns HTTP 200 even on a logical failure (e.g.
116
+ # a channel Agent Zero isn't in), so the outcome is read from the
117
+ # response body's `ok` field, not the HTTP status.
118
+ response=$(curl -sS -X POST \
119
+ -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
120
+ -H 'Content-type: application/json; charset=utf-8' \
121
+ --data "$payload" \
122
+ https://slack.com/api/chat.postMessage)
123
+ ok=$(echo "$response" | jq -r '.ok')
124
+ if [ "$ok" != "true" ]; then
125
+ echo "::error::Slack rejected the post: $response"
126
+ exit 1
127
+ fi
@@ -13,18 +13,30 @@ so Claude Code / Cowork auto-register them in the skill menu.
13
13
 
14
14
  ```
15
15
  skills/
16
+ ├── client-latest/ # resume-the-build brief for one client (state + risks/drift, then a next-step CTA)
16
17
  ├── client-deliverables/ # ORCHESTRATOR — the full client engagement package, checklist + sequencing
17
18
  ├── engagement-spec/ # discovery call → overview + tech-spec + onboarding docs
18
- ├── tech-call-prep/ # pre-call prep check + per-client call sheet (docs/05-call-sheet.md)
19
+ ├── tech-call-prep/ # pre-call prep check + per-client call agenda (docs/05-call-agenda.md + Drive copy)
19
20
  ├── client-llm-setup/ # the client's own Claude workspace → branded leave-behind guide
20
21
  ├── client-facing-docs/ # the branded client PDFs (exec overview, proposal/SOW, onboarding)
21
22
  ├── client-workflow-diagram/ # spec → Excalidraw stage-column diagram
22
- ├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw (logo + brand red #9b0506)
23
+ ├── google-chat-app-setup/ # deploy a Google Chat app (n8n-backed) in a client's Workspace, domain-wide
24
+ ├── salesforce-api-snapshot/ # read a client's Salesforce/managed-package org → schema spike + cached JSON snapshot
25
+ ├── sso-gated-client-app/ # a client-facing internal app behind their Google Workspace SSO (Next.js + Vercel)
26
+ ├── vendor-feed-ingestion/ # recurring vendor feeds (SFTP/email → S3 → n8n) + the guards that refuse a bad file
27
+ ├── email-triage-rollout/ # AI inbox triage into a live mailbox: staged soak → label → organize → full + the gate per stage
28
+ ├── ad-machine/ # Meta ads creative engine: brief or client asset library → ad batch for the banked paused-publish rail
29
+ ├── backtest-acceptance-gates/ # prove an automation works before the client trusts it (ground truth, evidence, gates)
30
+ ├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw/decks (logo + brand red #d11a1a)
23
31
  ├── design-system/ # the Install Agent Design System (screens/UI)
24
32
  ├── house-voice/ # house voice for client-facing writing, pulled from installagent.com/get-started
25
33
  ├── contract-tech-agnostic/ # contracts/SOWs by FUNCTION and OUTCOME, never tech (+ SOW template in references/)
26
34
  ├── linear/ # Linear issue workflow for client build work (status discipline, sub-issue trees, PR linking)
27
- └── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails
35
+ ├── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails
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)
38
+ ├── github-profile/ # force gh CLI + git commits onto the noahm-ia account before any GitHub action
39
+ └── init_repo/ # explicit-only /init_repo — dev branch + default branch + one milestone/root-branch per leaf issue
28
40
  ```
29
41
 
30
42
  Each is `skills/<name>/SKILL.md`, with bulky tables in `references/`.
@@ -36,20 +48,31 @@ Each is `skills/<name>/SKILL.md`, with bulky tables in `references/`.
36
48
  | Kicking off / assembling a full client deliverable package | `client-deliverables` |
37
49
  | Writing up a discovery/scoping call into build docs | `engagement-spec` |
38
50
  | Prepping for an upcoming client call (sheet + readiness check) | `tech-call-prep` |
51
+ | Catching up on a client / resuming a build / checking for drift | `client-latest` |
39
52
  | Setting up a client's own Claude workspace / its leave-behind guide | `client-llm-setup` |
40
53
  | Producing the branded client PDFs | `client-facing-docs` |
41
54
  | Drawing a workflow/architecture diagram for a client | `client-workflow-diagram` |
42
- | Branding a print/PDF/Excalidraw deliverable | `installagent-brand-kit` |
55
+ | Rolling an email-triage agent into a client's live mailbox | `email-triage-rollout` |
56
+ | Deploying a Google Chat app (n8n-backed) in a client's Workspace | `google-chat-app-setup` |
57
+ | Reading a client's Salesforce (or any vendor CRM/EHR) into something we build | `salesforce-api-snapshot` |
58
+ | Building a screen the client's staff log into (dashboard, map, worklist) | `sso-gated-client-app` |
59
+ | Setting up a recurring vendor data feed, or debugging one that went wrong | `vendor-feed-ingestion` |
60
+ | Proving accuracy / hitting an acceptance gate / writing up a validation run | `backtest-acceptance-gates` |
61
+ | Branding a print/PDF/Excalidraw deliverable, or building a client deck | `installagent-brand-kit` |
43
62
  | Building or reviewing any UI / web page / funnel / component | `design-system` |
44
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` |
45
65
  | Drafting/reviewing any contract, SOW, MSA, or proposal | `contract-tech-agnostic` |
46
66
  | Working an `INS-xxx` issue / a client's Linear project | `linear` |
47
67
  | Any task an `ia` command covers (client context, intake, agent bank, secrets, setup/doctor) | `ia-cli` |
68
+ | Setting up or switching gcloud CLI accounts/configurations | `gcloud-cli-setup` |
69
+ | Any `gh` command, git push/PR, or GitHub API call | `github-profile` |
70
+ | User explicitly runs `/init_repo` (dev branch + milestones + root branches on an existing client repo) | `init_repo` |
48
71
 
49
72
  `design-system` is the **screen** layer (dark, signal-red, Hanken Grotesk); it
50
73
  mirrors the code source of truth `team-web/packages/ui`.
51
- `installagent-brand-kit` is the **print/deliverable** layer for PDFs and
52
- Excalidraw on white. They share one brand and must agree. `house-voice` is
74
+ `installagent-brand-kit` is the **print/deliverable** layer for PDFs,
75
+ Excalidraw and decks on white. They share one brand and must agree. `house-voice` is
53
76
  the **words** layer that applies across both — what client-facing sentences
54
77
  sound like, regardless of surface.
55
78
 
@@ -0,0 +1,171 @@
1
+ # Install Agent skills
2
+
3
+ Twenty-five reusable, cross-repo how-tos that any coding agent in the workspace
4
+ loads when a task matches the skill's `description`. They encode the parts of
5
+ our delivery process that are easy to get wrong and expensive to rediscover —
6
+ the SOW clause we always forget, the Excalidraw JSON that has to be valid, the
7
+ four ways an SSO-gated app can look fine while being wide open.
8
+
9
+ This directory is its own git repo ([`InstallAgent/skills`](https://github.com/InstallAgent/skills)),
10
+ mounted at the workspace root because a single client engagement touches docs,
11
+ workflows, and diagrams across more than one repo. Repo-local skills live in
12
+ `team-clients/skills/` and `team-infra/skills/` instead.
13
+
14
+ > Working here as an agent? Read [`CLAUDE.md`](./CLAUDE.md) — it's the rule
15
+ > set. This README is the map.
16
+
17
+ ## How these get loaded
18
+
19
+ Every skill is `<name>/SKILL.md` with YAML frontmatter (`name`, `description`).
20
+ 23 of them are symlinked into [`../.claude/skills/`](../.claude/skills/), so Claude
21
+ Code and Cowork register them automatically — they appear in the skill menu and
22
+ fire on their own without being invoked by name. The `description` is the
23
+ trigger; the body is only read once the skill fires.
24
+
25
+ Nothing has to be run or installed. Adding a skill means adding a directory and
26
+ a symlink (see [Adding a skill](#adding-a-skill)).
27
+
28
+ ## The engagement lifecycle
29
+
30
+ Most of these skills are stops along one path — a lead becomes a signed
31
+ engagement becomes a working build. In rough order:
32
+
33
+ | Stage | Skill | What it produces |
34
+ |---|---|---|
35
+ | 0. Landing cold / resuming | [`client-latest`](./client-latest/) | A terminal brief — where the build stands, then risks + surface drift — then a four-option next-step prompt |
36
+ | 1. Before the call | [`tech-call-prep`](./tech-call-prep/) | Readiness check + `docs/05-call-agenda.md` and a Drive copy |
37
+ | 2. After the call | [`engagement-spec`](./engagement-spec/) | Client overview, internal tech spec, onboarding + access checklists, `onboarding.html` |
38
+ | 3. Package it | [`client-deliverables`](./client-deliverables/) | **Orchestrator** — sequences 4, 5, and the diagram into the full engagement set |
39
+ | ↳ | [`client-facing-docs`](./client-facing-docs/) | The three branded PDFs: exec overview, proposal/SOW, onboarding checklist |
40
+ | ↳ | [`contract-tech-agnostic`](./contract-tech-agnostic/) | SOW/MSA language by function and outcome, never by tool |
41
+ | ↳ | [`client-workflow-diagram`](./client-workflow-diagram/) | Stage-column `.excalidraw` + exported image |
42
+ | 4. Week 1 | [`client-llm-setup`](./client-llm-setup/) | The client's own Claude workspace + branded leave-behind guide |
43
+ | 5. Build | the integration skills below | The automation itself |
44
+ | 6. Track | [`linear`](./linear/) | `INS-xxx` status discipline, sub-issue trees, PR linking |
45
+ | 7. Prove it | [`backtest-acceptance-gates`](./backtest-acceptance-gates/) | Ground truth, evidence record, a defensible accuracy number |
46
+
47
+ ### Integration / build skills
48
+
49
+ Reach for these when the build touches a specific system. They're independent
50
+ of each other, except that a Salesforce read usually feeds one of the other two.
51
+
52
+ | Skill | Use when |
53
+ |---|---|
54
+ | [`vendor-feed-ingestion`](./vendor-feed-ingestion/) | A recurring vendor file lands (SFTP/email → S3 → n8n), or one went wrong |
55
+ | [`email-triage-rollout`](./email-triage-rollout/) | An AI triage agent goes into a client's live mailbox — the staged soak → label → organize → full program and its gates |
56
+ | [`ad-machine`](./ad-machine/) | A client needs a Meta video-ad batch — script/brief or their existing asset library → approved creatives + `batch.json`, handed to the banked `meta-video-ads-agent` paused-publish rail |
57
+ | [`salesforce-api-snapshot`](./salesforce-api-snapshot/) | Reading a client's Salesforce or managed-package org (Lumary, Vlocity, nCino) |
58
+ | [`sso-gated-client-app`](./sso-gated-client-app/) | Building a screen the client's staff log into — dashboard, map, worklist |
59
+ | [`google-chat-app-setup`](./google-chat-app-setup/) | Deploying an n8n-backed Chat app across a client's Workspace domain |
60
+
61
+ ### The three house-style layers
62
+
63
+ These are always-on constraints rather than lifecycle stages. They share one
64
+ brand and must agree with each other.
65
+
66
+ | Layer | Skill | Governs |
67
+ |---|---|---|
68
+ | **Screens** | [`design-system`](./design-system/) | Any UI, page, funnel, component. Dark, signal red, Hanken Grotesk. Mirrors `team-web/packages/ui`. |
69
+ | **Print** | [`installagent-brand-kit`](./installagent-brand-kit/) | PDFs, Excalidraw, decks — on white, brand red `#d11a1a`. Ships `scripts/brand.py`, `deck.py`, `deck_lint.py`. |
70
+ | **Words** | [`house-voice`](./house-voice/) | Every client-facing sentence, on any surface. Pulled verbatim from installagent.com. |
71
+
72
+ ### Internal ops
73
+
74
+ [`ia-cli`](./ia-cli/) — the decision map from task to `ia` command (client
75
+ context, intake, agent bank, secrets, `wizard`/`doctor`). Check it before
76
+ writing any custom script against GitHub, Airtable, Linear, Drive, n8n, or the
77
+ portal.
78
+
79
+ [`github-profile`](./github-profile/) — force gh CLI + git commits onto the
80
+ `noahm-ia` account before any GitHub action on this machine (two accounts are
81
+ logged in; only one is the work identity).
82
+
83
+ [`init_repo`](./init_repo/) — **explicit-invocation only**, never fires on
84
+ its own. Run `/init_repo` against an existing `client-<slug>` repo to create
85
+ a `dev` branch, set it as the GitHub default, and lay down one GitHub
86
+ milestone + one root branch per Linear main issue that will need a commit
87
+ (sub-issues fold into that milestone's checklist, never their own
88
+ milestone). Doesn't touch issue-level branches or GitHub issues — those
89
+ stay manual.
90
+
91
+ ## How they compose
92
+
93
+ Arrows point from a skill to the ones it defers to. `client-deliverables` is
94
+ the only true orchestrator; the rest cross-reference for a specific slice.
95
+
96
+ ```
97
+ client-deliverables ──┬─→ engagement-spec ──┬─→ client-workflow-diagram
98
+ │ ├─→ contract-tech-agnostic
99
+ │ └─→ ia-cli
100
+ ├─→ client-facing-docs
101
+ ├─→ contract-tech-agnostic
102
+ ├─→ client-workflow-diagram
103
+ └─→ installagent-brand-kit
104
+
105
+ tech-call-prep ───────→ engagement-spec
106
+ client-llm-setup ─────→ client-facing-docs, installagent-brand-kit
107
+ salesforce-api-snapshot → sso-gated-client-app, vendor-feed-ingestion
108
+ email-triage-rollout ─→ agents/ bank sop.md (per-provider), linear, house-voice
109
+ house-voice ──────────→ (applies across all client-facing output)
110
+ design-system ────────→ installagent-brand-kit (shared brand source)
111
+ ```
112
+
113
+ Also cross-referenced from here but living elsewhere: `business-research`
114
+ (team-clients) and `n8n-workflow` + `automation-design` (team-infra).
115
+
116
+ ## What's in each directory
117
+
118
+ `SKILL.md` is the whole skill; `references/` holds tables and templates too
119
+ bulky for the body; `scripts/` and `assets/` are only in the brand kit. A few
120
+ skills also ship a rendered PDF guide for handing to a technician.
121
+
122
+ | Skill | SKILL.md | Also ships |
123
+ |---|---:|---|
124
+ | `backtest-acceptance-gates` | 293 | `references/` evidence-record template, harness checklist · PDF guide |
125
+ | `client-deliverables` | 131 | `references/package-layout.md` |
126
+ | `client-latest` | 301 | `catchup.command.md` (the `/catchup` command) |
127
+ | `cloud-devops` | 235 | — · **orphan — adopt or delete (pending decision)**, not symlinked |
128
+ | `client-facing-docs` | 131 | `references/doc-structures.md` |
129
+ | `client-llm-setup` | 97 | `references/guide-template.md` |
130
+ | `client-workflow-diagram` | 141 | `references/excalidraw-format.md` |
131
+ | `contract-tech-agnostic` | 99 | `references/Install_Agent_SOW_Template.docx` |
132
+ | `design-system` | 118 | `references/tokens.md` |
133
+ | `email-triage-rollout` | 181 | — |
134
+ | `engagement-spec` | 272 | `references/spec-templates.md` |
135
+ | `gcloud-cli-setup` | 100 | — |
136
+ | `github-profile` | 56 | — |
137
+ | `google-chat-app-setup` | 136 | PDF guide |
138
+ | `house-voice` | 228 | `references/source-copy.md` |
139
+ | `ia-cli` | 87 | — |
140
+ | `init_repo` | 188 | — |
141
+ | `installagent-brand-kit` | 161 | 4 `references/`, 5 `scripts/` (brand, deck, deck_lint, logo_raster, make_deck_template), logo SVGs + deck template |
142
+ | `linear` | 186 | — |
143
+ | `salesforce-api-snapshot` | 379 | `references/` schema-discovery SOQL, snapshot storage · PDF guide |
144
+ | `slack-voice` | 158 | — |
145
+ | `sso-gated-client-app` | 337 | PDF guide |
146
+ | `tech-call-prep` | 240 | — |
147
+ | `vendor-feed-ingestion` | 323 | `references/` delivery contract, feed guards · PDF guide |
148
+
149
+ ## Conventions
150
+
151
+ Full rules in [`CLAUDE.md`](./CLAUDE.md). The short version:
152
+
153
+ - One skill per directory, `SKILL.md` under ~500 lines — push long tables into
154
+ `references/`.
155
+ - The `description` carries every "when to use" cue, stated concretely. That's
156
+ what makes the skill fire; the body never gets read otherwise.
157
+ - Nothing sensitive: no secrets, live credentials, internal hostnames, account
158
+ ids, or PII. Use placeholders and point at internal files.
159
+ - If a skill conflicts with [`../AGENT.md`](../AGENT.md), **AGENT.md wins** —
160
+ fix the skill in the same change.
161
+
162
+ ## Adding a skill
163
+
164
+ ```bash
165
+ mkdir -p skills/<name>/references
166
+ $EDITOR skills/<name>/SKILL.md # frontmatter: name, description
167
+ cd .claude/skills && ln -s ../../skills/<name> <name>
168
+ ```
169
+
170
+ Then add a row to the right table above and to the tree in `CLAUDE.md`. Skills
171
+ are how-tos — workspace-wide *rules* belong in `AGENT.md` instead.