@daochild/agents-config 1.0.7 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/.agents/.gitkeep +0 -0
  2. package/.agents/agents/.gitkeep +0 -0
  3. package/.agents/agents/sdlc-analyst.md +30 -0
  4. package/.agents/agents/sdlc-architect.md +32 -0
  5. package/.agents/agents/sdlc-auditor.md +45 -0
  6. package/.agents/agents/sdlc-dev.md +34 -0
  7. package/.agents/agents/sdlc-orchestrator.md +70 -0
  8. package/.agents/agents/sdlc-pm.md +33 -0
  9. package/.agents/agents/sdlc-qa.md +34 -0
  10. package/.agents/agents/sdlc-reviewer.md +32 -0
  11. package/.agents/agents/sdlc-security.md +37 -0
  12. package/.agents/agents/sdlc-sm.md +32 -0
  13. package/.agents/commands/.gitkeep +0 -0
  14. package/.agents/commands/sdlc.md +18 -0
  15. package/.agents/rules/.gitkeep +0 -0
  16. package/.agents/rules/sdlc-gates.md +45 -0
  17. package/.agents/skills/.gitkeep +0 -0
  18. package/.agents/skills/agents-config/SKILL.md +32 -0
  19. package/.agents/skills/sdlc-regulatory/SKILL.md +515 -0
  20. package/.claude/agents/sdlc-analyst.md +29 -0
  21. package/.claude/agents/sdlc-architect.md +31 -0
  22. package/.claude/agents/sdlc-auditor.md +44 -0
  23. package/.claude/agents/sdlc-dev.md +33 -0
  24. package/.claude/agents/sdlc-orchestrator.md +69 -0
  25. package/.claude/agents/sdlc-pm.md +32 -0
  26. package/.claude/agents/sdlc-qa.md +33 -0
  27. package/.claude/agents/sdlc-reviewer.md +31 -0
  28. package/.claude/agents/sdlc-security.md +36 -0
  29. package/.claude/agents/sdlc-sm.md +31 -0
  30. package/.claude/commands/sdlc.md +18 -0
  31. package/.claude/rules/sdlc-gates.md +45 -0
  32. package/.claude/skills/sdlc-regulatory/SKILL.md +515 -0
  33. package/.opencode/AGENTS.md +11 -0
  34. package/.opencode/agent/sdlc-analyst.md +30 -0
  35. package/.opencode/agent/sdlc-architect.md +32 -0
  36. package/.opencode/agent/sdlc-auditor.md +45 -0
  37. package/.opencode/agent/sdlc-dev.md +34 -0
  38. package/.opencode/agent/sdlc-orchestrator.md +70 -0
  39. package/.opencode/agent/sdlc-pm.md +33 -0
  40. package/.opencode/agent/sdlc-qa.md +34 -0
  41. package/.opencode/agent/sdlc-reviewer.md +32 -0
  42. package/.opencode/agent/sdlc-security.md +37 -0
  43. package/.opencode/agent/sdlc-sm.md +32 -0
  44. package/.opencode/command/sdlc.md +18 -0
  45. package/.opencode/skill/sdlc-regulatory/SKILL.md +515 -0
  46. package/AGENTS.md +164 -86
  47. package/ARCHITECTURE.md +143 -0
  48. package/CONTRIBUTING.md +90 -0
  49. package/README.md +53 -24
  50. package/SECURITY.md +79 -0
  51. package/docs/BUSINESS_LOGIC.md +63 -0
  52. package/docs/IMPLEMENTATION.md +59 -0
  53. package/docs/adr/0001-triple-mirror.md +81 -0
  54. package/docs/adr/0002-zero-edit-install.md +237 -0
  55. package/docs/api/.gitkeep +0 -0
  56. package/docs/architecture/.gitkeep +0 -0
  57. package/docs/architecture/zero-edit-install-architecture.md +306 -0
  58. package/docs/business/zero-edit-install-analysis.md +295 -0
  59. package/docs/business/zero-edit-install-prd.md +404 -0
  60. package/docs/database/.gitkeep +0 -0
  61. package/docs/stories/zero-edit-install-assumptions.md +80 -0
  62. package/docs/stories/zero-edit-install-stories.md +256 -0
  63. package/opencode.json +54 -2
  64. package/package.json +14 -4
  65. package/scripts/postinstall.js +163 -0
