@installagent/sdk 0.9.1 → 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-mirror.d.ts +28 -0
- package/dist/agent-mirror.js +45 -20
- package/dist/agent-templates.js +1 -1
- package/dist/client-drift.d.ts +126 -0
- package/dist/client-drift.js +558 -0
- package/dist/index.d.ts +5 -2
- package/dist/index.js +5 -2
- package/dist/linear-project.d.ts +18 -0
- package/dist/linear-project.js +43 -0
- 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 +42 -1
- package/dist/template-sync.js +101 -7
- package/package.json +1 -1
- package/templates/workspace-root/skills/CLAUDE.md +1 -1
- package/templates/workspace-root/skills/client-latest/SKILL.md +75 -63
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +61 -21
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +44 -17
- package/templates/workspace-root/skills/house-voice/SKILL.md +172 -77
- package/templates/workspace-root/skills/ia-cli/SKILL.md +3 -1
- package/templates/workspace-root/skills/linear/SKILL.md +32 -0
- package/templates/workspace-root/skills/slack-voice/SKILL.md +2 -2
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +14 -5
|
@@ -5,10 +5,10 @@ description: >-
|
|
|
5
5
|
a two-part terminal brief, where it stands now (by system), then one ranked
|
|
6
6
|
table of what is wrong and what to do about it. Reads the build repo
|
|
7
7
|
(CLIENT.md, docs/00-delivery-log.md, evidence/, onboarding.html, AGENT.md
|
|
8
|
-
gotchas),
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
gotchas), `ia client-drift` (one read-only call for the repo against n8n,
|
|
9
|
+
Linear, git and its own drift lint), log vs git and stray worktrees by
|
|
10
|
+
hand, the read-only `ia client` / `ia client-linear` commands, the
|
|
11
|
+
calendar and the client's Slack channel. Use this WHENEVER someone says "what's the latest on [client]",
|
|
12
12
|
"catch me up on [client]", "where did we leave off", "resume the [client]
|
|
13
13
|
build", "status of [client]", "what's blocked on [client]", "did anything
|
|
14
14
|
drift", or opens a `clients/client-[slug]/` repo cold. The brief is a pure
|
|
@@ -62,8 +62,8 @@ Run it in this order. Each step is cheap and narrows the next.
|
|
|
62
62
|
### 1. The manifest
|
|
63
63
|
|
|
64
64
|
`cat clients/client-<slug>/CLIENT.md`. It maps every external system.
|
|
65
|
-
|
|
66
|
-
|
|
65
|
+
A key that still holds a placeholder is a drift finding; `ia client-drift`
|
|
66
|
+
(step 3) reports it, so do not hunt for it by hand.
|
|
67
67
|
|
|
68
68
|
### 2. The repo, in the window
|
|
69
69
|
|
|
@@ -71,41 +71,72 @@ Note any key that is still a placeholder (`<...>`, or a literal
|
|
|
71
71
|
the "what shipped, does it work" record.
|
|
72
72
|
- `evidence/` — files dated in the window. An accuracy or go-live claim
|
|
73
73
|
with no evidence file is a risk, not a fact.
|
|
74
|
-
- `onboarding.html` —
|
|
75
|
-
|
|
74
|
+
- `onboarding.html` — read the status snapshot. `ia client-drift` (step 3)
|
|
75
|
+
checks its **`AS OF` date** against the newest log entry.
|
|
76
76
|
- `AGENT.md` § *Client-specific gotchas* — the traps for this repo. Carry
|
|
77
77
|
any that still apply into the risks/next table.
|
|
78
78
|
- `docs/` index — a high-numbered handoff or decision-log doc
|
|
79
79
|
(`NN-...-handoff.md`) is usually the freshest single page. Read it.
|
|
80
80
|
|
|
81
|
-
### 3.
|
|
81
|
+
### 3. `ia client-drift` — the drift checks, in one read
|
|
82
82
|
|
|
83
83
|
```bash
|
|
84
|
-
|
|
85
|
-
git status --porcelain # uncommitted work
|
|
86
|
-
git log --oneline @{u}..HEAD # committed but never pushed
|
|
87
|
-
git log --oneline --since=<window-start>
|
|
88
|
-
gh pr list --state open # if the repo pushes to GitHub
|
|
89
|
-
git worktree list
|
|
84
|
+
ia client-drift <slug> --json # from the workspace root, or add -w <root>
|
|
90
85
|
```
|
|
91
86
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
full duplicate `docs/` tree, and reading the wrong copy produces a
|
|
97
|
-
confidently wrong brief.
|
|
87
|
+
Read-only: it reads n8n (workflows, and run *status* only, never run data),
|
|
88
|
+
Linear (queries only), git, `gh` and the repo's own `ci/repo-lint.mjs`. It
|
|
89
|
+
writes nothing. One call makes every drift check in the table below except
|
|
90
|
+
two (step 4):
|
|
98
91
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
92
|
+
| `check` | What it compares |
|
|
93
|
+
|---|---|
|
|
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, 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
|
+
| `git`, `open-pr` | uncommitted, untracked or unpushed work, no upstream; open PRs |
|
|
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
|
+
| `missing-export`, `stale-export`, `orphan-export` | `workflows/` exports vs the instance |
|
|
99
|
+
| `silence`, `last-error` | an active schedule with no recent run; a failed newest run |
|
|
100
|
+
|
|
101
|
+
Each finding has a `level` (`drift`: two sources disagree and one is wrong;
|
|
102
|
+
`check`: a person should look), a `subject`, `sourceA` ≠ `sourceB`, and a
|
|
103
|
+
`hint`. The hint is the Fix cell of the row it becomes.
|
|
104
|
+
|
|
105
|
+
- **A partial report is not a clean one.** The command exits 1 on drift *or*
|
|
106
|
+
when a source could not be read. Every `unreadSources` entry (no
|
|
107
|
+
`N8N_API_KEY`, a key without `execution:read`, no `LINEAR_API_TOKEN`) and
|
|
108
|
+
every per-client `skipped` entry goes into **Could not read**. Never write
|
|
109
|
+
"no drift" from a run that skipped a source.
|
|
110
|
+
- A client with `backlog:` in `CLIENT.md` (no Linear) skips `linear`. Say so.
|
|
111
|
+
- **Built-but-unlanded work is the most common real risk in this
|
|
112
|
+
workspace.** The `git` and `open-pr` findings are the "Git vs reality"
|
|
113
|
+
row, and that row is in the brief even when it is clean (say "clean").
|
|
114
|
+
- **A PR that's green and ready to merge is not a passive fact — put it in
|
|
115
|
+
the ranked table as an action**, not just a count in the drift row.
|
|
116
|
+
"3 unpushed commits" is drift; "PR #25 is green, waiting on a merge
|
|
117
|
+
click" is a one-line fix, so it earns a row even though nothing is wrong.
|
|
118
|
+
- To look deeper into one workflow's finding:
|
|
119
|
+
`ia agent executions <workflowId> -n 20`. Never pass `--data` (run data
|
|
120
|
+
holds full client payloads), and never run a client workflow to "see if
|
|
121
|
+
it works".
|
|
122
|
+
|
|
123
|
+
### 4. Git — the two checks `ia client-drift` does not make
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
cd clients/client-<slug>
|
|
127
|
+
git log --oneline --since=<window-start> # log vs git
|
|
128
|
+
git worktree list # stray worktrees
|
|
129
|
+
ls .claude/worktrees/ 2>/dev/null
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
- **Log vs git:** a log entry in the window that claims a deploy or a merge
|
|
133
|
+
needs a matching commit in the window.
|
|
134
|
+
- **Worktrees:** a stale worktree holds a full duplicate `docs/` tree, and
|
|
135
|
+
reading the wrong copy produces a confidently wrong brief.
|
|
105
136
|
|
|
106
137
|
Never commit, never push, never force-push to undo something you find.
|
|
107
138
|
|
|
108
|
-
###
|
|
139
|
+
### 5. The `ia` read-only commands
|
|
109
140
|
|
|
110
141
|
```bash
|
|
111
142
|
ia client <slug> # registry profile + recent calls + delivery log
|
|
@@ -116,7 +147,7 @@ ia client-linear <slug> # OPEN issues in the client's Linear project
|
|
|
116
147
|
or a referenced doc is missing locally. Do not hand-roll GitHub, Airtable,
|
|
117
148
|
Linear, or Drive calls — see the `ia-cli` skill.
|
|
118
149
|
|
|
119
|
-
###
|
|
150
|
+
### 6. The calendar — the one date the repo cannot be trusted for
|
|
120
151
|
|
|
121
152
|
One query: `angello@installagent.com`'s calendar across the surrounding
|
|
122
153
|
week. Take the client's **next** and **last** meeting from it. Match the
|
|
@@ -138,7 +169,7 @@ inside the repo can catch that. Only the calendar can.
|
|
|
138
169
|
- **Never rewrite history to match.** A dated delivery-log entry records
|
|
139
170
|
what was believed then; correct it with a new entry, not an edit.
|
|
140
171
|
|
|
141
|
-
###
|
|
172
|
+
### 7. Slack — the client's own words
|
|
142
173
|
|
|
143
174
|
Read `slack_channel` from `CLIENT.md`. Read the channel back to the window
|
|
144
175
|
start. The convention is `#client-<slug>`, but real names vary (one has a
|
|
@@ -157,42 +188,22 @@ Slack. If you see one, report *that it happened* and that it needs
|
|
|
157
188
|
rotating and deleting. Never echo the value into the brief, a file, a
|
|
158
189
|
commit message, or a Linear issue.
|
|
159
190
|
|
|
160
|
-
### 7. n8n run health
|
|
161
|
-
|
|
162
|
-
Workflow IDs are **not** in the repo's `workflows/*.json` — those exports
|
|
163
|
-
are sanitized, so the `id` field is stripped. They live in the docs:
|
|
164
|
-
|
|
165
|
-
```bash
|
|
166
|
-
grep -rIoh '`[A-Za-z0-9]\{16\}`' docs/ evidence/ AGENT.md | sort | uniq -c | sort -rn
|
|
167
|
-
ia agent executions <workflowId> -n 20
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
A 16-character backticked string is an n8n workflow id. The most-cited one
|
|
171
|
-
is usually the live workflow, but confirm it against the tech spec before
|
|
172
|
-
you report on it — never guess an id from the client name.
|
|
173
|
-
|
|
174
|
-
Report last run, last error, and silence (a workflow that should run daily
|
|
175
|
-
and has not run). Flag "built but never published" — an inactive or draft
|
|
176
|
-
workflow while the docs or Linear call it live.
|
|
177
|
-
|
|
178
|
-
Do **not** pass `--data`: run data holds full client payloads. Do not
|
|
179
|
-
manually execute a client workflow to "see if it works".
|
|
180
|
-
|
|
181
191
|
## The drift checks
|
|
182
192
|
|
|
183
|
-
Run every one.
|
|
193
|
+
Run every one. `ia client-drift` (step 3) makes six of them; two stay by
|
|
194
|
+
hand (step 4). Report each as a pair of surfaces that disagree, with file
|
|
184
195
|
and line.
|
|
185
196
|
|
|
186
|
-
| Check | Drift looks like |
|
|
187
|
-
|
|
188
|
-
| Linear vs delivery log | Issue is Done, no log entry exists — or the log says shipped while the issue sits In Progress |
|
|
189
|
-
| `onboarding.html` vs delivery log | The `AS OF` snapshot date is older than the newest log entry |
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
| `
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
| Worktrees | A `.claude/worktrees/` copy of `docs/` is newer than the tracked one |
|
|
197
|
+
| Check | Made by | Drift looks like |
|
|
198
|
+
|---|---|---|
|
|
199
|
+
| Linear vs delivery log | `ia client-drift` · `linear` | Issue is Done, no log entry exists — or the log says shipped while the issue sits In Progress |
|
|
200
|
+
| `onboarding.html` vs delivery log | `ia client-drift` · `lint` rule 12 | The `AS OF` snapshot date is older than the newest log entry |
|
|
201
|
+
| Git vs reality | `ia client-drift` · `git`, `open-pr` | Uncommitted files, unpushed commits, or an open PR — whether or not a log entry claims it shipped. State "clean" here explicitly when there's nothing, rather than omitting the row |
|
|
202
|
+
| `CLIENT.md` | `ia client-drift` · `lint` rule 15 | A key still holds a placeholder, so every tool that resolves through it is guessing |
|
|
203
|
+
| n8n vs docs | `ia client-drift` · `active-flag`, `missing-workflow`, `name`, the export checks, `silence`, `last-error` | Workflow inactive, archived or silent while docs, Linear, or the client believe it is live |
|
|
204
|
+
| Evidence | `ia client-drift` · `lint` rule 13 | A log entry links `evidence/<file>.md` that does not exist, or an evidence file no entry mentions |
|
|
205
|
+
| Log vs git | **by hand** (step 4) | An entry claims a deploy or merge with no matching commit in the window |
|
|
206
|
+
| Worktrees | **by hand** (step 4) | A `.claude/worktrees/` copy of `docs/` is newer than the tracked one |
|
|
196
207
|
|
|
197
208
|
## Output — state, then one ranked table
|
|
198
209
|
|
|
@@ -254,7 +265,8 @@ Rules for the output:
|
|
|
254
265
|
gets its own row in the risks/next table so it isn't just reported and
|
|
255
266
|
forgotten.
|
|
256
267
|
- **`Could not read` is required** whenever a source failed — an
|
|
257
|
-
unauthenticated MCP session, a missing token, no Linear project
|
|
268
|
+
unauthenticated MCP session, a missing token, no Linear project, an
|
|
269
|
+
`unreadSources` or `skipped` entry from `ia client-drift`. A brief
|
|
258
270
|
that silently skips Slack reads as "Slack was quiet".
|
|
259
271
|
- **Never print a secret, key, password, or client PII**, and never a
|
|
260
272
|
client's dollar amount into anything shared. Point at the system that
|
|
@@ -40,9 +40,21 @@ 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
|
+
**Every doc carries a Type line** on the line under its title, so a reader
|
|
47
|
+
knows how long it lives (repo-lint rule 19; `client-template/AGENT.md` §
|
|
48
|
+
docs/). All four are `spec` — true now, edited in place:
|
|
49
|
+
|
|
50
|
+
| File | Line under the title |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `01-overview.md`, `03-client-onboarding.md` | `<!-- Type: spec -->` — the client reads these (on the portal), so the line is hidden |
|
|
53
|
+
| `02-tech-spec.md`, `04-access-checklist.md` | `Type: spec` |
|
|
54
|
+
|
|
55
|
+
On the update pass, keep the line; add it if the first pass left it out.
|
|
56
|
+
The templates in `references/spec-templates.md` already carry it.
|
|
57
|
+
|
|
46
58
|
Look at the canonical exemplars before writing — match their depth and
|
|
47
59
|
structure, not their specific domain:
|
|
48
60
|
|
|
@@ -95,7 +107,9 @@ This skill runs **twice** per engagement, against two different calls in
|
|
|
95
107
|
- For content already filled, update only what the tech call firms up,
|
|
96
108
|
corrects, or adds (a confirmed trigger, a newly-scoped item, a
|
|
97
109
|
resolved open question) — don't regenerate prose that's already
|
|
98
|
-
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.
|
|
99
113
|
- Leave anything a human has clearly hand-edited since the first pass
|
|
100
114
|
alone unless the tech call directly contradicts it.
|
|
101
115
|
- Move resolved items out of `02-tech-spec.md`'s open-questions list
|
|
@@ -149,7 +163,12 @@ the Kingdom tech-spec sections that apply:
|
|
|
149
163
|
defensive parser fallback.
|
|
150
164
|
- **Security** — where credentials live, what gets scrubbed from logs.
|
|
151
165
|
- **Open questions for the build** — the things the call left unresolved. This
|
|
152
|
-
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.
|
|
153
172
|
- **Build sequence** — the order you'll actually implement in.
|
|
154
173
|
|
|
155
174
|
### 4. Draft `03-client-onboarding.md` (what we need from them)
|
|
@@ -173,22 +192,34 @@ overwhelmed:
|
|
|
173
192
|
or a shared doc — every credential goes through the portal or 1Password,
|
|
174
193
|
never pasted in a message — and no access beyond the named systems.
|
|
175
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.
|
|
176
199
|
|
|
177
200
|
### 5. Draft `04-access-checklist.md` (internal tracker)
|
|
178
201
|
|
|
179
202
|
Two tables, never one. **§1 Credentials & grants** — one row per *system* we
|
|
180
203
|
need a credential or an access grant for (a login, an OAuth scope, a share, an
|
|
181
|
-
API key): **System |
|
|
182
|
-
|
|
183
|
-
|
|
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.
|
|
184
215
|
**§2 Decisions & information owed** — VIP lists, approvers, sample data, IT
|
|
185
216
|
intros, answers we owe them: **Item | Who owes it | Why | Status | Notes**. A
|
|
186
217
|
list, a person or a decision is never a §1 row; that mixing is what turns the
|
|
187
218
|
tracker into a wall nobody reads. Status is HAVE / REQUESTED / MISSING /
|
|
188
219
|
UNKNOWN / N/A — set from what the call notes and registry profile actually say
|
|
189
|
-
was granted or promised, never assumed. This is the doc
|
|
190
|
-
|
|
191
|
-
|
|
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
|
|
192
223
|
it in the same commit whenever access lands — it decays fast otherwise.
|
|
193
224
|
|
|
194
225
|
- **Capture status, don't invent it.** If a call didn't confirm an item was
|
|
@@ -204,10 +235,14 @@ it in the same commit whenever access lands — it decays fast otherwise.
|
|
|
204
235
|
thing the client must say, not grant.
|
|
205
236
|
- **No credential values or IDs** — status and the 1Password vault *name*
|
|
206
237
|
only (from `CLIENT.md`), same rule as everywhere else in the repo.
|
|
207
|
-
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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.
|
|
211
246
|
|
|
212
247
|
### 6. Populate `onboarding.html`
|
|
213
248
|
|
|
@@ -225,10 +260,9 @@ In short:
|
|
|
225
260
|
tokens, `TRIGGER`, `THRESHOLD`, `IDEMPOTENCY`, `INSTANCE`,
|
|
226
261
|
`STACK_NOTES`) — pulled straight from `02-tech-spec.md`'s architecture
|
|
227
262
|
summary and idempotency section. Repeating list tokens
|
|
228
|
-
(`SCOPE_ITEM`, `PARKED_ITEM`, `STEP
|
|
229
|
-
|
|
230
|
-
access
|
|
231
|
-
`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.
|
|
232
266
|
- **Builds tab** — one *systems-level* block per build in scope, duplicating
|
|
233
267
|
the template block (`BUILD_TITLE`, `BUILD_SLUG`, `STATUS`,
|
|
234
268
|
`SOURCE_SYSTEM`/`SECOND_SOURCE`/`DECISION`/`DESTINATION_SYSTEM`/`CHANNEL`
|
|
@@ -251,7 +285,8 @@ In short:
|
|
|
251
285
|
- **Public tab** — the client-safe rewrite: tech-agnostic
|
|
252
286
|
`PUBLIC_SUMMARY`/`TODAY`/`AFTER`/`METRIC`, `PLAIN_STEP`+`PLAIN_DETAIL`
|
|
253
287
|
pairs (same pipeline as the Client tab's architecture nodes, no tool
|
|
254
|
-
names), `PUBLIC_DONE_ITEM
|
|
288
|
+
names), `PUBLIC_DONE_ITEM`, `CLIENT_ASK` (no "Up next" list: the portal
|
|
289
|
+
reads Now / Next / Later from Linear).
|
|
255
290
|
|
|
256
291
|
If a list section has more real items than the template's stub `<li>`s,
|
|
257
292
|
duplicate the stub; if fewer, delete the extras — don't leave unfilled
|
|
@@ -285,12 +320,17 @@ tokens or empty bullets.
|
|
|
285
320
|
- [ ] `01-overview.md`: problem → build (plain) → expectations (measurable,
|
|
286
321
|
hedged); no bare tool names without a gloss.
|
|
287
322
|
- [ ] `02-tech-spec.md`: schema, node-by-node, idempotency (both halves),
|
|
288
|
-
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.
|
|
289
325
|
- [ ] `03-client-onboarding.md`: access / decisions / info / ongoing / not-asking
|
|
290
326
|
/ quick-fill; minimum roles; "creds in your vault, never a password".
|
|
291
327
|
- [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
|
|
292
|
-
sales-call software has a row
|
|
293
|
-
|
|
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).
|
|
332
|
+
- [ ] Each of `01`–`04` has its Type line under the title:
|
|
333
|
+
`<!-- Type: spec -->` in `01` and `03`, `Type: spec` in `02` and `04`.
|
|
294
334
|
- [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
|
|
295
335
|
update pass, only the ones the tech-discovery call still hasn't
|
|
296
336
|
answered); Client tab agrees with `02`, not the other way around.
|
|
@@ -10,10 +10,10 @@ the `client-kingdom/docs/` exemplars.
|
|
|
10
10
|
|
|
11
11
|
```markdown
|
|
12
12
|
# <Project name> — Project Overview
|
|
13
|
+
<!-- Type: spec -->
|
|
13
14
|
|
|
14
15
|
**Prepared for:** <Client legal/dba name>
|
|
15
16
|
**Prepared by:** Install Agent
|
|
16
|
-
**Status:** Proposal, post-discovery
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
@@ -56,9 +56,9 @@ daily review queue that shrinks as the system learns."><br/>
|
|
|
56
56
|
|
|
57
57
|
```markdown
|
|
58
58
|
# Tech Spec — <short system name>
|
|
59
|
+
Type: spec
|
|
59
60
|
|
|
60
61
|
**Audience:** Install Agent engineering. Internal.
|
|
61
|
-
**Status:** Pre-implementation, ready for build kickoff.
|
|
62
62
|
**Source diagram:** docs/<name>-diagram.html
|
|
63
63
|
|
|
64
64
|
---
|
|
@@ -101,7 +101,9 @@ parser fallback, retry policy, rough per-call cost at expected volume.>
|
|
|
101
101
|
<Audit log of record; daily/weekly digest; native dashboards.>
|
|
102
102
|
|
|
103
103
|
## 10. Open questions for the build
|
|
104
|
-
|
|
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>
|
|
105
107
|
|
|
106
108
|
## 11. Build sequence
|
|
107
109
|
<The order you'll implement: infra → fixtures → core nodes → rules → AI shadow →
|
|
@@ -114,6 +116,7 @@ write path → exception flow → prod cutover → tuning.>
|
|
|
114
116
|
|
|
115
117
|
```markdown
|
|
116
118
|
# Client Onboarding Checklist — <Client name>
|
|
119
|
+
<!-- Type: spec -->
|
|
117
120
|
|
|
118
121
|
<One line: plan on a ~45-min working session; build can start once §1 + §2 are
|
|
119
122
|
done; §3 can come in parallel during week 1.>
|
|
@@ -146,21 +149,33 @@ no access beyond the named systems.>
|
|
|
146
149
|
- [ ] <decision made>
|
|
147
150
|
- [ ] <contact + handle>
|
|
148
151
|
- [ ] <person available for live linking>
|
|
152
|
+
|
|
153
|
+
## Where things stand
|
|
154
|
+
|
|
155
|
+
<!-- ACCESS_STATUS_TABLE:START -->
|
|
156
|
+
<!-- ACCESS_STATUS_TABLE:END -->
|
|
149
157
|
```
|
|
150
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
|
+
|
|
151
163
|
---
|
|
152
164
|
|
|
153
165
|
## `04-access-checklist.md` (internal — status tracker)
|
|
154
166
|
|
|
155
167
|
```markdown
|
|
156
168
|
# Access & Credentials Checklist — <slug>
|
|
169
|
+
Type: spec
|
|
157
170
|
|
|
158
|
-
Internal tracker
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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).
|
|
164
179
|
|
|
165
180
|
No real credential values or IDs here — status and the 1Password vault
|
|
166
181
|
*name* only (see `CLIENT.md`).
|
|
@@ -168,12 +183,22 @@ No real credential values or IDs here — status and the 1Password vault
|
|
|
168
183
|
Status legend: **HAVE** · **REQUESTED** (asked, not yet received) ·
|
|
169
184
|
**MISSING** (not yet asked, or blocking) · **N/A**
|
|
170
185
|
|
|
186
|
+
## §1 — Credentials & grants
|
|
187
|
+
|
|
188
|
+
<!-- ACCESS_CLIENT_WORDS: the client reads Item, System and Why below on the portal -->
|
|
189
|
+
|
|
171
190
|
| Item | System | Why we need it | Status | Notes |
|
|
172
191
|
|---|---|---|---|---|
|
|
173
|
-
| <e.g.
|
|
174
|
-
| <e.g.
|
|
175
|
-
| <e.g.
|
|
176
|
-
| <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> |
|
|
177
202
|
|
|
178
203
|
_Last updated: <date> — update in the same commit as any access change._
|
|
179
204
|
```
|
|
@@ -198,9 +223,10 @@ once (even if the same value is reused verbatim in more than one spot, e.g.
|
|
|
198
223
|
`IDEMPOTENCY`, `INSTANCE`, `STACK_NOTES`, `CLIENT_SPECIFIC_RULE`, `DATE`
|
|
199
224
|
(status-snapshot "as of").
|
|
200
225
|
- **(repeat)** `SCOPE_ITEM` (Phase 1 scope), `PARKED_ITEM`, `STEP` (build
|
|
201
|
-
order, numbered)
|
|
202
|
-
|
|
203
|
-
|
|
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.
|
|
204
230
|
|
|
205
231
|
**Workflows tab** — one whole diagram block duplicated per automation in
|
|
206
232
|
scope:
|
|
@@ -219,7 +245,8 @@ scope:
|
|
|
219
245
|
`METRIC`, `DATE` (reused, progress "as of").
|
|
220
246
|
- **(repeat, paired)** `PLAIN_STEP`+`PLAIN_DETAIL` — same pipeline as the
|
|
221
247
|
Client tab's architecture nodes, described without tool names.
|
|
222
|
-
- **(repeat)** `PUBLIC_DONE_ITEM`, `
|
|
248
|
+
- **(repeat)** `PUBLIC_DONE_ITEM`, `CLIENT_ASK`. No "Up next" list: the
|
|
249
|
+
portal reads Now / Next / Later from Linear.
|
|
223
250
|
- **`portal-overview` JSON block** (the client portal's Onboarding tab):
|
|
224
251
|
not tokens you replace one by one — fill the whole JSON (`asOf`,
|
|
225
252
|
`summary` — one plain paragraph ≤ 280 chars that opens the page —,
|