@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,175 @@
1
+ """
2
+ Install Agent brand kit — one source of truth for branded diagrams and PDFs.
3
+
4
+ Import this from a generator script (diagram or PDF) so every deliverable uses
5
+ the official palette and the official logo instead of ad-hoc colors/glyphs.
6
+
7
+ import sys; sys.path.append(".../skills/installagent-brand-kit/scripts")
8
+ import brand
9
+
10
+ Palette mirrors team-web/packages/ui/theme.css (the single brand source).
11
+ Light surfaces (client PDFs + diagrams on white) use the ink/muted neutrals
12
+ below; the dark marketing-site neutrals in theme.css are NOT for documents.
13
+ """
14
+ from __future__ import annotations
15
+ import json, math, random
16
+ from pathlib import Path
17
+
18
+ # ─── Brand palette (mirror of theme.css — Design System v1.0 Signal Red) ─────
19
+ # Documents live on WHITE, so the primary uses the design system's DEEP red
20
+ # (#D11A1A = --color-accent-deep), which stays legible on white; the full
21
+ # Signal Red (#FF2D2D = --color-accent) is the bright attention accent.
22
+ BRAND = "#d11a1a" # --color-accent-deep → primary on white
23
+ BRAND_BRIGHT = "#ff2d2d" # --color-accent → bright accent / attention
24
+ BRAND_FG = "#ffffff" # --color-accent-foreground
25
+ BRAND_TINT = "#fdeaea" # light red fill (callouts, header bands)
26
+ ROW_TINT = "#fbf2f2" # zebra-row tint for tables
27
+
28
+ # Document neutrals (text/lines on white — NOT the dark-site neutrals)
29
+ INK = "#1f2430" # headings / strong text
30
+ BODY = "#2b3440" # body text
31
+ MUTED = "#5b6675" # secondary text
32
+ FAINT = "#8a93a0" # captions / footers
33
+ LINE = "#cfd5dd" # card borders
34
+ GRID = "#e8ebef" # table gridlines
35
+ HAIR = "#e4e8ee" # hairline rules
36
+ SOFT = "#f4f6f9" # neutral fill
37
+ WHITE = "#ffffff"
38
+ TRANSP = "transparent"
39
+
40
+ # Typography (Design System v1.0 — font files load per-app; documents fall
41
+ # back gracefully to a system sans/mono in a sandbox render).
42
+ FONT_BODY = '"Hanken Grotesk", -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif'
43
+ FONT_DISPLAY = FONT_BODY # Hanken Grotesk does both display and body
44
+ FONT_MONO = '"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
45
+
46
+ # ─── Official logo assets ────────────────────────────────────────────────────
47
+ ASSET_DIR = Path(__file__).resolve().parent.parent / "assets"
48
+ LOGO_PATH = ASSET_DIR / "installagent-logo.svg" # full wordmark + icon lockup
49
+ MARK_PATH = ASSET_DIR / "installagent-mark.svg" # icon only
50
+
51
+ def logo_svg(mark_only: bool = False, wordmark_color: str = INK) -> str:
52
+ """Return the official logo as an inline SVG string (embeddable in HTML).
53
+ The icon keeps its red gradient; the wordmark uses currentColor, so we wrap
54
+ it in a span/color via the returned markup's `color`."""
55
+ svg = (MARK_PATH if mark_only else LOGO_PATH).read_text()
56
+ # the wordmark path is fill="currentColor"; set it via a wrapping color
57
+ return f'<span style="color:{wordmark_color};display:inline-flex">{svg}</span>'
58
+
59
+ # ═════════════════════════════════════════════════════════════════════════════
60
+ # EXCALIDRAW — red house theme (matches the client-facing diagram set)
61
+ # ═════════════════════════════════════════════════════════════════════════════
62
+ def _rid(): return str(random.randint(10**9, 10**10))
63
+ def _nz(): return random.randint(10**8, 10**9)
64
+
65
+ class Excalidraw:
66
+ """Minimal Excalidraw builder in the Install Agent red theme.
67
+
68
+ Conventions match the repo's existing .excalidraw files: version 2,
69
+ roughness 0, fontFamily 2, source installagent.com. Brand red is the only
70
+ accent; everything else is document neutrals.
71
+ """
72
+ def __init__(self):
73
+ self.els = []
74
+
75
+ def _base(self, t, x, y, w, h, stroke, bg, sw, dashed=False, roundness=None):
76
+ return {"id": _rid(), "type": t, "x": x, "y": y, "width": w, "height": h,
77
+ "angle": 0, "strokeColor": stroke, "backgroundColor": bg, "fillStyle": "solid",
78
+ "strokeWidth": sw, "strokeStyle": "dashed" if dashed else "solid", "roughness": 0,
79
+ "opacity": 100, "groupIds": [], "frameId": None, "roundness": roundness,
80
+ "seed": _nz(), "version": 1, "versionNonce": _nz(), "isDeleted": False,
81
+ "boundElements": [], "updated": 1, "link": None, "locked": False}
82
+
83
+ def rect(self, x, y, w, h, stroke=LINE, bg=WHITE, sw=1.5, radius=True):
84
+ self.els.append(self._base("rectangle", x, y, w, h, stroke, bg, sw,
85
+ roundness={"type": 3} if radius else None)); return self
86
+
87
+ def line(self, x1, y1, x2, y2, color=GRID, sw=1, dashed=False):
88
+ e = self._base("line", x1, y1, abs(x2-x1), abs(y2-y1), color, TRANSP, sw, dashed=dashed)
89
+ e.update({"points": [[0, 0], [round(x2-x1, 1), round(y2-y1, 1)]], "lastCommittedPoint": None,
90
+ "startBinding": None, "endBinding": None, "startArrowhead": None, "endArrowhead": None})
91
+ self.els.append(e); return self
92
+
93
+ def arrow(self, pts, color=MUTED, dashed=False, sw=1.6):
94
+ xs = [p[0] for p in pts]; ys = [p[1] for p in pts]; x0, y0 = pts[0]
95
+ e = self._base("arrow", x0, y0, abs(max(xs)-min(xs)), abs(max(ys)-min(ys)),
96
+ color, TRANSP, sw, dashed=dashed, roundness={"type": 2})
97
+ e.update({"points": [[round(px-x0, 1), round(py-y0, 1)] for px, py in pts],
98
+ "lastCommittedPoint": None, "startBinding": None, "endBinding": None,
99
+ "startArrowhead": None, "endArrowhead": "arrow"})
100
+ self.els.append(e); return self
101
+
102
+ def ellipse(self, x, y, w, h, stroke=INK, bg=TRANSP, sw=1.5):
103
+ self.els.append(self._base("ellipse", x, y, w, h, stroke, bg, sw)); return self
104
+
105
+ def text(self, x, y, s, size=12, color=INK, bold=False, align="left", w=None):
106
+ lines = s.split("\n"); maxlen = max(len(l) for l in lines)
107
+ tw = w if w is not None else max(20, int(maxlen*size*0.55)); th = int(len(lines)*size*1.25)
108
+ e = self._base("text", x, y, tw, th, color, TRANSP, 1)
109
+ e.update({"text": s, "fontSize": size, "fontFamily": 2, "textAlign": align,
110
+ "verticalAlign": "top", "containerId": None, "originalText": s,
111
+ "lineHeight": 1.25, "baseline": int(size*0.9)})
112
+ self.els.append(e); return self
113
+
114
+ def dump(self, path):
115
+ doc = {"type": "excalidraw", "version": 2, "source": "https://installagent.com",
116
+ "elements": self.els, "appState": {"viewBackgroundColor": "#ffffff", "gridSize": None},
117
+ "files": {}}
118
+ Path(path).write_text(json.dumps(doc, ensure_ascii=True, indent=1))
119
+ json.loads(Path(path).read_text()) # validate
120
+ return path
121
+
122
+ # ═════════════════════════════════════════════════════════════════════════════
123
+ # BRANDED PDF — weasyprint HTML/CSS with the official logo + brand color
124
+ # ═════════════════════════════════════════════════════════════════════════════
125
+ def pdf_css(size="Letter", accent=BRAND) -> str:
126
+ """Shared print CSS: page setup, running footer with page numbers, brand
127
+ tokens, and the component classes (callouts, tables, signature blocks)."""
128
+ return f"""
129
+ @page {{ size: {size}; margin: 16mm 17mm 14mm 17mm;
130
+ @top-left {{ content: element(rhead); }}
131
+ @bottom-left {{ content:"Install Agent · Confidential"; font-size:8pt; color:{FAINT}; }}
132
+ @bottom-right {{ content:"Page " counter(page) " of " counter(pages); font-size:8pt; color:{FAINT}; }} }}
133
+ @page:first {{ @top-left {{ content: none }} }}
134
+ * {{ box-sizing:border-box }}
135
+ body {{ margin:0; color:{BODY}; font-family:{FONT_BODY}; font-size:10.3pt; line-height:1.5; }}
136
+ h1,h2,h3 {{ color:{INK}; font-family:{FONT_DISPLAY}; line-height:1.2; }}
137
+ strong {{ color:{INK}; }}
138
+ .rhead {{ position:running(rhead); width:100%; font-size:8pt; color:{FAINT}; display:flex; align-items:center; gap:7px; }}
139
+ .rhead svg {{ height:13px; width:auto; }}
140
+ .hero {{ border-bottom:2px solid {INK}; padding-bottom:11px; margin-bottom:14px; }}
141
+ .brandrow {{ display:flex; align-items:center; gap:10px; margin-bottom:12px; }}
142
+ .brandrow svg {{ height:26px; width:auto; }}
143
+ .kicker {{ font-size:8.4pt; letter-spacing:.13em; text-transform:uppercase; color:{accent}; font-weight:700; }}
144
+ h1.title {{ font-size:23pt; margin:7px 0 4px; letter-spacing:-.01em; }}
145
+ .sub {{ font-size:11pt; color:{MUTED}; margin:0; }}
146
+ h2 {{ font-size:12pt; margin:16px 0 5px; padding-top:8px; border-top:1px solid {HAIR}; }}
147
+ h2 .n {{ color:{accent}; font-weight:700; margin-right:.5em; }}
148
+ .call {{ border:1px solid {HAIR}; border-left-width:4px; border-radius:0 9px 9px 0; padding:10px 13px; margin:11px 0; background:#fcfdff; }}
149
+ .call.info {{ border-left-color:{accent}; background:{BRAND_TINT}; }}
150
+ table {{ border-collapse:collapse; width:100%; margin:10px 0; font-size:9.4pt; }}
151
+ th,td {{ border:1px solid {HAIR}; padding:7px 9px; text-align:left; vertical-align:top; }}
152
+ thead th {{ background:{accent}; color:{BRAND_FG}; font-size:8.6pt; }}
153
+ tbody tr {{ break-inside:avoid; page-break-inside:avoid; }}
154
+ tbody tr:nth-child(even) {{ background:{ROW_TINT}; }}
155
+ .sigline {{ margin-top:26px; border-top:1px solid {FAINT}; padding-top:4px; font-size:8.4pt; color:{MUTED}; }}
156
+ """
157
+
158
+ def pdf_hero(kicker, title, sub, meta_html="") -> str:
159
+ """Branded hero header with the OFFICIAL logo (not a generic glyph)."""
160
+ return f"""
161
+ <div class="rhead">{logo_svg(mark_only=True)}<b style="color:{MUTED};font-weight:600">Install Agent</b></div>
162
+ <div class="hero">
163
+ <div class="brandrow">{logo_svg(mark_only=False, wordmark_color=INK)}</div>
164
+ <div class="kicker">{kicker}</div>
165
+ <h1 class="title">{title}</h1>
166
+ <p class="sub">{sub}</p>
167
+ {meta_html}
168
+ </div>"""
169
+
170
+ def render_pdf(html_body: str, out_path: str, head_extra: str = ""):
171
+ """Render an HTML body (after pdf_hero + content) to a branded PDF."""
172
+ from weasyprint import HTML
173
+ html = f"<!DOCTYPE html><html><head><meta charset='utf-8'><style>{pdf_css()}{head_extra}</style></head><body>{html_body}</body></html>"
174
+ HTML(string=html, base_url=str(ASSET_DIR)).write_pdf(out_path)
175
+ return out_path
@@ -0,0 +1,186 @@
1
+ ---
2
+ name: linear
3
+ description: >-
4
+ Linear issue workflow for Install Agent client build work — retrieving and
5
+ updating issues, status discipline (Backlog → In Progress → In Review →
6
+ Done), sub-issue tree creation (with the sortOrder/blockedBy ordering
7
+ workaround), resolution write-ups, and PR linking for the client-[slug]
8
+ repos that do push to GitHub. Use this WHENEVER you're working an issue
9
+ identified by INS-xxx, a client's `linear_project` (from its CLIENT.md),
10
+ or someone says "check Linear", "update the issue", "make sub-issues for
11
+ this", "what's the status of INS-xxx", or "link this PR to the issue".
12
+ Every client-[slug]/CLIENT.md has a linear_project field — this is how
13
+ build work for that engagement is tracked.
14
+ ---
15
+
16
+ # Linear issue workflow
17
+
18
+ Install Agent tracks client build work in a single shared Linear workspace
19
+ (`install-agent`), one team ("Install Agent", key **`INS`**), with **one
20
+ Linear project per client engagement** (CarVision, Best Materials, Lazar
21
+ Stucco, Operations, …). A client's project is named in that client's
22
+ `CLIENT.md` under `linear_project` — always set `project` to that project
23
+ when creating issues for the engagement, not just `team`.
24
+
25
+ Issue identifiers are always `INS-xxx` — there is no per-client prefix.
26
+
27
+ ## Tools
28
+
29
+ This workspace uses the `mcp__claude_ai_Linear__*` connector, not a
30
+ `linear-server` MCP. If those tools aren't available, search for them before
31
+ assuming Linear isn't wired up — connector names have changed before and may
32
+ again. Key tools and quirks worth knowing up front:
33
+
34
+ - **`save_issue` is a single upsert** — pass `id` to update an existing issue,
35
+ omit it to create one. There's no separate create/update call.
36
+ - **`labels` replaces the full set** on update — it is not additive. To add
37
+ one label to an issue that already has others, pass the complete desired
38
+ label list, not just the new one.
39
+ - **`blockedBy` is append-only** — passing it again never removes an existing
40
+ relation, so it's safe to call repeatedly while building out a dependency
41
+ graph.
42
+ - **No `sortOrder` parameter** exists on `save_issue` — see the sub-issue
43
+ section below for the workaround this requires.
44
+ - **`get_issue` returns the issue's auto-generated git branch name**
45
+ (e.g. `angello/ins-40-fix-sftp-upload-path-...`) — reuse it verbatim as the
46
+ actual branch name in `client-<slug>` repos that use git branches, so the
47
+ branch Linear displays on the issue matches the one you pushed.
48
+
49
+ ## Status discipline
50
+
51
+ Statuses on this team: `Backlog` → `Todo` → `In Progress` → `In Review` →
52
+ `Done` (plus `Canceled` / `Duplicate` as needed). Discipline:
53
+
54
+ 1. Mark **In Progress** the moment you start planning or implementing — signals
55
+ to Angello/teammates the issue is owned.
56
+ 2. Mark **In Review** only when there's something to review — a PR is open
57
+ (see *PR linking* below), or the work is otherwise ready for the client or
58
+ teammate to sign off. Skip this state for issues with no review step.
59
+ 3. Mark **Done** only once the work is actually verified — merged, deployed,
60
+ or confirmed working. Not "I think this is right."
61
+ 4. **Close out each issue before starting the next.** Don't batch status
62
+ updates and write-ups to the end of a session — that's how issues sit in
63
+ "In Progress" days after the work actually finished.
64
+
65
+ ## Creating issues
66
+
67
+ - Set `project` to the client's Linear project (from `CLIENT.md`), not just
68
+ `team: "Install Agent"` — otherwise the issue lands untriaged instead of in
69
+ the engagement's project.
70
+ - Reuse existing labels where they fit before inventing new ones — call
71
+ `list_issue_labels` first. This workspace's labels are per-project
72
+ workstream tags (e.g. CarVision uses `Data Ingestion`, `Daily Workflow`,
73
+ `Backtest & Accuracy`, `Nestor Loop`, `Doc Hygiene`), plus generic `Bug` /
74
+ `Feature` / `Improvement`. There's no blanket "AI-generated" label
75
+ convention here — don't invent one unless asked.
76
+ - **Never put client-facing prices in Linear** — no dollar amounts, billing
77
+ splits, or "$X,XXX signed" phrasing in titles, descriptions, or comments,
78
+ even when quoting straight from a signed SoW. Install Agent staff (not just
79
+ the client-account owner) use this workspace, and pricing isn't their
80
+ business to see. Reference scope by name/phase instead (e.g. "Phase B —
81
+ QuickBooks migration" not "Phase B — $6,000 signed"); if a phase needs a
82
+ pointer to the actual number, link to `docs/phasing-and-pricing.md` in the
83
+ client repo rather than restating the figure.
84
+
85
+ ## Creating sub-issue trees
86
+
87
+ Same real Linear/MCP mechanics as any workspace, so these still apply:
88
+
89
+ ### 1. Prefix titles with an ordering index
90
+
91
+ The Sub-issues panel orders children by `sortOrder`, which **defaults to
92
+ newest-first**, and `save_issue` doesn't expose `sortOrder` at create time —
93
+ you can't set intended order directly. Workaround: encode order in the title:
94
+
95
+ ```plaintext
96
+ [1] [db] add schema fields
97
+ [2] [db] new table + repository
98
+ [3] [service] business logic layer
99
+ [4] [api] REST endpoints
100
+ [4.1] [sdk] client SDK wrapper
101
+ ```
102
+
103
+ Dotted numbering (`[n.m.k]`) should mirror parent-child nesting so the index
104
+ and the tree agree even when the panel's display order shuffles.
105
+
106
+ ### 2. Nest by logical parent-child, not flat under the root
107
+
108
+ Linear supports unlimited sub-issue depth. Group by main-subordinate logic
109
+ (core → its dependents) rather than piling 8+ siblings flat under one root.
110
+ Use `parentId` at creation, or `save_issue` with `id` + `parentId` to move an
111
+ issue later — moving doesn't disturb its `blockedBy` relations.
112
+
113
+ ### 3. Creation order follows `blockedBy`
114
+
115
+ `blockedBy` needs the blocker's identifier to exist first, so:
116
+
117
+ 1. Topologically sort the dependency graph — leaves (no deps) first, roots last.
118
+ 2. Create zero-dependency issues in the first wave.
119
+ 3. Create dependents only after collecting blocker identifiers from prior calls.
120
+ 4. `blockedBy` is append-only, so re-running a call with the same value is safe.
121
+
122
+ Don't try to parallelize this to save round-trips — tool calls in one message
123
+ still execute sequentially server-side, and later issues need identifiers
124
+ from earlier responses regardless.
125
+
126
+ ### 4. Keep each sub-issue description self-contained
127
+
128
+ State goal, key files/systems touched, concrete acceptance criteria,
129
+ dependencies (by `INS-xxx`), and validation steps — whoever picks up the
130
+ sub-issue may never open the parent.
131
+
132
+ ## Resolution write-ups
133
+
134
+ The observed convention in this workspace is to **edit the issue's own
135
+ description in place** when it's resolved, prefixing it:
136
+
137
+ ```markdown
138
+ **Resolved (2026-07-15)** — one or two sentences on what happened and
139
+ why, referencing the evidence doc or commit if there is one.
140
+ ```
141
+
142
+ This is what the existing `INS-xxx` issues in the CarVision project actually
143
+ do (no separate completion comments in use here) — it puts the outcome where
144
+ a PM or client landing on the issue sees it first, without having to open a
145
+ comment thread or a diff. When you cross-reference another issue, just write
146
+ its identifier (`INS-28`) — Linear auto-links it.
147
+
148
+ Use `save_comment` instead of an in-place edit when the resolution is a
149
+ long-running discussion thread (e.g. going back and forth with a client
150
+ contact) rather than a one-shot outcome — don't force that into the
151
+ description.
152
+
153
+ ## PR linking (only where a GitHub remote exists)
154
+
155
+ Client-<slug> repos are **local-git by default**; pushing to GitHub is a
156
+ per-client decision (some `clients/client-<slug>/` repos have an `origin`
157
+ remote today, several don't). Most build work in this workspace — n8n
158
+ workflow JSON, docs, evidence files — never produces a PR at all. So:
159
+
160
+ 1. **Check first**: `git -C clients/client-<slug> remote -v`. No remote (or
161
+ no PR for this change) → skip this section entirely; just update the
162
+ issue status and write the resolution note above.
163
+ 2. **If the repo has a GitHub remote and this change ships via a PR**: include
164
+ a magic keyword in the PR body — `Fixes INS-123`, `Closes INS-123`, or
165
+ `Resolves INS-123` — so Linear auto-links the PR and auto-closes the issue
166
+ on merge. Still mark the issue **In Review** yourself when the PR goes up;
167
+ don't wait for the merge-triggered auto-close as your only status update.
168
+ 3. Reuse the issue's `gitBranchName` (from `get_issue`) as the actual branch
169
+ name where practical, so the branch on GitHub matches what Linear displays
170
+ on the issue.
171
+
172
+ ## Validation before marking an issue In Review / Done
173
+
174
+ If the issue involves a code change in a `client-<slug>/web/` (Next.js)
175
+ scaffold, run the same checks CI and Lefthook run there:
176
+
177
+ ```bash
178
+ pnpm lint # biome lint .
179
+ pnpm type-check # tsc --noEmit
180
+ pnpm test # vitest run --passWithNoTests
181
+ ```
182
+
183
+ For everything else in a client build repo (workflow JSON, docs, evidence —
184
+ the majority of this work), there's no equivalent build/test step; rely on
185
+ `ci/repo-lint.mjs` (already enforced pre-commit via Lefthook in these repos)
186
+ rather than inventing a validation command that doesn't exist.
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: tech-call-prep
3
+ description: >-
4
+ Verify a technician is actually prepared for an upcoming client call and
5
+ generate the one-page per-client call sheet they run it from. Reads the
6
+ registry (team-clients/clients/[slug]/) and the build repo
7
+ (clients/client-[slug]/ docs 01–04, onboarding.html), checks the
8
+ come-prepared checklist (repo scaffolded, engagement docs drafted, proposals
9
+ loaded), and writes docs/05-call-sheet.md with tailored questions, access
10
+ gaps, and proposal talking points. Use this WHENEVER a discovery/scoping
11
+ call is coming up, or someone says "prep me for the call with [client]",
12
+ "generate the call sheet", "am I ready for the [client] call?", or you're
13
+ working in a client-[slug]/ repo before a call. Reach for it even if the
14
+ user never says "skill" — turning the registry profile + call history +
15
+ engagement docs into a concrete plan for the next conversation. The static
16
+ call script lives on the team hub (Techs → Discovery call); this skill
17
+ produces the per-client half.
18
+ ---
19
+
20
+ # Tech call prep — the per-client call sheet
21
+
22
+ The call script is static and lives on the team hub (`/docs/technicians/
23
+ discovery-call`). This skill produces the other half: the **call sheet** —
24
+ one page, specific to this client and this call, that the technician
25
+ actually runs from. It also refuses to produce one if the prep behind it
26
+ hasn't happened, because a call sheet over an empty repo is theater.
27
+
28
+ ## Inputs
29
+
30
+ - **Client slug** (required). Registry: `team-clients/clients/<slug>/`.
31
+ Build repo: `clients/client-<slug>/`.
32
+ - **Call type** (default: tech discovery call). Also works for monthly
33
+ scoping calls — same sheet, shorter question list, current-month
34
+ delivery status added.
35
+
36
+ ## Workflow
37
+
38
+ ### 1. Read everything first
39
+
40
+ In order: registry `PROFILE.md` (including Internal notes — that's where
41
+ name mis-transcriptions and discrepancies live), every file in registry
42
+ `calls/`, then the build repo's `CLIENT.md`, `docs/00`–`04`, and
43
+ `onboarding.html` (Proposals tab + access table). For a monthly scoping
44
+ call, add `docs/00-delivery-log.md` and `evidence/`.
45
+
46
+ Then derive the client's **vertical** from registry `PROFILE.md` §
47
+ "Industry & business model" (primary industry / NAICS) and look for a
48
+ matching playbook in
49
+ `team-web/apps/docs/content/docs/sales/industry-playbooks/` (`ls` the
50
+ directory; match on vertical, not exact wording — roofing contractor →
51
+ `roofing.mdx`). If one matches, its default wedge + automation list
52
+ feed the sheet's **Vertical context** block. If none matches, that goes
53
+ on the sheet as a prep-gap line ("no industry playbook for
54
+ \<vertical\>") — a real signal for the technician, never a silent skip.
55
+
56
+ ### 2. Verify the come-prepared checklist
57
+
58
+ Check, honestly, against the build repo:
59
+
60
+ | Check | Pass looks like |
61
+ | --- | --- |
62
+ | Repo scaffolded | `client-<slug>/` exists with the template skeleton (docs/, workflows/, data/, evidence/, onboarding.html) |
63
+ | Engagement docs drafted | `docs/01`–`04` exist and reflect the *latest* registry call, not the template |
64
+ | Proposals loaded | `onboarding.html` Proposals tab has ≥1 non-placeholder row per pitchable build, each grounded in a registry call file |
65
+ | Access tracker real | `04-access-checklist.md` statuses are set from calls, not left as template defaults |
66
+
67
+ Anything failing goes into a **PREP GAPS** block at the top of the sheet
68
+ with the fix (usually: run `engagement-spec`, or fill the Proposals tab).
69
+ If the repo doesn't exist at all, stop and say so — scaffolding comes
70
+ first (`client-template`), not a call sheet.
71
+
72
+ ### 3. Write `docs/05-call-sheet.md`
73
+
74
+ One page in the build repo, overwritten per call (it's a prep artifact,
75
+ not a record — records are registry call notes). Structure:
76
+
77
+ ```markdown
78
+ # Call sheet — <Client> — <call type> — <YYYY-MM-DD>
79
+
80
+ > Generated <date> by tech-call-prep. Script: team hub → Techs → Discovery call.
81
+
82
+ ## Prep gaps <!-- omit section if none -->
83
+ - [ ] <gap> → <fix>
84
+
85
+ ## Read-back facts <!-- 5–8 bullets max -->
86
+ - <who they are, in one line — verified name spelling>
87
+ - <the primary pain, in the client's own words, quoted from a call note>
88
+ - <commercial state: trial/signed, what's been paid, per registry + Airtable>
89
+ - <landmines: prior failed automation, name confusion, discrepancies>
90
+
91
+ ## Vertical context <!-- from industry-playbooks/<vertical>.mdx; if no playbook, log in Prep gaps instead -->
92
+ - Proven wedge: <the playbook's default wedge, one line>
93
+ - Common automations: <2–3 from the playbook, most relevant to this client first>
94
+
95
+ ## The month-one pitch
96
+ - Lead: <primary candidate> — because <their stated cost>.
97
+ - Park for later: <other CANDIDATE rows, one line each>.
98
+ - Outcome sentence to get agreed: "By <date>, <process> goes from
99
+ <current cost> to <target state>."
100
+
101
+ ## Questions to ask <!-- ONLY unanswered ones -->
102
+ - <question> → fills <02-tech-spec §X / trigger / volume / …>
103
+
104
+ ## Access to chase <!-- from 04-access-checklist.md -->
105
+ - <item> — MISSING/REQUESTED — <how they grant it, minimum role>
106
+
107
+ ## Close checklist
108
+ - [ ] Outcome sentence agreed out loud
109
+ - [ ] Point of contact named
110
+ - [ ] Working session booked (if any OAuth/2FA items)
111
+ - [ ] LLM-setup session booked
112
+ - [ ] Recap sent same day; docs 01–04 + onboarding.html updated
113
+ ```
114
+
115
+ ## Quality rules
116
+
117
+ - **Questions come from gaps, not templates.** A question already
118
+ answered in a call note never appears on the sheet — the sheet's job
119
+ is to prove to the client we listened. Every question names the doc
120
+ section its answer fills.
121
+ - **Facts get verified, not copied.** Transcripts mangle names; the
122
+ registry's Internal notes section is authoritative for known
123
+ discrepancies. Never propagate a mis-transcription onto a sheet the
124
+ tech will read out loud.
125
+ - **One page.** If it doesn't fit, the read-back facts are too long or
126
+ the questions aren't prioritized. The tech glances at this mid-call.
127
+ - **No PII beyond what the build repo already allows** — the sheet lives
128
+ in `client-<slug>/docs/`, so contact names are fine, but nothing from
129
+ the registry that the build repo's rules exclude (no personal
130
+ emails/phones — point at the registry instead), and never credentials.
131
+
132
+ ## Before you finish — checklist
133
+
134
+ - [ ] All four prep checks ran against the real repo (not assumed).
135
+ - [ ] Prep gaps, if any, are at the top with fixes — not buried.
136
+ - [ ] Every question maps to an unfilled doc section.
137
+ - [ ] Access list matches `04-access-checklist.md` exactly.
138
+ - [ ] Vertical context comes from a real playbook file — or its absence
139
+ is a prep-gap line, not a silently missing section.
140
+ - [ ] Sheet is ≤1 page; landmines (name spelling, prior failures) are in
141
+ read-back facts.