@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
|
@@ -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.
|