package/AGENTS.md CHANGED
@@ -1,8 +1,7 @@
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.
6
5
 
7
6
  ## Behavior
8
7
 
@@ -15,13 +14,72 @@ Instructions:
15
14
  - Distinguish clearly between facts, estimates, assumptions, and opinions.
16
15
  - If you are unsure, say what is uncertain and why.
17
16
  - 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.
17
+ - When discussing recent events or rapidly changing topics, indicate that information may have changed and recommend
18
+ verification from current sources.
19
+ - When providing statistics, identify whether they are exact figures, estimates, or approximations.
20
+ - If multiple interpretations are possible, explain the alternatives rather than assuming one is correct.
21
+
22
+ ## Audit Rule
23
+
24
+ When the current task involves significant code changes — for example, after the first code-generation prompt or after
25
+ substantial deviations from the agreed Statement of Work (SOW) — the agent MUST run a system audit before finalizing the
26
+ output.
27
+
28
+ 1. **Pick the right auditor skill** for the domain of the change. Examples (replace `xxx` with the actual domain):
29
+ - Smart contracts / EVM → `senior-solidity-auditor`
30
+ - Bitcoin / Taproot / PSBT → `senior-bitcoin-auditor`
31
+ - Quality assurance / test strategy → `senior-qa`
32
+ - General architecture / system design → `senior-software-architect`
33
+ 2. **Run the audit via the matching `xxx-auditor` skill.** Surface findings, severity, and concrete remediation steps.
34
+ 3. **If the required skill does not exist locally, create it first:**
35
+ - Add `.opencode/skill/<xxx-auditor>/SKILL.md`
36
+ - Mirror to `.claude/skills/<xxx-auditor>/SKILL.md` when a Claude Code counterpart is maintained
37
+ - Register the skill path in `opencode.json` if needed
38
+ - Then execute the audit using the newly created skill.
39
+
40
+ Do not skip the audit because a skill is missing; create the skill and perform the audit as part of the same session.
41
+
42
+ ## AI-Driven SDLC Regulatory Framework
43
+
44
+ This repo ships a BMad-style, subagent-based SDLC that operationalizes the AI-Driven Software Development Lifecycle (now
45
+ fully absorbed into the `sdlc-regulatory` skill). It is **always-on** via the `sdlc-gates` rule and is the default flow
46
+ for any feature/change that touches multiple modules or is medium/high risk.
47
+
48
+ ### Components
49
+
50
+ | Component | Path (opencode) | Claude mirror | Agent Skills mirror |
51
+ |-----------------------|--------------------------------------------------------------------------------------|------------------------------------------------|-------------------------------------------|
52
+ | Methodology skill | `.opencode/skill/sdlc-regulatory/SKILL.md` | `.claude/skills/sdlc-regulatory/SKILL.md` | `.agents/skills/sdlc-regulatory/SKILL.md` |
53
+ | Always-on rule | `.claude/rules/sdlc-gates.md` (also in `opencode.json` instructions) | same | `.agents/rules/sdlc-gates.md` |
54
+ | Orchestrator subagent | `.opencode/agent/sdlc-orchestrator.md` | `.claude/agents/sdlc-orchestrator.md` | `.agents/agents/sdlc-orchestrator.md` |
55
+ | Role subagents (×9) | `.opencode/agent/sdlc-{analyst,pm,architect,sm,dev,qa,security,reviewer,auditor}.md` | mirrored (Claude Code frontmatter, no `mode:`) | mirrored verbatim |
56
+ | `/sdlc` slash command | `.opencode/command/sdlc.md` | `.claude/commands/sdlc.md` | `.agents/commands/sdlc.md` |
57
+
58
+ ### SDLC chain
59
+
60
+ ```
61
+ requirement → sdlc-analyst → sdlc-pm → sdlc-architect → sdlc-sm
62
+ → sdlc-dev → sdlc-qa → sdlc-security → sdlc-reviewer → sdlc-auditor
63
+ → deploy (CI/CD, subject to the Deployment Gate)
64
+ ```
65
+
66
+ Each role owns one gate from the `sdlc-regulatory` skill. A failed gate returns work to the previous role with a
67
+ `BLOCKED` note; no gate is skipped. AI never self-validates its own work — reviewer/auditor/security are different
68
+ agents from dev. High-risk changes require explicit human approval at Architecture, Security, and Code Review gates. The
69
+ `sdlc-regulatory` skill also contains a compliance crosswalk (EU AI Act, NIST AI RMF, ISO/IEC 42001, SOC 2, GDPR) for
70
+ regulated projects.
71
+
72
+ ### When to use
73
+
74
+ - **Full `/sdlc` flow**: any change touching multiple modules, medium/high risk, or requiring traceability/compliance
75
+ artifacts.
76
+ - **Inline (main agent only)**: documentation, test generation, trivial internal refactoring (autonomy 80–100%). Still
77
+ subject to the `sdlc-gates` rule.
78
+ - **Above ~50% autonomy cap**: must use the full flow with human approvals.
79
+
80
+ See the `sdlc-regulatory` skill for the full gate checklists, risk-autonomy table, traceability format, and the
81
+ compliance crosswalk. Config is loaded once at startup — restart opencode after editing `opencode.json`, agents, skills,
82
+ plugins, or commands.
25
83
 
