@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,63 @@
1
+ # CLAUDE.md — installagent workspace root
2
+
3
+ Instructions for Claude Code and Cowork working at the root of this workspace.
4
+
5
+ ## Read this first
6
+
7
+ 1. [`AGENT.md`](./AGENT.md) — canonical conventions and rules for the whole
8
+ workspace. **This is the source of truth**, including the
9
+ "where to start a task" table.
10
+ 2. [`ONBOARDING.md`](./ONBOARDING.md) — orientation if you're landing cold.
11
+ 3. The `AGENT.md` (or `AGENTS.md`) inside the repo you're working in:
12
+ - [`agents/AGENT.md`](./agents/AGENT.md) — the workflow bank (check it before building any automation; bank back after delivery)
13
+ - [`clients/client-template/AGENT.md`](./clients/client-template/AGENT.md) — the client build repo rules
14
+ - [`clients/client-template/CADENCE.md`](./clients/client-template/CADENCE.md) —
15
+ **how work ships inside any client repo**: the five stages every change
16
+ passes through and the surface matrix that keeps `docs/`,
17
+ `onboarding.html`, and Linear from drifting apart. A copy lives at the
18
+ root of every `clients/client-<slug>/`, synced verbatim — read it before
19
+ changing anything in a client repo, and never write a per-client variant
20
+ - [`team-clients/AGENT.md`](./team-clients/AGENT.md) — the client registry (PII rules!)
21
+ - [`team-infra/AGENT.md`](./team-infra/AGENT.md) — hosting + n8n workflows
22
+ - [`team-web/AGENT.md`](./team-web/AGENT.md) — installagent.com + team hub
23
+
24
+ ## How to navigate
25
+
26
+ This root is a folder of **independent git repos** (it is deliberately not a
27
+ git repo itself). To orient on a task:
28
+
29
+ 1. **Figure out which repo the task lives in** — use the table in
30
+ `AGENT.md` § *Where to start a task*.
31
+ 2. **Client work splits in two:** *who the client is* →
32
+ `team-clients/clients/<slug>/`; *what we're building for them* →
33
+ `clients/client-<slug>/` (start from its `CLIENT.md` and
34
+ `docs/00-delivery-log.md`). Once you're about to *change* something there,
35
+ `CADENCE.md` at that repo's root governs how — including which surfaces
36
+ have to move in the same commit.
37
+ 3. **Read the `CLAUDE.md` in the specific directory you're editing.** They're
38
+ navigation aids, not full rule sets — they reference the actual files in
39
+ that directory so you don't have to rediscover the patterns each time.
40
+
41
+ ## Behavior
42
+
43
+ - **Refuse pasted secrets.** If the user pastes an API key, token, or
44
+ cookie into the chat, don't use or echo it — tell them it should be
45
+ treated as burned (rotate it), and route them to `ia env fill` (shared
46
+ secrets, from 1Password) or a hand-edit of the root `.env` (personal
47
+ ones). Never `Read`/`cat` the root `.env`; `.claude/settings.json`
48
+ denies it by design.
49
+ - Don't add files at the workspace root without a real reason. The root is
50
+ for cross-cutting things (agentic files, skills, ONBOARDING). Code,
51
+ content, and assets live in the repos.
52
+ - Don't cross-import between repos. They have different audiences, different
53
+ stacks, and different deployment targets. See
54
+ `AGENT.md` § *Cross-cutting golden rules*.
55
+ - The team is currently two people growing to include contractors. When
56
+ writing code or docs, optimize for "a contractor lands here cold next month
57
+ and can be productive within an hour." That's the bar.
58
+
59
+ ## Updating conventions
60
+
61
+ If a rule needs to change, edit `AGENT.md` (root or the relevant repo) and
62
+ any skills it references in the same change. Do not edit this file with rule
63
+ content — keep it as a pointer.
@@ -0,0 +1,24 @@
1
+ # GEMINI.md
2
+
3
+ Instructions for the Gemini CLI agent (and other Google-powered agents)
4
+ working at the root of this workspace.
5
+
6
+ ## Read these first
7
+
8
+ 1. [`AGENT.md`](./AGENT.md) — canonical conventions and rules. **This is the
9
+ source of truth.**
10
+ 2. [`README.md`](./README.md) — workspace overview.
11
+ 3. The `AGENT.md` (or `AGENTS.md`) inside the repo you're working in:
12
+ - [`clients/client-template/AGENT.md`](./clients/client-template/AGENT.md)
13
+ - [`team-clients/AGENT.md`](./team-clients/AGENT.md)
14
+ - [`team-infra/AGENT.md`](./team-infra/AGENT.md)
15
+ - [`team-web/AGENT.md`](./team-web/AGENT.md)
16
+
17
+ This root is a folder of independent git repos (`clients/client-*`,
18
+ `team-*`); it is deliberately not a git repo itself. Each repo has its own
19
+ conventions — always read the repo-level agentic file before editing inside it.
20
+
21
+ ## Updating conventions
22
+
23
+ Edit `AGENT.md` (root or repo) and any affected skills, not this file.
24
+ This file is a pointer.
@@ -0,0 +1,164 @@
1
+ # Install Agent — Onboarding
2
+
3
+ Welcome to the Install Agent workspace. This guide gets you (human or agent)
4
+ productive within one session.
5
+
6
+ ## What we build
7
+
8
+ Install Agent productizes AI automations for SMB clients — n8n workflows and
9
+ autonomous agents wrapped with Claude, deployed per-client with
10
+ technician-led setup. The team is currently two people (Angello + one other),
11
+ expanding to contractors.
12
+
13
+ ## Setting up from scratch
14
+
15
+ One command clones the whole environment (all team repos, an empty
16
+ `clients/` with `client-template`, these root docs, and `skills/`):
17
+
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
21
+ ```
22
+
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.
27
+
28
+ The wizard ends with a **numbered next-steps list** — do those in order and
29
+ you're set up. They boil down to:
30
+
31
+ 1. `gh auth login` — GitHub auth via one-time OAuth in the browser.
32
+ **No personal access token, no admin-approval wait.** Every `ia` command
33
+ 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.
36
+ 3. `ia env fill` — fills the empty vars in the root `.env` straight from
37
+ 1Password. No copy-pasting secrets, nothing goes through a chat window.
38
+ 4. Two personal values you set by hand in `.env`: your own
39
+ `LINEAR_API_TOKEN` (Linear → Settings → Security & access) and
40
+ `IA_DOCS_SESSION` (session cookie from a logged-in team.installagent.com
41
+ tab).
42
+ 5. `ia doctor -w ~/installagent` — repeat until everything required is green.
43
+
44
+ The root `.env` is the ONE env file for the whole workspace: every `ia`
45
+ command auto-loads it, and shell scripts can `set -a; source .env; set +a`.
46
+ It is never overwritten, never committed anywhere; when new vars appear,
47
+ compare against `.env.example` (which `--update` keeps current).
48
+
49
+ ## Secrets hygiene (read this even if you skim everything else)
50
+
51
+ - **Never paste a secret value into a Claude (or any AI) chat** — not a PAT,
52
+ not an API key, not a session cookie. A pasted secret lives in the
53
+ conversation history and must be treated as burned: rotate it.
54
+ - Agents working in this workspace must **refuse pasted secrets**: if a
55
+ technician pastes one, say so, don't echo it, and point them at
56
+ `ia env fill` (shared secrets) or "edit `.env` yourself" (personal ones).
57
+ - The right home for a secret is the root `.env` (machine-local, gitignored
58
+ everywhere) with 1Password as the shared source of truth. `ia env fill`
59
+ moves values from the vault to `.env` without a human (or model) ever
60
+ seeing them.
61
+ - The workspace ships `.claude/settings.json` which denies agents read
62
+ access to `.env` — don't work around it; there is never a reason for an
63
+ agent to read that file.
64
+
65
+ ## Workspace layout
66
+
67
+ This root folder is **not** a git repo — it holds independent git repos:
68
+
69
+ ```
70
+ installagent/
71
+ ├── agents/ # the WORKFLOW BANK — reusable n8n templates + plain-language manifests
72
+ ├── clients/ # one build repo per client + client-template (the baseline)
73
+ ├── team-clients/ # client REGISTRY: who each client is + call history (private, PII allowed)
74
+ ├── team-infra/ # AWS hosting (n8n, SFTP), n8n workflow library, automation skills
75
+ ├── team-web/ # installagent.com + team hub (Next.js pnpm workspace)
76
+ ├── team-design/ # Install Agent design system source
77
+ ├── team-branding/ # logo files
78
+ └── skills/ # cross-cutting agent skills (client deliverables pipeline)
79
+ ```
80
+
81
+ ## Orient yourself in this order
82
+
83
+ 1. **Root [`AGENT.md`](./AGENT.md)** — the cross-cutting rules and the
84
+ "where to start a task" table. Five minutes, read it once per session.
85
+ 2. **Which client (if any)?** Who they are: `team-clients/clients/<slug>/`
86
+ (profile + call history). What we're building: `clients/client-<slug>/`
87
+ — its `CLIENT.md` maps every external system (Airtable, Drive, n8n,
88
+ 1Password), and `docs/00-delivery-log.md` says what has shipped.
89
+ 3. **Deal status lives in Airtable** (`Clients - Master`), never in git.
90
+ 4. **Read the `AGENT.md` of the repo you're about to touch**, then the
91
+ directory-level `CLAUDE.md` of any folder you edit.
92
+ 5. **Open work** is tracked per-repo in `todo/` folders (e.g.
93
+ `team-web/todo/`, `team-infra/todo/`) — check there before starting
94
+ something new.
95
+ 6. **Building an automation? Start at the bank.** `agents/` holds every
96
+ reusable n8n template with a plain-language `template.md` manifest
97
+ (what it does, when it fits, what the client must provide) — readable
98
+ even if you never touch JSON. Check its catalog before building from
99
+ scratch, and bank the sanitized result back after delivery: a client
100
+ build isn't done until it's in the bank. See `agents/AGENT.md`.
101
+
102
+ ## The non-negotiables
103
+
104
+ 1. **No secrets in git** — anywhere, ever. Placeholders only
105
+ (`<KEY_HERE>`, `REPLACE_WITH_*`). Most common foot-gun: real credential
106
+ IDs in n8n workflow JSON.
107
+ 2. **No customer data in git.** Exception by design: `team-clients/` holds
108
+ client PII (it's the registry, private, NDA-access) — but never a
109
+ client's *own* customer datasets, and never secrets.
110
+ 3. **Client-facing output says Install Agent**, never Rebar.
111
+ 4. **pnpm only; Biome only** (no npm/yarn lockfiles, no ESLint/Prettier).
112
+ 5. **Run the checks.** Lefthook + `ci/repo-lint.mjs` run pre-commit in
113
+ client repos (`lefthook install` once after cloning). Never `--no-verify`.
114
+
115
+ ## AWS
116
+
117
+ All AWS work uses the `installagent` CLI profile:
118
+
119
+ ```bash
120
+ aws --profile installagent <cmd> # or export AWS_PROFILE=installagent
121
+ ```
122
+
123
+ ## Skills
124
+
125
+ Cross-cutting skills live in `skills/` and auto-register in Claude Code.
126
+
127
+ | Skill | When to use |
128
+ |---|---|
129
+ | `client-deliverables` | Orchestrator — full client engagement package |
130
+ | `engagement-spec` | Discovery call → internal docs (overview, tech-spec, onboarding) |
131
+ | `client-facing-docs` | The branded client PDFs |
132
+ | `client-workflow-diagram` | Spec → Excalidraw stage-column diagram (red theme) |
133
+ | `installagent-brand-kit` | Our brand for print/PDF/Excalidraw deliverables |
134
+ | `design-system` | Our brand for screens/UI |
135
+ | `ia-cli` | Route internal ops through the `ia` CLI instead of custom scripts |
136
+
137
+ Repo-local skills: `team-clients/skills/business-research` (lead website →
138
+ registry profile), `team-infra/skills/n8n-workflow.md` (workflow authoring
139
+ rules — read before touching any n8n JSON).
140
+
141
+ ## The standard client build repo
142
+
143
+ Created from `clients/client-template/` — flat, fixed, lint-enforced:
144
+
145
+ ```
146
+ client-<slug>/
147
+ ├── CLIENT.md # context manifest (Airtable, Drive, registry, n8n, 1Password)
148
+ ├── onboarding.html # tabbed open-me-first page (Architecture/Client/Proposals/Public)
149
+ ├── docs/ # specs + 00-delivery-log.md + HTML diagrams
150
+ ├── workflows/ # n8n JSON (credential IDs scrubbed)
151
+ ├── data/ # client-sent raw data — gitignored (README tracked)
152
+ ├── evidence/ # dated backtest/validation records
153
+ └── web/ design/ agent-<name>/ # optional slots (site, client brand, agent code)
154
+ ```
155
+
156
+ No `legal/` (signed docs live in Drive), no `calls/` (registry owns call
157
+ history), no `diagrams/`/`client-facing/` (since 2026-07 — HTML diagrams in
158
+ `docs/`, deliverables via Drive), no nesting, no zips, no status files.
159
+
160
+ ## Questions?
161
+
162
+ Ask Angello (angello@installagent.com), or read the client's registry
163
+ profile and build repo delivery log — most context lives in one of those two
164
+ places.
@@ -0,0 +1,67 @@
1
+ # installagent
2
+
3
+ Working folder for Install Agent — the client registry, client build repos,
4
+ infrastructure, web properties, and design system. We productize AI
5
+ automations (n8n workflows + autonomous agents wrapped with Claude) for SMB
6
+ clients and deploy them with technician-led setup sessions.
7
+
8
+ **This root is not a git repo** — it's a folder of independent git repos.
9
+
10
+ ## Layout
11
+
12
+ ```
13
+ installagent/
14
+ ├── clients/ # One build repo per client + client-template (the baseline)
15
+ ├── team-clients/ # Client registry (CRM-as-code) — PRIVATE, holds client PII
16
+ ├── team-infra/ # AWS CDK hosting (n8n, SFTP), n8n workflow library, skills
17
+ ├── team-web/ # installagent.com + team hub (Next.js pnpm workspace)
18
+ ├── team-design/ # Install Agent design system source
19
+ ├── team-branding/ # Logo files
20
+ ├── skills/ # Cross-cutting agent skills
21
+ ├── AGENT.md # Canonical rules for all AI coding agents
22
+ └── ONBOARDING.md # New-contractor orientation
23
+ ```
24
+
25
+ ## The two kinds of client folder
26
+
27
+ | | `team-clients/clients/<slug>/` | `clients/client-<slug>/` |
28
+ |---|---|---|
29
+ | Purpose | **Registry / CRM** — who they are | **Build** — what we make for them |
30
+ | Holds | Profile + call history (PII allowed) | Specs, workflows, agents, deliverables (no PII) |
31
+ | Created | The moment a lead arrives | When build work starts (from `client-template`) |
32
+
33
+ Deal status lives in **Airtable** (`Clients - Master`), never in git.
34
+
35
+ ## Quickstarts
36
+
37
+ | Repo | Quickstart |
38
+ |---|---|
39
+ | [`clients/client-template/`](./clients/client-template) | Copy to `clients/client-<slug>/`, fill `CLIENT.md`, `lefthook install` |
40
+ | [`team-web/`](./team-web) | `cd team-web && pnpm install && pnpm dev` |
41
+ | [`team-infra/`](./team-infra) | CDK — see its README; n8n JSON needs no build |
42
+ | [`team-clients/`](./team-clients) | Markdown only — read `CONTRIBUTING.md` before adding a client |
43
+
44
+ ## Conventions
45
+
46
+ The canonical rules live in [`AGENT.md`](./AGENT.md). The TL;DR:
47
+
48
+ - **pnpm only**, no npm/yarn lockfiles.
49
+ - **Biome only**, no ESLint/Prettier.
50
+ - **TypeScript strict**, no `any`.
51
+ - **Tailwind utility classes only**.
52
+ - **No secrets anywhere; no customer data** outside the private registry.
53
+ - **Install Agent, never Rebar,** on anything a client sees.
54
+ - **Don't cross-import** between repos.
55
+
56
+ Each repo has its own `AGENT.md`/`AGENTS.md` (canonical) with stack-specific
57
+ rules; many directories have a short `CLAUDE.md` navigation aid.
58
+
59
+ ## Who works here
60
+
61
+ Currently two people; expanding to contractors. Start with
62
+ [`ONBOARDING.md`](./ONBOARDING.md).
63
+
64
+ ## License
65
+
66
+ Internal. Treat everything as proprietary unless explicitly cleared for
67
+ external sharing.
@@ -0,0 +1,79 @@
1
+ # skills/ — cross-cutting agent skills (technician new-joiner set)
2
+
3
+ Reusable, vendor-neutral how-tos that any coding agent in this workspace reads
4
+ when a task matches the skill's `description`. These live at the workspace
5
+ root because they span repos (a client engagement touches docs, workflows, and
6
+ diagrams across more than one repo) — unlike the repo-local skills in
7
+ `team-clients/skills/` and `team-infra/skills/`.
8
+
9
+ They're mirrored into [`../.claude/skills/`](../.claude/skills/) (via symlink)
10
+ so Claude Code / Cowork auto-register them in the skill menu.
11
+
12
+ ## What's here
13
+
14
+ ```
15
+ skills/
16
+ ├── client-deliverables/ # ORCHESTRATOR — the full client engagement package, checklist + sequencing
17
+ ├── 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
+ ├── client-llm-setup/ # the client's own Claude workspace → branded leave-behind guide
20
+ ├── client-facing-docs/ # the branded client PDFs (exec overview, proposal/SOW, onboarding)
21
+ ├── client-workflow-diagram/ # spec → Excalidraw stage-column diagram
22
+ ├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw (logo + brand red #9b0506)
23
+ ├── design-system/ # the Install Agent Design System (screens/UI)
24
+ ├── house-voice/ # house voice for client-facing writing, pulled from installagent.com/get-started
25
+ ├── contract-tech-agnostic/ # contracts/SOWs by FUNCTION and OUTCOME, never tech (+ SOW template in references/)
26
+ ├── 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
28
+ ```
29
+
30
+ Each is `skills/<name>/SKILL.md`, with bulky tables in `references/`.
31
+
32
+ ## When to use which
33
+
34
+ | If the task is … | Use |
35
+ |---|---|
36
+ | Kicking off / assembling a full client deliverable package | `client-deliverables` |
37
+ | Writing up a discovery/scoping call into build docs | `engagement-spec` |
38
+ | Prepping for an upcoming client call (sheet + readiness check) | `tech-call-prep` |
39
+ | Setting up a client's own Claude workspace / its leave-behind guide | `client-llm-setup` |
40
+ | Producing the branded client PDFs | `client-facing-docs` |
41
+ | Drawing a workflow/architecture diagram for a client | `client-workflow-diagram` |
42
+ | Branding a print/PDF/Excalidraw deliverable | `installagent-brand-kit` |
43
+ | Building or reviewing any UI / web page / funnel / component | `design-system` |
44
+ | Writing or reviewing any client-facing copy (proposal, email, guide, web/ad copy) | `house-voice` |
45
+ | Drafting/reviewing any contract, SOW, MSA, or proposal | `contract-tech-agnostic` |
46
+ | Working an `INS-xxx` issue / a client's Linear project | `linear` |
47
+ | Any task an `ia` command covers (client context, intake, agent bank, secrets, setup/doctor) | `ia-cli` |
48
+
49
+ `design-system` is the **screen** layer (dark, signal-red, Hanken Grotesk); it
50
+ 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
53
+ the **words** layer that applies across both — what client-facing sentences
54
+ sound like, regardless of surface.
55
+
56
+ These complement the repo-local skills they cross-reference:
57
+ `business-research` (team-clients) and `n8n-workflow` + `automation-design`
58
+ (team-infra).
59
+
60
+ ## Convention
61
+
62
+ - One skill per directory: `skills/<name>/SKILL.md` with YAML frontmatter
63
+ (`name`, `description`) — same format as `team-clients/skills/`.
64
+ - The `description` is the trigger: say what the skill does **and** when to use
65
+ it, concretely. Put all "when to use" cues there, not in the body.
66
+ - Keep `SKILL.md` under ~500 lines; push long tables/detail into `references/`.
67
+ - Keep skills sanitized — no secrets, live credentials, internal hostnames,
68
+ account ids, or PII. Use placeholders and point at internal files for the
69
+ real values.
70
+ - If a rule in a skill conflicts with [`../AGENT.md`](../AGENT.md), **AGENT.md
71
+ wins** — update the skill in the same change.
72
+
73
+ ## Adding a skill
74
+
75
+ 1. Create `skills/<name>/SKILL.md` (frontmatter + body). Add `references/` for
76
+ bulky tables.
77
+ 2. Mirror it: `cd ../.claude/skills && ln -s ../../skills/<name> <name>`.
78
+ 3. Add it to the table above. Don't put workspace-wide rules here — those live
79
+ in `AGENT.md`. Skills are how-tos.
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: client-deliverables
3
+ description: >-
4
+ The standard deliverable package Install Agent produces for EVERY client
5
+ engagement. Three things, always: (1) an in-depth internal HTML overview
6
+ (CEO/pricing brief, architecture, tech spec, roadmap/intake), (2) three
7
+ client-facing PDFs (executive overview, proposal & SOW, onboarding
8
+ checklist), and (3) workflow/architecture diagrams. Use this WHENEVER
9
+ standing up a new client engagement, asked "set up the deliverables for
10
+ [client]", "build the client folder", "what do we owe this client", "package
11
+ this up", or working in a client-[slug]/ folder needing the complete set.
12
+ Reach for it even without the word "skill" — any time the goal is the full
13
+ artifact set an engagement should produce. It is an ORCHESTRATOR — composes
14
+ engagement-spec, client-facing-docs, client-workflow-diagram, and
15
+ installagent-brand-kit — and defines the flat client-[slug]/ folder layout
16
+ (per client-template) the new-lead workflow will eventually enforce.
17
+ ---
18
+
19
+ # Client deliverables (the standard package)
20
+
21
+ Every client engagement produces the **same three kinds of artifact**, so any
22
+ teammate (or a contractor landing cold) finds the same things in the same place:
23
+
24
+ 1. **In-depth internal HTML overview** — one self-contained, tabbed `.html`
25
+ that consolidates the full internal picture: CEO/pricing brief · architecture
26
+ · technical spec · roadmap & intake. This is the *deep* version (names tools,
27
+ shows the decision model), more thorough than anything the client sees. Lives
28
+ in `docs/`. Exemplars: `client-kingdom/docs/kingdom-workflow-overview.html`,
29
+ `client-carvision/pricing-agent/client-facing/carvision-pricing-overview.html`.
30
+ 2. **The three client-facing PDFs** — executive overview, proposal & SOW,
31
+ onboarding checklist. Built by **`client-facing-docs`** (branded, decision-maker
32
+ voice).
33
+ 3. **Workflow / architecture diagrams** — the how-it-works picture and any
34
+ mockups, authored as self-contained HTML in `docs/` (2026-07 baseline; no
35
+ `.excalidraw` in client repos — Excalidraw only for pitch-deck images).
36
+ Built by **`client-workflow-diagram`** in the brand's red theme
37
+ (**`installagent-brand-kit`**).
38
+
39
+ Plus **`evidence/`** — required scaffolding (per `client-template`) for dated
40
+ backtest/validation records. Most engagements have nothing to put there until
41
+ there's a decision/prediction component worth validating; it's fine for it to
42
+ hold only its `README.md` until then, but the directory itself must exist
43
+ (`ci/repo-lint.mjs` checks for it).
44
+
45
+ This skill is the **checklist + orchestrator** for producing all three; it does
46
+ not replace the skills that make each piece — it sequences them and owns the
47
+ folder layout. Full layout + build order:
48
+ [`references/package-layout.md`](references/package-layout.md).
49
+
50
+ ## The folder (one per client)
51
+
52
+ Flat, single-project layout — created from `client-template`, enforced per-repo
53
+ by its `ci/repo-lint.mjs`:
54
+
55
+ ```
56
+ client-<slug>/
57
+ ├── AGENT.md / CLAUDE.md / CLIENT.md
58
+ ├── onboarding.html # tabbed open-me-first page: Architecture/Client/Proposals/Public
59
+ ├── docs/ # internal markdown (engagement-spec): 01-overview, 02-tech-spec,
60
+ │ # 03-client-onboarding, ① the in-depth internal HTML (tabbed),
61
+ │ # plus ③ diagrams as self-contained HTML (<system>-<audience>-diagram.html)
62
+ ├── workflows/ # n8n JSON exports, credential IDs scrubbed
63
+ ├── data/ # client-sent raw data — gitignored (README tracked)
64
+ ├── evidence/ # dated backtest/validation records — required, README-only
65
+ │ # until there's a decision/prediction component to validate
66
+ └── web/ # OPTIONAL — pre-populated Next.js scaffold, only if the
67
+ # engagement includes a website build
68
+ ```
69
+
70
+ ② the three branded PDFs (client-facing-docs) are delivered via the client's
71
+ Google Drive folder — there is no `client-facing/` directory anymore, no
72
+ `diagrams/`, and there was never a `legal/` (signed SOW/MSA live in Drive).
73
+
74
+ Don't nest a `<project>/` subfolder — one client is one build tree. (CarVision's
75
+ `pricing-agent/` predates this convention and keeps PDFs/diagrams nested; new
76
+ clients follow the flat layout above.)
77
+
78
+ ## Build order (compose, don't reinvent)
79
+
80
+ 1. **Understand the client** — `business-research` → a registry profile.
81
+ 2. **Scaffold the engagement** — `client-project-kickoff` (the client-folder
82
+ cadence): clarifying questions → research → plan → folder + CLAUDE.md.
83
+ 3. **Write the internal docs** — `engagement-spec` → `docs/` markdown
84
+ (overview / tech-spec / onboarding). The source of truth for content.
85
+ 4. **Consolidate the in-depth internal HTML** — turn the briefs + tech spec +
86
+ roadmap into one tabbed `.html` (see the layout reference). Internal: names
87
+ tools, shows the model.
88
+ 5. **Produce the client PDFs** — `client-facing-docs` (branded; the commercial
89
+ model incl. capped API-credit pass-through).
90
+ 6. **Draw the diagrams** — `client-workflow-diagram` + `installagent-brand-kit`
91
+ (red theme); export images for the deck/overview.
92
+ 7. **Leave `evidence/` scaffolded** — the README-only convention if there's
93
+ nothing to validate yet; a dated record once there is.
94
+
95
+ ## Quality rules
96
+
97
+ - **All three artifact types, every client.** A folder missing the internal
98
+ HTML, the PDF set, or a diagram is incomplete.
99
+ - **`evidence/` and (if scoped) `web/` exist.** `evidence/` is required
100
+ scaffolding even when README-only; `web/` is optional and only present if
101
+ the engagement includes a website build — delete it entirely otherwise.
102
+ - **Internal vs client split holds throughout:** the internal HTML and `docs/`
103
+ name tools; the PDFs stay tech-agnostic (Exhibit A aside). See
104
+ `engagement-spec` / `contract-tech-agnostic`.
105
+ - **One brand:** every visual (HTML, PDFs, diagrams) uses
106
+ `installagent-brand-kit` (official logo + brand red).
107
+ - **No secrets / customer data / real VINs** in committed artifacts (root
108
+ `AGENT.md`); use redacted/sample data.
109
+
110
+ ## Enforcement
111
+
112
+ `client-template`'s `ci/repo-lint.mjs` enforces the skeleton (`docs/`,
113
+ `workflows/`, `data/`, `evidence/` and `onboarding.html` must exist; the
114
+ `.gitignore` must keep `data/` untracked) on every
115
+ push for repos created from the template. It does not check for the in-depth
116
+ internal HTML, the PDFs themselves, or a diagram's contents — that's still this
117
+ skill's job. Full automatic scaffolding on lead conversion (the new-lead /
118
+ new-client n8n workflow, `team-n8n-workflows`) is recorded as a project-level
119
+ intention in root `AGENT.md` but **not built yet**; until then, use
120
+ `client-template` to start a new client repo and this skill as the manual
121
+ checklist for what goes in it.
122
+
123
+ ## Before you finish — checklist
124
+
125
+ - [ ] In-depth internal HTML exists (tabbed: brief · architecture · spec · roadmap), in `docs/`.
126
+ - [ ] The three client PDFs exist (via `client-facing-docs`), on-brand.
127
+ - [ ] At least one workflow/architecture diagram exists (editable + exported).
128
+ - [ ] `evidence/` exists (README-only is fine); `web/` present only if a website was scoped.
129
+ - [ ] Folder matches the flat layout (no nested `<project>/`); `CLAUDE.md` orients the next person.
130
+ - [ ] Internal names tools; client-facing stays tech-agnostic; one brand throughout.
131
+ - [ ] No secrets/customer data; branding is Install Agent.
@@ -0,0 +1,103 @@
1
+ # Package layout + the in-depth internal HTML
2
+
3
+ Detail for the standard per-client deliverable package. Pairs with the SKILL.md.
4
+
5
+ ## Folder layout
6
+
7
+ Flat, single-project layout — created from `client-template`, enforced per-repo
8
+ by its `ci/repo-lint.mjs`. Don't nest a `<project>/` subfolder; if a client ever
9
+ grows a second genuinely distinct project, raise it and decide the shape
10
+ deliberately rather than guessing.
11
+
12
+ ```
13
+ client-<slug>/
14
+ ├── AGENT.md # canonical agent instructions
15
+ ├── CLAUDE.md # pointer + navigation aid
16
+ ├── CLIENT.md # context manifest (Airtable, Drive, registry, no PII)
17
+ ├── docs/ # engagement-spec output (internal markdown)
18
+ │ ├── 01-overview.md # client-facing prose, tech-agnostic
19
+ │ ├── 02-tech-spec.md # internal: names tools, the decision model
20
+ │ ├── 03-client-onboarding.md # what we need from the client
21
+ │ └── <system>-overview.html # ① in-depth INTERNAL html (tabbed), if built
22
+ ├── onboarding.html # tabbed open-me-first page (Architecture/Client/
23
+ │ # Proposals/Public — Public is client-presentable)
24
+ ├── workflows/ # n8n JSON exports, credential IDs scrubbed
25
+ ├── data/ # client-sent raw data — gitignored (README tracked)
26
+ ├── evidence/ # ④ dated backtest/validation records — required,
27
+ │ └── README.md # README-only until there's something to validate
28
+ └── web/ # OPTIONAL — pre-populated Next.js marketing site,
29
+ # only if the engagement includes a website build
30
+ ```
31
+
32
+ ③ diagrams are self-contained HTML in `docs/` (`<system>-<audience>-diagram.html`;
33
+ no `.excalidraw` in client repos since 2026-07). ② the three branded client PDFs
34
+ are delivered via the client's Google Drive folder — `client-facing/` and
35
+ `diagrams/` directories no longer exist, and `legal/` never belonged in git
36
+ (signed SOW/MSA live in Drive).
37
+
38
+ Keep internal artifacts (`docs/`, the HTML) and client-facing artifacts (the
39
+ Drive-delivered PDFs, the Public tab of `onboarding.html`) distinguishable —
40
+ those are the only things a client sees.
41
+
42
+ (CarVision's `pricing-agent/` predates this flat convention and nests its HTML,
43
+ PDFs, and diagrams under a project subfolder — it's a legacy exemplar for
44
+ content/structure, not for folder layout; follow the flat layout above for new
45
+ clients.)
46
+
47
+ ## ① The in-depth internal HTML
48
+
49
+ A single self-contained `.html` (inline CSS/JS, no build step) with **tabs**
50
+ that consolidate the internal picture into one navigable file, living in
51
+ `docs/`. Standard tabs, modeled on
52
+ `client-kingdom/docs/kingdom-workflow-overview.html` and
53
+ `client-carvision/pricing-agent/client-facing/carvision-pricing-overview.html`
54
+ (CarVision predates the current `docs/` placement):
55
+
56
+ | Tab | Contents |
57
+ |---|---|
58
+ | **CEO Brief & Pricing** | The business case + commercial rationale (problem, what we're building, why it's worth it, recommended pricing incl. the capped API-credit pass-through, what to set expectations on). |
59
+ | **Architecture** | The how-it-works diagram + a short narration. Embed the exported diagram image. |
60
+ | **Technical Spec** | The full internal spec: goal, current-state process, systems & data sources, the decision model, architecture, phasing, guardrails, risks, "what we need", effort→pricing rationale. Names tools. |
61
+ | **Roadmap & Intake** | The phased roadmap + the intake checklist (internal view). |
62
+
63
+ It's the deep, single-link reference for the team and contractors — more
64
+ thorough than the three client PDFs, which are distilled from it. Branding via
65
+ `installagent-brand-kit` (official logo + brand red); it can stay light on
66
+ chrome since it's internal, but keep the palette consistent.
67
+
68
+ Build it from the `engagement-spec` markdown (the briefs + tech spec + roadmap)
69
+ — the HTML is a *view* of those, not a separate source of truth. When the spec
70
+ changes, regenerate the HTML in the same pass.
71
+
72
+ ## ② Client PDFs
73
+
74
+ Built by **`client-facing-docs`** → `references/doc-structures.md`. Branded,
75
+ decision-maker voice, the full commercial model.
76
+
77
+ ## ③ Diagrams
78
+
79
+ Built by **`client-workflow-diagram`** (layout: left-to-right stage columns,
80
+ emoji node names; client-facing + internal flavors) skinned with
81
+ **`installagent-brand-kit`** (red theme). Commit the `.excalidraw`; export an
82
+ image for the deck and to embed in the Architecture tab of the internal HTML.
83
+
84
+ ## ④ Evidence
85
+
86
+ `evidence/` holds dated, self-contained `.md` records of backtests/validation
87
+ runs against the client's real data — proof the automation does what we said
88
+ it would, meant to be exported to the client's Drive. Required scaffolding on
89
+ every client repo (per `client-template`); most engagements have nothing to
90
+ put there until there's a decision/prediction component (pricing, scoring,
91
+ categorization, routing) worth backtesting, so it's fine to hold only its
92
+ `README.md` until then. See `evidence/README.md`'s convention for filenames
93
+ and format — one file per run, no raw customer PII, aggregate results only.
94
+
95
+ ## Composing the skills (order)
96
+
97
+ `business-research` → `client-project-kickoff` → `engagement-spec` →
98
+ in-depth internal HTML → `client-facing-docs` → `client-workflow-diagram` +
99
+ `installagent-brand-kit` → scaffold `evidence/` (populate once there's a
100
+ validation run to record).
101
+
102
+ Each step has its own skill that owns the details; this package just guarantees
103
+ the artifact types land, in the right folder, on-brand.