@daochild/agents-config 1.0.5 → 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 (76) 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/README.md +3 -0
  33. package/.claude/skills/sdlc-regulatory/SKILL.md +515 -0
  34. package/.opencode/AGENTS.md +11 -0
  35. package/.opencode/agent/sdlc-analyst.md +30 -0
  36. package/.opencode/agent/sdlc-architect.md +32 -0
  37. package/.opencode/agent/sdlc-auditor.md +45 -0
  38. package/.opencode/agent/sdlc-dev.md +34 -0
  39. package/.opencode/agent/sdlc-orchestrator.md +70 -0
  40. package/.opencode/agent/sdlc-pm.md +33 -0
  41. package/.opencode/agent/sdlc-qa.md +34 -0
  42. package/.opencode/agent/sdlc-reviewer.md +32 -0
  43. package/.opencode/agent/sdlc-security.md +37 -0
  44. package/.opencode/agent/sdlc-sm.md +32 -0
  45. package/.opencode/command/sdlc.md +18 -0
  46. package/.opencode/skill/archivarius/SKILL.md +203 -0
  47. package/.opencode/skill/data-engineer/SKILL.md +253 -0
  48. package/.opencode/skill/find-skills/SKILL.md +142 -0
  49. package/.opencode/skill/frontend-design/SKILL.md +54 -0
  50. package/.opencode/skill/sdlc-regulatory/SKILL.md +515 -0
  51. package/.opencode/skill/senior-bitcoin-auditor/SKILL.md +277 -0
  52. package/.opencode/skill/senior-frontend-dev/SKILL.md +72 -0
  53. package/.opencode/skill/senior-qa/SKILL.md +135 -0
  54. package/.opencode/skill/senior-software-developer/SKILL.md +56 -0
  55. package/.opencode/skill/senior-solidity-auditor/SKILL.md +180 -0
  56. package/.opencode/skill/senior-ux-ui-designer/SKILL.md +121 -0
  57. package/AGENTS.md +185 -85
  58. package/ARCHITECTURE.md +143 -0
  59. package/CONTRIBUTING.md +90 -0
  60. package/README.md +53 -24
  61. package/SECURITY.md +79 -0
  62. package/docs/BUSINESS_LOGIC.md +63 -0
  63. package/docs/IMPLEMENTATION.md +59 -0
  64. package/docs/adr/0001-triple-mirror.md +81 -0
  65. package/docs/adr/0002-zero-edit-install.md +237 -0
  66. package/docs/api/.gitkeep +0 -0
  67. package/docs/architecture/.gitkeep +0 -0
  68. package/docs/architecture/zero-edit-install-architecture.md +306 -0
  69. package/docs/business/zero-edit-install-analysis.md +295 -0
  70. package/docs/business/zero-edit-install-prd.md +404 -0
  71. package/docs/database/.gitkeep +0 -0
  72. package/docs/stories/zero-edit-install-assumptions.md +80 -0
  73. package/docs/stories/zero-edit-install-stories.md +256 -0
  74. package/opencode.json +54 -2
  75. package/package.json +14 -4
  76. package/scripts/postinstall.js +163 -0
