@installagent/sdk 0.9.0 → 0.10.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/client-drift.d.ts +120 -0
- package/dist/client-drift.js +556 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/linear-project.d.ts +18 -0
- package/dist/linear-project.js +43 -0
- package/dist/template-sync.d.ts +14 -0
- package/dist/template-sync.js +27 -0
- package/package.json +1 -1
- package/templates/workspace-root/AGENT.md +2 -0
- package/templates/workspace-root/AGENTS.md +10 -8
- package/templates/workspace-root/GEMINI.md +9 -21
- package/templates/workspace-root/ONBOARDING.md +3 -1
- package/templates/workspace-root/skills/CLAUDE.md +2 -2
- package/templates/workspace-root/skills/README.md +12 -4
- package/templates/workspace-root/skills/client-facing-docs/SKILL.md +3 -0
- package/templates/workspace-root/skills/client-latest/SKILL.md +75 -63
- package/templates/workspace-root/skills/engagement-spec/SKILL.md +14 -0
- package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +4 -0
- package/templates/workspace-root/skills/house-voice/SKILL.md +172 -77
- package/templates/workspace-root/skills/ia-cli/SKILL.md +2 -1
- package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +8 -0
- package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +8 -1
- package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +32 -5
- package/templates/workspace-root/skills/slack-voice/SKILL.md +2 -2
- package/templates/workspace-root/skills/tech-call-prep/SKILL.md +7 -2
package/dist/linear-project.js
CHANGED
|
@@ -97,6 +97,49 @@ const PROJECT_ISSUES_QUERY = `
|
|
|
97
97
|
}
|
|
98
98
|
}
|
|
99
99
|
`;
|
|
100
|
+
const PROJECT_ISSUE_STATES_QUERY = `
|
|
101
|
+
query ProjectIssueStates($projectId: ID!, $first: Int!, $after: String) {
|
|
102
|
+
issues(filter: { project: { id: { eq: $projectId } } }, first: $first, after: $after) {
|
|
103
|
+
nodes {
|
|
104
|
+
identifier
|
|
105
|
+
updatedAt
|
|
106
|
+
completedAt
|
|
107
|
+
state { type }
|
|
108
|
+
parent { identifier }
|
|
109
|
+
}
|
|
110
|
+
pageInfo { hasNextPage endCursor }
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
`;
|
|
114
|
+
/**
|
|
115
|
+
* Every issue in a project, open AND closed, as identifier + state + dates
|
|
116
|
+
* only (`client-drift`'s Linear mirror check). Strictly read-only: GraphQL
|
|
117
|
+
* queries, never mutations. Pages until done or `maxPages`.
|
|
118
|
+
*/
|
|
119
|
+
export async function linearProjectIssueStates(fetchImpl, token, project, options = {}) {
|
|
120
|
+
const out = [];
|
|
121
|
+
let after = null;
|
|
122
|
+
for (let page = 0; page < (options.maxPages ?? 20); page++) {
|
|
123
|
+
const { issues, } = await linearRequest(fetchImpl, token, PROJECT_ISSUE_STATES_QUERY, {
|
|
124
|
+
projectId: project.id,
|
|
125
|
+
first: ISSUE_FETCH_PAGE_SIZE,
|
|
126
|
+
after,
|
|
127
|
+
});
|
|
128
|
+
for (const node of issues.nodes) {
|
|
129
|
+
out.push({
|
|
130
|
+
identifier: node.identifier,
|
|
131
|
+
stateType: node.state.type,
|
|
132
|
+
updatedAt: node.updatedAt,
|
|
133
|
+
completedAt: node.completedAt ?? null,
|
|
134
|
+
parent: node.parent?.identifier ?? null,
|
|
135
|
+
});
|
|
136
|
+
}
|
|
137
|
+
if (!issues.pageInfo.hasNextPage || !issues.pageInfo.endCursor)
|
|
138
|
+
break;
|
|
139
|
+
after = issues.pageInfo.endCursor;
|
|
140
|
+
}
|
|
141
|
+
return out;
|
|
142
|
+
}
|
|
100
143
|
function toIssue(node) {
|
|
101
144
|
return {
|
|
102
145
|
identifier: node.identifier,
|
package/dist/template-sync.d.ts
CHANGED
|
@@ -32,6 +32,18 @@ import { type GcpManifestKey } from "./client-manifest.js";
|
|
|
32
32
|
* anywhere.
|
|
33
33
|
*/
|
|
34
34
|
export declare const TEMPLATE_SYNCED_FILES: string[];
|
|
35
|
+
/**
|
|
36
|
+
* Client repos that left the template on purpose, with the reason. They are
|
|
37
|
+
* listed (so the report shows they were seen) but never compared and never
|
|
38
|
+
* written, not even by `--apply`. A shared rule change reaches them only by a
|
|
39
|
+
* hand copy, recorded in that repo's own commit.
|
|
40
|
+
*
|
|
41
|
+
* best-materials (2026-10-19): the repo moved to the client's GitHub org
|
|
42
|
+
* and dropped Linear. Its CADENCE.md (backlog, not Linear),
|
|
43
|
+
* lefthook.yml (runs every ci/*.test.mjs) and repo-lint CI are its own, and it
|
|
44
|
+
* has no PR → Slack workflow (the Install Agent org secrets are not there).
|
|
45
|
+
*/
|
|
46
|
+
export declare const TEMPLATE_SYNC_EXCLUDED: Readonly<Record<string, string>>;
|
|
35
47
|
export interface TemplateSyncOptions {
|
|
36
48
|
/** The installagent/ workspace root (the dir that contains clients/). */
|
|
37
49
|
workspaceDir: string;
|
|
@@ -50,6 +62,8 @@ export interface TemplateSyncRepoResult {
|
|
|
50
62
|
dir: string;
|
|
51
63
|
files: TemplateSyncFileResult[];
|
|
52
64
|
inSync: boolean;
|
|
65
|
+
/** Set (with the reason) for a repo in TEMPLATE_SYNC_EXCLUDED: nothing was compared or written. */
|
|
66
|
+
excluded?: string;
|
|
53
67
|
/**
|
|
54
68
|
* CLIENT.md's Google Cloud keys (gcp_project / gcp_account) that are absent
|
|
55
69
|
* or still the placeholder. Report only: CLIENT.md is per-client, so even
|
package/dist/template-sync.js
CHANGED
|
@@ -49,6 +49,14 @@ export const TEMPLATE_SYNCED_FILES = [
|
|
|
49
49
|
// of CLIENT.md, the source of `ia portal sync-builds`.
|
|
50
50
|
"ci/builds-manifest.mjs",
|
|
51
51
|
"ci/builds-manifest.test.mjs",
|
|
52
|
+
// repo-lint also imports onboarding (rule 18): the generated status, news
|
|
53
|
+
// and Builds-card blocks of onboarding.html (client drift program, step 3).
|
|
54
|
+
"ci/onboarding.mjs",
|
|
55
|
+
"ci/onboarding.test.mjs",
|
|
56
|
+
// The one write command for every generated view (roadmap, progress list,
|
|
57
|
+
// onboarding blocks): rules 9, 10 and 18 name it, CADENCE.md points at it.
|
|
58
|
+
"ci/sync.mjs",
|
|
59
|
+
"ci/sync.test.mjs",
|
|
52
60
|
"lefthook.yml",
|
|
53
61
|
".github/workflows/repo-lint.yml",
|
|
54
62
|
".github/workflows/pr-to-slack.yml",
|
|
@@ -57,6 +65,20 @@ export const TEMPLATE_SYNCED_FILES = [
|
|
|
57
65
|
// in that repo's onboarding.html.
|
|
58
66
|
"docs/kickoff-presentation.html",
|
|
59
67
|
];
|
|
68
|
+
/**
|
|
69
|
+
* Client repos that left the template on purpose, with the reason. They are
|
|
70
|
+
* listed (so the report shows they were seen) but never compared and never
|
|
71
|
+
* written, not even by `--apply`. A shared rule change reaches them only by a
|
|
72
|
+
* hand copy, recorded in that repo's own commit.
|
|
73
|
+
*
|
|
74
|
+
* best-materials (2026-10-19): the repo moved to the client's GitHub org
|
|
75
|
+
* and dropped Linear. Its CADENCE.md (backlog, not Linear),
|
|
76
|
+
* lefthook.yml (runs every ci/*.test.mjs) and repo-lint CI are its own, and it
|
|
77
|
+
* has no PR → Slack workflow (the Install Agent org secrets are not there).
|
|
78
|
+
*/
|
|
79
|
+
export const TEMPLATE_SYNC_EXCLUDED = {
|
|
80
|
+
"best-materials": "diverged from the template on 2026-10-19 (client's GitHub org, no Linear): its CADENCE.md, lefthook.yml and CI are its own — copy a shared ci/ change by hand",
|
|
81
|
+
};
|
|
60
82
|
/**
|
|
61
83
|
* Compare (and optionally fix) the shared infra files every client-<slug>
|
|
62
84
|
* build repo copies verbatim from client-template at creation time. Never
|
|
@@ -80,6 +102,11 @@ export async function templateSync(options) {
|
|
|
80
102
|
const repos = [];
|
|
81
103
|
for (const slug of slugs) {
|
|
82
104
|
const dir = join(clientsDir, `client-${slug}`);
|
|
105
|
+
const excluded = TEMPLATE_SYNC_EXCLUDED[slug];
|
|
106
|
+
if (excluded) {
|
|
107
|
+
repos.push({ slug, dir, files: [], inSync: true, excluded, manifestGaps: [] });
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
83
110
|
const fileResults = [];
|
|
84
111
|
for (const rel of files) {
|
|
85
112
|
const templateFile = join(templateDir, rel);
|
package/package.json
CHANGED
|
@@ -34,6 +34,8 @@ installagent/
|
|
|
34
34
|
├── team-design/ # Install Agent design system source (tokens, components, guidelines)
|
|
35
35
|
├── team-branding/ # Logo files (static assets only)
|
|
36
36
|
├── skills/ # Cross-cutting agent skills (client deliverables pipeline, brand kit, …)
|
|
37
|
+
├── team-tools/ # Internal technician tooling: the `ia` CLI, SDK, MCP server (see its AGENT.md)
|
|
38
|
+
├── systems-department/ # Independent self-serve storefront repo (working name, unbranded) — own stack, no cross-imports
|
|
37
39
|
├── AGENT.md # ← you are here
|
|
38
40
|
└── ONBOARDING.md # New-contractor orientation — read once, first
|
|
39
41
|
```
|
|
@@ -1,11 +1,13 @@
|
|
|
1
|
-
# AGENTS.md
|
|
1
|
+
# AGENTS.md — installagent workspace root
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Pointer file for agents that read `AGENTS.md` (Codex, Copilot, Aider,
|
|
4
|
+
Continue, and others). It holds no rules of its own.
|
|
5
5
|
|
|
6
|
-
`
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
1. Read [`AGENT.md`](./AGENT.md). It is the source of truth for the whole
|
|
7
|
+
workspace: layout, the "where to start a task" table, the golden rules,
|
|
8
|
+
and how the agentic files are layered.
|
|
9
|
+
2. Read [`ONBOARDING.md`](./ONBOARDING.md) if you are landing here cold.
|
|
10
|
+
3. Inside a repo, read that repo's `AGENT.md` (or `AGENTS.md`). It overrides
|
|
11
|
+
the root rules while you work there.
|
|
9
12
|
|
|
10
|
-
|
|
11
|
-
drift.
|
|
13
|
+
Do not add rule content to this file. Edit `AGENT.md` instead.
|
|
@@ -1,24 +1,12 @@
|
|
|
1
|
-
# GEMINI.md
|
|
1
|
+
# GEMINI.md — installagent workspace root
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Pointer file for the Gemini CLI and other Google-powered agents. It holds no
|
|
4
|
+
rules of its own.
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
1. Read [`AGENT.md`](./AGENT.md). It is the source of truth for the whole
|
|
7
|
+
workspace.
|
|
8
|
+
2. Read [`ONBOARDING.md`](./ONBOARDING.md) if you are landing here cold.
|
|
9
|
+
3. Inside a repo, read that repo's `AGENT.md` (or `AGENTS.md`), then its
|
|
10
|
+
`GEMINI.md` if one exists (for example `team-web/apps/docs/GEMINI.md`).
|
|
7
11
|
|
|
8
|
-
|
|
9
|
-
source of truth.**
|
|
10
|
-
2. [`README.md`](./README.md) — workspace overview.
|
|
11
|
-
3. The `AGENT.md` (or `AGENTS.md`) inside the repo you're working in:
|
|
12
|
-
- [`clients/client-template/AGENT.md`](./clients/client-template/AGENT.md)
|
|
13
|
-
- [`team-clients/AGENT.md`](./team-clients/AGENT.md)
|
|
14
|
-
- [`team-infra/AGENT.md`](./team-infra/AGENT.md)
|
|
15
|
-
- [`team-web/AGENT.md`](./team-web/AGENT.md)
|
|
16
|
-
|
|
17
|
-
This root is a folder of independent git repos (`clients/client-*`,
|
|
18
|
-
`team-*`); it is deliberately not a git repo itself. Each repo has its own
|
|
19
|
-
conventions — always read the repo-level agentic file before editing inside it.
|
|
20
|
-
|
|
21
|
-
## Updating conventions
|
|
22
|
-
|
|
23
|
-
Edit `AGENT.md` (root or repo) and any affected skills, not this file.
|
|
24
|
-
This file is a pointer.
|
|
12
|
+
Do not add rule content to this file. Edit `AGENT.md` instead.
|
|
@@ -134,7 +134,9 @@ installagent/
|
|
|
134
134
|
├── team-web/ # installagent.com + team hub (Next.js pnpm workspace)
|
|
135
135
|
├── team-design/ # Install Agent design system source
|
|
136
136
|
├── team-branding/ # logo files
|
|
137
|
-
|
|
137
|
+
├── skills/ # cross-cutting agent skills (client deliverables pipeline)
|
|
138
|
+
├── team-tools/ # the `ia` CLI + SDK + MCP server for technicians
|
|
139
|
+
└── systems-department/ # independent self-serve storefront repo (unbranded working name)
|
|
138
140
|
```
|
|
139
141
|
|
|
140
142
|
## Orient yourself in this order
|
|
@@ -29,13 +29,13 @@ skills/
|
|
|
29
29
|
├── backtest-acceptance-gates/ # prove an automation works before the client trusts it (ground truth, evidence, gates)
|
|
30
30
|
├── installagent-brand-kit/ # our brand for print/PDF/Excalidraw/decks (logo + brand red #d11a1a)
|
|
31
31
|
├── design-system/ # the Install Agent Design System (screens/UI)
|
|
32
|
-
├── house-voice/ # house voice for client-facing writing
|
|
32
|
+
├── house-voice/ # house voice for client-facing writing; client messages are short by default (150 words = a flag, not a cap)
|
|
33
33
|
├── contract-tech-agnostic/ # contracts/SOWs by FUNCTION and OUTCOME, never tech (+ SOW template in references/)
|
|
34
34
|
├── linear/ # Linear issue workflow for client build work (status discipline, sub-issue trees, PR linking)
|
|
35
35
|
├── ia-cli/ # route internal ops through the `ia` CLI (team-tools) — decision map + guardrails
|
|
36
36
|
├── gcloud-cli-setup/ # one named gcloud configuration per account/client + check-before-you-run discipline
|
|
37
37
|
├── slack-voice/ # INTERNAL messages (Slack, email, chat): ~100 words, terse bullets, hard numbers (client → house-voice)
|
|
38
|
-
├── github-profile/ # force gh CLI + git commits onto the
|
|
38
|
+
├── github-profile/ # force gh CLI + git commits onto the work account in root `.github-account` before any GitHub action
|
|
39
39
|
└── init_repo/ # explicit-only /init_repo — dev branch + default branch + one milestone/root-branch per leaf issue
|
|
40
40
|
```
|
|
41
41
|
|
|
@@ -17,7 +17,7 @@ workflows, and diagrams across more than one repo. Repo-local skills live in
|
|
|
17
17
|
## How these get loaded
|
|
18
18
|
|
|
19
19
|
Every skill is `<name>/SKILL.md` with YAML frontmatter (`name`, `description`).
|
|
20
|
-
|
|
20
|
+
22 of them are symlinked into [`../.claude/skills/`](../.claude/skills/), so Claude
|
|
21
21
|
Code and Cowork register them automatically — they appear in the skill menu and
|
|
22
22
|
fire on their own without being invoked by name. The `description` is the
|
|
23
23
|
trigger; the body is only read once the skill fires.
|
|
@@ -76,9 +76,17 @@ context, intake, agent bank, secrets, `wizard`/`doctor`). Check it before
|
|
|
76
76
|
writing any custom script against GitHub, Airtable, Linear, Drive, n8n, or the
|
|
77
77
|
portal.
|
|
78
78
|
|
|
79
|
-
[`github-profile`](./github-profile/) — force gh CLI + git commits onto
|
|
80
|
-
|
|
81
|
-
logged in; only one
|
|
79
|
+
[`github-profile`](./github-profile/) — force gh CLI + git commits onto this
|
|
80
|
+
machine's work account before any GitHub action. The account comes from the
|
|
81
|
+
workspace-root `.github-account` file (two accounts are logged in; only one
|
|
82
|
+
is the work identity).
|
|
83
|
+
|
|
84
|
+
[`slack-voice`](./slack-voice/) — internal messages (Slack, email, chat):
|
|
85
|
+
terse, bulleted, hard numbers, about 100 words for an update. Client-facing
|
|
86
|
+
words stay with `house-voice`.
|
|
87
|
+
|
|
88
|
+
[`gcloud-cli-setup`](./gcloud-cli-setup/) — one named gcloud configuration
|
|
89
|
+
per account or client, and the check-before-you-run discipline.
|
|
82
90
|
|
|
83
91
|
[`init_repo`](./init_repo/) — **explicit-invocation only**, never fires on
|
|
84
92
|
its own. Run `/init_repo` against an existing `client-<slug>` repo to create
|
|
@@ -119,6 +119,9 @@ The onboarding checklist must **not feel overwhelming**. Rules:
|
|
|
119
119
|
- **Measurable, hedged outcomes** — never guarantees.
|
|
120
120
|
- **State the full commercial model** including the capped API-credit pass-through.
|
|
121
121
|
- **No secrets / customer data / real VINs** in any doc.
|
|
122
|
+
- **No dates in the PDFs.** `brand.render_pdf` refuses them. Use "month one",
|
|
123
|
+
"week 4" or "at acceptance" in place of a calendar date. Pass
|
|
124
|
+
`allow_dates=True` only when the user explicitly asks for a date.
|
|
122
125
|
|
|
123
126
|
## Before you finish — checklist
|
|
124
127
|
|
|
@@ -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: 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) |
|
|
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
|
|
@@ -43,6 +43,18 @@ you keep that same build folder's `onboarding.html` in sync:
|
|
|
43
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**, kept current as access lands. Mirror §1 only into `onboarding.html`'s Access tab. |
|
|
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
|
|
|
@@ -291,6 +303,8 @@ tokens or empty bullets.
|
|
|
291
303
|
- [ ] `04-access-checklist.md`: §1 systems-only credentials table (every
|
|
292
304
|
sales-call software has a row) + §2 decisions/information; Status set from
|
|
293
305
|
what's actually confirmed (not assumed); §1 mirrored into the Access tab.
|
|
306
|
+
- [ ] Each of `01`–`04` has its Type line under the title:
|
|
307
|
+
`<!-- Type: spec -->` in `01` and `03`, `Type: spec` in `02` and `04`.
|
|
294
308
|
- [ ] `onboarding.html`: no `REPLACE_WITH_*` tokens left unfilled (or, on an
|
|
295
309
|
update pass, only the ones the tech-discovery call still hasn't
|
|
296
310
|
answered); Client tab agrees with `02`, not the other way around.
|
|
@@ -10,6 +10,7 @@ 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
|
|
@@ -56,6 +57,7 @@ daily review queue that shrinks as the system learns."><br/>
|
|
|
56
57
|
|
|
57
58
|
```markdown
|
|
58
59
|
# Tech Spec — <short system name>
|
|
60
|
+
Type: spec
|
|
59
61
|
|
|
60
62
|
**Audience:** Install Agent engineering. Internal.
|
|
61
63
|
**Status:** Pre-implementation, ready for build kickoff.
|
|
@@ -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.>
|
|
@@ -154,6 +157,7 @@ no access beyond the named systems.>
|
|
|
154
157
|
|
|
155
158
|
```markdown
|
|
156
159
|
# Access & Credentials Checklist — <slug>
|
|
160
|
+
Type: spec
|
|
157
161
|
|
|
158
162
|
Internal tracker: same items as `03-client-onboarding.md`'s §1 Access and §2
|
|
159
163
|
Decisions, plus what we actually have. `03` is the **ask** we send the
|