@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/AGENTS.md CHANGED
@@ -1,8 +1,17 @@
1
1
  # agents-config
2
2
 
3
3
  A shared configuration repository for AI coding agents. Defines how
4
- `.claude/` (Claude Code) and `.opencode/` (opencode) are organized and how
5
- they reference each other.
4
+ `.claude/` (Claude Code) and `.opencode/` (opencode) are organized and how they reference each other.
5
+
6
+ ## Primary instruction
7
+
8
+ Primary instructions: `node_modules/@daochild/agents-config/AGENTS.md` — read in full and follow unless overridden below.
9
+
10
+ Mandatory start-of-session checklist:
11
+ 1. Read `node_modules/@daochild/agents-config/AGENTS.md` completely.
12
+ 2. If the task involves code changes, load the matching auditor skill from AGENTS.md's Audit Rule before implementation.
13
+ 3. Confirm the architecture approach with the user and document it before coding.
14
+ 4. Do not begin implementation until steps 1–3 are satisfied.
6
15
 
7
16
  ## Behavior
8
17
 
@@ -15,13 +24,72 @@ Instructions:
15
24
  - Distinguish clearly between facts, estimates, assumptions, and opinions.
16
25
  - If you are unsure, say what is uncertain and why.
17
26
  - Do not invent citations, quotes, studies, URLs, or sources.
18
- - When discussing recent events or rapidly changing topics, indicate that
19
- information may have changed and recommend verification from current
20
- sources.
21
- - When providing statistics, identify whether they are exact figures,
22
- estimates, or approximations.
23
- - If multiple interpretations are possible, explain the alternatives rather
24
- than assuming one is correct.
27
+ - When discussing recent events or rapidly changing topics, indicate that information may have changed and recommend
28
+ verification from current sources.
29
+ - When providing statistics, identify whether they are exact figures, estimates, or approximations.
30
+ - If multiple interpretations are possible, explain the alternatives rather than assuming one is correct.
31
+
32
+ ## Audit Rule
33
+
34
+ When the current task involves significant code changes — for example, after the first code-generation prompt or after
35
+ substantial deviations from the agreed Statement of Work (SOW) — the agent MUST run a system audit before finalizing the
36
+ output.
37
+
38
+ 1. **Pick the right auditor skill** for the domain of the change. Examples (replace `xxx` with the actual domain):
39
+ - Smart contracts / EVM → `senior-solidity-auditor`
40
+ - Bitcoin / Taproot / PSBT → `senior-bitcoin-auditor`
41
+ - Quality assurance / test strategy → `senior-qa`
42
+ - General architecture / system design → `senior-software-architect`
43
+ 2. **Run the audit via the matching `xxx-auditor` skill.** Surface findings, severity, and concrete remediation steps.
44
+ 3. **If the required skill does not exist locally, create it first:**
45
+ - Add `.opencode/skill/<xxx-auditor>/SKILL.md`
46
+ - Mirror to `.claude/skills/<xxx-auditor>/SKILL.md` when a Claude Code counterpart is maintained
47
+ - Register the skill path in `opencode.json` if needed
48
+ - Then execute the audit using the newly created skill.
49
+
50
+ Do not skip the audit because a skill is missing; create the skill and perform the audit as part of the same session.
51
+
52
+ ## AI-Driven SDLC Regulatory Framework
53
+
54
+ This repo ships a BMad-style, subagent-based SDLC that operationalizes the AI-Driven Software Development Lifecycle (now
55
+ fully absorbed into the `sdlc-regulatory` skill). It is **always-on** via the `sdlc-gates` rule and is the default flow
56
+ for any feature/change that touches multiple modules or is medium/high risk.
57
+
58
+ ### Components
59
+
60
+ | Component | Path (opencode) | Claude mirror | Agent Skills mirror |
61
+ |-----------------------|--------------------------------------------------------------------------------------|------------------------------------------------|-------------------------------------------|
62
+ | Methodology skill | `.opencode/skill/sdlc-regulatory/SKILL.md` | `.claude/skills/sdlc-regulatory/SKILL.md` | `.agents/skills/sdlc-regulatory/SKILL.md` |
63
+ | Always-on rule | `.claude/rules/sdlc-gates.md` (also in `opencode.json` instructions) | same | `.agents/rules/sdlc-gates.md` |
64
+ | Orchestrator subagent | `.opencode/agent/sdlc-orchestrator.md` | `.claude/agents/sdlc-orchestrator.md` | `.agents/agents/sdlc-orchestrator.md` |
65
+ | Role subagents (×9) | `.opencode/agent/sdlc-{analyst,pm,architect,sm,dev,qa,security,reviewer,auditor}.md` | mirrored (Claude Code frontmatter, no `mode:`) | mirrored verbatim |
66
+ | `/sdlc` slash command | `.opencode/command/sdlc.md` | `.claude/commands/sdlc.md` | `.agents/commands/sdlc.md` |
67
+
68
+ ### SDLC chain
69
+
70
+ ```
71
+ requirement → sdlc-analyst → sdlc-pm → sdlc-architect → sdlc-sm
72
+ → sdlc-dev → sdlc-qa → sdlc-security → sdlc-reviewer → sdlc-auditor
73
+ → deploy (CI/CD, subject to the Deployment Gate)
74
+ ```
75
+
76
+ Each role owns one gate from the `sdlc-regulatory` skill. A failed gate returns work to the previous role with a
77
+ `BLOCKED` note; no gate is skipped. AI never self-validates its own work — reviewer/auditor/security are different
78
+ agents from dev. High-risk changes require explicit human approval at Architecture, Security, and Code Review gates. The
79
+ `sdlc-regulatory` skill also contains a compliance crosswalk (EU AI Act, NIST AI RMF, ISO/IEC 42001, SOC 2, GDPR) for
80
+ regulated projects.
81
+
82
+ ### When to use
83
+
84
+ - **Full `/sdlc` flow**: any change touching multiple modules, medium/high risk, or requiring traceability/compliance
85
+ artifacts.
86
+ - **Inline (main agent only)**: documentation, test generation, trivial internal refactoring (autonomy 80–100%). Still
87
+ subject to the `sdlc-gates` rule.
88
+ - **Above ~50% autonomy cap**: must use the full flow with human approvals.
89
+
90
+ See the `sdlc-regulatory` skill for the full gate checklists, risk-autonomy table, traceability format, and the
91
+ compliance crosswalk. Config is loaded once at startup — restart opencode after editing `opencode.json`, agents, skills,
92
+ plugins, or commands.
25
93
 
