@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.
- package/dist/agent-templates.d.ts +90 -0
- package/dist/agent-templates.js +211 -0
- package/dist/client-build.d.ts +50 -0
- package/dist/client-build.js +155 -0
- package/dist/client-context.d.ts +40 -0
- package/dist/client-context.js +70 -0
- package/dist/client-drive.d.ts +67 -0
- package/dist/client-drive.js +278 -0
- package/dist/client-intake.d.ts +68 -0
- package/dist/client-intake.js +189 -0
- package/dist/client-linear.d.ts +30 -0
- package/dist/client-linear.js +85 -0
- package/dist/docs-search.d.ts +44 -0
- package/dist/docs-search.js +187 -0
- package/dist/doctor.d.ts +43 -0
- package/dist/doctor.js +425 -0
- package/dist/env-file.d.ts +25 -0
- package/dist/env-file.js +69 -0
- package/dist/env-fill.d.ts +43 -0
- package/dist/env-fill.js +161 -0
- package/dist/env-push.d.ts +37 -0
- package/dist/env-push.js +137 -0
- package/dist/env-registry.d.ts +49 -0
- package/dist/env-registry.js +230 -0
- package/dist/exec.d.ts +14 -0
- package/dist/exec.js +16 -0
- package/dist/fathom-webhook.d.ts +44 -0
- package/dist/fathom-webhook.js +123 -0
- package/dist/fs-utils.d.ts +9 -0
- package/dist/fs-utils.js +34 -0
- package/dist/gcp-service-account-key.d.ts +37 -0
- package/dist/gcp-service-account-key.js +66 -0
- package/dist/gemini-api-key.d.ts +47 -0
- package/dist/gemini-api-key.js +132 -0
- package/dist/git.d.ts +16 -0
- package/dist/git.js +29 -0
- package/dist/github-token.d.ts +24 -0
- package/dist/github-token.js +30 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.js +28 -0
- package/dist/init.d.ts +47 -0
- package/dist/init.js +101 -0
- package/dist/linear-project.d.ts +81 -0
- package/dist/linear-project.js +192 -0
- package/dist/new-client.d.ts +32 -0
- package/dist/new-client.js +89 -0
- package/dist/ping.d.ts +6 -0
- package/dist/ping.js +7 -0
- package/dist/portal-admin.d.ts +133 -0
- package/dist/portal-admin.js +144 -0
- package/dist/sync-templates.d.ts +58 -0
- package/dist/sync-templates.js +109 -0
- package/dist/template-sync.d.ts +55 -0
- package/dist/template-sync.js +90 -0
- package/dist/templates.d.ts +19 -0
- package/dist/templates.js +24 -0
- package/dist/wizard.d.ts +78 -0
- package/dist/wizard.js +213 -0
- package/package.json +30 -0
- package/templates/env.example +60 -0
- package/templates/workspace-root/.claude/settings.json +39 -0
- package/templates/workspace-root/AGENT.md +205 -0
- package/templates/workspace-root/AGENTS.md +11 -0
- package/templates/workspace-root/CLAUDE.md +63 -0
- package/templates/workspace-root/GEMINI.md +24 -0
- package/templates/workspace-root/ONBOARDING.md +164 -0
- package/templates/workspace-root/README.md +67 -0
- package/templates/workspace-root/skills/CLAUDE.md +79 -0
- package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
- package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
- package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
- package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
- package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
- package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
- package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
- package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
- package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
- package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
- package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
- package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
- package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
- package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
- package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
- package/templates/workspace-root/skills/linear/SKILL.md +186 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
package/dist/wizard.d.ts
ADDED
|
@@ -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.
|