@installagent/sdk 0.1.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 (94) hide show
  1. package/dist/agent-templates.d.ts +90 -0
  2. package/dist/agent-templates.js +211 -0
  3. package/dist/client-build.d.ts +50 -0
  4. package/dist/client-build.js +155 -0
  5. package/dist/client-context.d.ts +40 -0
  6. package/dist/client-context.js +70 -0
  7. package/dist/client-drive.d.ts +67 -0
  8. package/dist/client-drive.js +278 -0
  9. package/dist/client-intake.d.ts +68 -0
  10. package/dist/client-intake.js +189 -0
  11. package/dist/client-linear.d.ts +30 -0
  12. package/dist/client-linear.js +85 -0
  13. package/dist/docs-search.d.ts +44 -0
  14. package/dist/docs-search.js +187 -0
  15. package/dist/doctor.d.ts +43 -0
  16. package/dist/doctor.js +425 -0
  17. package/dist/env-file.d.ts +25 -0
  18. package/dist/env-file.js +69 -0
  19. package/dist/env-fill.d.ts +43 -0
  20. package/dist/env-fill.js +161 -0
  21. package/dist/env-push.d.ts +37 -0
  22. package/dist/env-push.js +137 -0
  23. package/dist/env-registry.d.ts +49 -0
  24. package/dist/env-registry.js +230 -0
  25. package/dist/exec.d.ts +14 -0
  26. package/dist/exec.js +16 -0
  27. package/dist/fathom-webhook.d.ts +44 -0
  28. package/dist/fathom-webhook.js +123 -0
  29. package/dist/fs-utils.d.ts +9 -0
  30. package/dist/fs-utils.js +34 -0
  31. package/dist/gcp-service-account-key.d.ts +37 -0
  32. package/dist/gcp-service-account-key.js +66 -0
  33. package/dist/gemini-api-key.d.ts +47 -0
  34. package/dist/gemini-api-key.js +132 -0
  35. package/dist/git.d.ts +16 -0
  36. package/dist/git.js +29 -0
  37. package/dist/github-token.d.ts +24 -0
  38. package/dist/github-token.js +30 -0
  39. package/dist/index.d.ts +25 -0
  40. package/dist/index.js +28 -0
  41. package/dist/init.d.ts +47 -0
  42. package/dist/init.js +101 -0
  43. package/dist/linear-project.d.ts +81 -0
  44. package/dist/linear-project.js +192 -0
  45. package/dist/new-client.d.ts +32 -0
  46. package/dist/new-client.js +89 -0
  47. package/dist/ping.d.ts +6 -0
  48. package/dist/ping.js +7 -0
  49. package/dist/portal-admin.d.ts +133 -0
  50. package/dist/portal-admin.js +144 -0
  51. package/dist/sync-templates.d.ts +58 -0
  52. package/dist/sync-templates.js +109 -0
  53. package/dist/template-sync.d.ts +55 -0
  54. package/dist/template-sync.js +90 -0
  55. package/dist/templates.d.ts +19 -0
  56. package/dist/templates.js +24 -0
  57. package/dist/wizard.d.ts +78 -0
  58. package/dist/wizard.js +213 -0
  59. package/package.json +30 -0
  60. package/templates/env.example +60 -0
  61. package/templates/workspace-root/.claude/settings.json +39 -0
  62. package/templates/workspace-root/AGENT.md +205 -0
  63. package/templates/workspace-root/AGENTS.md +11 -0
  64. package/templates/workspace-root/CLAUDE.md +63 -0
  65. package/templates/workspace-root/GEMINI.md +24 -0
  66. package/templates/workspace-root/ONBOARDING.md +164 -0
  67. package/templates/workspace-root/README.md +67 -0
  68. package/templates/workspace-root/skills/CLAUDE.md +79 -0
  69. package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
  70. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
  71. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
  72. package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
  73. package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
  74. package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
  75. package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
  76. package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
  77. package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
  78. package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
  79. package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
  80. package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
  81. package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
  82. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
  83. package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
  84. package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
  85. package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
  86. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
  87. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
  88. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
  89. package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
  90. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
  91. package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
  92. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
  93. package/templates/workspace-root/skills/linear/SKILL.md +186 -0
  94. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
