@daochild/agents-config 1.0.7 → 1.2.1

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 +174 -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
package/README.md CHANGED
@@ -4,47 +4,76 @@ This repository contains configuration and tooling for the Opencode and Claude C
4
4
 
5
5
  The package is intended for production‑grade automation: version control, CI/CD, and collaboration across development teams. Extend the configuration as needed for your ecosystem.
6
6
 
7
+ ## What's in the box
8
+
9
+ - **Shared layout & conventions** — `AGENTS.md` is the single source of truth, inherited (not copied) by consuming projects.
10
+ - **Triple-mirror model** — every subagent / skill / command / rule is mirrored across `.opencode/`, `.claude/`, and `.agents/` so it works in opencode, Claude Code, and any Agent-Skills-compatible client (see ADR 0001).
11
+ - **AI-Driven SDLC framework** — `sdlc-regulatory` skill + 10 `sdlc-*` subagents + `sdlc-gates` rule + `/sdlc` command. Gates run in order (requirement → architecture → implementation → testing → security → review → deployment → DoD), AI never self-validates, high-risk changes require human approval, and a compliance crosswalk covers EU AI Act / NIST AI RMF / ISO 42001 / SOC 2 / GDPR.
12
+ - **Domain skills** — `senior-qa`, `senior-solidity-auditor`, `senior-bitcoin-auditor`, `senior-frontend-dev`, `senior-software-developer`, `senior-ux-ui-designer`, `archivarius`, `data-engineer`, `find-skills`, `frontend-design`.
13
+ - **Always-on rules** — `programming-best-practices` and `sdlc-gates`.
14
+ - **AI-readable contract** — `ARCHITECTURE.md`, `CONTRIBUTING.md`, `SECURITY.md`, `docs/` (business logic, implementation status, ADRs).
15
+
7
16
  ## Installation
8
17
 
9
- NodeJs stack.
10
- Select your package manager. This package should be installed as a
11
- **dev dependency** since it configures the local development tooling.
18
+ Install as a **dev dependency** (this package configures local development tooling):
12
19
 
13
20
  ```bash
14
- # Using npm
21
+ # npm / yarn / pnpm / bun
15
22
  npm install --save-dev @daochild/agents-config
16
- ```
17
- ```bash
18
- # Using yarn
19
23
  yarn add --dev @daochild/agents-config
20
- ```
21
- ```bash
22
- # Using pnpm
23
24
  pnpm add --save-dev @daochild/agents-config
24
- ```
25
- ```bash
26
- # Using bun
27
25
  bun add --dev @daochild/agents-config
28
26
  ```
29
27
 
30
- The package exposes a set of configuration files and scripts that can be consumed by the Opencode and Claude Code tooling.
28
+ ### Automatic path (zero-edit)
31
29
 
32
- ## After installation
30
+ After `npm install`, this package's `postinstall` script automatically writes a
31
+ single pointer line into your project's `AGENTS.md` (if one exists), idempotently
32
+ and non-destructively. The script is deterministic (no network, no telemetry),
33
+ scoped to your project root (`cwd`), never overwrites existing content, and
34
+ always exits `0` so it can never break your install. It only writes when
35
+ `@daochild/agents-config` is a **direct** dependency in your `package.json`
36
+ (`dependencies` or `devDependencies`); transitive installs are left untouched.
33
37
 
34
- Add the following block at the top of your project's `AGENTS.md`, immediately
35
- after the title, so the agent loads this package as its primary instructions
36
- source:
38
+ The line it writes is:
37
39
 
38
40
  ```markdown
39
- Primary instructions are located at:
40
- - node_modules/@daochild/agents-config/AGENTS.md
41
+ Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — read in full and follow unless overridden below.
42
+ ```
43
+
44
+ If your project has no `AGENTS.md`, the script prints a notice and exits `0`
45
+ without creating one. To have it create a minimal `AGENTS.md` (a title line
46
+ followed by the pointer line), pass the explicit `--init` flag:
41
47
 