26
94
  ## Layout
27
95
 
@@ -33,6 +101,11 @@ agents-config/
33
101
  ├── docs/ # Project documentation
34
102
  ├── research/ # Research and investigation materials
35
103
  ├── resources/ # Project resources and assets
104
+ ├── .agents/ # Cross-client agent config (agentskills.io compatible)
105
+ │ ├── skills/ # Skill folders, each with SKILL.md
106
+ │ ├── agents/ # Subagents
107
+ │ ├── commands/ # Slash commands
108
+ │ └── rules/ # Always-loaded rule files
36
109
  ├── .claude/ # Claude Code project config
37
110
  │ ├── CLAUDE.md # Claude Code instructions (sources AGENTS.md)
38
111
  │ ├── CLAUDE.local.md # Personal overrides (gitignored)
@@ -64,30 +137,33 @@ agents-config/
64
137
 
65
138
  ## Linking
66
139
 
67
- - `AGENTS.md` (root) is the single source of truth for layout and conventions.
68
- Both tools read it: Claude Code via `.claude/CLAUDE.md`, opencode via
140
+ - `AGENTS.md` (root) is the single source of truth for layout and conventions. Both tools read it: Claude Code via
141
+ `.claude/CLAUDE.md`, opencode via
69
142
  `opencode.json` → `instructions` → `AGENTS.md`.
