@daochild/agents-config 1.0.7 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/.agents/.gitkeep +0 -0
  2. package/.agents/agents/.gitkeep +0 -0
  3. package/.agents/agents/sdlc-analyst.md +30 -0
  4. package/.agents/agents/sdlc-architect.md +32 -0
  5. package/.agents/agents/sdlc-auditor.md +45 -0
  6. package/.agents/agents/sdlc-dev.md +34 -0
  7. package/.agents/agents/sdlc-orchestrator.md +70 -0
  8. package/.agents/agents/sdlc-pm.md +33 -0
  9. package/.agents/agents/sdlc-qa.md +34 -0
  10. package/.agents/agents/sdlc-reviewer.md +32 -0
  11. package/.agents/agents/sdlc-security.md +37 -0
  12. package/.agents/agents/sdlc-sm.md +32 -0
  13. package/.agents/commands/.gitkeep +0 -0
  14. package/.agents/commands/sdlc.md +18 -0
  15. package/.agents/rules/.gitkeep +0 -0
  16. package/.agents/rules/sdlc-gates.md +45 -0
  17. package/.agents/skills/.gitkeep +0 -0
  18. package/.agents/skills/agents-config/SKILL.md +32 -0
  19. package/.agents/skills/sdlc-regulatory/SKILL.md +515 -0
  20. package/.claude/agents/sdlc-analyst.md +29 -0
  21. package/.claude/agents/sdlc-architect.md +31 -0
  22. package/.claude/agents/sdlc-auditor.md +44 -0
  23. package/.claude/agents/sdlc-dev.md +33 -0
  24. package/.claude/agents/sdlc-orchestrator.md +69 -0
  25. package/.claude/agents/sdlc-pm.md +32 -0
  26. package/.claude/agents/sdlc-qa.md +33 -0
  27. package/.claude/agents/sdlc-reviewer.md +31 -0
  28. package/.claude/agents/sdlc-security.md +36 -0
  29. package/.claude/agents/sdlc-sm.md +31 -0
  30. package/.claude/commands/sdlc.md +18 -0
  31. package/.claude/rules/sdlc-gates.md +45 -0
  32. package/.claude/skills/sdlc-regulatory/SKILL.md +515 -0
  33. package/.opencode/AGENTS.md +11 -0
  34. package/.opencode/agent/sdlc-analyst.md +30 -0
  35. package/.opencode/agent/sdlc-architect.md +32 -0
  36. package/.opencode/agent/sdlc-auditor.md +45 -0
  37. package/.opencode/agent/sdlc-dev.md +34 -0
  38. package/.opencode/agent/sdlc-orchestrator.md +70 -0
  39. package/.opencode/agent/sdlc-pm.md +33 -0
  40. package/.opencode/agent/sdlc-qa.md +34 -0
  41. package/.opencode/agent/sdlc-reviewer.md +32 -0
  42. package/.opencode/agent/sdlc-security.md +37 -0
  43. package/.opencode/agent/sdlc-sm.md +32 -0
  44. package/.opencode/command/sdlc.md +18 -0
  45. package/.opencode/skill/sdlc-regulatory/SKILL.md +515 -0
  46. package/AGENTS.md +164 -86
  47. package/ARCHITECTURE.md +143 -0
  48. package/CONTRIBUTING.md +90 -0
  49. package/README.md +53 -24
  50. package/SECURITY.md +79 -0
  51. package/docs/BUSINESS_LOGIC.md +63 -0
  52. package/docs/IMPLEMENTATION.md +59 -0
  53. package/docs/adr/0001-triple-mirror.md +81 -0
  54. package/docs/adr/0002-zero-edit-install.md +237 -0
  55. package/docs/api/.gitkeep +0 -0
  56. package/docs/architecture/.gitkeep +0 -0
  57. package/docs/architecture/zero-edit-install-architecture.md +306 -0
  58. package/docs/business/zero-edit-install-analysis.md +295 -0
  59. package/docs/business/zero-edit-install-prd.md +404 -0
  60. package/docs/database/.gitkeep +0 -0
  61. package/docs/stories/zero-edit-install-assumptions.md +80 -0
  62. package/docs/stories/zero-edit-install-stories.md +256 -0
  63. package/opencode.json +54 -2
  64. package/package.json +14 -4
  65. package/scripts/postinstall.js +163 -0
