@installagent/sdk 0.10.0 → 0.11.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.js +1 -1
- package/dist/client-drift.d.ts +6 -0
- package/dist/client-drift.js +30 -28
- package/dist/index.d.ts +4 -2
- package/dist/index.js +4 -2
- package/dist/roadmap-migrate.d.ts +75 -0
- package/dist/roadmap-migrate.js +328 -0
- package/dist/roadmap-retire.d.ts +61 -0
- package/dist/roadmap-retire.js +416 -0
- package/dist/template-sync.d.ts +38 -11
- package/dist/template-sync.js +88 -21
- package/package.json +1 -1
- package/templates/workspace-root/skills/client-latest/SKILL.md +1 -1
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +47 -21
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +40 -17
- package/templates/workspace-root/skills/ia-cli/SKILL.md +1 -0
- package/templates/workspace-root/skills/linear/SKILL.md +32 -0
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +7 -3
package/dist/template-sync.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { existsSync } from "node:fs";
|
|
2
|
-
import { copyFile, mkdir, readdir, readFile } from "node:fs/promises";
|
|
1
|
+
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
2
|
+
import { copyFile, mkdir, readdir, readFile, rm } from "node:fs/promises";
|
|
3
3
|
import { dirname, join, resolve } from "node:path";
|
|
4
4
|
import { readGcpManifestFromRepo } from "./client-manifest.js";
|
|
5
5
|
/**
|
|
@@ -41,10 +41,6 @@ export const TEMPLATE_SYNCED_FILES = [
|
|
|
41
41
|
// repo-lint imports log-progress (rule 9), so the two always travel together.
|
|
42
42
|
"ci/log-progress.mjs",
|
|
43
43
|
"ci/log-progress.test.mjs",
|
|
44
|
-
// repo-lint also imports roadmap (rule 10): the Roadmap tab + client roadmap
|
|
45
|
-
// are generated from docs/06-roadmap.md.
|
|
46
|
-
"ci/roadmap.mjs",
|
|
47
|
-
"ci/roadmap.test.mjs",
|
|
48
44
|
// repo-lint also imports builds-manifest (rule 11): the `## Builds` block
|
|
49
45
|
// of CLIENT.md, the source of `ia portal sync-builds`.
|
|
50
46
|
"ci/builds-manifest.mjs",
|
|
@@ -53,8 +49,13 @@ export const TEMPLATE_SYNCED_FILES = [
|
|
|
53
49
|
// and Builds-card blocks of onboarding.html (client drift program, step 3).
|
|
54
50
|
"ci/onboarding.mjs",
|
|
55
51
|
"ci/onboarding.test.mjs",
|
|
56
|
-
//
|
|
57
|
-
//
|
|
52
|
+
// repo-lint also imports access (rule 21, 2026-11-08): docs/04 §1 is the one
|
|
53
|
+
// source of access status; the client's block in docs/03 is generated.
|
|
54
|
+
"ci/access.mjs",
|
|
55
|
+
"ci/access.test.mjs",
|
|
56
|
+
// The one write command for every generated view (progress list,
|
|
57
|
+
// onboarding blocks, the access block): rules 9, 18 and 21 name it,
|
|
58
|
+
// CADENCE.md points at it.
|
|
58
59
|
"ci/sync.mjs",
|
|
59
60
|
"ci/sync.test.mjs",
|
|
60
61
|
"lefthook.yml",
|
|
@@ -66,19 +67,75 @@ export const TEMPLATE_SYNCED_FILES = [
|
|
|
66
67
|
"docs/kickoff-presentation.html",
|
|
67
68
|
];
|
|
68
69
|
/**
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
* hand copy, recorded in that repo's own commit.
|
|
70
|
+
* Files the template used to sync and has since retired. A client repo that
|
|
71
|
+
* still has one is not in sync: the dry run lists it as `retired`, and
|
|
72
|
+
* `--apply` deletes it (`deleted`). Nothing else is ever deleted.
|
|
73
73
|
*
|
|
74
|
-
*
|
|
75
|
-
* and
|
|
76
|
-
*
|
|
77
|
-
*
|
|
74
|
+
* ci/roadmap.mjs + its test (2026-11-08): docs/06-roadmap.md is retired —
|
|
75
|
+
* Linear owns the order of work and the portal reads Now / Next / Later from
|
|
76
|
+
* it. The per-client docs/06-roadmap.md itself is history: `ia roadmap-retire`
|
|
77
|
+
* moves it to docs/archive/, never this operation.
|
|
78
78
|
*/
|
|
79
|
-
export const
|
|
80
|
-
|
|
81
|
-
|
|
79
|
+
export const TEMPLATE_RETIRED_FILES = ["ci/roadmap.mjs", "ci/roadmap.test.mjs"];
|
|
80
|
+
const AD_HOC = "ad hoc repo: CLIENT.md says `linear_project: none`, so it is not an official Install Agent project — no template-sync, no Linear-based rule; it keeps its own docs/06-roadmap.md and rules";
|
|
81
|
+
const AD_HOC_BACKLOG = "ad hoc repo: CLIENT.md has `backlog:` in place of a Linear project — its CADENCE.md, lefthook.yml and CI are its own; copy a shared ci/ change by hand";
|
|
82
|
+
/**
|
|
83
|
+
* Why a client repo is ad hoc (not an official Install Agent project), or null.
|
|
84
|
+
* The repo says so itself, in its CLIENT.md: `linear_project: none`, or a
|
|
85
|
+
* `backlog:` key in place of a Linear project. A new repo still holds the
|
|
86
|
+
* template placeholder and is official. The names are read at run time and
|
|
87
|
+
* never listed in this package: @installagent/sdk is public on npm.
|
|
88
|
+
*
|
|
89
|
+
* Ad hoc repos are listed (so a report shows they were seen) but never compared
|
|
90
|
+
* and never written by `template-sync` (not even `--apply`), and `client-drift
|
|
91
|
+
* --all`, `roadmap-migrate --all` and `roadmap-retire --all` skip them and say
|
|
92
|
+
* so. A shared rule change reaches them only by a hand copy, recorded in that
|
|
93
|
+
* repo's own commit. The portal falls back to their hand today / next.
|
|
94
|
+
*/
|
|
95
|
+
export function adhocReason(repoDir) {
|
|
96
|
+
const path = join(repoDir, "CLIENT.md");
|
|
97
|
+
if (!existsSync(path))
|
|
98
|
+
return null;
|
|
99
|
+
const text = readFileSync(path, "utf8");
|
|
100
|
+
if (/^backlog\s*:/m.test(text))
|
|
101
|
+
return AD_HOC_BACKLOG;
|
|
102
|
+
const linear = /^linear_project\s*:\s*(\S*)/m.exec(text)?.[1] ?? "";
|
|
103
|
+
return linear.toLowerCase() === "none" ? AD_HOC : null;
|
|
104
|
+
}
|
|
105
|
+
const CLIENT_SLUG = /^[a-z0-9][a-z0-9-]*$/;
|
|
106
|
+
/**
|
|
107
|
+
* The client slugs an operation runs on: one named slug (its checkout must
|
|
108
|
+
* exist; an ad hoc repo is kept, so the caller can say why it skips it), or
|
|
109
|
+
* every clients/client-*\/ checkout except client-template with `all`, where
|
|
110
|
+
* the ad hoc repos are left out and returned in `adhoc` so the report can say so.
|
|
111
|
+
*/
|
|
112
|
+
export function selectClientSlugs(workspaceDir, options, op) {
|
|
113
|
+
if (Boolean(options.slug) === Boolean(options.all)) {
|
|
114
|
+
throw new Error(`${op} needs a slug or --all (one of them, not both)`);
|
|
115
|
+
}
|
|
116
|
+
const clientsDir = join(workspaceDir, "clients");
|
|
117
|
+
if (options.all) {
|
|
118
|
+
const all = existsSync(clientsDir)
|
|
119
|
+
? readdirSync(clientsDir, { withFileTypes: true })
|
|
120
|
+
.filter((e) => e.isDirectory() && e.name.startsWith("client-") && e.name !== "client-template")
|
|
121
|
+
.map((e) => e.name.slice("client-".length))
|
|
122
|
+
.sort()
|
|
123
|
+
: [];
|
|
124
|
+
const isAdhoc = (slug) => adhocReason(join(clientsDir, `client-${slug}`)) !== null;
|
|
125
|
+
return {
|
|
126
|
+
slugs: all.filter((slug) => !isAdhoc(slug)),
|
|
127
|
+
adhoc: all.filter(isAdhoc),
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
const slug = String(options.slug).replace(/^client-/, "");
|
|
131
|
+
if (!CLIENT_SLUG.test(slug)) {
|
|
132
|
+
throw new Error(`"${options.slug}" is not a client slug (kebab-case, e.g. acme-hvac)`);
|
|
133
|
+
}
|
|
134
|
+
if (!existsSync(join(clientsDir, `client-${slug}`))) {
|
|
135
|
+
throw new Error(`no checkout at clients/client-${slug} under ${workspaceDir}`);
|
|
136
|
+
}
|
|
137
|
+
return { slugs: [slug], adhoc: [] };
|
|
138
|
+
}
|
|
82
139
|
/**
|
|
83
140
|
* Compare (and optionally fix) the shared infra files every client-<slug>
|
|
84
141
|
* build repo copies verbatim from client-template at creation time. Never
|
|
@@ -102,7 +159,7 @@ export async function templateSync(options) {
|
|
|
102
159
|
const repos = [];
|
|
103
160
|
for (const slug of slugs) {
|
|
104
161
|
const dir = join(clientsDir, `client-${slug}`);
|
|
105
|
-
const excluded =
|
|
162
|
+
const excluded = adhocReason(dir);
|
|
106
163
|
if (excluded) {
|
|
107
164
|
repos.push({ slug, dir, files: [], inSync: true, excluded, manifestGaps: [] });
|
|
108
165
|
continue;
|
|
@@ -128,12 +185,22 @@ export async function templateSync(options) {
|
|
|
128
185
|
}
|
|
129
186
|
fileResults.push({ file: rel, status });
|
|
130
187
|
}
|
|
188
|
+
if (!options.files) {
|
|
189
|
+
for (const rel of TEMPLATE_RETIRED_FILES) {
|
|
190
|
+
const repoFile = join(dir, rel);
|
|
191
|
+
if (!existsSync(repoFile))
|
|
192
|
+
continue;
|
|
193
|
+
if (apply)
|
|
194
|
+
await rm(repoFile);
|
|
195
|
+
fileResults.push({ file: rel, status: apply ? "deleted" : "retired" });
|
|
196
|
+
}
|
|
197
|
+
}
|
|
131
198
|
const manifest = readGcpManifestFromRepo(dir);
|
|
132
199
|
repos.push({
|
|
133
200
|
slug,
|
|
134
201
|
dir,
|
|
135
202
|
files: fileResults,
|
|
136
|
-
inSync: fileResults.every((f) =>
|
|
203
|
+
inSync: fileResults.every((f) => ["in-sync", "fixed", "deleted"].includes(f.status)),
|
|
137
204
|
manifestGaps: manifest
|
|
138
205
|
? [...manifest.missing, ...manifest.unfilled, ...manifest.invalid]
|
|
139
206
|
: [],
|
package/package.json
CHANGED
|
@@ -92,7 +92,7 @@ two (step 4):
|
|
|
92
92
|
| `check` | What it compares |
|
|
93
93
|
|---|---|
|
|
94
94
|
| `linear` | Linear vs the delivery log: an issue Done with no entry, or an entry that says shipped while the issue is open |
|
|
95
|
-
| `lint` | the repo's drift rules 12–19: an `AS OF` date behind the log (12), a dead evidence link or an evidence file no entry names (13), a Builds `workflow_id` no doc names (14), a `CLIENT.md` placeholder (15), stale status words on an active build (16), a dead pointer (17), a generated block behind its source (18), a doc with no `Type:` line (19) |
|
|
95
|
+
| `lint` | the repo's drift rules 12–19, 21 and 22: an `AS OF` date behind the log (12), a dead evidence link or an evidence file no entry names (13), a Builds `workflow_id` no doc names (14), a `CLIENT.md` placeholder (15), stale status words on an active build (16), a dead pointer (17), a generated block behind its source (18), a doc with no `Type:` line (19), the client's access block in `03` not matching `04` §1, or the retired Access tab still in the page (21), work state in a spec (a `Status:` line, an open question with no INS id) or a hand-kept "Next" list in the page (22) |
|
|
96
96
|
| `git`, `open-pr` | uncommitted, untracked or unpushed work, no upstream; open PRs |
|
|
97
97
|
| `active-flag`, `missing-workflow`, `name` | `CLIENT.md` `## Builds` vs n8n: inactive or archived while the repo says live, an id the instance does not have, `SHADOW`/`TEST` still in a live name |
|
|
98
98
|
| `missing-export`, `stale-export`, `orphan-export` | `workflows/` exports vs the instance |
|
|
@@ -40,7 +40,7 @@ you keep that same build folder's `onboarding.html` in sync:
|
|
|
40
40
|
| `01-overview.md` | The client | Plain English, **tech-agnostic** | What we're solving, what we're building, what to expect. The doc you'd send them. |
|
|
41
41
|
| `02-tech-spec.md` | Install Agent engineering | Precise, **names tools** | The implementation: architecture, data shapes, node-by-node, error handling, open questions. This is `onboarding.html`'s source of truth per `client-template/AGENT.md` — if they disagree, fix the page. |
|
|
42
42
|
| `03-client-onboarding.md` | The client's admin/bookkeeper | Plain English, checklist | Access + decisions + info we need, split by "before kickoff" vs "during week 1". This is the **ask**. |
|
|
43
|
-
| `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING. This is the **tracker
|
|
43
|
+
| `04-access-checklist.md` | Install Agent (internal) | Two terse status tables | §1 **credentials & grants** — one row per *system* we need a login, OAuth scope, share or API key for (every software named on the sales call); §2 **decisions & information owed** — never mixed in. Status HAVE/REQUESTED/MISSING/N/A. This is the **tracker** and the **one source** of access status: §1's Item, System and Why are client words, and the client's table in `03` is generated from them (`node ci/sync.mjs --write`, repo-lint rule 21). |
|
|
44
44
|
| `onboarding.html` | A technician landing on the build cold | Scannable, tab per topic | Every `REPLACE_WITH_*` token filled from the same source material as `01`–`04` (step 6) — so the tech discovery call happens with real context already on screen, not a blank template. |
|
|
45
45
|
|
|
46
46
|
**Every doc carries a Type line** on the line under its title, so a reader
|
|
@@ -107,7 +107,9 @@ This skill runs **twice** per engagement, against two different calls in
|
|
|
107
107
|
- For content already filled, update only what the tech call firms up,
|
|
108
108
|
corrects, or adds (a confirmed trigger, a newly-scoped item, a
|
|
109
109
|
resolved open question) — don't regenerate prose that's already
|
|
110
|
-
accurate just because you're touching the file.
|
|
110
|
+
accurate just because you're touching the file. A resolved open
|
|
111
|
+
question: write the answer into the spec, close its Linear issue, and
|
|
112
|
+
drop its INS id from § Open questions.
|
|
111
113
|
- Leave anything a human has clearly hand-edited since the first pass
|
|
112
114
|
alone unless the tech call directly contradicts it.
|
|
113
115
|
- Move resolved items out of `02-tech-spec.md`'s open-questions list
|
|
@@ -161,7 +163,12 @@ the Kingdom tech-spec sections that apply:
|
|
|
161
163
|
defensive parser fallback.
|
|
162
164
|
- **Security** — where credentials live, what gets scrubbed from logs.
|
|
163
165
|
- **Open questions for the build** — the things the call left unresolved. This
|
|
164
|
-
section is the most valuable; it prevents building on an assumption.
|
|
166
|
+
section is the most valuable; it prevents building on an assumption. **Each
|
|
167
|
+
one is a Linear issue** in the client's project (the `linear` skill; ask
|
|
168
|
+
before you create issues — Linear is shared): the spec lists only the INS
|
|
169
|
+
ids (`- INS-123 — short title`), never the open work itself. A spec holds no
|
|
170
|
+
work state — no `Status:` line under the title either (build status lives in
|
|
171
|
+
`CLIENT.md` `## Builds`); repo-lint rule 22 warns on both.
|
|
165
172
|
- **Build sequence** — the order you'll actually implement in.
|
|
166
173
|
|
|
167
174
|
### 4. Draft `03-client-onboarding.md` (what we need from them)
|
|
@@ -185,22 +192,34 @@ overwhelmed:
|
|
|
185
192
|
or a shared doc — every credential goes through the portal or 1Password,
|
|
186
193
|
never pasted in a message — and no access beyond the named systems.
|
|
187
194
|
- **§6 Quick-fill checklist** — the one-screen "have this ready" recap.
|
|
195
|
+
- **`## Where things stand`** — the last section: only the two marker lines
|
|
196
|
+
`<!-- ACCESS_STATUS_TABLE:START -->` and `<!-- ACCESS_STATUS_TABLE:END -->`.
|
|
197
|
+
Never write the table by hand: after step 5, `node ci/sync.mjs --write`
|
|
198
|
+
builds it from `04` §1, and the client sees it on the portal Access tab.
|
|
188
199
|
|
|
189
200
|
### 5. Draft `04-access-checklist.md` (internal tracker)
|
|
190
201
|
|
|
191
202
|
Two tables, never one. **§1 Credentials & grants** — one row per *system* we
|
|
192
203
|
need a credential or an access grant for (a login, an OAuth scope, a share, an
|
|
193
|
-
API key): **System |
|
|
194
|
-
|
|
195
|
-
|
|
204
|
+
API key): **Item | System | Why we need it | Status | Notes**. §1 is the one
|
|
205
|
+
source of access status, and the client reads part of it: **Item, System and
|
|
206
|
+
Why we need it are client words** (plain, no tool jargon, no ticket numbers,
|
|
207
|
+
no dollar amounts) — `node ci/sync.mjs --write` builds the client's table in
|
|
208
|
+
`03` from them. **Notes** stays internal: the minimum role/scope, which build
|
|
209
|
+
uses it, chase detail, INS ids. You may add internal columns (`Access we need`,
|
|
210
|
+
`Used by`); they are never shown. A row that is ours only (our vault, our
|
|
211
|
+
Airtable base) gets `—` in Item: it stays internal. Every software the client
|
|
212
|
+
named on the sales call gets a row, even when the ask is still MISSING; a row
|
|
213
|
+
where it is UNKNOWN whether a credential is needed stays internal (`—` in Item)
|
|
214
|
+
until you know — a client row is HAVE, REQUESTED, MISSING or N/A.
|
|
196
215
|
**§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
|
|
197
216
|
intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
|
|
198
217
|
list, a person or a decision is never a §1 row; that mixing is what turns the
|
|
199
218
|
tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
|
|
200
219
|
UNKNOWN / N/A — set from what the call notes and registry profile actually say
|
|
201
|
-
was granted or promised, never assumed. This is the doc
|
|
202
|
-
|
|
203
|
-
|
|
220
|
+
was granted or promised, never assumed. This is the doc a teammate opens to
|
|
221
|
+
answer "what are we still waiting on from this client?" without re-reading
|
|
222
|
+
the call transcript. Update
|
|
204
223
|
it in the same commit whenever access lands — it decays fast otherwise.
|
|
205
224
|
|
|
206
225
|
- **Capture status, don't invent it.** If a call didn't confirm an item was
|
|
@@ -216,10 +235,14 @@ it in the same commit whenever access lands — it decays fast otherwise.
|
|
|
216
235
|
thing the client must say, not grant.
|
|
217
236
|
- **No credential values or IDs** — status and the 1Password vault *name*
|
|
218
237
|
only (from `CLIENT.md`), same rule as everywhere else in the repo.
|
|
219
|
-
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
238
|
+
- **Put the line `<!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->` above the §1 table** once you have read Item,
|
|
239
|
+
System and Why as the client would: it tells sync that §1 may be shown.
|
|
240
|
+
Without it nothing is generated.
|
|
241
|
+
- **Then run `node ci/sync.mjs --write`** in the repo: it builds the client's
|
|
242
|
+
table (the `ACCESS_STATUS_TABLE` block in `03`) from §1. Never hand-edit
|
|
243
|
+
that block; repo-lint rule 21 warns when it says something else. There is
|
|
244
|
+
no Access tab in `onboarding.html` any more (retired 2026-11-08):
|
|
245
|
+
technicians read `04`. §2 stays in the doc.
|
|
223
246
|
|
|
224
247
|
### 6. Populate `onboarding.html`
|
|
225
248
|
|
|
@@ -237,10 +260,9 @@ In short:
|
|
|
237
260
|
tokens, `TRIGGER`, `THRESHOLD`, `IDEMPOTENCY`, `INSTANCE`,
|
|
238
261
|
`STACK_NOTES`) — pulled straight from `02-tech-spec.md`'s architecture
|
|
239
262
|
summary and idempotency section. Repeating list tokens
|
|
240
|
-
(`SCOPE_ITEM`, `PARKED_ITEM`, `STEP
|
|
241
|
-
|
|
242
|
-
access
|
|
243
|
-
`04-access-checklist.md` mirror already required in step 5.
|
|
263
|
+
(`SCOPE_ITEM`, `PARKED_ITEM`, `STEP`) — one `<li>` per item, duplicate
|
|
264
|
+
the template's stub `<li>` as needed. The page has no access table and no
|
|
265
|
+
hand-kept "Next" list: access lives in `04` §1, open work in Linear.
|
|
244
266
|
- **Builds tab** — one *systems-level* block per build in scope, duplicating
|
|
245
267
|
the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
|
|
246
268
|
`SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
|
|
@@ -263,7 +285,8 @@ In short:
|
|
|
263
285
|
- **Public tab** — the client-safe rewrite: tech-agnostic
|
|
264
286
|
`PUBLIC_SUMMARY`/`TODAY`/`AFTER`/`METRIC`, `PLAIN_STEP`+`PLAIN_DETAIL`
|
|
265
287
|
pairs (same pipeline as the Client tab's architecture nodes, no tool
|
|
266
|
-
names), `PUBLIC_DONE_ITEM
|
|
288
|
+
names), `PUBLIC_DONE_ITEM`, `CLIENT_ASK` (no "Up next" list: the portal
|
|
289
|
+
reads Now / Next / Later from Linear).
|
|
267
290
|
|
|
268
291
|
If a list section has more real items than the template's stub `<li>`s,
|
|
269
292
|
duplicate the stub; if fewer, delete the extras — don't leave unfilled
|
|
@@ -297,12 +320,15 @@ tokens or empty bullets.
|
|
|
297
320
|
- [ ] `01-overview.md`: problem → build (plain) → expectations (measurable,
|
|
298
321
|
hedged); no bare tool names without a gloss.
|
|
299
322
|
- [ ] `02-tech-spec.md`: schema, node-by-node, idempotency (both halves),
|
|
300
|
-
error table, AI specifics, **open questions
|
|
323
|
+
error table, AI specifics, **open questions** (each a Linear issue; the
|
|
324
|
+
spec lists INS ids only), build sequence; no `Status:` line.
|
|
301
325
|
- [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
|
|
302
326
|
/ quick-fill; minimum roles; "creds in your vault, never a password".
|
|
303
327
|
- [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
|
|
304
|
-
sales-call software has a row
|
|
305
|
-
|
|
328
|
+
sales-call software has a row; Item / System / Why in client words,
|
|
329
|
+
`—` in Item for an internal row) + §2 decisions/information; Status set
|
|
330
|
+
from what's actually confirmed (not assumed); `node ci/sync.mjs --write`
|
|
331
|
+
run, so the `03` block matches §1 (repo-lint rule 21 clean).
|
|
306
332
|
- [ ] Each of `01`–`04` has its Type line under the title:
|
|
307
333
|
`<!-- Type: spec -->` in `01` and `03`, `Type: spec` in `02` and `04`.
|
|
308
334
|
- [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
|
|
@@ -14,7 +14,6 @@ the `client-kingdom/docs/` exemplars.
|
|
|
14
14
|
|
|
15
15
|
**Prepared for:** <Client legal/dba name>
|
|
16
16
|
**Prepared by:** Install Agent
|
|
17
|
-
**Status:** Proposal, post-discovery
|
|
18
17
|
|
|
19
18
|
---
|
|
20
19
|
|
|
@@ -60,7 +59,6 @@ daily review queue that shrinks as the system learns."><br/>
|
|
|
60
59
|
Type: spec
|
|
61
60
|
|
|
62
61
|
**Audience:** Install Agent engineering. Internal.
|
|
63
|
-
**Status:** Pre-implementation, ready for build kickoff.
|
|
64
62
|
**Source diagram:** docs/<name>-diagram.html
|
|
65
63
|
|
|
66
64
|
---
|
|
@@ -103,7 +101,9 @@ parser fallback, retry policy, rough per-call cost at expected volume.>
|
|
|
103
101
|
<Audit log of record; daily/weekly digest; native dashboards.>
|
|
104
102
|
|
|
105
103
|
## 10. Open questions for the build
|
|
106
|
-
|
|
104
|
+
Each open item is a Linear issue in this client's project (`linear_project` in
|
|
105
|
+
`CLIENT.md`), never a line here: list its INS id below, one per line.
|
|
106
|
+
- INS-<id> — <short title of one thing the call left unresolved>
|
|
107
107
|
|
|
108
108
|
## 11. Build sequence
|
|
109
109
|
<The order you'll implement: infra → fixtures → core nodes → rules → AI shadow →
|
|
@@ -149,8 +149,17 @@ no access beyond the named systems.>
|
|
|
149
149
|
- [ ] <decision made>
|
|
150
150
|
- [ ] <contact + handle>
|
|
151
151
|
- [ ] <person available for live linking>
|
|
152
|
+
|
|
153
|
+
## Where things stand
|
|
154
|
+
|
|
155
|
+
<!-- ACCESS_STATUS_TABLE:START -->
|
|
156
|
+
<!-- ACCESS_STATUS_TABLE:END -->
|
|
152
157
|
```
|
|
153
158
|
|
|
159
|
+
The two marker lines stay empty here: `node ci/sync.mjs --write` fills them
|
|
160
|
+
from `04` §1 (the client's table on the portal Access tab). Never write the
|
|
161
|
+
table by hand.
|
|
162
|
+
|
|
154
163
|
---
|
|
155
164
|
|
|
156
165
|
## `04-access-checklist.md` (internal — status tracker)
|
|
@@ -159,12 +168,14 @@ no access beyond the named systems.>
|
|
|
159
168
|
# Access & Credentials Checklist — <slug>
|
|
160
169
|
Type: spec
|
|
161
170
|
|
|
162
|
-
Internal tracker
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
171
|
+
Internal tracker, and the one source of access status. `03` is the **ask**
|
|
172
|
+
we send the client; this file is the **tracker** — update it the moment
|
|
173
|
+
access lands or a decision gets made, so anyone can answer "what are we still
|
|
174
|
+
waiting on?" without re-reading the call notes. In §1, **Item, System and Why
|
|
175
|
+
we need it are client words**: the client reads them on the portal Access tab
|
|
176
|
+
(no ticket numbers, no dollar amounts). **Notes** stays internal. `—` in Item
|
|
177
|
+
keeps a row internal. After any change, run `node ci/sync.mjs --write`: it
|
|
178
|
+
rebuilds the client's table in `03` (repo-lint rule 21).
|
|
168
179
|
|
|
169
180
|
No real credential values or IDs here — status and the 1Password vault
|
|
170
181
|
*name* only (see `CLIENT.md`).
|
|
@@ -172,12 +183,22 @@ No real credential values or IDs here — status and the 1Password vault
|
|
|
172
183
|
Status legend: **HAVE** · **REQUESTED** (asked, not yet received) ·
|
|
173
184
|
**MISSING** (not yet asked, or blocking) · **N/A**
|
|
174
185
|
|
|
186
|
+
## §1 — Credentials & grants
|
|
187
|
+
|
|
188
|
+
<!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->
|
|
189
|
+
|
|
175
190
|
| Item | System | Why we need it | Status | Notes |
|
|
176
191
|
|---|---|---|---|---|
|
|
177
|
-
| <e.g.
|
|
178
|
-
| <e.g.
|
|
179
|
-
| <e.g.
|
|
180
|
-
| <e.g.
|
|
192
|
+
| <e.g. A login for your portal> | <e.g. Catalyte> | <what it lets us do for them, in their words> | MISSING | <minimum role; which build; who's chasing it, by when> |
|
|
193
|
+
| <e.g. An admin user for your records system> | <e.g. Lumary> | <what it unblocks> | REQUESTED | <date asked> |
|
|
194
|
+
| <e.g. A space for alerts> | <e.g. Google Chat> | <what it unblocks> | HAVE | <date confirmed> |
|
|
195
|
+
| — | <e.g. 1Password vault `client-<slug>`> | — | HAVE | <ours: never shown to the client> |
|
|
196
|
+
|
|
197
|
+
## §2 — Decisions & information owed
|
|
198
|
+
|
|
199
|
+
| Item | Who owes it | Why | Status | Notes |
|
|
200
|
+
|---|---|---|---|---|
|
|
201
|
+
| <e.g. Data-handling agreement (BAA / DPA)> | <client> | <legal gate before real data flows> | MISSING | <blocking real-data cutover> |
|
|
181
202
|
|
|
182
203
|
_Last updated: <date> — update in the same commit as any access change._
|
|
183
204
|
```
|
|
@@ -202,9 +223,10 @@ once (even if the same value is reused verbatim in more than one spot, e.g.
|
|
|
202
223
|
`IDEMPOTENCY`, `INSTANCE`, `STACK_NOTES`, `CLIENT_SPECIFIC_RULE`, `DATE`
|
|
203
224
|
(status-snapshot "as of").
|
|
204
225
|
- **(repeat)** `SCOPE_ITEM` (Phase 1 scope), `PARKED_ITEM`, `STEP` (build
|
|
205
|
-
order, numbered)
|
|
206
|
-
|
|
207
|
-
|
|
226
|
+
order, numbered). No "Next" list: open work lives in Linear (repo-lint
|
|
227
|
+
rule 22 warns on a hand-kept one).
|
|
228
|
+
- No access table: the Access tab is retired (2026-11-08). Access lives in
|
|
229
|
+
`04-access-checklist.md` §1; the client's table in `03` is generated from it.
|
|
208
230
|
|
|
209
231
|
**Workflows tab** — one whole diagram block duplicated per automation in
|
|
210
232
|
scope:
|
|
@@ -223,7 +245,8 @@ scope:
|
|
|
223
245
|
`METRIC`, `DATE` (reused, progress "as of").
|
|
224
246
|
- **(repeat, paired)** `PLAIN_STEP`+`PLAIN_DETAIL` — same pipeline as the
|
|
225
247
|
Client tab's architecture nodes, described without tool names.
|
|
226
|
-
- **(repeat)** `PUBLIC_DONE_ITEM`, `
|
|
248
|
+
- **(repeat)** `PUBLIC_DONE_ITEM`, `CLIENT_ASK`. No "Up next" list: the
|
|
249
|
+
portal reads Now / Next / Later from Linear.
|
|
227
250
|
- **`portal-overview` JSON block** (the client portal's Onboarding tab):
|
|
228
251
|
not tokens you replace one by one — fill the whole JSON (`asOf`,
|
|
229
252
|
`summary` — one plain paragraph ≤ 280 chars that opens the page —,
|
|
@@ -41,6 +41,7 @@ secrets).
|
|
|
41
41
|
| What's in client X's build repo docs? | `ia client-build <slug> [query]` |
|
|
42
42
|
| Find a client's call transcript / Drive deliverable | `ia client-drive <slug> [query]` |
|
|
43
43
|
| Open Linear issues for a client | `ia client-linear <slug> [query]` |
|
|
44
|
+
| Move a client's old `docs/06-roadmap.md` into Linear / retire the roadmap file | `ia roadmap-migrate <slug> \| --all` (dry run: labels and `Client line:` to add, state mismatches, rows with no INS id), then `ia roadmap-retire <slug> \| --all` (dry run: the `git mv` and the `onboarding.html` removals). The account owner runs each `--apply`; ad hoc repos are skipped |
|
|
44
45
|
| Did anything drift? / does client X's repo still agree with n8n, Linear and git? | `ia client-drift <slug> [--json]` (`--all` for every client repo) — read-only: Builds vs n8n (active flag, missing workflow, SHADOW/TEST names), exports vs the instance, silent schedules and failed last runs (status only), git and open PRs, Linear vs the delivery log, the repo's drift lint (rules 12–19). Exit 1 on drift or when a source could not be read. The `client-latest` skill runs it for you |
|
|
45
46
|
| Open issues in an internal Linear project | `ia linear-project <project> [query]` |
|
|
46
47
|
| Start a new client engagement | `ia client-intake <slug> --name <name>` (or bare `ia new-client <slug>`) |
|
|
@@ -62,6 +62,38 @@ Statuses on this team: `Backlog` → `Todo` → `In Progress` → `In Review`
|
|
|
62
62
|
updates and write-ups to the end of a session — that's how issues sit in
|
|
63
63
|
"In Progress" days after the work actually finished.
|
|
64
64
|
|
|
65
|
+
## Order of work and the client's plan (Linear owns it)
|
|
66
|
+
|
|
67
|
+
Linear owns work state; the client repo owns context. Since 2026-11-08 there
|
|
68
|
+
is no `docs/06-roadmap.md` (old ones sit in `docs/archive/`), and the client
|
|
69
|
+
portal reads **Now / Next / Later** from the client's project at request time.
|
|
70
|
+
|
|
71
|
+
| Fact | In Linear | On the client portal |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| Being worked this week | state In Progress / In Review (type *started*) | **Now** |
|
|
74
|
+
| Up next | state Todo (type *unstarted*) | **Next** |
|
|
75
|
+
| Later | state Backlog (type *backlog*) | **Later** |
|
|
76
|
+
| Parked | label `parked` (any state) | never shown |
|
|
77
|
+
| Done | Done; the delivery-log entry names the INS id | the progress list (from the log) |
|
|
78
|
+
| Rank | priority, then the project's manual sort order. The account owner moves ranks; a technician moves states | the order inside each list |
|
|
79
|
+
| Who it serves | label `value` (moves the number we committed to), `client-ask` (the client asked); both labels = both | — |
|
|
80
|
+
| Why this rank | the issue description | — |
|
|
81
|
+
| The client-safe line | one line in the description: `Client line: <one sentence, 140 characters at most>` | the only text the client sees |
|
|
82
|
+
|
|
83
|
+
**Client line rules:** plain words, no tool names, no ticket numbers, **no
|
|
84
|
+
dollar amounts** (Linear is shared by all staff). An issue with no `Client
|
|
85
|
+
line:` is internal: the client never sees it. The portal never shows an issue
|
|
86
|
+
title or any other part of the description, and drops a line with `$` or a
|
|
87
|
+
ticket id.
|
|
88
|
+
|
|
89
|
+
**A new client ask** is a new issue in the client's project: its `Client
|
|
90
|
+
line:`, the `client-ask` label, and a priority. The account owner places it.
|
|
91
|
+
|
|
92
|
+
**Follow-ups are issues.** Work still owed after something ships is a Linear
|
|
93
|
+
issue. The delivery-log entry's `- **Follow-ups:**` holds only its INS ids, or
|
|
94
|
+
`none` (repo-lint rule 20, entries dated 2026-11-08 or later). `ia
|
|
95
|
+
client-drift` flags a follow-up id that is not in the client's project.
|
|
96
|
+
|
|
65
97
|
## Creating issues
|
|
66
98
|
|
|
67
99
|
- Set `project` to the client's Linear project (from `CLIENT.md`), not just
|
|
@@ -70,7 +70,7 @@ its agenda carries forward intact.
|
|
|
70
70
|
In order: registry `PROFILE.md` (including Internal notes — that's where
|
|
71
71
|
name mis-transcriptions and discrepancies live), every file in registry
|
|
72
72
|
`calls/`, then the build repo's `CLIENT.md`, `docs/00`–`04`, and
|
|
73
|
-
`onboarding.html` (Proposals tab
|
|
73
|
+
`onboarding.html` (Proposals tab). For a monthly scoping
|
|
74
74
|
call, add `docs/00-delivery-log.md` and `evidence/`.
|
|
75
75
|
|
|
76
76
|
**Check for the auto-drafted agenda.** The portal's Lead Close Kickoff
|
|
@@ -151,7 +151,7 @@ access I need. At the end we book the follow-ups."
|
|
|
151
151
|
- <which process to walk, who should drive, what artifact to ask them to share>
|
|
152
152
|
|
|
153
153
|
## Questions to ask <!-- ONLY unanswered ones; use the script's question FORMS -->
|
|
154
|
-
- <question> → fills <02-tech-spec §X / trigger / volume / boundary / …>
|
|
154
|
+
- <question> → fills <02-tech-spec §X / trigger / volume / boundary / …> (INS-<id> when it is an open Linear issue)
|
|
155
155
|
|
|
156
156
|
## The month-one pitch
|
|
157
157
|
- Lead: <primary candidate> — because <their stated cost>.
|
|
@@ -202,7 +202,11 @@ convention.
|
|
|
202
202
|
- **Questions come from gaps, not templates.** A question already
|
|
203
203
|
answered in a call note never appears on the agenda — re-known facts go
|
|
204
204
|
in the read-back as statements to confirm, not questions to re-ask.
|
|
205
|
-
Every question names the doc section its answer fills.
|
|
205
|
+
Every question names the doc section its answer fills. The spec's open
|
|
206
|
+
questions are Linear issues (its § Open questions lists their INS ids;
|
|
207
|
+
`ia client-linear <slug>` shows them): ask the open ones and name the INS
|
|
208
|
+
id. After the call, the answer goes into the spec and the issue closes —
|
|
209
|
+
the agenda and the spec never keep their own list of open work.
|
|
206
210
|
- **Facts get verified, not copied.** Transcripts mangle names; the
|
|
207
211
|
registry's Internal notes section is authoritative for known
|
|
208
212
|
discrepancies. Never propagate a mis-transcription onto an agenda the
|