@@ -0,0 +1,404 @@
1
+ # PRD — zero-edit-install
2
+
3
+ > SDLC stage 2 (Technical specification / PRD) artifact. Owner: `sdlc-pm`.
4
+ > Traceability id (slug): `zero-edit-install`.
5
+ > Prior artifact: `docs/business/zero-edit-install-analysis.md` (analyst, gate: pass).
6
+ > Gate: Requirement (complete — PM owns the second half: acceptance criteria + edge cases).
7
+
8
+ ## Source
9
+
10
+ This PRD is derived from `docs/business/zero-edit-install-analysis.md` and the
11
+ maintainer's five hard constraints. The analyst's crisp restatement is adopted
12
+ verbatim as the requirement; this document adds acceptance criteria, edge cases,
13
+ out-of-scope, and priority.
14
+
15
+ ### Revision 2 (maintainer change request, transitive-install suppression)
16
+
17
+ The maintainer reviewed Revision 1 and returned one change request before
18
+ approving the Architecture Gate dispatch: **suppress transitive installs**. The
19
+ `postinstall` script MUST only write the pointer line when
20
+ `@daochild/agents-config` is a **direct** dependency (in the consumer's
21
+ `dependencies` or `devDependencies` in their `package.json`). When installed
22
+ transitively, the script MUST no-op (no `AGENTS.md` modification, at most a
23
+ debug-level stdout note, exit 0). Rationale: this aligns with "never modify files
24
+ outside cwd" and US-8 "no surprises in my environment"; a project that did not
25
+ directly opt in should not have its `AGENTS.md` modified. The safe-append + exit-0
26
+ contract is necessary but not sufficient; explicit opt-in via direct dependency
27
+ is the stronger guarantee.
28
+
29
+ Revision 2 changes (line-level summary, for the maintainer's re-review):
30
+ - US-8 updated to explicitly include transitive-install suppression.
31
+ - AC-11 added (direct-dependency-only gate).
32
+ - EC-14 rewritten from an architecture-decision "default assumption" to a
33
+ **binding PRD requirement** (suppress).
34
+ - EC-16, EC-17, EC-18 added (edge cases introduced by the detection mechanism).
35
+ - "Out of scope" updated: EC-14 is no longer an architecture decision.
36
+ - AC-D1 / AC-D2 updated: the direct-dependency-only contract is now part of the
37
+ postinstall contract that must not change without human approval.
38
+ - "Non-functional requirements" updated: direct-dependency-only added.
39
+ - Risk note: suppress-transitive **reduces** blast radius (risk reduction);
40
+ security sensitivity remains High.
41
+
42
+ The analyst's artifact (`docs/business/zero-edit-install-analysis.md`) is
43
+ unchanged. The analyst already surfaced EC-14 as an unknown; the PM resolving it
44
+ here is the expected next step.
45
+
46
+ ## Requirement (adopted from the analyst, verbatim)
47
+
48
+ > Ship a `postinstall` script in `@daochild/agents-config` that, after a consumer
49
+ > installs the package as a dev dependency, automatically and idempotently writes
50
+ > the single pointer line
51
+ > `Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.`
52
+ > into the consumer's `AGENTS.md` — **safe-append only** (prepend or append if the
53
+ > line is missing; no-op if already present; never overwrite existing content),
54
+ > **never creates an `AGENTS.md` silently** (if absent, print a notice and exit 0
55
+ > unless `--init` was passed), **never modifies files outside `cwd`**, is
56
+ > **deterministic** (no network, no telemetry), and **always exits 0** so it can
57
+ > never break `npm install`.
58
+ >
59
+ > Consumers who refuse `postinstall` (via `--ignore-scripts` or policy) MUST still
60
+ > have a fully documented, supported manual fallback (the current one-line edit in
61
+ > `README.md`).
62
+ >
63
+ > **Direct-dependency only (Revision 2).** The script MUST only write the pointer
64
+ > line when `@daochild/agents-config` is a **direct** dependency of the consumer
65
+ > (listed in the consumer's `dependencies` or `devDependencies` in their
66
+ > `<cwd>/package.json`). When the package is installed transitively
67
+ > (dependency-of-a-dependency), the script MUST **no-op**: do not touch
68
+ > `AGENTS.md`, print at most a debug-level note to stdout, and exit 0. This is a
69
+ > binding PRD requirement, not an architecture decision (see AC-11, EC-14).
70
+ >
71
+ > The change supersedes repo invariants that forbid runtime code; this requires a
72
+ > new ADR (ADR 0002, produced downstream by `sdlc-architect`) and updates to
73
+ > `ARCHITECTURE.md`, `docs/adr/0001-triple-mirror.md` alt.2, and
74
+ > `docs/BUSINESS_LOGIC.md` non-goals. It also partially resolves backlog item BL-1
75
+ > (the `index.js` stub). `SECURITY.md` must be updated to cover the postinstall
76
+ > supply-chain surface (downstream of this role).
77
+
78
+ ## User stories
79
+
80
+ ### US-1 — Zero-edit install (happy path)
81
+ **As a** consumer developer,
82
+ **I want** `npm install --save-dev @daochild/agents-config` to automatically add
83
+ the pointer line to my `AGENTS.md`,
84
+ **so that** I don't have to hand-edit any file — I only restart my agent session.
85
+
86
+ ### US-2 — Idempotent reinstall
87
+ **As a** consumer developer,
88
+ **I want** running `npm install` again (or upgrading the package) to NOT duplicate
89
+ the pointer line,
90
+ **so that** my `AGENTS.md` stays clean no matter how many times I install.
91
+
92
+ ### US-3 — Non-destructive
93
+ **As a** consumer developer,
94
+ **I want** the script to never overwrite my existing `AGENTS.md` content,
95
+ **so that** my custom instructions are preserved.
96
+
97
+ ### US-4 — No silent file creation
98
+ **As a** consumer developer without an `AGENTS.md`,
99
+ **I want** the script to print a clear notice (and not fail) instead of silently
100
+ creating a file,
101
+ **so that** I understand what happened and can choose the manual path or `--init`.
102
+
103
+ ### US-5 — Explicit init
104
+ **As a** consumer developer who wants the package to seed a minimal `AGENTS.md`,
105
+ **I want** an explicit `--init` flag that creates a minimal `AGENTS.md` with the
106
+ pointer line,
107
+ **so that** file creation is an opt-in, never a surprise.
108
+
109
+ ### US-6 — Refused-postinstall fallback
110
+ **As a** consumer on a CI policy that blocks `postinstall` (or who uses
111
+ `--ignore-scripts`),
112
+ **I want** a documented one-line manual edit in `README.md`,
113
+ **so that** I can still use the package.
114
+
115
+ ### US-7 — Never breaks install
116
+ **As a** consumer,
117
+ **I want** the script to always exit 0,
118
+ **so that** a config package can never break my dependency install.
119
+
120
+ ### US-8 — No surprises in my environment
121
+ **As a** consumer security reviewer,
122
+ **I want** the script to be deterministic, network-free, telemetry-free, scoped to
123
+ `cwd`, **and to not run (no-op) on projects that installed this package
124
+ transitively**,
125
+ **so that** I can approve it as a low-blast-radius supply-chain surface. A project
126
+ that did not directly opt into `@daochild/agents-config` must not have its
127
+ `AGENTS.md` modified by it.
128
+
129
+ ## Acceptance criteria
130
+
131
+ > Measurable and testable. Each AC has an id (AC-*) for traceability into the
132
+ > Testing Gate. The downstream `sdlc-architect` decides *how* (placement rule,
133
+ > `--init` template shape, cross-manager behavior); these criteria constrain
134
+ > *what* must be true.
135
+
136
+ ### Functional
137
+
138
+ - **AC-1 (idempotent, missing line).** Given an `AGENTS.md` that does NOT contain
139
+ the pointer line, when the `postinstall` runs, then the pointer line is added
140
+ exactly once.
141
+ - **AC-2 (idempotent, already present).** Given an `AGENTS.md` that already
142
+ contains the pointer line (anywhere in the file), when the `postinstall` runs,
143
+ then the file is unchanged (byte-for-byte, modulo trailing newline
144
+ normalization which MUST be documented by the architect) and no second copy is
145
+ added.
146
+ - **AC-3 (non-destructive).** Given an `AGENTS.md` with arbitrary existing content,
147
+ when the `postinstall` runs, then all pre-existing content is preserved. No
148
+ existing line is overwritten or deleted. The pointer line is inserted (prepended
149
+ or appended per the architect's placement rule) without removing anything.
150
+ - **AC-4 (exact pointer line).** The written line is byte-identical to:
151
+ `Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.`
152
+ (including the em dash `—`, U+2014). No paraphrasing.
153
+ - **AC-5 (no `AGENTS.md`, default).** Given no `AGENTS.md` in `cwd` and no
154
+ `--init` flag, when the `postinstall` runs, then: (a) no `AGENTS.md` is created,
155
+ (b) a notice is printed to stdout telling the user how to proceed (manual edit
156
+ or `--init`), (c) the script exits 0.
157
+ - **AC-6 (no `AGENTS.md`, `--init`).** Given no `AGENTS.md` in `cwd` and the
158
+ `--init` flag, when the `postinstall` runs, then a minimal `AGENTS.md` is
159
+ created containing at least the pointer line. The exact minimal shape is an
160
+ architecture decision (architect MUST specify it in the architecture artifact).
161
+ - **AC-7 (always exit 0).** In every code path — happy path, no-op, missing file,
162
+ `--init`, permission error, unexpected exception — the script exits 0. Errors
163
+ are printed as notices to stdout, never thrown as non-zero exits. The install
164
+ MUST NOT fail because of this script.
165
+ - **AC-8 (cwd-scoped).** The script only reads/writes within the npm-provided
166
+ `cwd` (the consumer's project root). It does not touch the home directory, any
167
+ global config, any parent directory, or any sibling project. (Cross-package-
168
+ manager `cwd` semantics are an architecture concern; the architect MUST verify
169
+ and document them.)
170
+ - **AC-9 (deterministic).** The script makes no network calls, collects no
171
+ telemetry, uses no `Date`/`Math.random`, and writes no files other than
172
+ `AGENTS.md` (when permitted). Output is a pure function of (`AGENTS.md` content,
173
+ flags). This is enforceable by static review and by a test that blocks the
174
+ script from importing `http`, `https`, `net`, `fetch`, `dns`, `child_process`
175
+ (except where strictly required by the install lifecycle, which it isn't).
176
+ - **AC-11 (direct-dependency only).** The script MUST verify that
177
+ `@daochild/agents-config` is a **direct** dependency of the consumer before
178
+ writing the pointer line. "Direct" means the package name
179
+ `@daochild/agents-config` appears as a key in the `dependencies` or
180
+ `devDependencies` object of the consumer's `<cwd>/package.json`. If it does not
181
+ (i.e. the package was installed transitively, or is absent from
182
+ `package.json`), the script MUST no-op: do not modify `AGENTS.md`, print at most
183
+ a debug-level note to stdout, and exit 0.
184
+ - **Behavior locked by the PRD (not an architecture decision):** transitive
185
+ installs are suppressed.
186
+ - **Detection mechanism (PRD-level definition, implementation refinable by the
187
+ architect):** the script reads the consumer's `<cwd>/package.json` and checks
188
+ for `@daochild/agents-config` under `dependencies` or `devDependencies`. The
189
+ architect MAY refine the mechanism (e.g. prefer `process.env.npm_config_*` /
190
+ `process.env.npm_package_*` env vars when available and reliable, or read
191
+ `<cwd>/package.json` directly) — but the *behavior* (suppress unless direct)
192
+ is locked here. Whichever mechanism is chosen MUST satisfy AC-9
193
+ (deterministic, no network, no `child_process`) and AC-8 (cwd-scoped, reading
194
+ only `<cwd>/package.json`).
195
+ - **`peerDependencies` and `optionalDependencies` are NOT "direct" for this
196
+ check** — see EC-17 for the resolution and rationale.
197
+
198
+ ### Manual fallback
199
+
200
+ - **AC-10 (README documents both paths).** `README.md` documents BOTH the
201
+ automatic (postinstall) path AND the manual (one-line edit) path. The manual
202
+ path is explicitly labeled as the **supported fallback** for consumers who use
203
+ `--ignore-scripts` or whose CI rejects `postinstall`. The manual path must be
204
+ runnable without the postinstall ever having run.
205
+
206
+ ### Downstream-artifact acceptance criteria (dependencies, not this role's scope)
207
+
208
+ These are acceptance criteria the PRD requires to be satisfied *downstream* by
209
+ other roles. They are listed here so the orchestrator and later gates can verify
210
+ them. They are NOT the PM's to produce.
211
+
212
+ - **AC-D1 (ADR 0002 required).** `sdlc-architect` MUST produce
213
+ `docs/adr/0002-<slug>.md` that explicitly supersedes:
214
+ - `ARCHITECTURE.md` rule 6 ("No runtime code") — narrowed to permit this
215
+ constrained postinstall while retaining the general "no runtime application
216
+ code" stance;
217
+ - `docs/adr/0001-triple-mirror.md` alt.2 ("Generate `.claude/` from `.opencode/`
218
+ at install time. Rejected: adds a build step...") — distinguished: that
219
+ rejection was about generating *config* (coupling release cadences); this
220
+ change writes a *one-line pointer in the consumer's file*, not config in this
221
+ repo;
222
+ - `docs/BUSINESS_LOGIC.md` non-goal ("This repo does not ship runtime
223
+ application code") — narrowed to "no runtime *application* code; a constrained
224
+ install-time file-pointer helper is permitted".
225
+ ADR 0002 MUST also record the **direct-dependency-only contract** (AC-11) as a
226
+ binding constraint of the postinstall: the script only writes for direct
227
+ dependencies; transitive installs are suppressed. This contract must not change
228
+ without human approval (Revision 2).
229
+ ADR 0002 must be approved by a human at the Architecture Gate before
230
+ advancement.
231
+ - **AC-D2 (`ARCHITECTURE.md` updated).** `sdlc-architect` MUST update
232
+ `ARCHITECTURE.md` rule 6 (and the Constraints / Stack sections as needed) to
233
+ reflect the ADR 0002 narrowing. The "What must NOT be changed without human
234
+ approval" list must explicitly include the postinstall script's contract:
235
+ idempotency, safe-append, exit-0, cwd-scoped, deterministic, **and
236
+ direct-dependency-only (transitive suppression) — Revision 2**.
237
+ - **AC-D3 (`docs/BUSINESS_LOGIC.md` non-goal updated).** `sdlc-architect` (or
238
+ `sdlc-dev` under the architect's direction) MUST narrow the non-goal wording per
239
+ AC-D1.
240
+ - **AC-D4 (`SECURITY.md` updated).** `sdlc-security` MUST update `SECURITY.md` to
241
+ cover the postinstall supply-chain surface: the script is deterministic,
242
+ network-free, telemetry-free, cwd-scoped, exit-0; the manual fallback exists;
243
+ consumers may use `--ignore-scripts`. This update is a gate artifact of the
244
+ Security Gate and requires human approval (high-risk).
245
+ - **AC-D5 (BL-1 partially resolved).** `sdlc-dev` (under the architect's plan)
246
+ MUST update `docs/IMPLEMENTATION.md` so BL-1's status moves from "Stub" to
247
+ "Partially resolved (postinstall only)" and notes that a full plugin host hook
248
+ remains a separate concern. The `package.json` `main` field reconciliation is
249
+ an architecture decision (architect MUST address it in the architecture
250
+ artifact).
251
+ - **AC-D6 (human approvals recorded).** The orchestrator MUST request and record
252
+ explicit human approvals at the Architecture, Security, and Code Review gates
253
+ (approver handle + date) in the eventual DoD audit artifact, per the
254
+ `sdlc-regulatory` skill. This is a medium/high-risk change (security sensitivity
255
+ is High).
256
+
257
+ ## Edge cases and negative paths
258
+
259
+ | ID | Scenario | Expected behavior |
260
+ |----|----------|-------------------|
261
+ | EC-1 | `AGENTS.md` missing, no `--init` | Print notice, no file created, exit 0 (AC-5) |
262
+ | EC-2 | `AGENTS.md` missing, `--init` passed | Create minimal `AGENTS.md` with pointer line, exit 0 (AC-6) |
263
+ | EC-3 | Pointer line already present (exact match) | No-op, exit 0, file unchanged (AC-2) |
264
+ | EC-4 | Pointer line present with different whitespace | Treated as present if the canonical line is detectable; the architect MUST define the match rule (exact bytes vs. normalized). If normalized, the script MUST NOT rewrite the existing line. |
265
+ | EC-5 | Pointer line present but inside a code block / quoted | The architect MUST define whether "present anywhere" counts, or only "present as a top-level instruction line". Default assumption (to be confirmed): present-anywhere counts, to stay conservative and avoid double-insert. |
266
+ | EC-6 | `AGENTS.md` exists but is empty (0 bytes) | Add the pointer line (per placement rule), exit 0 |
267
+ | EC-7 | `AGENTS.md` exists but is not writable (perms) | Print notice, do not throw, exit 0 (AC-7) |
268
+ | EC-8 | `AGENTS.md` is a symlink to another file | Architect MUST decide: follow symlink or skip. Default assumption: skip (do not follow) to respect "never modify files outside cwd"; but this is an architecture decision. |
269
+ | EC-9 | Install run with `--ignore-scripts` | Script does not run; manual fallback in README is the supported path (AC-10). The package cannot detect this; the README must be clear. |
270
+ | EC-10 | Install in a monorepo workspace | Behavior is an architecture concern (AC-8). The architect MUST document: does the script run per-workspace, at the root, or not at all? What is the target `AGENTS.md`? If out of scope, the PRD must say so explicitly (see Out of scope). |
271
+ | EC-11 | Cross-package-manager differences (npm/yarn classic/yarn berry/pnpm/bun) | The architect MUST verify and document lifecycle + `cwd` semantics for each supported manager. If a manager does not run `postinstall` by default, the manual fallback covers it. |
272
+ | EC-12 | Consumer runs install inside a CI sandbox with read-only project root | Print notice, exit 0 (AC-7). Do not fail the build. |
273
+ | EC-13 | Pointer line is present but misspelled / stale (points at a different path) | Out of scope: the script does not repair stale lines. It only ensures the canonical line is present. The architect MUST confirm this in the architecture artifact. |
274
+ | EC-14 | The package is installed as a *transitive* dependency (not directly by the consumer) | **Binding PRD requirement (Revision 2): suppress.** The script MUST no-op — do not modify `AGENTS.md`, print at most a debug-level note to stdout, and exit 0. This is enforced by AC-11. It is NO LONGER an architecture decision. |
275
+ | EC-15 | Concurrent installs racing on the same `AGENTS.md` | The script should use atomic write (temp file + rename) to avoid torn writes. Architect MUST specify. |
276
+ | EC-16 | Consumer's `<cwd>/package.json` is unreadable or missing (no package.json at cwd) | The script MUST no-op: do not modify `AGENTS.md`, print at most a debug-level note to stdout, and exit 0. This is consistent with AC-7 (always exit 0) and AC-11 (cannot verify direct dependency → treat as not-direct → suppress). The script MUST NOT throw. |
277
+ | EC-17 | `@daochild/agents-config` is listed under `peerDependencies` or `optionalDependencies` but NOT under `dependencies`/`devDependencies` | **PRD decision: treat as NOT direct → suppress (no-op, exit 0).** Justification: peer/optional dependencies are a weaker signal of consumer intent than `dependencies`/`devDependencies`. A peer dependency declares "this package works alongside X if X is present", not "this consumer explicitly opted into X". A consumer's tooling may pull in a peer without a direct install decision by a developer on that consumer. The safe-append + exit-0 contract keeps suppression safe. The maintainer is asked to confirm this choice; if they prefer to treat peer/optional as direct, this AC and EC-17 flip and downstream artifacts update accordingly. *(Flagged for maintainer review in the handoff.)* |
278
+ | EC-18 | Workspace/monorepo: the package is hoisted to a root `node_modules` while the consumer is a sub-workspace; the direct-dependency check against the *root* `package.json` may give a wrong answer | The direct-dependency check runs against the `<cwd>/package.json` (per AC-11). If `cwd` is a workspace root and the package was declared in a sub-workspace's `package.json` (or vice versa), the check may incorrectly suppress or incorrectly fire. This interacts with EC-10 (monorepo, architect-owned). The PRD does NOT solve monorepo here. The architect MUST address the interaction under EC-10: either (a) document that the script checks `<cwd>/package.json` as-is and monorepo is a known limitation covered by the manual fallback, or (b) propose a workspace-aware detection that still satisfies AC-9 (deterministic, no network, no `child_process`) and AC-8 (cwd-scoped). Until the architect resolves EC-10, the PRD locks behavior as: check `<cwd>/package.json` only; do not traverse parents or workspaces. |
279
+
280
+ ## Out of scope
281
+
282
+ - **Placement rule** (prepend vs. append; "immediately after the title" semantics)
283
+ — architecture decision (`sdlc-architect`).
284
+ - **`--init` minimal `AGENTS.md` template shape** — architecture decision.
285
+ - **Cross-package-manager lifecycle verification** — architecture decision (the
286
+ PRD requires it to be *verified and documented*, not that the PRD pick the
287
+ behavior).
288
+ - **Monorepo / workspace semantics** — architecture decision; may be explicitly
289
+ deferred (the PRD allows the architect to scope it out, in which case the
290
+ architecture artifact must say so and the README must note the limitation). The
291
+ direct-dependency check interacts with monorepo (EC-18); the PRD locks the
292
+ check to `<cwd>/package.json` only and leaves workspace-aware detection to the
293
+ architect under EC-10.
294
+ - **Exact direct-dependency detection mechanism** — architecture decision. The
295
+ PRD locks the *behavior* (suppress unless direct; transitive suppressed;
296
+ peer/optional treated as not-direct per EC-17) and gives a PRD-level mechanism
297
+ (read `<cwd>/package.json`, check `dependencies`/`devDependencies`). The
298
+ architect MAY refine the mechanism (e.g. `process.env.npm_*` env vars) as long
299
+ as AC-9 and AC-8 hold.
300
+ - **ADR 0002 and the supersession edits** — `sdlc-architect` (AC-D1/D2/D3).
301
+ - **`SECURITY.md` update** — `sdlc-security` (AC-D4).
302
+ - **BL-1 full resolution / plugin host hook** — separate concern; only the
303
+ partial resolution is in scope here (AC-D5).
304
+ - **Repairing stale/misspelled pointer lines** — explicitly out of scope (EC-13).
305
+ - **Detecting `--ignore-scripts`** — impossible by design; out of scope (EC-9).
306
+ - **Transitive-install behavior** — NO LONGER an architecture decision; locked by
307
+ the PRD as "suppress" (AC-11, EC-14, Revision 2).
308
+ - **Implementation, tests, review, deployment** — downstream roles.
309
+
310
+ ## Priority and sequencing
311
+
312
+ - **Priority:** High (adoption friction removal; the README was already
313
+ simplified today to a single line, making this the natural next step).
314
+ - **Risk:** Medium/High (security sensitivity High; requires human approvals at
315
+ Architecture, Security, Code Review gates).
316
+ - **Risk note (Revision 2):** the suppress-transitive requirement (AC-11) is a
317
+ **risk reduction**, not an increase — it narrows the blast radius to consumers
318
+ who explicitly opted in via direct dependency. Security sensitivity remains
319
+ High (postinstall is still a supply-chain vector); the autonomy cap stays ≤40%.
320
+ The detection mechanism itself introduces minor complexity (reading
321
+ `<cwd>/package.json`), addressed by EC-16/17/18.
322
+ - **Sequencing constraint:** This PRD MUST NOT advance to `sdlc-architect`
323
+ without the maintainer's review of this PRD (the orchestrator's instruction:
324
+ stop after PM returns pass). The next dispatch (`sdlc-architect`) is a separate
325
+ run.
326
+ - **Open item for maintainer (Revision 2):** EC-17 resolution (peer/optional
327
+ treated as NOT direct → suppress) is a PM recommendation flagged for maintainer
328
+ confirmation. If the maintainer disagrees, the PRD flips AC-11's definition of
329
+ "direct" and EC-17's resolution; downstream artifacts (AC-D1/D2) update
330
+ accordingly. This is the one item in Revision 2 that is not yet locked.
331
+ - **Downstream critical path:** PRD (this) → `sdlc-architect` (ADR 0002 +
332
+ architecture + `ARCHITECTURE.md`/`docs/BUSINESS_LOGIC.md` edits) →
333
+ `sdlc-sm` (stories + risk cap, expected ≤40% autonomy) → `sdlc-dev` →
334
+ `sdlc-qa` → `sdlc-security` (`SECURITY.md` update + security report) →
335
+ `sdlc-reviewer` → `sdlc-auditor` → deploy (npm publish, subject to Deployment
336
+ Gate).
337
+
338
+ ## Non-functional requirements (binding constraints, restated)
339
+
340
+ - **Determinism:** no network, no telemetry, no time/random (AC-9).
341
+ - **Exit 0 always:** every path (AC-7).
342
+ - **cwd-scoped:** no traversal outside the consumer root (AC-8).
343
+ - **Safe-append only:** never overwrite existing content (AC-3).
344
+ - **Direct-dependency-only (Revision 2):** no-op when installed transitively; only
345
+ write when `@daochild/agents-config` is a direct dependency
346
+ (`dependencies`/`devDependencies` in `<cwd>/package.json`); peer/optional
347
+ treated as not-direct (AC-11, EC-14, EC-17). This is a risk-reduction control:
348
+ it shrinks the blast radius to consumers who explicitly opted in.
349
+ - **No new runtime dependency:** the script uses Node.js built-ins only. (This
350
+ is a constraint that bounds the architect; restated here because it also bounds
351
+ the Implementation Gate's "no unnecessary dependencies" item.)
352
+ - **CommonJS:** the repo is `"type": "commonjs"`; the script must conform.
353
+ - **Triple-mirror unaffected:** this change does NOT add a subagent/skill/command/
354
+ rule, so the triple-mirror invariant is not in play. (Confirmed: a `postinstall`
355
+ script is not a mirrored component type per `AGENTS.md` → "Adding a new
356
+ component". The architect should confirm.)
357
+
358
+ ## Compliance note (regulatory crosswalk)
359
+
360
+ If any consuming project of `@daochild/agents-config` targets a regulated domain
361
+ (EU AI Act high-risk, ISO 42001, SOC 2, GDPR), this change's Security Gate must
362
+ produce the supply-chain-relevant artifacts per the `sdlc-regulatory` compliance
363
+ crosswalk (Security Gate row: EU AI Act Art. 15 cybersecurity, NIST MEASURE-1.3,
364
+ ISO 42001 clause 8.8, SOC 2 CC6.1–CC6.8, GDPR Art. 32). This PRD does not itself
365
+ produce those artifacts; it flags them as Security-Gate dependencies. This repo
366
+ itself is configuration-only and not a regulated system, but its consumers may
367
+ be — the supply-chain surface of a `postinstall` is exactly the kind of thing
368
+ those regimes care about.
369
+
370
+ ## Gate self-check (Requirement Gate — full)
371
+
372
+ - [x] Requirement is clearly defined — adopted verbatim from the analyst, plus the
373
+ Revision 2 direct-dependency-only clause.
374
+ - [x] Acceptance criteria exist — AC-1..AC-11 + AC-D1..AC-D6, measurable/testable.
375
+ AC-11 (direct-dependency only) added in Revision 2.
376
+ - [x] Edge cases are identified — EC-1..EC-18, each with expected behavior or an
377
+ explicit "architecture decision" flag where appropriate. EC-14 is now a
378
+ binding requirement (no longer architect-owned); EC-16/17/18 added in
379
+ Revision 2 to cover the detection-mechanism surface.
380
+ - [x] Business requirements are understood — US-1..US-8 map to the problem
381
+ statement and constraints. US-8 updated in Revision 2 to include
382
+ transitive-install suppression.
383
+
384
+ All Requirement Gate items pass. No item is unchecked.
385
+
386
+ ## Handoff
387
+
388
+ ```
389
+ HANDOFF: sdlc-architect | artifact: docs/business/zero-edit-install-prd.md | gate: pass
390
+ ```
391
+
392
+ Per the orchestrator's instruction, this run STOPS here for maintainer approval.
393
+ `sdlc-architect` will be dispatched in a separate run after the maintainer
394
+ reviews this revised PRD (Revision 2). The architect MUST produce ADR 0002
395
+ (AC-D1), update `ARCHITECTURE.md` (AC-D2), and coordinate the
396
+ `docs/BUSINESS_LOGIC.md` non-goal narrowing (AC-D3) as part of passing the
397
+ Architecture Gate. Human approval is required at that gate (AC-D6).
398
+
399
+ **Revision 2 open item for the maintainer (please confirm before architect
400
+ dispatch):** EC-17 — `@daochild/agents-config` under `peerDependencies` or
401
+ `optionalDependencies` (but not `dependencies`/`devDependencies`) is treated by
402
+ the PM as **NOT direct → suppress**. If the maintainer prefers peer/optional to
403
+ count as direct, say so and the PM will flip AC-11 and EC-17 (and adjust AC-D1/D2)
404
+ before the architect is dispatched.
File without changes
@@ -0,0 +1,80 @@
1
+ # AI assumptions log — zero-edit-install
2
+
3
+ > SDLC Implementation Gate artifact. Owner: `sdlc-dev`.
4
+ > Traceability id (slug): `zero-edit-install`.
5
+ > Per the `sdlc-regulatory` skill Implementation Gate ("AI assumptions are documented") and the SM's risk cap
6
+ > (S02/S03 High risk, autonomy ≤40%), every assumption the dev made during implementation is logged here. The reviewer
7
+ > and auditor validate these at the Code Review and DoD gates.
8
+
9
+ ## S02 — `scripts/postinstall.js`
10
+
11
+ | # | Assumption | Why made | What would invalidate it |
12
+ |---|------------|----------|--------------------------|
13
+ | A1 | The consumer's install `cwd` is their project root (where `AGENTS.md` and `package.json` live). | npm/yarn/pnpm/bun set `cwd` to the consumer project root for lifecycle scripts, per the architecture artifact's cross-manager table. | A package manager that runs `postinstall` with a different `cwd` (e.g. the package's own dir). QA must verify per-manager `cwd` (S07). |
14
+ | A2 | `process.env.npm_*` env vars are NOT used as the authoritative direct-dependency check. | Per the architecture artifact: env var availability differs across managers/versions; `<cwd>/package.json` is authoritative. | None — this follows the locked architecture decision. |
15
+ | A3 | `peerDependencies` and `optionalDependencies` do NOT count as "direct". | Locked by PRD EC-17 (maintainer-approved). | A future maintainer decision to flip EC-17; would require PRD revision + ADR update. |
16
+ | A4 | The pointer line uses the em dash `—` (U+2014), byte-identical to `POINTER_LINE` in the script. | Locked by PRD AC-4 + maintainer decision #1. | None. |
17
+ | A5 | "Present anywhere in the file" counts as present (no-op), including inside code blocks / quotes. | Locked by PRD EC-5 (conservative default) + architecture artifact match rule. | A future decision to only match top-level instruction lines; would require ADR update. |
18
+ | A6 | A line with different whitespace but the same canonical content is NOT rewritten. | Locked by PRD EC-4 + architecture artifact ("leave the user's formatting alone"). | None. |
19
+ | A7 | The match is exact byte equality per line (not normalized, not substring). | Architecture artifact match rule. | None. |
20
+ | A8 | The temp filename uses `process.pid` (`.agents-config-postinstall.tmp-<pid>`). | Per the architecture artifact EC-15 note: `process.pid` is allowed for the temp filename (not content, not time-based). | A stricter reading of AC-9 that forbids `process.pid`; the architecture artifact flagged this as an implementation choice. If rejected, switch to a fixed `.agents-config-postinstall.tmp.md` filename. |
21
+ | A9 | The temp file is created with mode `0o600` (owner read/write only) and in the same directory as `AGENTS.md` (so the rename is atomic on the same filesystem). | Per architecture artifact atomic-write rule (same dir + rename). `0o600` limits the temp file's visibility during the brief write window. | A consumer filesystem that does not support atomic rename across the same dir (extremely rare on POSIX/NTFS/APFS). QA should test rename atomicity (S07). |
22
+ | A10 | The notice text for "no AGENTS.md, no --init" mentions both the `--init` flag command and the manual one-line edit. | Per AC-5: notice must tell the user how to proceed (manual edit or `--init`). Exact wording is the dev's choice; reviewer validates it is accurate and not misleading. | Reviewer rejects the wording as ambiguous or incorrect. |
23
+ | A11 | The notice text for the symlink case is a single debug-level line. | Per EC-8: print a debug note, exit 0. Wording is the dev's choice. | Reviewer rejects the wording. |
24
+ | A12 | The notice text for "not a direct dependency" is a single line identifying the package.json path checked. | Per EC-14/EC-16: at most a debug-level note to stdout. Wording is the dev's choice. | Reviewer rejects the wording. |
25
+ | A13 | The script does NOT create `AGENTS.md` when `--init` is passed AND the file already exists — it falls through to the normal idempotent insert logic. | Per the run instruction: "`--init` when `AGENTS.md` already exists: treat `--init` as a no-op for file creation; still apply the normal idempotent insert logic. Do not overwrite." | None — follows the binding instruction. |
26
+ | A14 | The script uses `fs.lstatSync` (not `statSync`) to detect symlinks without following them. | Per EC-8: skip symlinks, do not follow. `lstat` does not follow; `stat` would. | None. |
27
+ | A15 | The `--init` minimal `AGENTS.md` content is `# <cwd-basename>\n\n<POINTER_LINE>\n` (title, blank, pointer, trailing newline). | Per architecture artifact `--init` template. `<cwd-basename>` from `path.basename(process.cwd())`. | None. |
28
+ | A16 | The script reads `AGENTS.md` with `utf8` encoding. | Markdown is text; `utf8` is the safe default. | A consumer `AGENTS.md` with a different encoding (rare; Markdown is UTF-8 by convention). QA may add an encoding edge test (S07). |
29
+ | A17 | No code comments are present in the script. | Per the run instruction (repo convention: "DO NOT ADD ANY COMMENTS unless asked"). The architecture artifact is the documentation; the code is the source of truth for behavior. | None. |
30
+ | A18 | The script is CommonJS (`require`/`module.exports`-style, but no exports needed — it's a top-level script). | Per architecture artifact: `"type": "commonjs"`. | None. |
31
+ | A19 | The script always calls `process.exit(0)` at the end, in addition to the try/catch around `main()`. | Per AC-7: every path exits 0. The explicit `process.exit(0)` is a belt-and-suspenders guarantee that no accidental non-zero exit leaks. | None. |
32
+ | A20 | The whole `main()` is wrapped in a try/catch at the call site that prints the error as a notice and falls through to `process.exit(0)`. | Per AC-7: unexpected exception → notice, exit 0. | None. |
33
+
34
+ ## S03 — `package.json` `postinstall` field
35
+
36
+ | # | Assumption | Why made | What would invalidate it |
37
+ |---|------------|----------|--------------------------|
38
+ | A21 | The `postinstall` script is invoked as `node scripts/postinstall.js` (explicit `node`). | Per architecture artifact: explicit `node` so the script runs under the same Node as the install. | None. |
39
+ | A22 | `package.json` `main` is left as `"index.js"` (unchanged). | Per AC-D5 + architecture artifact: BL-1 full resolution is out of scope; postinstall is not the main entry. | None. |
40
+ | A23 | No new dependency is added to `package.json`. | Per ADR 0002 contract + AC-9: Node built-ins only. | None. |
41
+ | A24 | `type` stays `"commonjs"`. | Per architecture artifact. | None. |
42
+ | A25 | The existing `test` script placeholder is left unchanged. | Out of scope; tests are S07 (Testing Gate, owned by QA). | None. |
43
+
44
+ ## S04 — `README.md` update
45
+
46
+ | # | Assumption | Why made | What would invalidate it |
47
+ |---|------------|----------|--------------------------|
48
+ | A26 | The README "Installation" section is restructured into "Automatic path", "Manual path (supported fallback)", and "After either path" subsections. | Per AC-10: document both paths; manual = supported fallback. | Reviewer rejects the structure. |
49
+ | A27 | The README mentions the monorepo limitation (cwd-only check) under the automatic path. | Per architecture artifact EC-10/EC-18 deferral + AC-10. | None. |
50
+ | A28 | The README mentions the direct-dependency-only behavior (transitive untouched). | Per AC-11/EC-14 — consumers should know. | None. |
51
+ | A29 | The README describes `--init` as the explicit opt-in for consumers without an `AGENTS.md`. | Per US-5/AC-6 + run instruction. | None. |
52
+ | A30 | The README does NOT promise the script creates files silently. | Per AC-5/US-4: no silent file creation. | None. |
53
+
54
+ ## S06 — `docs/IMPLEMENTATION.md` update
55
+
56
+ | # | Assumption | Why made | What would invalidate it |
57
+ |---|------------|----------|--------------------------|
58
+ | A31 | BL-1 status moves from "Stub" to "Partially resolved (postinstall only)" with a note that a full plugin host hook remains separate and `main` reconciliation is still open. | Per AC-D5 + architecture artifact. | None. |
59
+ | A32 | A new "Postinstall pointer script" row is added to the "Implemented components" table with status "Done". | Reflects what shipped (S02+S03). | None. |
60
+ | A33 | A change log entry for 2026-08-18 records the implementation (S02+S03+S04+S06) per ADR 0002. | Per AC-D5 + run instruction. | None. |
61
+ | A34 | The change log entry notes `SECURITY.md` update is deferred to the Security Gate (S05) and tests to the Testing Gate (S07). | Traceability: makes the deferred stories visible. | None. |
62
+
63
+ ## Out-of-scope adherence (did NOT touch)
64
+
65
+ - `SECURITY.md` — owned by `sdlc-security` (S05, Security Gate). Not touched.
66
+ - `tests/` — owned by `sdlc-qa` (S07, Testing Gate). Not touched.
67
+ - `ARCHITECTURE.md` — architect-owned, already done in the prior run. Not re-edited.
68
+ - `docs/BUSINESS_LOGIC.md` — architect-owned, already done. Not re-edited.
69
+ - `docs/adr/0002-zero-edit-install.md` — architect-owned. Not re-edited.
70
+ - `package.json` `main` field — left as `"index.js"` (AC-D5).
71
+ - `package.json` `dependencies` — no new dependency added (AC-9 / ADR 0002).
72
+ - Triple-mirror components (`.opencode/`, `.claude/`, `.agents/`) — the postinstall is not a mirrored component type per `AGENTS.md` "Adding a new component"; not mirrored.
73
+
74
+ ## Open questions for the reviewer / QA / security (not blocks, surfaced for downstream)
75
+
76
+ - Q1 (QA): verify `cwd` is the consumer project root for npm, yarn classic, yarn berry, pnpm, bun (A1).
77
+ - Q2 (QA): verify atomic rename works on the target platforms (A9).
78
+ - Q3 (QA): consider an encoding edge test for non-UTF-8 `AGENTS.md` (A16).
79
+ - Q4 (Security): the script writes a temp file in the consumer's `cwd` (`.agents-config-postinstall.tmp-<pid>`). Confirm this is acceptable (it is cleaned up in `finally`). If a consumer's `cwd` is read-only, the openSync will throw → caught → notice → exit 0 (AC-7).
80
+ - Q5 (Reviewer): validate the notice wordings (A10, A11, A12) are accurate and not misleading.