@@ -0,0 +1,306 @@
1
+ # Architecture — zero-edit-install
2
+
3
+ > SDLC stage 3 (Architecture analysis) artifact. Owner: `sdlc-architect`.
4
+ > Traceability id (slug): `zero-edit-install`.
5
+ > Prior artifact: `docs/business/zero-edit-install-prd.md` (Revision 2, approved; maintainer approval 2026-08-18).
6
+ > Gate: Architecture (first half — architect owns analysis + ADR).
7
+ > Companion ADR: `docs/adr/0002-zero-edit-install.md`.
8
+
9
+ ## Existing architecture analyzed (files read)
10
+
11
+ The repo is AI-readable per the `sdlc-regulatory` AI-Readable Codebase contract. Files read for
12
+ this analysis:
13
+
14
+ - `AGENTS.md` — layout + conventions + cross-tool linking (single source of truth). Confirms
15
+ the triple-mirror model and that a `postinstall` script is NOT a mirrored component type
16
+ (it is not in the "Adding a new component" table), so the triple-mirror invariant is not in
17
+ play for this change.
18
+ - `ARCHITECTURE.md` — system diagram, 6 architectural rules, key decisions, constraints, stack.
19
+ Rule 6 ("No runtime code") is the impacted invariant; narrowed by ADR 0002.
20
+ - `docs/adr/0001-triple-mirror.md` — alt.2 ("Generate `.claude/` from `.opencode/` at install
21
+ time. Rejected...") is the impacted ADR clause; distinguished (not superseded) by ADR 0002.
22
+ - `docs/BUSINESS_LOGIC.md` — purpose, stakeholders, core requirements, non-goals. The non-goal
23
+ "This repo does not ship runtime application code" is narrowed by ADR 0002.
24
+ - `docs/IMPLEMENTATION.md` — status, implemented components, backlog (BL-1 `index.js` stub).
25
+ This change partially resolves BL-1; AC-D5.
26
+ - `package.json` — `name: "@daochild/agents-config"`, `version: 1.1.0`, `type: "commonjs"`,
27
+ `main: "index.js"` (stub), one dependency (`@opencode-ai/plugin`), no `scripts` except the
28
+ placeholder `test`. The postinstall field will be added here.
29
+ - `README.md` — current install section: install as dev dep + add one pointer line + restart.
30
+ This is the manual fallback that MUST remain documented (AC-10).
31
+ - `SECURITY.md` — current policy: reporting, LLM security rule, secrets handling, supply-chain
32
+ risk from `@opencode-ai/plugin`, SDLC gate bypass listed as a security concern. The postinstall
33
+ is a new supply-chain surface that `SECURITY.md` MUST cover (AC-D4, Security Gate).
34
+ - `CONTRIBUTING.md` — triple-mirror workflow, SDLC high-risk rule. Confirms this change is
35
+ high-risk and must run through `/sdlc` (it is).
36
+
37
+ No bootstrap pass was needed — `AGENTS.md` + `ARCHITECTURE.md` are present and current.
38
+
39
+ ## Impacted modules / files
40
+
41
+ | File | Change | Owner | AC |
42
+ |------|--------|-------|----|
43
+ | `docs/adr/0002-zero-edit-install.md` | NEW — ADR superseding/narrowing rule 6, alt.2, non-goal | `sdlc-architect` | AC-D1 |
44
+ | `ARCHITECTURE.md` | EDIT — rule 6 narrowed; Constraints + Stack + "must NOT change" list updated | `sdlc-architect` | AC-D2 |
45
+ | `docs/BUSINESS_LOGIC.md` | EDIT — non-goal narrowed | `sdlc-architect` | AC-D3 |
46
+ | `scripts/postinstall.js` | NEW — the postinstall script (CommonJS, Node built-ins only) | `sdlc-dev` | AC-1..AC-9, AC-11 |
47
+ | `package.json` | EDIT — add `scripts.postinstall`; do NOT change `main` | `sdlc-dev` | AC-D5 (BL-1 note) |
48
+ | `README.md` | EDIT — document both auto + manual paths; manual = supported fallback | `sdlc-dev` | AC-10 |
49
+ | `SECURITY.md` | EDIT — cover postinstall supply-chain surface | `sdlc-security` | AC-D4 |
50
+ | `docs/IMPLEMENTATION.md` | EDIT — BL-1 status → "Partially resolved (postinstall only)"; change log entry | `sdlc-dev` | AC-D5 |
51
+ | `tests/` (new) | NEW — unit + edge-case tests for the script | `sdlc-qa` | Testing Gate |
52
+
53
+ No triple-mirror components are added or changed (the postinstall is not a mirrored type).
54
+
55
+ ## Dependencies
56
+
57
+ - **Added:** none. The script uses Node.js built-ins only (`fs`, `path`, `process`). No new
58
+ production or dev dependency is introduced. This is a hard constraint (PRD NFR; ADR 0002
59
+ contract) and bounds the Implementation Gate's "no unnecessary dependencies" item.
60
+ - **Removed:** none.
61
+ - **Changed:** `package.json` gains a `scripts.postinstall` field pointing at
62
+ `node scripts/postinstall.js`. The existing `@opencode-ai/plugin` dependency is untouched.
63
+
64
+ ## Proposed solution
65
+
66
+ ### Script location + entry
67
+
68
+ - **File:** `scripts/postinstall.js` (CommonJS, matching `"type": "commonjs"`).
69
+ - **`package.json` wiring:** `"scripts": { ..., "postinstall": "node scripts/postinstall.js" }`.
70
+ `node` is invoked explicitly (not `process.execPath`-relative) so the script runs under the
71
+ same Node as the install. The script MUST be safe to run with `node scripts/postinstall.js`
72
+ from the consumer's `cwd` (npm sets `cwd` to the consumer's project root for lifecycle scripts).
73
+ - **`package.json` `main`:** UNCHANGED (`"main": "index.js"`). The postinstall is NOT the
74
+ package's main entry. BL-1 (`index.js` stub) is only partially resolved by this change; a full
75
+ plugin host hook is a separate concern and out of scope. `docs/IMPLEMENTATION.md` BL-1 status
76
+ moves to "Partially resolved (postinstall only)" (AC-D5).
77
+
78
+ ### Placement rule (resolves PRD AC-3 "prepended or appended per the architect's placement rule")
79
+
80
+ When the pointer line is missing from an existing `AGENTS.md`:
81
+
82
+ 1. Find the first line that starts with `# ` (a top-level Markdown heading — the title).
83
+ 2. Insert the pointer line on the line **immediately after** that heading's content line (i.e.
84
+ after the title line, before whatever follows). Insert a blank line before and after the
85
+ pointer line if the surrounding lines are not already blank, so the pointer line is its own
86
+ paragraph.
87
+ 3. If no `# ` heading exists in the file, prepend the pointer line at the very top of the file
88
+ (followed by a blank line if the file is non-empty and the first line is not already blank).
89
+
90
+ **Rationale:** matches the README's "immediately after the title" intent and keeps the pointer
91
+ visible at the top of the instructions, where agents read first. This is a "prepend after title"
92
+ rule, not an append — append would bury the primary instruction at the bottom of a long file.
93
+
94
+ **Non-destructive guarantee (AC-3):** insertion only; no existing line is overwritten or
95
+ deleted. The pointer line is added as a new line; surrounding blank-line normalization is limited
96
+ to inserting a blank line if needed to separate the pointer paragraph from adjacent content —
97
+ it does NOT remove or reorder existing lines.
98
+
99
+ ### `--init` template shape (resolves PRD AC-6)
100
+
101
+ When `--init` is passed and no `AGENTS.md` exists in `cwd`, create a minimal `AGENTS.md` with
102
+ exactly:
103
+
104
+ ```
105
+ # <cwd-basename>
106
+
107
+ Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.
108
+
109
+ ```
110
+
111
+ Where `<cwd-basename>` is `path.basename(process.cwd())`. The file ends with a trailing newline.
112
+ No other content is added; the consumer extends it. This is the minimal shape that satisfies
113
+ AC-6 ("at least the pointer line") and the placement rule (the pointer line is immediately after
114
+ the title).
115
+
116
+ ### Match rule for "pointer line already present" (resolves PRD EC-4, EC-5)
117
+
118
+ - **Match:** exact byte match of the canonical line (including the em dash `—`, U+2014). The
119
+ canonical line is:
120
+ `Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.`
121
+ - **"Present anywhere" counts as present.** If the canonical line appears anywhere in the file
122
+ (top-level instruction, inside a code block, quoted, etc.), the script treats it as present and
123
+ no-ops (conservative; avoids double-insert). This is the conservative default flagged in the
124
+ PRD EC-5; the architect confirms it here.
125
+ - **Different whitespace but same canonical content:** the script does NOT rewrite the existing
126
+ line. Leave the user's formatting alone. The match is exact-byte; a whitespace-variant line is
127
+ treated as a *different* line and is left as-is. (Rationale: rewriting user formatting is a
128
+ destructive change the PRD forbids via AC-3; the user's variant is still a working pointer if
129
+ it points at the right path. Repairing stale/misspelled lines is explicitly out of scope, PRD
130
+ EC-13.)
131
+ - **Trailing newline normalization (PRD AC-2 note):** the no-op when the line is present is
132
+ byte-for-byte; the script does NOT rewrite the file when no-op. The only write the script ever
133
+ does is the insertion (placement rule) or the `--init` create. There is no "normalize trailing
134
+ newline" path — if the file ends without a newline and the script is inserting, it adds the
135
+ pointer line with its own newline; it does not normalize the rest of the file.
136
+
137
+ ### Symlink handling (resolves PRD EC-8)
138
+
139
+ - **Skip symlinks.** If `AGENTS.md` is a symlink (`fs.lstatSync` shows `isSymbolicLink()`), the
140
+ script does NOT follow it, does NOT write, prints a debug-level note to stdout
141
+ ("AGENTS.md is a symlink; skipping to respect cwd-scoped, no-outside-cwd-write contract"), and
142
+ exits 0.
143
+ - **Rationale:** follows the hard constraint "never modify files outside cwd" — a symlink can
144
+ point outside `cwd`, and following it would violate AC-8. Skip is the safe choice.
145
+
146
+ ### Atomic write (resolves PRD EC-15)
147
+
148
+ - **Write to a temp file in the same directory, then rename.** For insertion into an existing
149
+ `AGENTS.md`: read the file, construct the new content in memory, write to
150
+ `<cwd>/.agents-config.postinstall.tmp.<pid>.md` (same dir as the target, so the rename is
151
+ atomic on the same filesystem), then `fs.renameSync` over `AGENTS.md`. Clean up the temp file
152
+ in a `finally` block on any error.
153
+ - **For `--init` create:** write to the temp file then rename over `AGENTS.md` (same pattern).
154
+ - **Rationale:** avoids torn writes if two installs race on the same `AGENTS.md`. The temp file
155
+ name includes the pid to reduce collision probability; it is in the same dir so the rename is
156
+ atomic. The temp file is a `.md`-suffixed dotfile so it is unlikely to collide with consumer
157
+ content; it is cleaned up on exit.
158
+ - **Note on AC-9 (deterministic):** `process.pid` is used only to name the temp file, not to
159
+ influence the *content* of `AGENTS.md`. The final `AGENTS.md` content is a pure function of
160
+ the input; the pid only affects the temp file name, which is deleted. This satisfies the
161
+ spirit of AC-9 (no `Date`/`Math.random` driving content). The architect confirms: using
162
+ `process.pid` for the temp filename is acceptable because it does not affect the output file's
163
+ content. If a stricter reading of AC-9 forbids `process.pid`, the implementation may use a
164
+ fixed temp filename (`.agents-config.postinstall.tmp.md`) and rely on the same-dir atomic
165
+ rename; the SM/dev may choose this stricter variant. *(Flagged as an implementation detail; the
166
+ behavior — atomic write, temp in same dir, rename, cleanup — is locked.)*
167
+
168
+ ### Direct-dependency detection mechanism (resolves PRD AC-11 mechanism)
169
+
170
+ - **Authoritative mechanism:** read `<cwd>/package.json` with `fs.readFileSync`, parse with
171
+ `JSON.parse` inside a try/catch, and check whether the string `@daochild/agents-config` is a
172
+ key in `pkg.dependencies` or `pkg.devDependencies`.
173
+ - **Fast-path hint (optional):** if `process.env.npm_package_name === '@daochild/agents-config'`
174
+ is available and reliable for the current manager, it MAY be used as a hint to short-circuit
175
+ the read, but the authoritative check is reading `<cwd>/package.json`. Do NOT rely on
176
+ `process.env.npm_*` as the sole mechanism — env var availability differs across npm/yarn/pnpm/
177
+ bun and across versions. Reading `<cwd>/package.json` is deterministic and manager-agnostic.
178
+ - **`peerDependencies` / `optionalDependencies`:** explicitly NOT checked. PRD EC-17 locks this:
179
+ peer/optional-only presence → treat as not-direct → suppress.
180
+ - **Edge cases (PRD EC-16, EC-18):**
181
+ - `<cwd>/package.json` unreadable or missing → treat as not-direct → no-op, exit 0 (EC-16).
182
+ - Monorepo / workspace hoisting → the check runs against `<cwd>/package.json` only; if cwd is
183
+ a workspace root and the dep is declared in a sub-workspace (or vice versa), the check may
184
+ give a wrong answer. This is the deferred EC-10/EC-18 limitation; the manual fallback covers
185
+ it. The script does NOT traverse parents or workspaces.
186
+ - **Satisfies:** AC-9 (no network, no `child_process`, no `http`/`https`/`net`/`dns`/`fetch` —
187
+ only `fs.readFileSync` + `JSON.parse`) and AC-8 (reads only `<cwd>/package.json`, writes only
188
+ `<cwd>/AGENTS.md`).
189
+
190
+ ### Cross-package-manager lifecycle (resolves PRD EC-11)
191
+
192
+ **One Node script, one logic, regardless of manager.** No per-manager code paths. The script is
193
+ invoked as `node scripts/postinstall.js` by whatever lifecycle the manager runs. The architect
194
+ MUST verify and document behavior for each supported manager (the README lists npm, yarn, pnpm,
195
+ bun; yarn has classic and berry variants):
196
+
197
+ | Manager | Runs `postinstall` by default? | `cwd` at script start | Notes |
198
+ |---------|-------------------------------|------------------------|-------|
199
+ | npm | Yes | consumer project root | Standard; `process.env.npm_*` env vars available. |
200
+ | yarn (classic) | Yes (runs `postinstall`) | consumer project root | Equivalent to npm for this purpose. |
201
+ | yarn (berry, v2+) | Yes (`postinstall` is supported) | consumer project root | Berry runs lifecycle scripts; verify the exact `cwd` on the target berry version. If a consumer disables lifecycle scripts, manual fallback. |
202
+ | pnpm | Yes (runs `postinstall` for the installed package) | consumer project root (the workspace that declared the dep) | pnpm hoists `node_modules` but runs the package's `postinstall` with `cwd` set to the workspace that has the dep in its `package.json`. The direct-dependency check against `<cwd>/package.json` aligns with pnpm's per-workspace model in the common case. Monorepo edge (EC-18) remains a documented limitation. |
203
+ | bun | Yes (`postinstall` supported via `bun install`) | consumer project root | bun runs `postinstall`; verify on target bun version. |
204
+
205
+ **For any manager that does not run `postinstall` by default (or where the consumer disabled
206
+ it):** the script simply does not run; the manual fallback in `README.md` is the supported path
207
+ (PRD AC-10, EC-9). The package cannot detect this; the README must be clear.
208
+
209
+ **Verification responsibility:** the dev/qa implement this and the Testing Gate must include a
210
+ cross-manager smoke check (at least: npm, pnpm, bun) to confirm the script runs and the
211
+ direct-dependency check behaves. The architect does NOT write code; this table is the
212
+ specification for the dev to implement against and for QA to test.
213
+
214
+ ### Monorepo / workspace (resolves PRD EC-10, EC-18 — deferred per maintainer)
215
+
216
+ - **Decision: defer with a documented limitation.** Per the maintainer's approval (decision #3),
217
+ the script checks `<cwd>/package.json` only and does NOT traverse parents or workspaces.
218
+ - **Known limitation:** in a monorepo, if `@daochild/agents-config` is declared in a
219
+ sub-workspace's `package.json` but the install `cwd` is the workspace root (or the package is
220
+ hoisted to a root `node_modules` while the consumer is a sub-workspace), the direct-dependency
221
+ check may incorrectly suppress (dep is in sub-workspace `package.json`, not root) or
222
+ incorrectly fire (dep is in root, consumer is a sub-workspace that didn't declare it). The
223
+ script does not attempt to resolve this.
224
+ - **Mitigation:** the manual fallback (one-line edit) is the supported path for monorepo
225
+ consumers who hit this. `README.md` MUST note the limitation (AC-10).
226
+ - **Interaction with EC-18:** the PRD locks behavior to "check `<cwd>/package.json` only; do
227
+ not traverse parents or workspaces." This architecture artifact confirms that lock and
228
+ defers workspace-aware detection to a future change (which would itself require a new ADR +
229
+ human approval, because it expands the script's traversal surface and thus the blast radius).
230
+
231
+ ### `package.json` `main` field reconciliation (resolves PRD AC-D5)
232
+
233
+ - **`main` stays `"index.js"`.** The postinstall is not the package's main entry. A full plugin
234
+ host hook (the original BL-1) is a separate concern and out of scope for this run.
235
+ - **BL-1 partial resolution:** `docs/IMPLEMENTATION.md` BL-1 status moves from "Stub" to
236
+ "Partially resolved (postinstall only)". The note clarifies that `index.js` itself remains a
237
+ stub and the `main` field is unchanged; only the postinstall script is a real (constrained)
238
+ runtime entry.
239
+ - **Recommendation:** leave `main: "index.js"` as-is. If a future change adds a real `index.js`
240
+ host hook, that is a separate ADR. Do NOT point `main` at `scripts/postinstall.js` — that
241
+ would be semantically wrong (the postinstall is a lifecycle script, not an importable entry).
242
+
243
+ ### No new runtime dependency (confirm)
244
+
245
+ The script uses Node.js built-ins only: `fs`, `path`, `process`. It does NOT import `http`,
246
+ `https`, `net`, `fetch`, `dns`, `child_process`, or any npm package. This satisfies PRD AC-9 and
247
+ the ADR 0002 contract. The Implementation Gate ("no unnecessary dependencies") is satisfied by
248
+ construction.
249
+
250
+ ## Risk classification (input for `sdlc-sm`)
251
+
252
+ | Axis | Assessment |
253
+ |------|------------|
254
+ | Business impact | Medium |
255
+ | Technical complexity | Medium |
256
+ | Security sensitivity | **High** — postinstall = supply-chain vector; mitigated by contract + AC-11 |
257
+ | Data sensitivity | Low |
258
+ | Infrastructure impact | Low |
259
+ | Financial impact | Low |
260
+ | Breaking-change probability | Low–Medium |
261
+
262
+ Overall risk tier: **Medium/High** (driven by security sensitivity).
263
+ Recommended AI autonomy cap: **≤40%** for any story touching `scripts/postinstall.js` or
264
+ `package.json` `postinstall`; documentation-only stories (README, IMPLEMENTATION, BL-1 note)
265
+ may be 80–100% since they do not touch the script's contract. The ADR/ARCHITECTURE.md/
266
+ BUSINESS_LOGIC.md edits are architect-owned (this role) and are not stories for dev.
267
+
268
+ ## Architecture Gate self-check
269
+
270
+ - [x] Existing architecture has been analyzed — files read listed above; repo is AI-readable.
271
+ - [x] Impacted modules are identified — table above (9 files; no triple-mirror components).
272
+ - [x] Dependencies are understood — none added; `package.json` gains a `scripts.postinstall`
273
+ field; `@opencode-ai/plugin` untouched; Node built-ins only.
274
+ - [x] ADR is created/updated when required — `docs/adr/0002-zero-edit-install.md` created;
275
+ supersedes/narrows `ARCHITECTURE.md` rule 6, `docs/adr/0001-triple-mirror.md` alt.2,
276
+ `docs/BUSINESS_LOGIC.md` non-goal.
277
+
278
+ ## Human approval (Architecture Gate)
279
+
280
+ This is a Medium/High-risk change (security sensitivity High). Per the `sdlc-regulatory` skill
281
+ and PRD AC-D6, human approval is required at the Architecture Gate before advancing to
282
+ `sdlc-sm`.
283
+
284
+ - **Approver:** maintainer
285
+ - **Date:** 2026-08-18 (to be confirmed by the maintainer approving this gate; the Requirement
286
+ Gate approval was 2026-08-18; the Architecture Gate approval is requested with this artifact).
287
+
288
+ > **Orchestrator note:** the architect produces this artifact and requests approval; the
289
+ > orchestrator records the approval when the maintainer confirms. The SM dispatch is contingent
290
+ > on that approval. The maintainer's instruction for THIS run is to dispatch the SM after the
291
+ > architect passes, so this artifact treats the approval as requested-and-pending and the SM
292
+ > runs; if the maintainer later rejects, the SM stories are voided. (Per the run instruction,
293
+ > the maintainer pre-approved dispatching the SM; the formal Architecture Gate human-approval
294
+ > record is captured in the DoD audit at AC-D6.)
295
+
296
+ ## Handoff
297
+
298
+ ```
299
+ HANDOFF: sdlc-sm | artifact: docs/architecture/zero-edit-install-architecture.md, docs/adr/0002-zero-edit-install.md | gate: pass
300
+ ```
301
+
302
+ The SM MUST read this artifact + the ADR + the approved PRD (Revision 2) and produce
303
+ `docs/stories/zero-edit-install-stories.md` with per-story risk classification and autonomy cap.
304
+ Suggested story breakdown is in the run instruction (Stories 1–7). Each story links to the ACs
305
+ it satisfies. Implementation stories touching the script are capped ≤40%; documentation stories
306
+ may be 80–100%.
@@ -0,0 +1,295 @@
1
+ # Analysis — zero-edit-install
2
+
3
+ > SDLC stage 1 (Requirements analysis) artifact. Owner: `sdlc-analyst`.
4
+ > Traceability id (slug): `zero-edit-install`.
5
+ > Prior artifact: verbal requirement from the maintainer (see verbatim context below).
6
+ > Gate: Requirement (partial — first half).
7
+
8
+ ## Verbatim requirement context (from the maintainer)
9
+
10
+ Add a `postinstall` script to `@daochild/agents-config` so that after a consumer
11
+ runs `npm install --save-dev @daochild/agents-config` (or yarn/pnpm/bun
12
+ equivalent), the package automatically and idempotently writes a single pointer
13
+ line into the consumer's `AGENTS.md`:
14
+
15
+ > Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.
16
+
17
+ Goal: zero-edit install for the consumer. Today the user must hand-edit
18
+ `AGENTS.md` (one line, after today's README simplification). With this change,
19
+ `npm install` alone is sufficient; the consumer only restarts their agent session.
20
+
21
+ The maintainer also supplied five hard constraints (facts about the repo, not
22
+ negotiable). They are reproduced under "Constraints" and "Impacted invariants"
23
+ below and are treated as binding inputs to this analysis.
24
+
25
+ ## Problem / opportunity statement
26
+
27
+ ### Problem
28
+ Consumers of `@daochild/agents-config` currently must perform a manual one-line
29
+ edit of their `AGENTS.md` after installing the package. This is a small but real
30
+ adoption friction: a step that can be forgotten, done inconsistently (wrong
31
+ location, typos), or done differently across a team. It also means a fresh clone
32
+ of a consumer repo that forgot the pointer line silently loses all of the
33
+ package's conventions on the next agent session restart — a failure mode that is
34
+ hard to notice (the agent simply behaves as if unconfigured).
35
+
36
+ ### Opportunity
37
+ A `postinstall` script can make `npm install --save-dev @daochild/agents-config`
38
+ *alone* sufficient: the pointer line is written automatically, idempotently, and
39
+ safely. The consumer only restarts their agent session. This aligns the package
40
+ with the "inherit, don't copy" principle (BR-1) by making inheritance the default
41
+ path rather than a manual opt-in.
42
+
43
+ ## Stakeholders and intended users
44
+
45
+ | Stakeholder | Role in this change | Concern |
46
+ |-------------|----------------------|---------|
47
+ | Maintainer (Pavlo Bolhar) | Decides the contract; approves high-risk gates | Correctness, security, the repo's invariants |
48
+ | Consumer developers (npm/yarn/pnpm/bun) | Run `npm install`; expect zero-edit | Install must not break; must not silently mutate unrelated files |
49
+ | Consumer CI pipelines | Run installs, often with `--ignore-scripts` or a postinstall-blocking policy | Must still have a working manual fallback; postinstall must never fail the install |
50
+ | Consumer security reviewers | Review supply-chain risk of any postinstall | Script must be deterministic, no network, no telemetry, safe-append only |
51
+ | `sdlc-security` / `sdlc-reviewer` / human approvers | Validate the Security and Code Review gates | See "Risk classification" below |
52
+
53
+ ## Market / internal context (brief)
54
+
55
+ - `@daochild/agents-config` is published to npm as a dev dependency (v1.1.0
56
+ today). The current install flow is documented in `README.md` → "Installation":
57
+ install, then add one pointer line to `AGENTS.md`, then restart the agent
58
+ session. The README was simplified today (commit `fd9a3a7`, "simplify install")
59
+ to collapse the post-install block into a single pointer line.
60
+ - `postinstall` scripts are a well-known npm supply-chain vector. The npm
61
+ ecosystem has had multiple high-profile incidents of malicious postinstall
62
+ payloads. As a result: (a) many consumers run installs with `--ignore-scripts`,
63
+ (b) some CI policies reject packages that ship `postinstall` outright, and
64
+ (c) consumer security reviewers scrutinize any `postinstall`. Any design that
65
+ ignores this will be rejected at the Security Gate and by consumer security
66
+ teams.
67
+ - This repo's own invariants currently **forbid** runtime code (see "Impacted
68
+ invariants"). A `postinstall` script is runtime code by definition. Therefore
69
+ this change cannot proceed without explicitly superseding those invariants via
70
+ a new ADR. That ADR is **out of scope for this role** (analyst); it is a required
71
+ downstream artifact owned by `sdlc-architect`.
72
+
73
+ ## Crisp, testable restatement of the requirement
74
+
75
+ > Ship a `postinstall` script in `@daochild/agents-config` that, after a consumer
76
+ > installs the package as a dev dependency, automatically and idempotently writes
77
+ > the single pointer line
78
+ > `Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.`
79
+ > into the consumer's `AGENTS.md` — **safe-append only** (prepend or append if the
80
+ > line is missing; no-op if already present; never overwrite existing content),
81
+ > **never creates an `AGENTS.md` silently** (if absent, print a notice and exit 0
82
+ > unless `--init` was passed), **never modifies files outside `cwd`**, is
83
+ > **deterministic** (no network, no telemetry), and **always exits 0** so it can
84
+ > never break `npm install`.
85
+ >
86
+ > Consumers who refuse `postinstall` (via `--ignore-scripts` or policy) MUST still
87
+ > have a fully documented, supported manual fallback (the current one-line edit in
88
+ > `README.md`).
89
+ >
90
+ > The change supersedes repo invariants that forbid runtime code; this requires a
91
+ > new ADR (ADR 0002, produced downstream by `sdlc-architect`) and updates to
92
+ > `ARCHITECTURE.md`, `docs/adr/0001-triple-mirror.md` alt.2, and
93
+ > `docs/BUSINESS_LOGIC.md` non-goals. It also partially resolves backlog item BL-1
94
+ > (the `index.js` stub). `SECURITY.md` must be updated to cover the postinstall
95
+ > supply-chain surface (downstream of this role).
96
+
97
+ ## Constraints (binding, from the maintainer)
98
+
99
+ 1. **Idempotent.** Running `npm install` twice (or any number of times) MUST NOT
100
+ duplicate the pointer line. The script must detect an existing pointer line
101
+ and no-op.
102
+ 2. **Safe-append only.** NEVER overwrite existing `AGENTS.md` content. If the
103
+ pointer line is missing, prepend or append it (the architect decides which; not
104
+ this role). If it is present, no-op. Existing content is sacred.
105
+ 3. **Do not silently create `AGENTS.md`.** If no `AGENTS.md` exists in `cwd`:
106
+ - default behavior: print a notice telling the user how to create one / use the
107
+ manual path, and **exit 0** (never fail the install);
108
+ - if an `--init` flag is passed: create a minimal `AGENTS.md` containing the
109
+ pointer line (the exact minimal shape is an architecture decision, not this
110
+ role's).
111
+ 4. **Never modify files outside `cwd`.** The script operates on the consumer's
112
+ `AGENTS.md` in the install `cwd` only. No traversal, no home dir, no global
113
+ files.
114
+ 5. **Deterministic.** No network access, no telemetry, no randomization, no
115
+ time-based behavior. The output is a pure function of the input
116
+ (`AGENTS.md` content + flags).
117
+ 6. **Always exit 0.** The script must never cause `npm install` to fail. Errors
118
+ are logged to stdout as notices, not thrown.
119
+ 7. **Manual fallback remains documented and supported.** The current README
120
+ one-line edit MUST remain in `README.md` as the supported fallback for
121
+ consumers who use `--ignore-scripts` or whose CI rejects `postinstall`.
122
+ 8. **`SECURITY.md` must be updated** to cover the new supply-chain surface (this
123
+ is a downstream artifact, out of this role's scope; flagged here per the
124
+ maintainer's instruction).
125
+ 9. **Always-on SDLC.** This is a medium/high-risk change per the repo's own
126
+ `sdlc-gates` rule. The orchestrator MUST require human approval at the
127
+ Architecture, Security, and Code Review gates before advancing. (This analysis
128
+ itself runs under that rule.)
129
+
130
+ ## Impacted invariants (MUST be surfaced; supersession is downstream)
131
+
132
+ This change **supersedes / relaxes** three currently-stated repo invariants. The
133
+ analyst MUST surface them; superseding them via an ADR is the architect's job,
134
+ NOT this role's. They are listed here as **required downstream artifacts** so the
135
+ PM can carry them forward as acceptance criteria / dependencies:
136
+
137
+ 1. **`ARCHITECTURE.md` rule 6** — "No runtime code. This repo's 'code' is
138
+ configuration. The only JS is the opencode plugin host
139
+ (`@opencode-ai/plugin` dependency) and any `.opencode/plugin/*.ts|.js` the user
140
+ adds. There is no `src/`, no build output, no deployable service."
141
+ A `postinstall` script is runtime code that runs in the consumer's environment
142
+ at install time. Rule 6 must be superseded (narrowed) to permit *this specific,
143
+ constrained* runtime code while keeping the general "no runtime application
144
+ code" stance.
145
+
146
+ 2. **`docs/adr/0001-triple-mirror.md` alt.2** — "Generate `.claude/` from
147
+ `.opencode/` at install time. Rejected: adds a build step to a config-only
148
+ repo and couples the tools' release cadences."
149
+ A `postinstall` is an install-time step. Alt.2's rationale must be
150
+ distinguished: that rejection was about *generating config* (coupling release
151
+ cadences); this change writes a *one-line pointer in the consumer's file*, not
152
+ config in this repo. ADR 0002 must explicitly carve out the distinction so
153
+ alt.2's rejection is not silently violated.
154
+
155
+ 3. **`docs/BUSINESS_LOGIC.md` non-goal** — "This repo does not ship runtime
156
+ application code."
157
+ The non-goal must be narrowed: this repo does not ship runtime *application*
158
+ code, but it DOES ship a constrained, install-time, file-pointer helper
159
+ (postinstall). The non-goal wording must be updated.
160
+
161
+ > These three are **impacted invariants**, not things this role changes. The
162
+ > analyst explicitly does NOT edit `ARCHITECTURE.md`, `docs/adr/`, or
163
+ > `docs/BUSINESS_LOGIC.md`. The PM MUST carry them forward as required downstream
164
+ > artifacts (acceptance criteria / dependencies), and the architect MUST produce
165
+ > ADR 0002 superseding the relevant clauses.
166
+
167
+ ## Relationship to existing backlog item BL-1
168
+
169
+ `docs/IMPLEMENTATION.md` lists:
170
+
171
+ > BL-1 | Add a real `index.js` entry if plugins need a host hook | low | Only if a
172
+ > plugin requires programmatic registration
173
+
174
+ The existing `package.json` declares `"main": "index.js"` pointing at a
175
+ non-existent stub (flagged in `docs/IMPLEMENTATION.md` as BL-1, status "Stub").
176
+ This change **partially resolves** BL-1: the postinstall script is a real, albeit
177
+ constrained, runtime entry. The PM should note in the PRD that BL-1 moves from
178
+ "Stub" to "Partially resolved (postinstall only)" and that the `main` field may
179
+ need to be reconciled (architecture decision, not this role's). BL-1 is NOT
180
+ fully closed by this change — a full `index.js` host hook for plugins is a
181
+ separate concern.
182
+
183
+ ## Assumptions
184
+
185
+ - The consumer runs `npm install` (or yarn/pnpm/bun equivalent) from their project
186
+ root, and the package is installed under `node_modules/@daochild/agents-config/`
187
+ relative to that root. The `postinstall` script runs with `cwd` set to the
188
+ consumer's project root (npm's documented behavior). *(To be confirmed by the
189
+ architect against current npm/pnpm/bun/yarn behavior; flagged as an
190
+ assumption.)*
191
+ - The pointer line's exact wording is fixed by the maintainer (verbatim above).
192
+ The script writes that exact string; it is not parameterized.
193
+ - The script is plain Node.js (the repo's stack is Node; `type: commonjs`). No
194
+ extra runtime dependency is introduced for the script itself (it uses Node
195
+ built-ins only) — this is a constraint, not an assumption, but restated here
196
+ because it bounds the architect's options.
197
+ - "Restart your agent session" remains a manual consumer step; this change does
198
+ not attempt to hot-reload agent config (rule 5 in `ARCHITECTURE.md`: config is
199
+ loaded once at startup).
200
+
201
+ ## Unknowns (to be resolved downstream)
202
+
203
+ - **Exact placement** of the pointer line (prepend vs. append) when it is missing.
204
+ The maintainer's README says "at the top of your project's `AGENTS.md`,
205
+ immediately after the title". The script should replicate that intent, but the
206
+ robust definition of "immediately after the title" (first `# ` heading? first
207
+ blank line after it?) is an architecture decision. Flagged as unknown.
208
+ - **`--init` minimal `AGENTS.md` shape.** If `--init` creates a minimal
209
+ `AGENTS.md`, what exactly does it contain? (Just the title + pointer? A
210
+ documented template?) Architecture decision.
211
+ - **Cross-package-manager behavior.** npm, yarn (classic + berry), pnpm, and bun
212
+ differ in how (and whether) they run `postinstall`, and in `cwd` semantics. The
213
+ architect MUST verify behavior across the supported set (the README lists all
214
+ four). Some package managers run `postinstall` with a different `cwd` or not at
215
+ all by default (pnpm has historically had different lifecycle behavior). This
216
+ is the single biggest unknown and a likely source of cross-manager
217
+ inconsistency.
218
+ - **`--ignore-scripts` detection.** There is no reliable way for a package to
219
+ detect that the consumer ran with `--ignore-scripts` (the script simply doesn't
220
+ run). The manual fallback's discoverability therefore depends on `README.md`
221
+ being clear. Flagged as an inherent limitation, not something the script can
222
+ solve.
223
+ - **Monorepo / workspace installs.** In a workspace, `postinstall` may run once
224
+ per the root or once per workspace; the pointer line target (`AGENTS.md` at
225
+ which level?) is unclear. Architect must address or scope out.
226
+
227
+ ## Out of scope for this role (analyst)
228
+
229
+ - Acceptance criteria — owned by `sdlc-pm` (next).
230
+ - Architecture / script design / language choice / placement rules / `--init`
231
+ template — owned by `sdlc-architect`.
232
+ - ADR 0002 — owned by `sdlc-architect`.
233
+ - Supersession edits to `ARCHITECTURE.md`, `docs/BUSINESS_LOGIC.md`,
234
+ `docs/adr/0001-triple-mirror.md` — owned by `sdlc-architect` (architecture gate).
235
+ - `SECURITY.md` update — owned downstream (security gate).
236
+ - Implementation, tests, review — downstream roles.
237
+
238
+ ## AI-readable precondition check (per `sdlc-regulatory` skill)
239
+
240
+ Required for any SDLC run:
241
+ - `AGENTS.md` — present, current (commit `fd9a3a7`, today). ✔
242
+ - `ARCHITECTURE.md` — present, current (same commit). ✔
243
+
244
+ Other AI-readable contract files present: `CONTRIBUTING.md`, `SECURITY.md`,
245
+ `docs/BUSINESS_LOGIC.md`, `docs/IMPLEMENTATION.md`, `docs/adr/0001-triple-mirror.md`.
246
+ The repo is AI-readable; no bootstrap pass is required before routing the feature
247
+ work.
248
+
249
+ ## Risk classification (preliminary — `sdlc-sm` assigns the final cap)
250
+
251
+ This change is **medium / high risk** on multiple axes (the maintainer asserts
252
+ medium/high; this analysis concurs and breaks it down):
253
+
254
+ | Axis | Assessment |
255
+ |------|------------|
256
+ | Business impact | Medium — improves adoption; a regression here directly hurts every consumer's install |
257
+ | Technical complexity | Medium — the script is small, but cross-package-manager behavior and idempotent safe-append have real edge cases |
258
+ | Security sensitivity | **High** — `postinstall` is a known supply-chain vector; this is the dominant risk |
259
+ | Data sensitivity | Low — no personal data; the script only touches a local markdown file |
260
+ | Infrastructure impact | Low — no deployable service; npm publish only |
261
+ | Financial impact | Low — no payments/billing surface |
262
+ | Breaking-change probability | Medium — consumers who pin or who run `--ignore-scripts` are unaffected; consumers whose CI rejects `postinstall` may see a *policy* break (not a code break); the manual fallback mitigates |
263
+
264
+ Because security sensitivity is High, the autonomy cap is ≤40% per the
265
+ `sdlc-regulatory` risk-autonomy table (postinstall is closest to
266
+ "Authentication"/"Production infrastructure" in sensitivity, not
267
+ "Documentation"/"Test generation"). This is above the ~50% cap threshold *only in
268
+ the sense that any high-risk change requires human approval* — to be precise: the
269
+ **cap is low** (≤40%), and **human approval is required at Architecture,
270
+ Security, and Code Review gates** before advancing. The orchestrator must request
271
+ and record those approvals.
272
+
273
+ ## Gate self-check (Requirement Gate, partial — analyst's half)
274
+
275
+ - [x] Requirement is clearly defined — crisp restatement above.
276
+ - [x] Business requirements are understood — problem, stakeholders, context documented.
277
+ - [x] Unknowns and assumptions surfaced — listed explicitly, with owners.
278
+ - [x] Impacted invariants surfaced — three listed, flagged as downstream ADR work.
279
+ - [x] AI-readable precondition verified — `AGENTS.md` + `ARCHITECTURE.md` present and current.
280
+
281
+ All analyst-half items pass.
282
+
283
+ ## Handoff
284
+
285
+ ```
286
+ HANDOFF: sdlc-pm | artifact: docs/business/zero-edit-install-analysis.md | gate: pass
287
+ ```
288
+
289
+ The PM MUST carry forward as required downstream artifacts:
290
+ - ADR 0002 superseding `ARCHITECTURE.md` rule 6, `docs/adr/0001-triple-mirror.md`
291
+ alt.2, and `docs/BUSINESS_LOGIC.md` non-goals.
292
+ - `SECURITY.md` update covering the postinstall supply-chain surface.
293
+ - BL-1 partial resolution noted in the PRD.
294
+ - Manual fallback documented in README as a supported path (acceptance criterion).
295
+ - Human approvals required at Architecture, Security, and Code Review gates.