@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.
- package/.agents/.gitkeep +0 -0
- package/.agents/agents/.gitkeep +0 -0
- package/.agents/agents/sdlc-analyst.md +30 -0
- package/.agents/agents/sdlc-architect.md +32 -0
- package/.agents/agents/sdlc-auditor.md +45 -0
- package/.agents/agents/sdlc-dev.md +34 -0
- package/.agents/agents/sdlc-orchestrator.md +70 -0
- package/.agents/agents/sdlc-pm.md +33 -0
- package/.agents/agents/sdlc-qa.md +34 -0
- package/.agents/agents/sdlc-reviewer.md +32 -0
- package/.agents/agents/sdlc-security.md +37 -0
- package/.agents/agents/sdlc-sm.md +32 -0
- package/.agents/commands/.gitkeep +0 -0
- package/.agents/commands/sdlc.md +18 -0
- package/.agents/rules/.gitkeep +0 -0
- package/.agents/rules/sdlc-gates.md +45 -0
- package/.agents/skills/.gitkeep +0 -0
- package/.agents/skills/agents-config/SKILL.md +32 -0
- package/.agents/skills/sdlc-regulatory/SKILL.md +515 -0
- package/.claude/agents/sdlc-analyst.md +29 -0
- package/.claude/agents/sdlc-architect.md +31 -0
- package/.claude/agents/sdlc-auditor.md +44 -0
- package/.claude/agents/sdlc-dev.md +33 -0
- package/.claude/agents/sdlc-orchestrator.md +69 -0
- package/.claude/agents/sdlc-pm.md +32 -0
- package/.claude/agents/sdlc-qa.md +33 -0
- package/.claude/agents/sdlc-reviewer.md +31 -0
- package/.claude/agents/sdlc-security.md +36 -0
- package/.claude/agents/sdlc-sm.md +31 -0
- package/.claude/commands/sdlc.md +18 -0
- package/.claude/rules/sdlc-gates.md +45 -0
- package/.claude/skills/sdlc-regulatory/SKILL.md +515 -0
- package/.opencode/AGENTS.md +11 -0
- package/.opencode/agent/sdlc-analyst.md +30 -0
- package/.opencode/agent/sdlc-architect.md +32 -0
- package/.opencode/agent/sdlc-auditor.md +45 -0
- package/.opencode/agent/sdlc-dev.md +34 -0
- package/.opencode/agent/sdlc-orchestrator.md +70 -0
- package/.opencode/agent/sdlc-pm.md +33 -0
- package/.opencode/agent/sdlc-qa.md +34 -0
- package/.opencode/agent/sdlc-reviewer.md +32 -0
- package/.opencode/agent/sdlc-security.md +37 -0
- package/.opencode/agent/sdlc-sm.md +32 -0
- package/.opencode/command/sdlc.md +18 -0
- package/.opencode/skill/sdlc-regulatory/SKILL.md +515 -0
- package/AGENTS.md +164 -86
- package/ARCHITECTURE.md +143 -0
- package/CONTRIBUTING.md +90 -0
- package/README.md +53 -24
- package/SECURITY.md +79 -0
- package/docs/BUSINESS_LOGIC.md +63 -0
- package/docs/IMPLEMENTATION.md +59 -0
- package/docs/adr/0001-triple-mirror.md +81 -0
- package/docs/adr/0002-zero-edit-install.md +237 -0
- package/docs/api/.gitkeep +0 -0
- package/docs/architecture/.gitkeep +0 -0
- package/docs/architecture/zero-edit-install-architecture.md +306 -0
- package/docs/business/zero-edit-install-analysis.md +295 -0
- package/docs/business/zero-edit-install-prd.md +404 -0
- package/docs/database/.gitkeep +0 -0
- package/docs/stories/zero-edit-install-assumptions.md +80 -0
- package/docs/stories/zero-edit-install-stories.md +256 -0
- package/opencode.json +54 -2
- package/package.json +14 -4
- 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
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
`.claude
|
|
77
|
-
|
|
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
|
|
85
|
-
|
|
86
|
-
| Subagent
|
|
87
|
-
| Skill
|
|
88
|
-
| Slash command
|
|
89
|
-
| Plugin
|
|
90
|
-
| Always-on rule
|
|
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
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
-
|
|
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
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
189
|
-
|
|
190
|
-
- **
|
|
191
|
-
|
|
192
|
-
- **
|
|
193
|
-
|
|
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
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
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
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
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
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
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
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
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
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
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
|
-
- **
|
|
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
|
package/ARCHITECTURE.md
ADDED
|
@@ -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).
|
package/CONTRIBUTING.md
ADDED
|
@@ -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`).
|