26
84
  ## Layout
27
85
 
@@ -33,6 +91,11 @@ agents-config/
33
91
  ├── docs/ # Project documentation
34
92
  ├── research/ # Research and investigation materials
35
93
  ├── resources/ # Project resources and assets
94
+ ├── .agents/ # Cross-client agent config (agentskills.io compatible)
95
+ │ ├── skills/ # Skill folders, each with SKILL.md
96
+ │ ├── agents/ # Subagents
97
+ │ ├── commands/ # Slash commands
98
+ │ └── rules/ # Always-loaded rule files
36
99
  ├── .claude/ # Claude Code project config
37
100
  │ ├── CLAUDE.md # Claude Code instructions (sources AGENTS.md)
38
101
  │ ├── CLAUDE.local.md # Personal overrides (gitignored)
@@ -64,30 +127,33 @@ agents-config/
64
127
 
65
128
  ## Linking
66
129
 
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
130
+ - `AGENTS.md` (root) is the single source of truth for layout and conventions. Both tools read it: Claude Code via
131
+ `.claude/CLAUDE.md`, opencode via
69
132
  `opencode.json` → `instructions` → `AGENTS.md`.
70
133
  - `.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.
134
+ `opencode.json`). It defers to the root `AGENTS.md` for shared structure and only adds opencode-only notes.
135
+ - `.claude/CLAUDE.md` is Claude Code's instructions file. It sources the root `AGENTS.md` so both tools see the same
136
+ layout.
137
+ - `.agents/` is the cross-client configuration directory compatible with the
138
+ [Agent Skills](https://agentskills.io/) convention. It is optional; existing
139
+ `.claude/` and `.opencode/` directories remain authoritative for their respective clients. The `.agents/` directory is
140
+ intended as a shared fallback so skills registered there are visible to any agent that scans the
141
+ `.agents/skills/` convention.
142
+ - Skills live in `.opencode/skill/` (or `.opencode/skills/`), `.claude/skills/`, and `.agents/skills/`. `opencode.json`
143
+ declares all three paths under
144
+ `skills.paths` so opencode auto-discovers both Claude-format and Agent-Skills skills.
78
145
  - 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.
146
+ `.claude/agents/docs.md`. Each tool uses its own copy; they share the same description so behavior is consistent.
81
147
 
82
148
  ## Adding a new component
83
149
 
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/` |
150
+ | Component | opencode path | Claude Code path | Agent Skills path |
151
+ |----------------|---------------------------------------|-------------------------------|-------------------------------|
152
+ | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
153
+ | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
154
+ | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
155
+ | Plugin | `.opencode/plugin/<n>.ts` | n/a | n/a |
156
+ | Always-on rule | add to `opencode.json` `instructions` | add to `.claude/rules/` | add to `.agents/rules/` |
91
157
 