42
- Follow all instructions from that file unless overridden below.
48
+ ```bash
49
+ node node_modules/@daochild/agents-config/scripts/postinstall.js --init
43
50
  ```
44
51
 
45
- Then restart your agent session (e.g. restart opencode or Claude Code) so
46
- the new instructions take effect — config is loaded once at startup and is
47
- not hot-reloaded.
52
+ **Known limitation (monorepo / workspace):** the script checks only the
53
+ `package.json` in the directory where the install is running (`cwd`); it does
54
+ not traverse parent or sibling workspace `package.json` files. In a monorepo
55
+ where the dependency is declared in a sub-workspace but the install `cwd` is the
56
+ workspace root (or vice versa), the automatic write may not fire. Use the manual
57
+ path below in that case.
58
+
59
+ ### Manual path (supported fallback)
60
+
61
+ If your CI policy rejects `postinstall`, you use `--ignore-scripts`, or the
62
+ automatic path does not apply (e.g. the monorepo limitation above), add this one
63
+ line at the top of your project's `AGENTS.md`, immediately after the title, so
64
+ the agent inherits this package as its primary instructions source:
65
+
66
+ ```markdown
67
+ Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — read in full and follow unless overridden below.
68
+ ```
69
+
70
+ This manual path is the supported fallback and is runnable without the
71
+ `postinstall` ever having run.
72
+
73
+ ### After either path
74
+
75
+ Restart your agent session (opencode or Claude Code) so the new instructions
76
+ take effect — config is loaded once at startup and is not hot-reloaded.
48
77
 
49
78
  ## License
50
79
 