@@ -0,0 +1,78 @@
1
+ import { type DoctorResult } from "./doctor.js";
2
+ import type { ExecFileFn } from "./exec.js";
3
+ import { type CloneFn, type PullFn } from "./git.js";
4
+ import { type McpRecommendation } from "./init.js";
5
+ /**
6
+ * The full team repo set a technician's workspace mirrors — everything at the
7
+ * installagent/ root that lives on GitHub. client-<slug> build repos are
8
+ * deliberately excluded: technicians clone only the client(s) they work on.
9
+ */
10
+ export declare const WIZARD_REPO_NAMES: readonly ["team-clients", "team-tools", "team-infra", "team-web", "team-design", "agents"];
11
+ export interface WizardStep {
12
+ name: string;
13
+ status: "created" | "updated" | "skipped" | "failed";
14
+ detail: string;
15
+ }
16
+ export interface WizardWorkspaceOptions {
17
+ /** Directory to set up (or update) as the installagent/ workspace root. */
18
+ dir: string;
19
+ /**
20
+ * Sync an existing workspace: fast-forward pull every repo and overwrite
21
+ * drifted root docs/skills from the templates. Default false — strictly
22
+ * additive, nothing existing is touched.
23
+ */
24
+ update?: boolean;
25
+ /** Injectable for tests; defaults to real `git clone`. */
26
+ clone?: CloneFn;
27
+ /** Injectable for tests; defaults to real `git pull --ff-only`. */
28
+ pull?: PullFn;
29
+ /**
30
+ * Chain a doctor checkup after setup and derive the numbered next steps
31
+ * from its live findings. Default true — pass false to skip the gh/op/
32
+ * gcloud probes (tests, offline runs); nextSteps falls back to the full
33
+ * static list.
34
+ */
35
+ runDoctor?: boolean;
36
+ /** Environment for the chained doctor. Defaults to process.env. */
37
+ env?: Record<string, string | undefined>;
38
+ /** Injectable for tests (doctor's CLI probes); defaults to real execFile. */
39
+ execFileImpl?: ExecFileFn;
40
+ /** Injectable for tests (doctor's live credential checks); defaults to fetch. */
41
+ fetchImpl?: typeof fetch;
42
+ }
43
+ export interface WizardWorkspaceResult {
44
+ ok: boolean;
45
+ dir: string;
46
+ update: boolean;
47
+ steps: WizardStep[];
48
+ /** Root docs + skills relative paths, by what happened to each. */
49
+ docs: {
50
+ created: string[];
51
+ updated: string[];
52
+ kept: string[];
53
+ };
54
+ /** Where the root docs/skills came from — the cloned team-tools beats the bundled copy. */
55
+ templateSource: "workspace-clone" | "bundled";
56
+ mcpRecommendations: McpRecommendation[];
57
+ /** The chained checkup (absent when runDoctor was false). */
58
+ doctor?: DoctorResult;
59
+ /** Numbered, in-order setup steps still ahead of the technician. */
60
+ nextSteps: string[];
61
+ }
62
+ /**
63
+ * `ia wizard` — clone the entire perfected technician environment: the six
64
+ * team repos, an otherwise-empty clients/ with client-template, and the root
65
+ * orientation docs + skills/.
66
+ *
67
+ * Default run is strictly additive (existing repos and files are skipped,
68
+ * exactly like `ia init`). With `update: true` it converges an existing
69
+ * workspace instead: fast-forward-only pulls per repo (local commits or dirty
70
+ * trees make that repo fail loudly, never merged over) and root docs/skills
71
+ * overwritten only where their content drifted from the template.
72
+ *
73
+ * Root docs/skills are sourced from the just-cloned/pulled
74
+ * team-tools/packages/sdk/templates/workspace-root when present — so an
75
+ * update distributes the workspace owner's latest root files without waiting
76
+ * for a CLI rebuild — falling back to the copy bundled with this package.
77
+ */
78
+ export declare function wizardWorkspace(options: WizardWorkspaceOptions): Promise<WizardWorkspaceResult>;
package/dist/wizard.js ADDED
@@ -0,0 +1,213 @@
1
+ import { existsSync } from "node:fs";
2
+ import { copyFile, mkdir, readFile } from "node:fs/promises";
3
+ import { dirname, join, resolve } from "node:path";
4
+ import { doctor } from "./doctor.js";
5
+ import { ENV_VARS } from "./env-registry.js";
6
+ import { listFiles } from "./fs-utils.js";
7
+ import { gitClone, gitPullFfOnly } from "./git.js";
8
+ import { MCP_RECOMMENDATIONS } from "./init.js";
9
+ import { envExampleTemplatePath, workspaceRootTemplateDir } from "./templates.js";
10
+ /**
11
+ * The full team repo set a technician's workspace mirrors — everything at the
12
+ * installagent/ root that lives on GitHub. client-<slug> build repos are
13
+ * deliberately excluded: technicians clone only the client(s) they work on.
14
+ */
15
+ export const WIZARD_REPO_NAMES = [
16
+ "team-clients",
17
+ "team-tools",
18
+ "team-infra",
19
+ "team-web",
20
+ "team-design",
21
+ "agents",
22
+ ];
23
+ const repoUrl = (name) => `git@github.com:InstallAgent/${name}.git`;
24
+ /**
25
+ * `ia wizard` — clone the entire perfected technician environment: the six
26
+ * team repos, an otherwise-empty clients/ with client-template, and the root
27
+ * orientation docs + skills/.
28
+ *
29
+ * Default run is strictly additive (existing repos and files are skipped,
30
+ * exactly like `ia init`). With `update: true` it converges an existing
31
+ * workspace instead: fast-forward-only pulls per repo (local commits or dirty
32
+ * trees make that repo fail loudly, never merged over) and root docs/skills
33
+ * overwritten only where their content drifted from the template.
34
+ *
35
+ * Root docs/skills are sourced from the just-cloned/pulled
36
+ * team-tools/packages/sdk/templates/workspace-root when present — so an
37
+ * update distributes the workspace owner's latest root files without waiting
38
+ * for a CLI rebuild — falling back to the copy bundled with this package.
39
+ */
40
+ export async function wizardWorkspace(options) {
41
+ const dir = resolve(options.dir);
42
+ const update = options.update ?? false;
43
+ const clone = options.clone ?? gitClone;
44
+ const pull = options.pull ?? gitPullFfOnly;
45
+ const steps = [];
46
+ await mkdir(dir, { recursive: true });
47
+ const repoStep = async (name, url, dest) => {
48
+ if (!existsSync(dest)) {
49
+ try {
50
+ await clone(url, dest);
51
+ steps.push({ name, status: "created", detail: `cloned ${url}` });
52
+ }
53
+ catch (error) {
54
+ steps.push({
55
+ name,
56
+ status: "failed",
57
+ detail: String(error instanceof Error ? error.message : error),
58
+ });
59
+ }
60
+ return;
61
+ }
62
+ if (!update) {
63
+ steps.push({ name, status: "skipped", detail: "already exists — left untouched" });
64
+ return;
65
+ }
66
+ try {
67
+ await pull(dest);
68
+ steps.push({ name, status: "updated", detail: "pulled (fast-forward only)" });
69
+ }
70
+ catch (error) {
71
+ steps.push({
72
+ name,
73
+ status: "failed",
74
+ detail: String(error instanceof Error ? error.message : error),
75
+ });
76
+ }
77
+ };
78
+ for (const name of WIZARD_REPO_NAMES) {
79
+ await repoStep(`${name}/`, repoUrl(name), join(dir, name));
80
+ }
81
+ const clientsDir = join(dir, "clients");
82
+ if (existsSync(clientsDir)) {
83
+ steps.push({ name: "clients/", status: "skipped", detail: "clients/ already exists" });
84
+ }
85
+ else {
86
+ await mkdir(clientsDir, { recursive: true });
87
+ steps.push({
88
+ name: "clients/",
89
+ status: "created",
90
+ detail: "empty clients/ dir — clone or create only the client repos you work on",
91
+ });
92
+ }
93
+ await repoStep("clients/client-template/", repoUrl("client-template"), join(clientsDir, "client-template"));
94
+ // Root docs + skills. The cloned team-tools' template dir is fresher than
95
+ // this package's bundled copy (it was just cloned/pulled above), so prefer it.
96
+ const cloneTemplateDir = join(dir, "team-tools", "packages", "sdk", "templates", "workspace-root");
97
+ const templateSource = existsSync(cloneTemplateDir)
98
+ ? "workspace-clone"
99
+ : "bundled";
100
+ const templateDir = templateSource === "workspace-clone" ? cloneTemplateDir : workspaceRootTemplateDir();
101
+ const docs = { created: [], updated: [], kept: [] };
102
+ for (const rel of await listFiles(templateDir)) {
103
+ const source = join(templateDir, rel);
104
+ const target = join(dir, rel);
105
+ if (!existsSync(target)) {
106
+ await mkdir(dirname(target), { recursive: true });
107
+ await copyFile(source, target);
108
+ docs.created.push(rel);
109
+ continue;
110
+ }
111
+ if (update && !(await readFile(source)).equals(await readFile(target))) {
112
+ await copyFile(source, target);
113
+ docs.updated.push(rel);
114
+ }
115
+ else {
116
+ docs.kept.push(rel);
117
+ }
118
+ }
119
+ // Root .env: one env file for the whole workspace. `.env.example` (names
120
+ // only) tracks the template like the docs above; `.env` itself holds the
121
+ // technician's secrets — created once from the example, NEVER overwritten,
122
+ // not even in update mode.
123
+ const envExampleInClone = join(cloneTemplateDir, "..", "env.example");
124
+ const envExampleSource = existsSync(envExampleInClone)
125
+ ? envExampleInClone
126
+ : envExampleTemplatePath();
127
+ const envExampleTarget = join(dir, ".env.example");
128
+ if (!existsSync(envExampleTarget)) {
129
+ await copyFile(envExampleSource, envExampleTarget);
130
+ steps.push({ name: ".env.example", status: "created", detail: "var layout, no values" });
131
+ }
132
+ else if (update &&
133
+ !(await readFile(envExampleSource)).equals(await readFile(envExampleTarget))) {
134
+ await copyFile(envExampleSource, envExampleTarget);
135
+ steps.push({ name: ".env.example", status: "updated", detail: "refreshed from template" });
136
+ }
137
+ else {
138
+ steps.push({ name: ".env.example", status: "skipped", detail: "up to date" });
139
+ }
140
+ const envTarget = join(dir, ".env");
141
+ if (existsSync(envTarget)) {
142
+ steps.push({
143
+ name: ".env",
144
+ status: "skipped",
145
+ detail: "already exists — holds your secrets, never overwritten (new vars: see .env.example)",
146
+ });
147
+ }
148
+ else {
149
+ await copyFile(envExampleSource, envTarget);
150
+ steps.push({
151
+ name: ".env",
152
+ status: "created",
153
+ detail: "placeholders only — fill values from 1Password (`ia doctor` lists what's missing)",
154
+ });
155
+ }
156
+ steps.push({
157
+ name: "root docs + skills/",
158
+ status: docs.created.length > 0 || docs.updated.length > 0
159
+ ? docs.created.length > 0
160
+ ? "created"
161
+ : "updated"
162
+ : "skipped",
163
+ detail: `${docs.created.length} created, ${docs.updated.length} updated, ${docs.kept.length} unchanged`,
164
+ });
165
+ const runDoctor = options.runDoctor ?? true;
166
+ const checkup = runDoctor
167
+ ? await doctor({
168
+ workspaceDir: dir,
169
+ env: options.env,
170
+ execFileImpl: options.execFileImpl,
171
+ fetchImpl: options.fetchImpl,
172
+ })
173
+ : undefined;
174
+ return {
175
+ ok: steps.every((step) => step.status !== "failed"),
176
+ dir,
177
+ update,
178
+ steps,
179
+ docs,
180
+ templateSource,
181
+ mcpRecommendations: MCP_RECOMMENDATIONS,
182
+ ...(checkup ? { doctor: checkup } : {}),
183
+ nextSteps: buildNextSteps(dir, checkup),
184
+ };
185
+ }
186
+ /**
187
+ * The technician's remaining setup, in the order to do it. Derived from the
188
+ * chained doctor findings when available (steps already green are dropped);
189
+ * the full static list otherwise.
190
+ */
191
+ function buildNextSteps(dir, checkup) {
192
+ const notOk = (id) => !checkup || checkup.checks.some((c) => c.id === id && c.status !== "ok");
193
+ const steps = [];
194
+ if (notOk("tools/gh")) {
195
+ steps.push("run `gh auth login` — one-time GitHub OAuth; no PAT, no approval wait");
196
+ }
197
+ if (notOk("tools/op")) {
198
+ steps.push("install the 1Password CLI if needed (`brew install 1password-cli`), then `op signin`");
199
+ }
200
+ const vaultVarMissing = ENV_VARS.some((spec) => spec.doctor && spec.source === "vault" && notOk(`env/${spec.name}`));
201
+ if (vaultVarMissing) {
202
+ steps.push(`run \`ia env fill -w ${dir}\` — fills the shared secrets from 1Password`);
203
+ }
204
+ for (const spec of ENV_VARS) {
205
+ if (spec.doctor && spec.source === "personal" && spec.tier === "required") {
206
+ if (notOk(`env/${spec.name}`)) {
207
+ steps.push(`set ${spec.name} in ${join(dir, ".env")} — ${spec.howToGet}`);
208
+ }
209
+ }
210
+ }
211
+ steps.push(`run \`ia doctor -w ${dir}\` until everything required is green`);
212
+ return steps;
213
+ }
package/package.json ADDED
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "@installagent/sdk",
3
+ "version": "0.1.0",
4
+ "description": "Install Agent's shared SDK for internal team operations (client repos, n8n workflows, docs search, and more).",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "files": [
9
+ "dist",
10
+ "templates"
11
+ ],
12
+ "publishConfig": {
13
+ "access": "public"
14
+ },
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/InstallAgent/team-tools.git",
18
+ "directory": "packages/sdk"
19
+ },
20
+ "devDependencies": {
21
+ "@types/node": "^22.10.0",
22
+ "typescript": "^5.7.0",
23
+ "vitest": "^3.0.0"
24
+ },
25
+ "scripts": {
26
+ "build": "tsc -p tsconfig.json",
27
+ "type-check": "tsc -p tsconfig.json --noEmit",
28
+ "test": "vitest run"
29
+ }
30
+ }
@@ -0,0 +1,60 @@
1
+ # installagent/ workspace root .env — ONE env file for the whole workspace.
2
+ #
3
+ # - `ia` commands load this automatically (vars already set in your shell win).
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`).
6
+ # Personal values (marked below) you fill by hand. NEVER commit this file
7
+ # anywhere — the root is not a git repo, and no repo may ever contain it.
8
+ # Only env.example (this placeholder layout, no values) is shareable.
9
+ # - `ia doctor -w <workspace>` tells you which vars are still missing and why.
10
+
11
+ # ── ia CLI: technician daily drivers ─────────────────────────────────────────
12
+ GITHUB_API_TOKEN=
13
+ # normally EMPTY — GitHub auth comes from `gh auth login` (no PAT, no
14
+ # approval wait). Set only to override with a fine-grained PAT.
15
+ LINEAR_API_TOKEN=
16
+ # your personal Linear API key — Linear → Settings → Security & access
17
+ LINEAR_CLIENT_TEAM_ID=
18
+ # the fixed Linear client team's ID — filled by `ia env fill`
19
+ IA_DOCS_SESSION=
20
+ # team.installagent.com __Secure-authjs.session-token cookie (expires periodically)
21
+ IA_PORTAL_ADMIN_SECRET=
22
+ # portal.installagent.com admin API bearer — filled by `ia env fill`
23
+ AIRTABLE_API_TOKEN=
24
+ # read-only Airtable PAT (data.records:read on Clients - Master) — `ia env fill`
25
+ GOOGLE_SERVICE_ACCOUNT_KEY=
26
+ # the Drive service-account key JSON, single line — filled by `ia env fill`
27
+ FATHOM_API_KEY=
28
+ # Fathom dashboard → Settings → API Access — filled by `ia env fill`
29
+ N8N_API_URL=
30
+ # n8n API base INCLUDING /api/v1, e.g. https://n8n.installagent.com/api/v1
31
+ N8N_API_KEY=
32
+ # n8n → Settings → API — filled by `ia env fill`
33
+ GEMINI_API_KEY=
34
+
35
+ # ── 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
+
43
+ # ── 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=
51
+
52
+ # ── 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=
@@ -0,0 +1,39 @@
1
+ {
2
+ "permissions": {
3
+ "allow": [
4
+ "Bash(ia ping*)",
5
+ "Bash(ia doctor*)",
6
+ "Bash(ia wizard*)",
7
+ "Bash(ia env fill*)",
8
+ "Bash(ia client *)",
9
+ "Bash(ia client-build *)",
10
+ "Bash(ia client-drive *)",
11
+ "Bash(ia client-linear *)",
12
+ "Bash(ia linear-project *)",
13
+ "Bash(ia docs search *)",
14
+ "Bash(ia agent templates*)",
15
+ "Bash(git status*)",
16
+ "Bash(git log*)",
17
+ "Bash(git diff*)",
18
+ "Bash(git show*)",
19
+ "Bash(git branch*)",
20
+ "Bash(ls*)",
21
+ "Bash(pwd)",
22
+ "Bash(rg *)",
23
+ "Bash(grep *)",
24
+ "Bash(find * -type f*)",
25
+ "Bash(pnpm test*)",
26
+ "Bash(pnpm check*)",
27
+ "Bash(pnpm type-check*)"
28
+ ],
29
+ "deny": [
30
+ "Read(.env)",
31
+ "Read(./.env)",
32
+ "Read(**/.env)",
33
+ "Read(**/.env.local)",
34
+ "Bash(cat .env*)",
35
+ "Bash(cat ./.env*)",
36
+ "Bash(cat **/.env*)"
37
+ ]
38
+ }
39
+ }
@@ -0,0 +1,205 @@
1
+ # AGENT.md — installagent workspace root
2
+
3
+ Canonical instructions for any AI coding agent working at the root of this
4
+ workspace (Claude Code, Cowork, Codex, Cursor, Gemini, Copilot, Aider,
5
+ Continue, etc.). Tool-specific files at the root (`CLAUDE.md`, `AGENTS.md`,
6
+ `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`) all defer to
7
+ this document.
8
+
9
+ Each repo below has its own `AGENT.md` / `AGENTS.md` / `CLAUDE.md` with rules
10
+ that override these when you are working inside it.
11
+
12
+ ## What this is
13
+
14
+ The working folder for all Install Agent code, content, and assets. We are a
15
+ small team (currently two people, expanding to contractors) productizing AI
16
+ automations for SMB clients — primarily n8n workflows and autonomous agents
17
+ wrapped with Claude, deployed per-client with technician-led setup.
18
+
19
+ **This root is deliberately not a git repo.** It is a folder of independent
20
+ git repos (each `team-*` and each `clients/client-*` is its own repo with its
21
+ own remote and its own rules). Don't `git init` the root.
22
+
23
+ ## Top-level layout
24
+
25
+ ```
26
+ installagent/
27
+ ├── agents/ # The WORKFLOW BANK — reusable, sanitized n8n templates + plain-language manifests (start client automations here; bank back after delivery)
28
+ ├── clients/ # One build repo per client engagement + client-template
29
+ │ ├── client-template/ # THE baseline — every client repo is created from this
30
+ │ └── client-<slug>/ # e.g. client-carvision, client-kingdom, …
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
33
+ ├── team-web/ # Public web: installagent.com (apps/web) + team hub (apps/docs)
34
+ ├── team-design/ # Install Agent design system source (tokens, components, guidelines)
35
+ ├── team-branding/ # Logo files (static assets only)
36
+ ├── skills/ # Cross-cutting agent skills (client deliverables pipeline, brand kit, …)
37
+ ├── AGENT.md # ← you are here
38
+ └── ONBOARDING.md # New-contractor orientation — read once, first
39
+ ```
40
+
41
+ ## Where to start a task
42
+
43
+ | Task | Go to | Read first |
44
+ |---|---|---|
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 |
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
+ | 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
+ | Answer "what did we ship for X / does it work?" | `clients/client-<slug>/docs/00-delivery-log.md` + `evidence/` | same |
50
+ | Check or change deal status | **Airtable (`Clients - Master`)** — never a file in git | — |
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
+ | 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
+ | Reuse or bank a workflow template (`ia agent save\|templates\|create`) | `agents/` | `agents/AGENT.md` |
54
+ | Infra (n8n hosting, SFTP, AWS) | `team-infra/` | `team-infra/AGENT.md` |
55
+ | Marketing site or team hub | `team-web/apps/web` or `team-web/apps/docs` | `team-web/AGENT.md` |
56
+ | UI/design tokens & components | `team-design/` | `team-design/SKILL.md` |
57
+ | New client engagement kickoff | copy `clients/client-template/` → `clients/client-<slug>/` | `clients/client-template/README.md` |
58
+ | Internal team tooling (SDK/CLI/MCP for technicians, future Slack team agent) | `team-tools/` | `team-tools/AGENT.md` + `team-tools/docs/spec.md` |
59
+
60
+ **The registry vs. build split is load-bearing:** `team-clients/clients/<slug>/`
61
+ says *who the client is* (profile + call history, PII allowed, private).
62
+ `clients/client-<slug>/` is *what we make for them* (specs, workflows, agents,
63
+ deliverables — no PII, no customer data). Slug = the lead's email domain
64
+ (`pbenitez@carvision.com` → `carvision`), identical in both places and in
65
+ Airtable.
66
+
67
+ ## Cross-cutting golden rules
68
+
69
+ These apply everywhere unless a repo explicitly overrides them
70
+ (`team-clients` overrides #2 by design — see its `AGENT.md`).
71
+
72
+ 1. **No secrets in committed files.** API keys, OAuth client IDs, n8n
73
+ credential IDs, passwords — none of it, in any repo, ever. Use
74
+ placeholders (`<KEY_HERE>`, `REPLACE_WITH_*`, `__SET_IN_N8N__*__`). The
75
+ most common foot-gun is a real credential ID left in n8n workflow JSON.
76
+ 2. **No customer data in committed files.** Real names, emails, account IDs,
77
+ transcripts, and especially a client's *own* customer datasets. The single
78
+ exception is `team-clients/` (the registry), which is private and holds
79
+ client PII by design — but never their customers' data, and never secrets.
80
+ 3. **Client-facing output is Install Agent, never Rebar.** Internal accounts
81
+ may be `@rebarlabs.io`; anything a client sees says Install Agent.
82
+ 4. **pnpm only.** No npm or yarn lockfiles.
83
+ 5. **Biome over ESLint/Prettier.** Don't install ESLint or Prettier next to it.
84
+ 6. **TypeScript strict, no `any`.** `// biome-ignore lint/suspicious/noExplicitAny: <reason>`
85
+ only when genuinely unknowable.
86
+ 7. **Tailwind utility classes only.** No CSS modules, inline `style`, or
87
+ styled-components in the Next.js apps.
88
+ 8. **Run checks before committing.** Repos with Lefthook configured run it —
89
+ never bypass with `--no-verify` unless explicitly asked. Client repos lint
90
+ their structure with `ci/repo-lint.mjs` pre-commit.
91
+ 9. **Don't cross-import between repos.** Different audiences, stacks, and
92
+ deployment targets. Copy deliberately (and say so) rather than import.
93
+ 10. **AWS access uses the `installagent` CLI profile.**
94
+ `aws --profile installagent <cmd>` or `AWS_PROFILE=installagent`.
95
+ Credentials live in `~/.aws/credentials`, never in a repo.
96
+ 11. **The workflow bank is a loop, not an archive.** Check `agents/` before
97
+ building any client automation, and bank the sanitized reusable version
98
+ back (with its `template.md` manifest + catalog row) after delivery —
99
+ a client build isn't done until that happens. See `agents/AGENT.md`.
100
+ 12. **One shared `.env` at the workspace root.** Real secrets live in
101
+ `installagent/.env` (gitignored — root isn't a git repo so this is a
102
+ filesystem convention, not a git one). Every repo's own env file
103
+ (`.env.local` for the Next.js apps in `team-web`, `.env` for `team-infra`
104
+ and its subprojects) is a symlink pointing back at it, e.g.
105
+ `ln -s ../../../.env team-web/apps/portal/.env.local`. To wire up a new
106
+ repo/app: symlink its expected env filename the same way instead of
107
+ hand-copying values. Because it's one flat file, keys that different
108
+ apps deliberately want distinct (e.g. `AUTH_SECRET` across
109
+ docs/operations/portal) now share a single value — a known tradeoff for
110
+ having one file to manage; rename a key app-specific in the root `.env`
111
+ if that ever causes a problem. Never `Read`/`cat`/print this file's
112
+ contents into an LLM context or chat.
113
+ 13. **Every site we ship credits Install Agent and links back to us.** A tiny
114
+ "Created by Install Agent" line, last thing in the footer below everything
115
+ else, linking to `https://installagent.com` — `target="_blank"`,
116
+ `rel="noopener"` and **never** `rel="nofollow"` (the backlink is the
117
+ point). It's part of the deal, not an optional flourish: applies to every
118
+ `clients/client-*/web/` build and any other public site we hand over.
119
+ Mechanics: the label + href live in the site's content layer
120
+ (`content/site.ts`, or `i18n/<locale>/site.ts` on multilingual sites) as
121
+ `footer.builtBy`, are schema-required (`href` is a `z.literal`), and are
122
+ covered by a test in that repo so removing the credit fails `pnpm test`.
123
+ Style it muted and small so it reads as a credit, never as a second CTA.
124
+ Our *own* properties (`team-web`) are exempt — they don't self-backlink.
125
+
126
+ ## Standard client build repo
127
+
128
+ Every `clients/client-<slug>/` is created from `clients/client-template/` and
129
+ keeps this **flat, fixed shape** (enforced by `ci/repo-lint.mjs` pre-commit
130
+ and in CI). That `ci/repo-lint.mjs` (plus `lefthook.yml`, the repo-lint
131
+ CI workflow, and `CADENCE.md`) is a **one-time copy**, not a symlink — a repo
132
+ keeps running whatever version it was created with until someone re-syncs it.
133
+ If you change any of those four files in `client-template`, run
134
+ `ia template-sync --apply` (`team-tools`) against the workspace in the same
135
+ change — this already caught three client repos silently enforcing a
136
+ pre-2026-07 skeleton. See `team-tools/AGENT.md` § *Keeping client repos in
137
+ sync*.
138
+
139
+ **How work ships inside a client repo is `CADENCE.md`** (at the root of every
140
+ `client-<slug>/`, synced verbatim from the template). It is the contract for
141
+ introducing any change — feature, workflow tweak, bug fix, scope change:
142
+ five stages (contract → reproduce → observability → green → evidence + sync)
143
+ plus the **surface matrix** naming which of `docs/`, `onboarding.html`,
144
+ Linear, and `workflows/*.json` must move in the *same commit*. It exists
145
+ because one engagement is described in three places for three audiences and
146
+ nothing else forces them to stay consistent. Read it before touching a client
147
+ repo; don't invent a per-client process.
148
+
149
+ ```
150
+ client-<slug>/
151
+ ├── CADENCE.md # how work ships: five stages + the anti-drift surface matrix
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
154
+ ├── docs/ # engagement-spec output + 00-delivery-log.md + diagrams as self-contained HTML
155
+ ├── workflows/ # n8n JSON exports (credential IDs scrubbed)
156
+ ├── data/ # client-sent raw data — gitignored (only its README is tracked)
157
+ ├── evidence/ # dated backtest/validation records
158
+ ├── web/ # OPTIONAL — Next.js site scaffold (website builds only)
159
+ ├── design/ # OPTIONAL — the client's own brand assets
160
+ └── agent-<name>/ # OPTIONAL — code for an autonomous agent build (one dir per agent)
161
+ ```
162
+
163
+ No nesting (`<project>/` subfolders are forbidden — prefix filenames instead),
164
+ no `legal/` (signed documents live in the client's Google Drive folder), no
165
+ `calls/` (call history lives in the registry), no `.zip` archives, no status
166
+ files (Airtable owns deal status). No `diagrams/` or `client-facing/` since
167
+ 2026-07: diagrams are HTML files in `docs/`; branded deliverables ship via
168
+ the client's Drive folder, and the client-presentable view is the Public
169
+ tab of `onboarding.html`.
170
+
171
+ Skills that produce the deliverables: **`client-deliverables`** (orchestrator),
172
+ **`engagement-spec`** (internal docs), **`client-facing-docs`** (branded PDFs),
173
+ **`client-workflow-diagram`** (diagrams), **`installagent-brand-kit`** (brand —
174
+ official logo + brand red `#9b0506`), **`contract-tech-agnostic`** (contracts
175
+ 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
177
+ workspace guide). All live in `skills/`. The engagement playbook the skills
178
+ plug into — lifecycle, discovery-call script, LLM-setup runbook — lives on the
179
+ team hub (`team-web/apps/docs` → Techs).
180
+
181
+ The proposal's commercial model is standard: a one-time build fee, a monthly
182
+ service fee, and usage-based third-party API credits passed through at cost,
183
+ capped.
184
+
185
+ ## How agentic files are layered
186
+
187
+ | File | Audience | Status |
188
+ |---|---|---|
189
+ | `AGENT.md` (root) | All agents, workspace-wide rules | Canonical |
190
+ | `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` / `.cursorrules` (root) | Tool-specific conventions | Pointers to this file |
191
+ | `<repo>/AGENT.md` (or `AGENTS.md`) | Canonical for that repo | Canonical |
192
+ | `<repo>/CLAUDE.md` | Claude Code / Cowork | Pointer + Claude-flavored notes |
193
+ | `<repo>/<dir>/CLAUDE.md` | Navigation aid for one directory | Short orientation, not full rules |
194
+
195
+ When you update conventions, edit the relevant `AGENT.md` and any skills it
196
+ references in the same change. Don't put rule content in pointer files — they
197
+ drift fast. **Always read the directory `CLAUDE.md` before editing files in
198
+ that directory.**
199
+
200
+ ## When something doesn't fit
201
+
202
+ If a task has no obvious home — a new automation that isn't an n8n workflow
203
+ or client agent, a new internal tool, a new client-facing surface — **ask
204
+ before scaffolding a new top-level directory.** This workspace has stayed
205
+ clean because new directories require a real reason.
@@ -0,0 +1,11 @@
1
+ # AGENTS.md
2
+
3
+ This repo's canonical agent instructions live in [`AGENT.md`](./AGENT.md).
4
+ Read that file first.
5
+
6
+ `AGENTS.md` exists so OpenAI Codex, ChatGPT desktop, and other tools that
7
+ follow the [agents.md](https://agents.md) convention pick up the same rules.
8
+ The contents are identical to `AGENT.md` — treat them as one document.
9
+
10
+ If you're updating conventions, edit `AGENT.md`. Do not let these two files
11
+ drift.