92
158
  ## Code Generation Pipeline
93
159
 
@@ -108,9 +174,9 @@ To create an agent for code generation tasks:
108
174
  ```
109
175
 
110
176
  2. **Create supporting rules** in `.claude/rules/code-generation.md`:
111
- - Coding standards and patterns
112
- - Language-specific guidelines
113
- - Testing requirements
177
+ - Coding standards and patterns
178
+ - Language-specific guidelines
179
+ - Testing requirements
114
180
 
115
181
  3. **Add skills** in `.opencode/skill/code-gen/SKILL.md`:
116
182
  ```markdown
@@ -147,22 +213,25 @@ To create an agent for code generation tasks:
147
213
  }
148
214
  ```
149
215
 
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.
216
+ After editing `opencode.json`, an agent file, a skill, a plugin, or any other config-time file, restart opencode —
217
+ config is loaded once on startup and is not hot-reloaded.
153
218
 
154
219
  ## General Recommendations
155
220
 
156
221
  - Create a `README.md` file with deployment instructions
157
222
  - Create a `.aiignore` file to exclude files and directories from AI analysis
158
223
  - 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
224
+ - `docs/BUSINESS_LOGIC.md` - Business requirements and logic
225
+ - `docs/IMPLEMENTATION.md` - Implementation plan, status, and progress
226
+ - `docs/adr/NNNN-<slug>.md` - Architecture Decision Records
227
+
228
+ The AI-Readable Codebase contract in the `sdlc-regulatory` skill also requires root-level `ARCHITECTURE.md`,
229
+ `CONTRIBUTING.md`, and `SECURITY.md` files for any project the SDLC runs against. This repo maintains all of them.
162
230
 
163
231
  ## Architecture Approach Selection
164
232
 
165
- Before implementation, always ask the user what architecture approach to use, as the choice depends on business logic complexity. Consider these patterns:
233
+ Before implementation, always ask the user what architecture approach to use, as the choice depends on business logic
234
+ complexity. Consider these patterns:
166
235
 
167
236
  - **Clean Architecture** - Separates business logic from frameworks and I/O, promoting testability and maintainability
168
237
  - **Onion Architecture** - Layers of dependencies pointing inward toward the domain core, emphasizing domain isolation
@@ -172,25 +241,33 @@ Before implementation, always ask the user what architecture approach to use, as
172
241
  - **Microservices** - Decomposes application into loosely coupled, independently deployable services
173
242
  - **Monolithic** - Single deployable unit containing all functionality, suitable for simpler applications
174
243
 
175
- Choose the approach based on project scope, team size, scalability requirements, and business logic complexity. Document the decision in `docs/ARCHITECTURE.md`.
244
+ Choose the approach based on project scope, team size, scalability requirements, and business logic complexity. Document
245
+ the decision in an ADR under `docs/adr/` and summarize it in root `ARCHITECTURE.md`.
176
246
 
177
247
  ## Security Guidelines
178
248
 
179
249
  - Set up a vault (e.g., Hardhat vault) on your machine or repository to securely store private keys
180
250
  - Never commit sensitive information directly to the repository
181
251
  - 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.
252
+ - **LLM Security Rule**: LLMs must never commit tokens, keys, personal data, or any sensitive information to code, even
253
+ if they have permission to read such data. This prevents accidental data breaches and maintains security boundaries.
183
254
 
184
255
  ## Cross-Platform Portability
185
256
 
186
257
  To make the project portable across Node.js, Python, and Rust infrastructures:
187
258
 
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
259
+ - **Language-Agnostic Configuration**: Store environment-specific settings in `.env` files or external configuration
260
+ management systems
261
+ - **Containerization**: Use Docker and docker-compose to package applications and their dependencies for consistent
262
+ deployment across platforms
263
+ - **API-First Design**: Expose functionality through REST/gRPC APIs to enable interoperability between services written
264
+ in different languages
265
+ - **Shared Libraries**: Implement core business logic in portable formats (e.g., Protocol Buffers, JSON Schema) that can
266
+ be consumed by all target platforms
267
+ - **Infrastructure as Code**: Use tools like Terraform or CloudFormation to define infrastructure that can deploy any of
268
+ the language-specific services
269
+ - **Polyglot Persistence**: Design data access patterns that work across different database clients and ORMs for each
270
+ platform
194
271
 
195
272
  ## AI Pipeline Configuration
196
273
 
@@ -210,67 +287,68 @@ All generated code must meet production-ready standards:
210
287
  - **Deep Research First** - Conduct thorough research at the beginning of development
211
288
  - **Document Findings** - Store research results and technical decisions
212
289
  - **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
290
+ - **Comprehensive Testing** -
291
+ - Local and development environment testing required
292
+ - Minimum 80% code coverage
293
+ - Include unit tests, integration tests, and end-to-end tests
294
+ - Automated test execution as part of the development workflow
218
295
 
219
296
  ## Expert Agent Personalities
220
297
 
221
298
  Create specialized AI agents with senior-level expertise in key domains:
222
299
 
223
300
  - **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
301
+ - Web architecture and scalable systems design
302
+ - Mobile app architecture (iOS/Android)
303
+ - Embedded systems and IoT applications
304
+ - Cloud infrastructure and microservices
305
+ - Database design and optimization
306
+ - Security architecture and compliance
230
307
 
231
308
  - **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
309
+ - Frontend development (React, Vue, Angular, etc.)
310
+ - Backend development (Node.js, Python, Java, Go, etc.)
311
+ - Mobile development (React Native, Flutter, native iOS/Android)
312
+ - Embedded programming (C/C++, Rust, Arduino, etc.)
313
+ - Database technologies (SQL, NoSQL, GraphQL)
314
+ - DevOps and CI/CD pipelines
315
+ - Testing frameworks and methodologies
239
316
 
240
317
  - **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
318
+ - Infrastructure as Code (Terraform, CloudFormation)
319
+ - Containerization and orchestration (Docker, Kubernetes)
320
+ - CI/CD pipeline design and implementation
321
+ - Cloud platforms (AWS, Azure, GCP)
322
+ - Monitoring and logging solutions
323
+ - System performance optimization
324
+ - Deployment strategies and rollback procedures
248
325
 
249
326
  - **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
327
+ - Security monitoring and incident response
328
+ - Vulnerability assessment and penetration testing
329
+ - Compliance frameworks (SOC 2, ISO 27001, GDPR)
330
+ - Threat modeling and risk assessment
331
+ - Security tooling and automation
332
+ - Secure coding practices and code review
333
+ - Identity and access management
257
334
 
258
335
  - **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
336
+ - Test planning and strategy development
337
+ - Manual and automated testing methodologies
338
+ - Test case design and execution
339
+ - Bug tracking and reporting
340
+ - Performance and load testing
341
+ - API and integration testing
342
+ - Test automation frameworks (Selenium, Cypress, Jest, etc.)
343
+ - Continuous testing in CI/CD pipelines
267
344
 
268
345
  ## Documentation Maintenance
269
346
 
270
347
  At the end of each session or task, review and update relevant documentation:
271
348
 
272
349
  - **AGENTS.md** - Update if new conventions, patterns, or structures were introduced
273
- - **docs/ARCHITECTURE.md** - Document architecture decisions and changes
350
+ - **ARCHITECTURE.md** - Document architecture decisions and changes (root file; per the AI-Readable Codebase contract in
351
+ the `sdlc-regulatory` skill)
274
352
  - **docs/BUSINESS_LOGIC.md** - Record new business requirements or logic changes
275
353
  - **docs/IMPLEMENTATION.md** - Track implementation progress and status
276
354
  - **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`).