70
143
  - `.opencode/AGENTS.md` is opencode-specific instructions (loaded by
71
- `opencode.json`). It defers to the root `AGENTS.md` for shared structure
72
- and only adds opencode-only notes.
73
- - `.claude/CLAUDE.md` is Claude Code's instructions file. It sources the
74
- root `AGENTS.md` so both tools see the same layout.
75
- - Skills live in `.opencode/skill/` (or `.opencode/skills/`) and
76
- `.claude/skills/`. `opencode.json` declares both paths under
77
- `skills.paths` so opencode auto-discovers the Claude-format skills.
144
+ `opencode.json`). It defers to the root `AGENTS.md` for shared structure and only adds opencode-only notes.
145
+ - `.claude/CLAUDE.md` is Claude Code's instructions file. It sources the root `AGENTS.md` so both tools see the same
146
+ layout.
147
+ - `.agents/` is the cross-client configuration directory compatible with the
148
+ [Agent Skills](https://agentskills.io/) convention. It is optional; existing
149
+ `.claude/` and `.opencode/` directories remain authoritative for their respective clients. The `.agents/` directory is
150
+ intended as a shared fallback so skills registered there are visible to any agent that scans the
151
+ `.agents/skills/` convention.
152
+ - Skills live in `.opencode/skill/` (or `.opencode/skills/`), `.claude/skills/`, and `.agents/skills/`. `opencode.json`
153
+ declares all three paths under
154
+ `skills.paths` so opencode auto-discovers both Claude-format and Agent-Skills skills.
78
155
  - The example `docs` subagent exists in both `.opencode/agent/docs.md` and
79
- `.claude/agents/docs.md`. Each tool uses its own copy; they share the same
80
- description so behavior is consistent.
156
+ `.claude/agents/docs.md`. Each tool uses its own copy; they share the same description so behavior is consistent.
81
157
 
82
158
  ## Adding a new component
83
159
 
84
- | Component | opencode path | Claude Code path |
85
- | --------------- | ------------------------- | -------------------------- |
86
- | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` |
87
- | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` |
88
- | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` |
89
- | Plugin | `.opencode/plugin/<n>.ts` | n/a |
90
- | Always-on rule | add to `opencode.json` `instructions` | add to `.claude/rules/` |
160
+ | Component | opencode path | Claude Code path | Agent Skills path |
161
+ |----------------|---------------------------------------|-------------------------------|-------------------------------|
162
+ | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
163
+ | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
164
+ | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
165
+ | Plugin | `.opencode/plugin/<n>.ts` | n/a | n/a |
166
+ | Always-on rule | add to `opencode.json` `instructions` | add to `.claude/rules/` | add to `.agents/rules/` |
91
167
 
92
168
  ## Code Generation Pipeline
93
169
 
@@ -108,9 +184,9 @@ To create an agent for code generation tasks:
108
184
  ```
109
185
 
110
186
  2. **Create supporting rules** in `.claude/rules/code-generation.md`:
111
- - Coding standards and patterns
112
- - Language-specific guidelines
113
- - Testing requirements
187
+ - Coding standards and patterns
188
+ - Language-specific guidelines
189
+ - Testing requirements
114
190
 
115
191
  3. **Add skills** in `.opencode/skill/code-gen/SKILL.md`:
116
192
  ```markdown
@@ -147,22 +223,25 @@ To create an agent for code generation tasks:
147
223
  }
148
224
  ```
149
225
 
150
- After editing `opencode.json`, an agent file, a skill, a plugin, or any
151
- other config-time file, restart opencode — config is loaded once on startup
152
- and is not hot-reloaded.
226
+ After editing `opencode.json`, an agent file, a skill, a plugin, or any other config-time file, restart opencode —
227
+ config is loaded once on startup and is not hot-reloaded.
153
228
 
154
229
  ## General Recommendations
155
230
 
156
231
  - Create a `README.md` file with deployment instructions
157
232
  - Create a `.aiignore` file to exclude files and directories from AI analysis
158
233
  - Store R&D artifacts in the `docs/` directory:
159
- - `docs/BUSINESS_LOGIC.md` - Business requirements and logic
160
- - `docs/IMPLEMENTATION.md` - Implementation plan, status, and progress
161
- - `docs/ARCHITECTURE.md` - Technical approaches, stack decisions, and architecture
234
+ - `docs/BUSINESS_LOGIC.md` - Business requirements and logic
235
+ - `docs/IMPLEMENTATION.md` - Implementation plan, status, and progress
236
+ - `docs/adr/NNNN-<slug>.md` - Architecture Decision Records
237
+
238
+ The AI-Readable Codebase contract in the `sdlc-regulatory` skill also requires root-level `ARCHITECTURE.md`,
239
+ `CONTRIBUTING.md`, and `SECURITY.md` files for any project the SDLC runs against. This repo maintains all of them.
162
240
 
163
241
  ## Architecture Approach Selection
164
242
 
165
- Before implementation, always ask the user what architecture approach to use, as the choice depends on business logic complexity. Consider these patterns:
243
+ Before implementation, always ask the user what architecture approach to use, as the choice depends on business logic
244
+ complexity. Consider these patterns:
166
245
 
167
246
  - **Clean Architecture** - Separates business logic from frameworks and I/O, promoting testability and maintainability
168
247
  - **Onion Architecture** - Layers of dependencies pointing inward toward the domain core, emphasizing domain isolation
@@ -172,25 +251,33 @@ Before implementation, always ask the user what architecture approach to use, as
172
251
  - **Microservices** - Decomposes application into loosely coupled, independently deployable services
173
252
  - **Monolithic** - Single deployable unit containing all functionality, suitable for simpler applications
174
253
 
175
- Choose the approach based on project scope, team size, scalability requirements, and business logic complexity. Document the decision in `docs/ARCHITECTURE.md`.
254
+ Choose the approach based on project scope, team size, scalability requirements, and business logic complexity. Document
255
+ the decision in an ADR under `docs/adr/` and summarize it in root `ARCHITECTURE.md`.
176
256
 
177
257
  ## Security Guidelines
178
258
 
179
259
  - Set up a vault (e.g., Hardhat vault) on your machine or repository to securely store private keys
180
260
  - Never commit sensitive information directly to the repository
181
261
  - Use environment variables or secure vault solutions for all secrets
182
- - **LLM Security Rule**: LLMs must never commit tokens, keys, personal data, or any sensitive information to code, even if they have permission to read such data. This prevents accidental data breaches and maintains security boundaries.
262
+ - **LLM Security Rule**: LLMs must never commit tokens, keys, personal data, or any sensitive information to code, even
263
+ if they have permission to read such data. This prevents accidental data breaches and maintains security boundaries.
183
264
 
184
265
  ## Cross-Platform Portability
185
266
 
186
267
  To make the project portable across Node.js, Python, and Rust infrastructures:
187
268
 
188
- - **Language-Agnostic Configuration**: Store environment-specific settings in `.env` files or external configuration management systems
189
- - **Containerization**: Use Docker and docker-compose to package applications and their dependencies for consistent deployment across platforms
190
- - **API-First Design**: Expose functionality through REST/gRPC APIs to enable interoperability between services written in different languages
191
- - **Shared Libraries**: Implement core business logic in portable formats (e.g., Protocol Buffers, JSON Schema) that can be consumed by all target platforms
192
- - **Infrastructure as Code**: Use tools like Terraform or CloudFormation to define infrastructure that can deploy any of the language-specific services
193
- - **Polyglot Persistence**: Design data access patterns that work across different database clients and ORMs for each platform
269
+ - **Language-Agnostic Configuration**: Store environment-specific settings in `.env` files or external configuration
270
+ management systems
271
+ - **Containerization**: Use Docker and docker-compose to package applications and their dependencies for consistent
272
+ deployment across platforms
273
+ - **API-First Design**: Expose functionality through REST/gRPC APIs to enable interoperability between services written
274
+ in different languages
275
+ - **Shared Libraries**: Implement core business logic in portable formats (e.g., Protocol Buffers, JSON Schema) that can
276
+ be consumed by all target platforms
277
+ - **Infrastructure as Code**: Use tools like Terraform or CloudFormation to define infrastructure that can deploy any of
278
+ the language-specific services
279
+ - **Polyglot Persistence**: Design data access patterns that work across different database clients and ORMs for each
280
+ platform
194
281
 
195
282
  ## AI Pipeline Configuration
196
283
 
@@ -210,67 +297,68 @@ All generated code must meet production-ready standards:
210
297
  - **Deep Research First** - Conduct thorough research at the beginning of development
211
298
  - **Document Findings** - Store research results and technical decisions
212
299
  - **Time Estimates** - Provide estimates in hours and weeks for all development work
213
- - **Comprehensive Testing** -
214
- - Local and development environment testing required
215
- - Minimum 80% code coverage
216
- - Include unit tests, integration tests, and end-to-end tests
217
- - Automated test execution as part of the development workflow
300
+ - **Comprehensive Testing** -
301
+ - Local and development environment testing required
302
+ - Minimum 80% code coverage
303
+ - Include unit tests, integration tests, and end-to-end tests
304
+ - Automated test execution as part of the development workflow
218
305
 
219
306
  ## Expert Agent Personalities
220
307
 
221
308
  Create specialized AI agents with senior-level expertise in key domains:
222
309
 
223
310
  - **Senior Software Architect** - Deep knowledge in:
224
- - Web architecture and scalable systems design
225
- - Mobile app architecture (iOS/Android)
226
- - Embedded systems and IoT applications
227
- - Cloud infrastructure and microservices
228
- - Database design and optimization
229
- - Security architecture and compliance
311
+ - Web architecture and scalable systems design
312
+ - Mobile app architecture (iOS/Android)
313
+ - Embedded systems and IoT applications
314
+ - Cloud infrastructure and microservices
315
+ - Database design and optimization
316
+ - Security architecture and compliance
230
317
 
231
318
  - **Senior Software Developer** - Comprehensive skills across:
232
- - Frontend development (React, Vue, Angular, etc.)
233
- - Backend development (Node.js, Python, Java, Go, etc.)
234
- - Mobile development (React Native, Flutter, native iOS/Android)
235
- - Embedded programming (C/C++, Rust, Arduino, etc.)
236
- - Database technologies (SQL, NoSQL, GraphQL)
237
- - DevOps and CI/CD pipelines
238
- - Testing frameworks and methodologies
319
+ - Frontend development (React, Vue, Angular, etc.)
320
+ - Backend development (Node.js, Python, Java, Go, etc.)
321
+ - Mobile development (React Native, Flutter, native iOS/Android)
322
+ - Embedded programming (C/C++, Rust, Arduino, etc.)
323
+ - Database technologies (SQL, NoSQL, GraphQL)
324
+ - DevOps and CI/CD pipelines
325
+ - Testing frameworks and methodologies
239
326
 
240
327
  - **DevOps Engineer** - Expertise in:
241
- - Infrastructure as Code (Terraform, CloudFormation)
242
- - Containerization and orchestration (Docker, Kubernetes)
243
- - CI/CD pipeline design and implementation
244
- - Cloud platforms (AWS, Azure, GCP)
245
- - Monitoring and logging solutions
246
- - System performance optimization
247
- - Deployment strategies and rollback procedures
328
+ - Infrastructure as Code (Terraform, CloudFormation)
329
+ - Containerization and orchestration (Docker, Kubernetes)
330
+ - CI/CD pipeline design and implementation
331
+ - Cloud platforms (AWS, Azure, GCP)
332
+ - Monitoring and logging solutions
333
+ - System performance optimization
334
+ - Deployment strategies and rollback procedures
248
335
 
249
336
  - **SecOps Specialist** - Specialized security operations knowledge:
250
- - Security monitoring and incident response
251
- - Vulnerability assessment and penetration testing
252
- - Compliance frameworks (SOC 2, ISO 27001, GDPR)
253
- - Threat modeling and risk assessment
254
- - Security tooling and automation
255
- - Secure coding practices and code review
256
- - Identity and access management
337
+ - Security monitoring and incident response
338
+ - Vulnerability assessment and penetration testing
339
+ - Compliance frameworks (SOC 2, ISO 27001, GDPR)
340
+ - Threat modeling and risk assessment
341
+ - Security tooling and automation
342
+ - Secure coding practices and code review
343
+ - Identity and access management
257
344
 
258
345
  - **QA Engineer** - Comprehensive testing expertise:
259
- - Test planning and strategy development
260
- - Manual and automated testing methodologies
261
- - Test case design and execution
262
- - Bug tracking and reporting
263
- - Performance and load testing
264
- - API and integration testing
265
- - Test automation frameworks (Selenium, Cypress, Jest, etc.)
266
- - Continuous testing in CI/CD pipelines
346
+ - Test planning and strategy development
347
+ - Manual and automated testing methodologies
348
+ - Test case design and execution
349
+ - Bug tracking and reporting
350
+ - Performance and load testing
351
+ - API and integration testing
352
+ - Test automation frameworks (Selenium, Cypress, Jest, etc.)
353
+ - Continuous testing in CI/CD pipelines
267
354
 
268
355
  ## Documentation Maintenance
269
356
 
270
357
  At the end of each session or task, review and update relevant documentation:
271
358
 
272
359
  - **AGENTS.md** - Update if new conventions, patterns, or structures were introduced
273
- - **docs/ARCHITECTURE.md** - Document architecture decisions and changes
360
+ - **ARCHITECTURE.md** - Document architecture decisions and changes (root file; per the AI-Readable Codebase contract in
361
+ the `sdlc-regulatory` skill)
274
362
  - **docs/BUSINESS_LOGIC.md** - Record new business requirements or logic changes
275
363
  - **docs/IMPLEMENTATION.md** - Track implementation progress and status
276
364
  - **README.md** - Update setup, deployment, or usage instructions if changed
@@ -0,0 +1,143 @@
1
+ # Architecture
2
+
3
+ > AI-readable architecture doc for the `agents-config` repository. Required by the
4
+ > `sdlc-regulatory` skill's AI-Readable Codebase contract (hard minimum: `AGENTS.md`
5
+ > + `ARCHITECTURE.md`). Update whenever the repo's structure or conventions change.
6
+
7
+ ## What this repository is
8
+
9
+ `agents-config` is a **shared configuration package** for AI coding agents. It does not ship runtime code; it ships the
10
+ instructions, subagents, skills, slash commands, plugins, and always-on rules that configure how AI agents (opencode and
11
+ Claude Code)
12
+ behave on any project that consumes it.
13
+
14
+ Published to npm as `@daochild/agents-config` and intended to be installed as a **dev dependency**. Consuming projects
15
+ point their `AGENTS.md` at
16
+ `node_modules/@daochild/agents-config/AGENTS.md` to inherit this repo's conventions.
17
+
18
+ ## System diagram
19
+
20
+ ```
21
+ Consuming project
22
+ │
23
+ │ AGENTS.md → "Primary instructions are located at:
24
+ │ node_modules/@daochild/agents-config/AGENTS.md"
25
+ ▼
26
+ agents-config (this repo)
27
+ │
28
+ ├── AGENTS.md .................. single source of truth (layout + conventions)
29
+ │
30
+ ├── opencode.json .............. opencode project config
31
+ │ ├─ instructions[] ....... always-loaded files (AGENTS.md, rules)
32
+ │ ├─ skills.paths[] ....... skill discovery dirs
33
+ │ └─ agent{} .............. subagent registry ({file:./.opencode/agent/<n>.md})
34
+ │
35
+ ├── .opencode/ ................. opencode-native config
36
+ │ ├─ agent/ ............... subagent definitions (opencode frontmatter, mode: subagent)
37
+ │ ├─ skill/ ............... skills (each <n>/SKILL.md)
38
+ │ ├─ command/ ............. slash commands
39
+ │ └─ plugin/ ............. local plugins (*.ts/*.js)
40
+ │
41
+ ├── .claude/ .................. Claude Code-native config
42
+ │ ├─ CLAUDE.md ............ Claude instructions (@AGENTS.md)
43
+ │ ├─ agents/ .............. subagents (Claude Code frontmatter — NO mode: field)
44
+ │ ├─ skills/ .............. skills (auto-discovered by opencode via skills.paths)
45
+ │ ├─ commands/ ............ slash commands
46
+ │ └─ rules/ ............... always-on rules (also listed in opencode.json instructions)
47
+ │
48
+ └── .agents/ ................... cross-client fallback (Agent Skills / agentskills.io)
49
+ ├─ agents/ .............. verbatim opencode frontmatter
50
+ ├─ skills/ .............. verbatim SKILL.md
51
+ ├─ commands/ ............ verbatim
52
+ └─ rules/ ............... verbatim
53
+ ```
54
+
55
+ ## Architectural rules
56
+
57
+ 1. **`AGENTS.md` is the single source of truth.** Both opencode (via `opencode.json`
58
+ → `instructions`) and Claude Code (via `.claude/CLAUDE.md` → `@AGENTS.md`) read it. Never duplicate layout/convention
59
+ content in tool-specific files; reference it.
60
+ 2. **Triple-mirror for components that must work in all clients.** A new subagent / skill / command / rule goes in
61
+ `.opencode/`, `.claude/`, and `.agents/`. The
62
+ `.opencode/` copy is authoritative for opencode; `.claude/` is authoritative for Claude Code; `.agents/` is a
63
+ verbatim cross-client fallback. See `AGENTS.md` →
64
+ "Adding a new component" for the per-format differences (e.g. Claude Code subagents omit the `mode:` frontmatter
65
+ field).
66
+ 3. **Skills are the methodology layer; subagents are thin.** Subagent `.md` files hold the role description,
67
+ responsibilities, and handoff protocol. Deep methodology (gate checklists, risk tables, compliance crosswalks) lives
68
+ in skills (`<n>/SKILL.md`) so it can be loaded by any agent or reviewer.
69
+ 4. **Always-on rules are always-on everywhere.** A rule in `.claude/rules/` is loaded by Claude Code on every turn; to
70
+ make the same rule apply in opencode it MUST also be listed in `opencode.json` → `instructions`. The `.agents/rules/`
71
+ mirror covers Agent-Skills-compatible clients.
72
+ 5. **Config is loaded once at startup.** After editing `opencode.json`, an agent file, a skill, a plugin, or a command,
73
+ restart opencode. No hot reload.
74
+ 6. **No runtime *application* code.** This repo's "code" is configuration. The only JS is the
75
+ opencode plugin host (`@opencode-ai/plugin` dependency), any
76
+ `.opencode/plugin/*.ts|.js` the user adds, **and one constrained install-time file-pointer
77
+ helper (`scripts/postinstall.js`) permitted by [ADR 0002](docs/adr/0002-zero-edit-install.md)**.
78
+ There is no `src/`, no build output, no deployable service, no long-running process. (Rule 6
79
+ narrowed by ADR 0002 from "No runtime code" to "No runtime *application* code"; a single
80
+ bounded install-time helper is permitted.)
81
+
82
+ ## Key decisions
83
+
84
+ - **Schema-pinned config.** `opencode.json` declares
85
+ `"$schema": "https://opencode.ai/config.json"` for editor IntelliSense and validation against the opencode config
86
+ schema.
87
+ - **opencode frontmatter vs Claude Code frontmatter.** opencode agent files use
88
+ `mode: subagent` (and optional `permission`). Claude Code agent files omit
89
+ `mode:`. `.agents/` mirrors keep the opencode frontmatter verbatim so any Agent-Skills-compatible client can use them.
90
+ - **Skill discovery is union of paths.** `opencode.json` lists
91
+ `.agents/skills`, `.opencode/skill`, `.opencode/skills` (optional plural fallback), and `.claude/skills` so a
92
+ Claude-format skill is visible to opencode and vice-versa. This is why triple-mirroring skills is safe.
93
+ - **SDLC regulatory framework.** The `sdlc-*` subagents + `sdlc-regulatory` skill +
94
+ `sdlc-gates` rule implement the AI-Driven SDLC. The skill is the source of truth for the methodology (it superseded
95
+ the deleted `SOW.md`). The orchestrator is the single entry point via the `/sdlc` command.
96
+
97
+ ## What must NOT be changed without human approval
98
+
99
+ - `AGENTS.md` — layout and linking model (any change breaks both tools).
100
+ - `opencode.json` schema pin and `instructions` list (changes what's always-loaded).
101
+ - The triple-mirror invariant for any component already published to consumers (deleting a mirror breaks that client).
102
+ - The `sdlc-regulatory` skill's gate checklists and risk-autonomy table (these are the control surface; relaxing them is
103
+ a high-risk change per the skill's own risk model).
104
+ - **The `postinstall` script's contract (per [ADR 0002](docs/adr/0002-zero-edit-install.md))**:
105
+ idempotency, safe-append (never overwrite), exit-0 (every path), cwd-scoped (no traversal
106
+ outside the consumer root), deterministic (no network/telemetry/`Date`/`Math.random`; no
107
+ `http`/`https`/`net`/`fetch`/`dns`/`child_process` imports), direct-dependency-only (transitive
108
+ suppression; `peerDependencies`/`optionalDependencies` do NOT count as direct), and pointer-line
109
+ content (the em dash `—` U+2014 and the exact wording — see ADR 0002). Relaxing any clause is a
110
+ high-risk change requiring human approval at the Architecture, Security, and Code Review gates.
111
+
112
+ ## Constraints
113
+
114
+ - Node.js stack; package type `commonjs`; main entry `index.js` (currently a placeholder — see `package.json`).
115
+ - **Install-time helper:** `scripts/postinstall.js` (CommonJS, Node built-ins only — `fs`,
116
+ `path`, `process`; no new runtime dependency) is the one constrained runtime entry permitted by
117
+ [ADR 0002](docs/adr/0002-zero-edit-install.md). It writes a single pointer line into the
118
+ consumer's `AGENTS.md` after `npm install`, idempotently, safe-append only, cwd-scoped,
119
+ deterministic, exit-0, and only for direct dependencies (transitive installs are suppressed).
120
+ See ADR 0002 for the full binding contract.
121
+ - `.gitignore` excludes `node_modules`, `.idea`, `.vscode`, `*.logs`.
122
+ - `.npmignore` excludes tests, coverage, CI configs, linters, editor settings,
123
+ `.env*`, `secrets`.
124
+
125
+ ## Stack
126
+
127
+ | Concern | Choice |
128
+ |----------------------|-----------------------------------------------------------------|
129
+ | Package manager | npm / yarn / pnpm / bun (consumer's choice) |
130
+ | Runtime | Node.js (plugin host only; + one install-time helper, ADR 0002) |
131
+ | Install-time helper | `scripts/postinstall.js` (CommonJS; Node built-ins only) |
132
+ | Config format | JSON (`opencode.json`), Markdown (agents/skills/rules/commands) |
133
+ | Schema | `https://opencode.ai/config.json` |
134
+ | Plugin SDK | `@opencode-ai/plugin` |
135
+ | License | MIT |
136
+
137
+ ## See also
138
+
139
+ - `AGENTS.md` — full layout, linking, and "Adding a new component" table.
140
+ - `CONTRIBUTING.md` — how to add agents/skills/commands/rules.
141
+ - `SECURITY.md` — security policy and the LLM security rule.
142
+ - `docs/` — business logic, implementation status, architecture deep-dives, ADRs.
143
+ - `.opencode/skill/sdlc-regulatory/SKILL.md` — AI-Driven SDLC methodology (source of truth for the SDLC controls).
@@ -0,0 +1,90 @@
1
+ # Contributing
2
+
3
+ > How to add to and modify the `agents-config` repository. Read `AGENTS.md` first for
4
+ > the authoritative layout and the "Adding a new component" table.
5
+
6
+ This repo configures AI coding agents (opencode and Claude Code). Contributions are almost always **new configuration
7
+ files** (agents, skills, commands, rules, plugins), not runtime code.
8
+
9
+ ## Before you start
10
+
11
+ 1. Read `AGENTS.md` — it is the single source of truth for layout and conventions.
12
+ 2. Read `ARCHITECTURE.md` — explains the triple-mirror model and what must not be changed without approval.
13
+ 3. Read `SECURITY.md` — the LLM security rule applies to every change.
14
+ 4. If your change touches the SDLC, load the `sdlc-regulatory` skill; if it is medium/high risk or spans multiple
15
+ components, run it through `/sdlc`.
16
+
17
+ ## Adding a component (the triple-mirror rule)
18
+
19
+ Every new subagent / skill / command / rule MUST be added in all three locations so it works in opencode, Claude Code,
20
+ and any Agent-Skills-compatible client.
21
+
22
+ | Component | opencode path | Claude Code path | Agent Skills path |
23
+ |----------------|---------------------------------------|-------------------------------|-------------------------------|
24
+ | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
25
+ | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
26
+ | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
27
+ | Plugin | `.opencode/plugin/<n>.ts` | n/a | n/a |
28
+ | Always-on rule | add to `opencode.json` `instructions` | add to `.claude/rules/` | add to `.agents/rules/` |
29
+
30
+ ### Format differences
31
+
32
+ - **opencode subagent frontmatter** uses `mode: subagent` (and optional `permission`).
33
+ - **Claude Code subagent frontmatter** omits the `mode:` field.
34
+ - **`.agents/` mirrors** keep the opencode frontmatter verbatim.
35
+ - **Skills** use the same `SKILL.md` format in all three locations.
36
+
37
+ ## Workflow
38
+
39
+ 1. Create a branch: `feat/<name>` or `chore/<name>`.
40
+ 2. Make the change in `.opencode/` first (authoritative for opencode).
41
+ 3. Mirror to `.claude/` (apply format differences above) and `.agents/` (verbatim).
42
+ 4. If you added/changed an always-on rule, update `opencode.json` `instructions` and add the file to `.claude/rules/` +
43
+ `.agents/rules/`.
44
+ 5. If you added a subagent, register it under `agent` in `opencode.json` with a
45
+ `prompt: "{file:./.opencode/agent/<n>.md}"` entry.
46
+ 6. **Restart opencode** to validate — config is loaded once at startup, not hot-reloaded.
47
+ 7. Verify mirror consistency before committing (see the verify script below).
48
+
49
+ ## Verifying mirror consistency
50
+
51
+ Before committing, confirm the three mirrors are consistent:
52
+
53
+ ```bash
54
+ # opencode <-> .agents should be byte-identical
55
+ diff -q .opencode/agent/<n>.md .agents/agents/<n>.md
56
+ # opencode <-> .claude should differ ONLY by the 'mode: subagent' line
57
+ diff <(grep -v '^mode: subagent$' .opencode/agent/<n>.md) .claude/agents/<n>.md
58
+ # skills should be byte-identical across all three
59
+ diff -q .opencode/skill/<n>/SKILL.md .claude/skills/<n>/SKILL.md
60
+ diff -q .opencode/skill/<n>/SKILL.md .agents/skills/<n>/SKILL.md
61
+ ```
62
+
63
+ ## Commit conventions
64
+
65
+ - Conventional Commits style: `feat:`, `fix:`, `chore:`, `docs:`.
66
+ - One logical change per commit. Do not batch unrelated mirrors with feature work.
67
+ - Never commit secrets, tokens, or personal data (see `SECURITY.md`).
68
+
69
+ ## SDLC changes
70
+
71
+ If your change modifies the SDLC framework itself (gates, risk table, compliance crosswalk, subagent handoff protocol),
72
+ it is **high-risk** per the
73
+ `sdlc-regulatory` skill's own risk model. Run it through `/sdlc` and require human approval at the Architecture,
74
+ Security, and Code Review gates. Do not relax the autonomy caps or gate checklists without explicit sign-off.
75
+
76
+ ## Updating documentation
77
+
78
+ After any change, update:
79
+
80
+ - `AGENTS.md` — if layout/conventions changed.
81
+ - `ARCHITECTURE.md` — if structure or key decisions changed.
82
+ - `docs/adr/NNNN-<slug>.md` — for any non-trivial architectural decision.
83
+ - `README.md` — if install/usage changed.
84
+ - `package.json` version — follow SemVer; breaking config changes are a major bump.
85
+
86
+ Treat outdated docs as technical debt.
87
+
88
+ ## License
89
+
90
+ By contributing, you agree your contributions are licensed under the MIT license (see `LICENSE`).