package/SECURITY.md ADDED
@@ -0,0 +1,79 @@
1
+ # Security Policy
2
+
3
+ > Security policy for the `agents-config` repository. Required by the
4
+ > `sdlc-regulatory` skill's AI-Readable Codebase contract.
5
+
6
+ ## Reporting a vulnerability
7
+
8
+ Do not open a public GitHub issue for security vulnerabilities. Instead, email the
9
+ maintainer at the address listed in `package.json` → `author`, or open a private
10
+ security advisory on GitHub. Include:
11
+
12
+ - A description of the issue and its impact.
13
+ - Steps to reproduce or a proof of concept.
14
+ - Affected file(s) or component(s).
15
+ - Suggested remediation if you have one.
16
+
17
+ You will receive an acknowledgment within 72 hours. Please do not disclose the
18
+ vulnerability publicly until a fix has been released.
19
+
20
+ ## LLM Security Rule (binding on every agent and contributor)
21
+
22
+ > **LLMs must never commit tokens, keys, personal data, or any sensitive
23
+ > information to code, even if they have permission to read such data.**
24
+
25
+ This is the single most important security rule in this repository:
26
+
27
+ - Agents that read secrets (env vars, `.env` files, vault contents, API tokens)
28
+ must NEVER write them into any file, commit message, log, or artifact.
29
+ - This prevents accidental data breaches and maintains the security boundary
30
+ between "agent can read" and "agent can publish".
31
+ - If an agent encounters a secret while editing, it MUST redact it (replace with
32
+ `<redacted>` or a placeholder) rather than copy it forward.
33
+ - The `sdlc-security` subagent's Security Gate includes secrets scanning; any
34
+ detected secret in a diff blocks advancement until remediated or explicitly
35
+ accepted by a human.
36
+
37
+ ## Secrets handling
38
+
39
+ - **No secrets in the repository.** `.gitignore` excludes `.env*` and `secrets`;
40
+ `.npmignore` reinforces this for package publishing.
41
+ - Use environment variables or a secure vault (e.g., Hardhat vault, AWS Secrets
42
+ Manager, 1Password CLI) for all secrets — never inline them.
43
+ - The `sdlc-regulatory` skill's Security Gate requires secrets scanning on every
44
+ AI-generated change (SAST, dependency scan, secrets scan, security AI review,
45
+ authN/Z validation where applicable).
46
+
47
+ ## What is in scope
48
+
49
+ This repository is configuration-only (no runtime code, no deployable service).
50
+ Security concerns are therefore primarily:
51
+
52
+ - **Secret leakage** via agent-generated content (the LLM Security Rule above).
53
+ - **Supply-chain risk** from the npm dependency `@opencode-ai/plugin` — keep it
54
+ pinned and monitor advisories.
55
+ - **Permission overreach** in `opencode.json` agent `permission` blocks — prefer
56
+ `ask` over `allow` for `edit` and `bash` on any agent that touches production.
57
+ - **SDLC gate bypass** — any change that weakens a gate, removes a reviewer, or
58
+ raises an autonomy cap is a high-risk security change requiring human approval.
59
+
60
+ ## Out of scope
61
+
62
+ - Vulnerabilities in downstream projects that consume this config — report those to
63
+ the downstream project, not here.
64
+ - Vulnerabilities in opencode or Claude Code themselves — report to the respective
65
+ upstream project.
66
+
67
+ ## Compliance
68
+
69
+ When a consuming project targets a regulated domain (EU AI Act high-risk, ISO 42001
70
+ certified, SOC 2 audited, or processes personal data under GDPR), the SDLC gates
71
+ must produce the artifacts the compliance crosswalk in the `sdlc-regulatory` skill
72
+ lists. This policy does not replace legal review.
73
+
74
+ ## See also
75
+
76
+ - `AGENTS.md` → "Security Guidelines"
77
+ - `sdlc-regulatory` skill → Security Gate checklist + compliance crosswalk
78
+ - `CONTRIBUTING.md` → SDLC changes are high-risk
79
+ - `.gitignore`, `.npmignore` — what is excluded from repo and package
@@ -0,0 +1,63 @@
1
+ # Business Logic
2
+
3
+ > Business requirements and logic for the `agents-config` repository.
4
+ > AGENTS.md "General Recommendations" / "Documentation Maintenance" require this file.
5
+
6
+ ## Purpose
7
+
8
+ `agents-config` exists to give AI coding agents (opencode and Claude Code) a **single, shared, version-controlled
9
+ configuration source** so that:
10
+
11
+ 1. Agent behavior is consistent across projects and across tools.
12
+ 2. Conventions, skills, subagents, and rules are inherited, not copy-pasted.
13
+ 3. The AI-Driven SDLC (gates, risk model, traceability, compliance) is always-on by default for any consuming project.
14
+ 4. New AI capabilities can be added once and propagate to every consumer via an npm update.
15
+
16
+ ## Stakeholders
17
+
18
+ - **Maintainer**: Pavlo Bolhar (`package.json` author).
19
+ - **Consumers**: any project that installs `@daochild/agents-config` as a dev dependency and points its `AGENTS.md` at
20
+ the package.
21
+ - **End users**: developers using opencode or Claude Code on those consumer projects.
22
+
23
+ ## Core requirements
24
+
25
+ | ID | Requirement | Status |
26
+ |------|---------------------------------------------------------|--------------------------------------------------------------------------------------|
27
+ | BR-1 | Single source of truth for agent layout and conventions | Met by `AGENTS.md` |
28
+ | BR-2 | Works in both opencode and Claude Code from one config | Met by triple-mirror model |
29
+ | BR-3 | Skills are loadable expertise, reusable across agents | Met by `skills.paths` union in `opencode.json` |
30
+ | BR-4 | SDLC gates are always-on, not opt-in | Met by `sdlc-gates` rule in `opencode.json` instructions + `.claude/rules/` |
31
+ | BR-5 | AI never self-validates its own work | Met by separate `sdlc-reviewer` / `sdlc-security` / `sdlc-auditor` agents |
32
+ | BR-6 | High-risk changes require human approval | Met by autonomy caps + human approval gates in `sdlc-regulatory` skill |
33
+ | BR-7 | Changes are traceable to requirements | Met by the traceability block in the DoD audit artifact |
34
+ | BR-8 | Config is portable across Node ecosystems | Met by npm packaging; consumer picks package manager |
35
+ | BR-9 | Repo is itself AI-readable (dogfoods its own contract) | Met by `AGENTS.md` + `ARCHITECTURE.md` + `SECURITY.md` + `CONTRIBUTING.md` + `docs/` |
36
+
37
+ ## Non-goals
38
+
39
+ - This repo does not ship runtime *application* code. A constrained install-time file-pointer
40
+ helper (`scripts/postinstall.js`, per [ADR 0002](adr/0002-zero-edit-install.md)) is
41
+ permitted; it is not application code (no business logic, no service, no long-running process).
42
+ - This repo does not deploy anything; it has no `services/`, `tests/`, or
43
+ `infrastructure/` of its own (those dirs are part of the contract for consuming projects, not for this config
44
+ package).
45
+ - This repo does not replace opencode's or Claude Code's own configuration schemas; it conforms to them (`opencode.json`
46
+ is pinned to the opencode config schema).
47
+
48
+ ## Scope of the SDLC framework
49
+
50
+ The `sdlc-regulatory` skill + `sdlc-*` subagents + `sdlc-gates` rule implement the AI-Driven Software Development
51
+ Lifecycle. The original specification lived in
52
+ `SOW.md` and has been **fully absorbed into the `sdlc-regulatory` skill** (the skill header records that it supersedes
53
+ the deleted `SOW.md`). The business logic of the SDLC — gates, risk model, autonomy caps, traceability, Definition of
54
+ Done, compliance crosswalk — lives in that skill, not in this file. This file records *why* the SDLC framework exists as
55
+ a business requirement (BR-4 through BR-7).
56
+
57
+ ## Change log
58
+
59
+ | Date | Change | Author |
60
+ |------------|-------------------------------------------------|------------|
61
+ | 2026-08-18 | Bumped version to 1.1.0; broadened package metadata (description/keywords) to cover the SDLC governance scope introduced today | maintainer |
62
+ | 2026-08-18 | Simplified README install flow (A+C): one combined section, single-line `AGENTS.md` pointer replacing the 3-line block | maintainer |
63
+ | 2026-08-18 | Initial creation; absorbed SOW business context | maintainer |
@@ -0,0 +1,59 @@
1
+ # Implementation
2
+
3
+ > Implementation plan, status, and progress for the `agents-config` repository.
4
+ > AGENTS.md "General Recommendations" / "Documentation Maintenance" require this file.
5
+
6
+ ## Status: stable
7
+
8
+ The repository is production-published as `@daochild/agents-config` (see
9
+ `package.json`). The core configuration model (triple-mirror, single source of truth, skill/subagent split) is stable.
10
+ The SDLC regulatory framework was added in the current cycle and is the most recent significant feature.
11
+
12
+ ## Implemented components
13
+
14
+ | Component | Status | Location | Notes |
15
+ |---------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
16
+ | Root instructions (`AGENTS.md`) | Done | `AGENTS.md` | Single source of truth |
17
+ | opencode config | Done | `opencode.json` | Schema-pinned; 11 agents registered |
18
+ | Cross-client fallback | Done | `.agents/` | Verbatim mirrors |
19
+ | Claude Code config | Done | `.claude/` | `CLAUDE.md` sources `AGENTS.md` |
20
+ | Always-on rules | Done | `.claude/rules/`, `.agents/rules/`, `opencode.json` instructions | `programming-best-practices`, `sdlc-gates` |
21
+ | SDLC regulatory skill | Done | `.opencode/skill/sdlc-regulatory/` (+ mirrors) | Supersedes deleted `SOW.md` |
22
+ | SDLC orchestrator | Done | `.opencode/agent/sdlc-orchestrator.md` (+ mirrors) | Entry point for `/sdlc` |
23
+ | SDLC role subagents (×9) | Done | `.opencode/agent/sdlc-{analyst,pm,architect,sm,dev,qa,security,reviewer,auditor}.md` (+ mirrors) | One per gate |
24
+ | `/sdlc` command | Done | `.opencode/command/sdlc.md` (+ mirrors) | Invokes orchestrator |
25
+ | Domain skills | Done | `.opencode/skill/{senior-qa,senior-solidity-auditor,senior-bitcoin-auditor,senior-frontend-dev,senior-software-developer,senior-ux-ui-designer,archivarius,data-engineer,find-skills,frontend-design}/` | Loaded on demand |
26
+ | AI-readable contract files | Done | `ARCHITECTURE.md`, `CONTRIBUTING.md`, `SECURITY.md`, `docs/` | This cycle |
27
+ | `index.js` entry | Stub | `package.json` → `main` | Placeholder; no runtime code yet |
28
+ | Postinstall pointer script | Done | `scripts/postinstall.js`, `package.json` → `scripts.postinstall` | Per ADR 0002; constrained install-time helper |
29
+
30
+ ## In progress
31
+
32
+ - Nothing actively in progress.
33
+
34
+ ## Backlog
35
+
36
+ | ID | Item | Priority | Notes |
37
+ |------|--------------------------------------------------------------|----------|-----------------------------------------------------|
38
+ | BL-1 | Add a real `index.js` entry if plugins need a host hook | low | Partially resolved (postinstall only); a full plugin host hook remains a separate concern. `package.json` `main: "index.js"` is unchanged — the postinstall script (`scripts/postinstall.js`) is a constrained install-time helper per ADR 0002, not the package's main entry. Reconciling `main` with a real `index.js` host hook is still open. |
39
+ | BL-2 | Seed `docs/api/` if the plugin interface becomes public | low | Config-only repo has no public API today |
40
+ | BL-3 | Seed `docs/database/` if any stateful metadata is introduced | low | Config-only repo has no database |
41
+ | BL-4 | Add CI workflow to verify triple-mirror consistency on PR | medium | See `CONTRIBUTING.md` verify script |
42
+ | BL-5 | Record an ADR for the triple-mirror decision | low | `docs/adr/0001-triple-mirror.md` |
43
+
44
+ ## Definition of Done (per the `sdlc-regulatory` skill)
45
+
46
+ Every change to this repo should be able to check off the DoD checklist in the
47
+ `sdlc-regulatory` skill. For config-only changes (no code, no deploy), the
48
+ "Deployment successfully validated" item is satisfied by "npm publish succeeds and a consumer can install the new
49
+ version"; the "Observability" item is satisfied by
50
+ "the change is documented in this file and in `AGENTS.md`/`ARCHITECTURE.md` as relevant".
51
+
52
+ ## Change log
53
+
54
+ | Date | Change | Author |
55
+ |------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
56
+ | 2026-08-18 | Bumped version to 1.1.0 (minor) for the SDLC feature release; updated `package.json` description and keywords to reflect the SDLC/governance scope. | maintainer |
57
+ | 2026-08-18 | Simplified `README.md` install section: collapsed "After installation" into "Installation"; replaced 3-line `AGENTS.md` block with a single pointer line. No contract change (no postinstall/bin; respects the "no runtime code" invariant). | maintainer |
58
+ | 2026-08-18 | Added SDLC regulatory framework (skill + 10 subagents + rule + command); absorbed `SOW.md` into the skill; deleted `SOW.md`; added AI-readable contract files (`ARCHITECTURE.md`, `CONTRIBUTING.md`, `SECURITY.md`, `docs/`) | maintainer |
59
+ | 2026-08-18 | Implemented postinstall zero-edit install (S02+S03+S04+S06) per ADR 0002 + architecture artifact. Added `scripts/postinstall.js` (CommonJS, Node built-ins only) wired via `package.json` `scripts.postinstall`; updated `README.md` to document both the automatic (postinstall) and manual (one-line edit) paths; updated BL-1 status to "Partially resolved (postinstall only)". Narrowed `ARCHITECTURE.md` rule 6 and `docs/BUSINESS_LOGIC.md` non-goal per ADR 0002. `SECURITY.md` update deferred to the Security Gate (S05); tests deferred to the Testing Gate (S07). | sdlc-dev (Implementation Gate) |
@@ -0,0 +1,81 @@
1
+ # ADR 0001 — Triple-mirror every shared component
2
+
3
+ - **Status**: accepted
4
+ - **Date**: 2026-08-18
5
+ - **Deciders**: maintainer
6
+
7
+ ## Context
8
+
9
+ `agents-config` configures two AI coding agents (opencode and Claude Code) that use incompatible frontmatter formats and
10
+ different discovery mechanisms:
11
+
12
+ - opencode reads `opencode.json` → `agent` registry with `{file:...}` prompts and
13
+ `mode: subagent` frontmatter; skills via `skills.paths`.
14
+ - Claude Code reads `.claude/agents/*.md` with Claude Code frontmatter (no `mode:`
15
+ field), `.claude/skills/<n>/SKILL.md`, and `.claude/commands/*.md`; rules in
16
+ `.claude/rules/` are always-on.
17
+ - A third convention, [Agent Skills](https://agentskills.io/) (`.agents/`), is a cross-client fallback for any tool that
18
+ scans it.
19
+
20
+ A component added in only one location works in only one tool. Consumers using both tools would see inconsistent
21
+ behavior.
22
+
23
+ ## Decision
24
+
25
+ Every subagent, skill, slash command, and always-on rule that must work across clients is **triple-mirrored**:
26
+
27
+ | Component | opencode (authoritative) | Claude Code (authoritative) | `.agents/` (fallback) |
28
+ |----------------|-----------------------------------|-------------------------------|-------------------------------|
29
+ | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
30
+ | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
31
+ | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
32
+ | Always-on rule | in `opencode.json` `instructions` | `.claude/rules/<n>.md` | `.agents/rules/<n>.md` |
33
+
34
+ ### Format differences
35
+
36
+ - opencode subagent frontmatter: `mode: subagent` (and optional `permission`).
37
+ - Claude Code subagent frontmatter: omits `mode:`.
38
+ - `.agents/` mirrors: keep the opencode frontmatter verbatim.
39
+ - Skills are identical across all three (same `SKILL.md` format).
40
+
41
+ ### Authoritative copy
42
+
43
+ For drift resolution: the `.opencode/` copy is authoritative for opencode; the
44
+ `.claude/` copy is authoritative for Claude Code. When a change is made, update
45
+ `.opencode/` first, then mirror to `.claude/` (applying the format difference) and
46
+ `.agents/` (verbatim). Skills are byte-identical in all three.
47
+
48
+ ## Consequences
49
+
50
+ **Positive**
51
+
52
+ - One change works in both tools and any Agent-Skills-compatible client.
53
+ - Skills are universally discoverable (`opencode.json` lists all three skill dirs).
54
+ - Clear ownership: each tool's authoritative copy is in its own directory.
55
+
56
+ **Negative**
57
+
58
+ - Three files to keep in sync per component; mirror drift is a real risk.
59
+ - Requires a verification step before commit (see `CONTRIBUTING.md`).
60
+ - More files in the repo; larger diff surface.
61
+
62
+ **Mitigations**
63
+
64
+ - `CONTRIBUTING.md` documents the verify commands.
65
+ - Backlog item BL-4: add CI to check mirror consistency on PR.
66
+ - The `.agents/` mirror is verbatim from `.opencode/`, so it can be regenerated; the `.claude/` mirror differs only by
67
+ the `mode:` line, which is mechanical.
68
+
69
+ ## Alternatives considered
70
+
71
+ 1. **Single source + symlinks.** Rejected: symlinks don't reliably survive npm packaging across platforms and OSes.
72
+ 2. **Generate `.claude/` from `.opencode/` at install time.** Rejected: adds a build step to a config-only repo and
73
+ couples the tools' release cadences.
74
+ 3. **`.agents/` only, let both tools scan it.** Rejected: opencode and Claude Code do not both natively scan `.agents/`
75
+ for all component types today; relying on it would lose tool-specific frontmatter.
76
+
77
+ ## References
78
+
79
+ - `AGENTS.md` → "Adding a new component"
80
+ - `ARCHITECTURE.md` → Architectural rules + Key decisions
81
+ - `CONTRIBUTING.md` → "Verifying mirror consistency"
@@ -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