@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,237 @@
1
+ # ADR 0002 — Permit a constrained postinstall file-pointer helper (zero-edit-install)
2
+
3
+ - **Status**: accepted
4
+ - **Date**: 2026-08-18
5
+ - **Deciders**: maintainer
6
+ - **Supersedes / narrows**: `ARCHITECTURE.md` rule 6; `docs/adr/0001-triple-mirror.md` alt.2; `docs/BUSINESS_LOGIC.md` non-goal ("This repo does not ship runtime application code").
7
+ - **Traceability id (slug)**: `zero-edit-install`.
8
+
9
+ ## Context
10
+
11
+ `@daochild/agents-config` is a configuration-only npm package. Consumers install it as a dev
12
+ dependency and currently must hand-edit their `AGENTS.md` to add one pointer line:
13
+
14
+ ```
15
+ Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.
16
+ ```
17
+
18
+ This is adoption friction: a step that is forgotten, done inconsistently, or lost on a fresh
19
+ clone. The maintainer wants `npm install --save-dev @daochild/agents-config` alone to be
20
+ sufficient (the consumer only restarts their agent session).
21
+
22
+ The natural mechanism is an npm `postinstall` script. But three currently-stated repo
23
+ invariants forbid runtime code / install-time steps:
24
+
25
+ 1. `ARCHITECTURE.md` rule 6 — "No runtime code. This repo's 'code' is configuration. The only JS
26
+ is the opencode plugin host (`@opencode-ai/plugin` dependency) and any
27
+ `.opencode/plugin/*.ts|.js` the user adds. There is no `src/`, no build output, no deployable
28
+ service."
29
+ 2. `docs/adr/0001-triple-mirror.md` alt.2 — "Generate `.claude/` from `.opencode/` at install
30
+ time. Rejected: adds a build step to a config-only repo and couples the tools' release
31
+ cadences."
32
+ 3. `docs/BUSINESS_LOGIC.md` non-goal — "This repo does not ship runtime application code."
33
+
34
+ This ADR narrows (does not abolish) those invariants to permit a single, tightly-constrained
35
+ install-time helper.
36
+
37
+ ### Maintainer decisions (binding inputs to this ADR, recorded for traceability)
38
+
39
+ The maintainer reviewed the PRD (`docs/business/zero-edit-install-prd.md`, Revision 2) and
40
+ approved it with four open items resolved. These are binding decisions for this ADR and the
41
+ downstream implementation; they are not re-litigated here:
42
+
43
+ 1. **Pointer line uses the em dash `—` (U+2014).** PRD AC-4 stands as written — the line is
44
+ byte-identical to
45
+ `Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.`
46
+ 2. **`--init` flag is kept.** PRD US-5 / AC-6 / EC-2 stand as written — the script supports an
47
+ explicit `--init` flag that creates a minimal `AGENTS.md` when none exists.
48
+ 3. **Monorepo / workspace (PRD EC-10) — architect MAY defer** with a documented limitation
49
+ covered by the manual fallback. The direct-dependency check is locked to `<cwd>/package.json`
50
+ only; the script does not traverse parents or workspaces (PRD EC-18).
51
+ 4. **PRD EC-17 — `peerDependencies` and `optionalDependencies` are NOT "direct".** PRD AC-11 and
52
+ EC-17 stand as the PM wrote them: peer/optional-only presence → suppress (no-op, exit 0).
53
+
54
+ **Human approval recorded for the Requirement Gate**: approver = maintainer, date = 2026-08-18.
55
+ (To be recorded in the eventual DoD audit per PRD AC-D6.)
56
+
57
+ ## Decision
58
+
59
+ Permit **one** constrained install-time helper: a `postinstall` script at
60
+ `scripts/postinstall.js` (CommonJS, matching the repo's `"type": "commonjs"`), wired via
61
+ `package.json` → `"scripts" → "postinstall": "node scripts/postinstall.js"`.
62
+
63
+ ### The postinstall contract (binding; must NOT change without human approval)
64
+
65
+ The script is bounded by these contract clauses. Relaxing any of them is a high-risk change
66
+ requiring human approval at the Architecture, Security, and Code Review gates (per the
67
+ `sdlc-regulatory` skill):
68
+
69
+ - **Idempotent.** Running install any number of times does not duplicate the pointer line.
70
+ - **Safe-append only.** Never overwrites existing `AGENTS.md` content. Inserts the pointer line
71
+ if missing; no-op if present; never deletes existing lines.
72
+ - **Always exits 0.** Every code path (happy path, no-op, missing file, `--init`, permission
73
+ error, unexpected exception) exits 0. The script must never break `npm install`. Errors are
74
+ notices to stdout, never thrown as non-zero exits.
75
+ - **cwd-scoped.** Reads/writes only within the npm-provided `cwd` (the consumer's project root).
76
+ Does not touch the home directory, global config, parent directories, or sibling projects.
77
+ Does not traverse parents or workspaces.
78
+ - **Deterministic.** No network calls, no telemetry, no `Date`/`Math.random`. No imports of
79
+ `http`, `https`, `net`, `fetch`, `dns`, or `child_process`. Output is a pure function of
80
+ (`AGENTS.md` content, flags, `<cwd>/package.json` content).
81
+ - **Direct-dependency only (transitive suppression).** Only writes when
82
+ `@daochild/agents-config` is a direct dependency (listed in the consumer's `dependencies` or
83
+ `devDependencies` in `<cwd>/package.json`). Transitive installs no-op. `peerDependencies` and
84
+ `optionalDependencies` do NOT count as direct (PRD EC-17). This is a blast-radius reduction
85
+ control.
86
+ - **No silent file creation.** If no `AGENTS.md` exists in `cwd` and no `--init` flag is passed,
87
+ the script prints a notice and exits 0; it does not create `AGENTS.md`. With `--init`, it
88
+ creates a minimal `AGENTS.md` (shape defined in the architecture artifact).
89
+ - **Pointer-line content is fixed.** The exact line is byte-identical to the canonical line
90
+ above, including the em dash `—` (U+2014).
91
+ - **No new runtime dependency.** The script uses Node.js built-ins only (`fs`, `path`,
92
+ `process`). It introduces no production dependency.
93
+ - **Manual fallback remains documented.** `README.md` documents both the automatic (postinstall)
94
+ path and the manual (one-line edit) path. The manual path is the supported fallback for
95
+ consumers who use `--ignore-scripts` or whose CI rejects `postinstall`.
96
+
97
+ ### How this narrows the superseded invariants (not abolishes)
98
+
99
+ 1. **`ARCHITECTURE.md` rule 6** — narrowed from "No runtime code" to:
100
+ > No runtime *application* code. This repo's "code" is configuration. The only JS is the
101
+ > opencode plugin host (`@opencode-ai/plugin` dependency), any
102
+ > `.opencode/plugin/*.ts|.js` the user adds, **and one constrained install-time
103
+ > file-pointer helper (`scripts/postinstall.js`) permitted by ADR 0002**. There is no
104
+ > `src/`, no build output, no deployable service, no long-running process.
105
+ The general "no runtime application code" stance is retained; only this specific, bounded
106
+ helper is permitted.
107
+
108
+ 2. **`docs/adr/0001-triple-mirror.md` alt.2** — distinguished, not superseded. Alt.2 rejected
109
+ *generating config in this repo* at install time (which would couple the opencode and Claude
110
+ Code release cadences). This ADR permits writing a *one-line pointer in the consumer's
111
+ file* at install time. The distinction: alt.2 was about producing `.claude/` from `.opencode/`
112
+ inside the package (config generation, release coupling); this ADR is about a single-line
113
+ edit to a file *outside* the package in the consumer's tree (pointer installation, no release
114
+ coupling). The `.claude/` ↔ `.opencode/` generation remains rejected; the postinstall
115
+ pointer-writer is a different concern. This carve-out is explicit so alt.2's rejection is not
116
+ silently violated.
117
+
118
+ 3. **`docs/BUSINESS_LOGIC.md` non-goal** — narrowed from "This repo does not ship runtime
119
+ application code" to:
120
+ > This repo does not ship runtime *application* code. A constrained install-time
121
+ > file-pointer helper (`scripts/postinstall.js`, per ADR 0002) is permitted; it is not
122
+ > application code (no business logic, no service, no long-running process).
123
+ The non-goal's intent (no app code, no service, no deployable runtime) is preserved.
124
+
125
+ ## Architecture decisions carried by this ADR (see architecture artifact for detail)
126
+
127
+ These are the architecture-level decisions that resolve the PRD's "architecture decision" items.
128
+ Full rationale is in `docs/architecture/zero-edit-install-architecture.md`; this ADR records them
129
+ so they are binding:
130
+
131
+ - **Script location/entry:** `scripts/postinstall.js` (CommonJS). `package.json` gets
132
+ `"postinstall": "node scripts/postinstall.js"`. `package.json` `main` is NOT changed to point
133
+ at the postinstall; `main: "index.js"` stays (BL-1 partial resolution only — full plugin host
134
+ hook is out of scope).
135
+ - **Placement rule:** when the pointer line is missing, insert it immediately after the first
136
+ `# ` heading (the title). If no `# ` heading exists, prepend at the top.
137
+ - **`--init` template:** `# <cwd-basename>` + blank line + the pointer line + trailing newline.
138
+ - **Match rule:** exact byte match of the canonical line; "present anywhere in the file" counts
139
+ as present (conservative; avoids double-insert). User formatting with different whitespace but
140
+ the same canonical content is left untouched (never rewritten).
141
+ - **Symlink handling:** skip symlinks (do not follow), print a debug note, exit 0.
142
+ - **Atomic write:** write to a temp file in the same dir, then rename.
143
+ - **Direct-dependency detection:** read `<cwd>/package.json` with `fs.readFileSync`, parse with
144
+ `JSON.parse` in try/catch, check `dependencies` and `devDependencies` for
145
+ `@daochild/agents-config`. `process.env.npm_*` may be used only as a fast-path hint if
146
+ available; the authoritative check is reading `<cwd>/package.json`. Mechanism satisfies AC-9
147
+ and AC-8.
148
+ - **Monorepo / workspace (EC-10):** deferred per maintainer decision. The script checks
149
+ `<cwd>/package.json` only; it does not traverse parents or workspaces. Documented as a known
150
+ limitation covered by the manual fallback. Interacts with EC-18 (cwd-vs-workspace mismatch).
151
+ - **Cross-package-manager:** one Node script, one logic, regardless of manager. Behavior
152
+ verified and documented for npm, yarn classic, yarn berry, pnpm, bun in the architecture
153
+ artifact. For any manager that does not run `postinstall` by default, the manual fallback
154
+ covers it. No per-manager code paths.
155
+
156
+ ## Consequences
157
+
158
+ **Positive**
159
+
160
+ - Zero-edit install for direct consumers; adoption friction removed.
161
+ - Blast radius explicitly bounded: direct-dependency-only, cwd-scoped, deterministic, exit-0,
162
+ safe-append, no network. The AC-11 transitive suppression is a deliberate risk-reduction
163
+ control (security sensitivity is High; this narrows it).
164
+ - The repo's "no runtime application code" stance is preserved — only a bounded helper is
165
+ carved out.
166
+ - Manual fallback documented, so consumers who refuse `postinstall` are not stranded.
167
+ - ADR makes the supersession explicit and traceable; no silent invariant drift.
168
+
169
+ **Negative**
170
+
171
+ - A `postinstall` script is a known npm supply-chain vector. Mitigations: the contract above
172
+ (deterministic, network-free, cwd-scoped, direct-only, exit-0); `SECURITY.md` update required
173
+ (downstream, Security Gate, PRD AC-D4); human approval required at Security and Code Review
174
+ gates (PRD AC-D6).
175
+ - The script is new runtime surface in a config-only repo. Mitigation: the ADR narrows (not
176
+ abolishes) the invariant; the contract clauses are binding and human-approval-gated to change.
177
+ - Cross-package-manager lifecycle differences (EC-11) and monorepo (EC-10) are real; the
178
+ latter is deferred with a documented limitation, the former is verified/documented in the
179
+ architecture artifact.
180
+ - BL-1 (`index.js` stub) is only partially resolved; the `main` field is not reconciled here.
181
+
182
+ **Mitigations**
183
+
184
+ - `sdlc-security` updates `SECURITY.md` (AC-D4) and runs the Security Gate.
185
+ - `sdlc-reviewer` + human run the Code Review Gate; high-risk → senior/security review (AC-D6).
186
+ - `sdlc-auditor` verifies the contract clauses at DoD; any violation blocks.
187
+ - Tests (Testing Gate) assert idempotency, safe-append, exit-0, cwd-scope, direct-only,
188
+ determinism (static import block), and every EC.
189
+
190
+ ## Alternatives considered
191
+
192
+ 1. **Keep the manual one-line edit only (do nothing).** Rejected: leaves the adoption friction
193
+ the maintainer explicitly wants removed.
194
+ 2. **A `bin` CLI the consumer runs (`npx @daochild/agents-config init`).** Considered. Rejected
195
+ for this run: still requires a manual step (only shifts which one). Could be added later as a
196
+ companion to the postinstall; not required by the PRD. The manual one-line edit remains the
197
+ documented fallback either way.
198
+ 3. **Generate `.claude/` from `.opencode/` at install time (ADR 0001 alt.2).** Rejected (and
199
+ this ADR explicitly does NOT reopen it): that couples release cadences and generates config
200
+ *in this repo*. The postinstall pointer-writer is a distinct, narrower concern (one line in
201
+ the consumer's file).
202
+ 4. **Allow the script to write for transitive installs.** Rejected by the maintainer (PRD
203
+ Revision 2): a project that did not directly opt in should not have its `AGENTS.md`
204
+ modified. AC-11 transitive suppression is the stronger guarantee.
205
+ 5. **Workspace-aware dependency detection (traverse parents/workspaces).** Deferred per
206
+ maintainer decision (EC-10/EC-18): the script checks `<cwd>/package.json` only; monorepo is
207
+ a documented limitation covered by the manual fallback. Solving it here would expand scope
208
+ and the blast radius.
209
+
210
+ ## References
211
+
212
+ - `docs/business/zero-edit-install-analysis.md` — analyst artifact (Requirement Gate, pass).
213
+ - `docs/business/zero-edit-install-prd.md` — PRD Revision 2 (Requirement Gate, pass; maintainer
214
+ approved 2026-08-18).
215
+ - `docs/architecture/zero-edit-install-architecture.md` — architecture artifact (this gate).
216
+ - `ARCHITECTURE.md` — rule 6 narrowed per this ADR.
217
+ - `docs/BUSINESS_LOGIC.md` — non-goal narrowed per this ADR.
218
+ - `docs/adr/0001-triple-mirror.md` — alt.2 distinguished (not superseded) per this ADR.
219
+ - `SECURITY.md` — to be updated at the Security Gate (AC-D4).
220
+ - `docs/IMPLEMENTATION.md` — BL-1 status update (AC-D5).
221
+ - `sdlc-regulatory` skill — gate checklists, risk-autonomy table, compliance crosswalk.
222
+
223
+ ## Risk classification (input for `sdlc-sm`)
224
+
225
+ | Axis | Assessment |
226
+ |------|------------|
227
+ | Business impact | Medium — adoption gain; regression hurts every consumer's install |
228
+ | Technical complexity | Medium — small script, but idempotent safe-append + cross-manager + direct-dep detection have real edges |
229
+ | Security sensitivity | **High** — postinstall is a supply-chain vector; mitigated by the contract + AC-11 |
230
+ | Data sensitivity | Low — only a local markdown file |
231
+ | Infrastructure impact | Low — npm publish only, no service |
232
+ | Financial impact | Low — no payments |
233
+ | Breaking-change probability | Low–Medium — `--ignore-scripts` users unaffected; CI that rejects postinstall sees a *policy* signal, not a code break; manual fallback mitigates |
234
+
235
+ Overall risk tier: **Medium/High** (driven by security sensitivity).
236
+ Recommended AI autonomy cap: **≤40%** for implementation stories touching the script;
237
+ documentation-only stories may be higher (80–100%).
File without changes
File without changes
@@ -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%.