@daochild/agents-config 1.2.0 → 2.1.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 (116) hide show
  1. package/.agents/skills/security-audit/AI-AND-LLM.md +83 -0
  2. package/.agents/skills/security-audit/ATTACK-CLASSES.md +130 -0
  3. package/.agents/skills/security-audit/CLIENT-SIDE.md +83 -0
  4. package/.agents/skills/security-audit/CLOUD-AND-DEPLOYMENT.md +86 -0
  5. package/.agents/skills/security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
  6. package/.agents/skills/security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
  7. package/.agents/skills/security-audit/HUNTING.md +251 -0
  8. package/.agents/skills/security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -0
  9. package/.agents/skills/security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
  10. package/.agents/skills/security-audit/RECONNAISSANCE.md +156 -0
  11. package/.agents/skills/security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
  12. package/.agents/skills/security-audit/SKILL.md +192 -0
  13. package/.agents/skills/security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
  14. package/.agents/skills/security-audit/VALIDATION-AND-REPORTING.md +186 -0
  15. package/.agents/skills/security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -0
  16. package/.agents/skills/security-audit/report-schema.json +461 -0
  17. package/.agents/skills/security-audit/validate-coverage-ledger.cjs +872 -0
  18. package/.agents/skills/security-audit/validate-coverage-ledger.test.cjs +740 -0
  19. package/.agents/skills/security-audit/validate-findings.cjs +773 -0
  20. package/.agents/skills/security-audit/validate-findings.test.cjs +652 -0
  21. package/.aiignore +2 -0
  22. package/.github/copilot-instructions.md +18 -0
  23. package/AGENTS.md +39 -67
  24. package/ARCHITECTURE.md +37 -52
  25. package/CLAUDE.md +1 -0
  26. package/CONTRIBUTING.md +24 -24
  27. package/README.md +75 -3
  28. package/SECURITY.md +8 -0
  29. package/docs/BUSINESS_LOGIC.md +7 -1
  30. package/docs/IMPLEMENTATION.md +37 -13
  31. package/docs/adr/0003-document-external-skill.md +29 -0
  32. package/docs/stories/harness-engineering-assumptions.md +44 -0
  33. package/docs/stories/harness-engineering-implementation-plan.md +151 -0
  34. package/instructions/agent/docs.md +17 -0
  35. package/instructions/agent/harness-orchestrator.md +60 -0
  36. package/instructions/agent/harness-verifier.md +30 -0
  37. package/{.agents/agents → instructions/agent}/sdlc-orchestrator.md +8 -0
  38. package/instructions/command/harness.md +13 -0
  39. package/instructions/rules/harness-engineering.md +19 -0
  40. package/{.claude → instructions}/rules/sdlc-gates.md +1 -1
  41. package/instructions/skills/harness-engineering/SKILL.md +76 -0
  42. package/opencode.json +77 -19
  43. package/package.json +16 -9
  44. package/scripts/postinstall.js +1 -1
  45. package/scripts/sdlc-session-check.js +526 -0
  46. package/skills-lock.json +11 -0
  47. package/.agents/agents/.gitkeep +0 -0
  48. package/.agents/commands/.gitkeep +0 -0
  49. package/.agents/rules/.gitkeep +0 -0
  50. package/.agents/rules/sdlc-gates.md +0 -45
  51. package/.agents/skills/.gitkeep +0 -0
  52. package/.agents/skills/agents-config/SKILL.md +0 -32
  53. package/.claude/.gitkeep +0 -0
  54. package/.claude/CLAUDE.md +0 -19
  55. package/.claude/agents/.gitkeep +0 -0
  56. package/.claude/agents/docs.md +0 -15
  57. package/.claude/agents/sdlc-analyst.md +0 -29
  58. package/.claude/agents/sdlc-architect.md +0 -31
  59. package/.claude/agents/sdlc-auditor.md +0 -44
  60. package/.claude/agents/sdlc-dev.md +0 -33
  61. package/.claude/agents/sdlc-orchestrator.md +0 -69
  62. package/.claude/agents/sdlc-pm.md +0 -32
  63. package/.claude/agents/sdlc-qa.md +0 -33
  64. package/.claude/agents/sdlc-reviewer.md +0 -31
  65. package/.claude/agents/sdlc-security.md +0 -36
  66. package/.claude/agents/sdlc-sm.md +0 -31
  67. package/.claude/commands/.gitkeep +0 -0
  68. package/.claude/commands/sdlc.md +0 -18
  69. package/.claude/rules/.gitkeep +0 -0
  70. package/.claude/rules/programming-best-practices.md +0 -18
  71. package/.claude/skills/.gitkeep +0 -0
  72. package/.claude/skills/README.md +0 -3
  73. package/.claude/skills/sdlc-regulatory/SKILL.md +0 -515
  74. package/.opencode/.gitkeep +0 -0
  75. package/.opencode/AGENTS.md +0 -34
  76. package/.opencode/agent/.gitkeep +0 -0
  77. package/.opencode/agent/docs.md +0 -15
  78. package/.opencode/agent/sdlc-analyst.md +0 -30
  79. package/.opencode/agent/sdlc-architect.md +0 -32
  80. package/.opencode/agent/sdlc-auditor.md +0 -45
  81. package/.opencode/agent/sdlc-dev.md +0 -34
  82. package/.opencode/agent/sdlc-orchestrator.md +0 -70
  83. package/.opencode/agent/sdlc-pm.md +0 -33
  84. package/.opencode/agent/sdlc-qa.md +0 -34
  85. package/.opencode/agent/sdlc-reviewer.md +0 -32
  86. package/.opencode/agent/sdlc-security.md +0 -37
  87. package/.opencode/agent/sdlc-sm.md +0 -32
  88. package/.opencode/command/.gitkeep +0 -0
  89. package/.opencode/command/sdlc.md +0 -18
  90. package/.opencode/plugin/.gitkeep +0 -0
  91. package/.opencode/skill/.gitkeep +0 -0
  92. package/.opencode/skill/sdlc-regulatory/SKILL.md +0 -515
  93. package/docs/adr/0001-triple-mirror.md +0 -81
  94. package/docs/adr/0002-zero-edit-install.md +0 -237
  95. /package/{.agents → docs/adr}/.gitkeep +0 -0
  96. /package/{.agents/agents → instructions/agent}/sdlc-analyst.md +0 -0
  97. /package/{.agents/agents → instructions/agent}/sdlc-architect.md +0 -0
  98. /package/{.agents/agents → instructions/agent}/sdlc-auditor.md +0 -0
  99. /package/{.agents/agents → instructions/agent}/sdlc-dev.md +0 -0
  100. /package/{.agents/agents → instructions/agent}/sdlc-pm.md +0 -0
  101. /package/{.agents/agents → instructions/agent}/sdlc-qa.md +0 -0
  102. /package/{.agents/agents → instructions/agent}/sdlc-reviewer.md +0 -0
  103. /package/{.agents/agents → instructions/agent}/sdlc-security.md +0 -0
  104. /package/{.agents/agents → instructions/agent}/sdlc-sm.md +0 -0
  105. /package/{.agents/commands → instructions/command}/sdlc.md +0 -0
  106. /package/{.opencode/skill → instructions/skills}/archivarius/SKILL.md +0 -0
  107. /package/{.opencode/skill → instructions/skills}/data-engineer/SKILL.md +0 -0
  108. /package/{.opencode/skill → instructions/skills}/find-skills/SKILL.md +0 -0
  109. /package/{.opencode/skill → instructions/skills}/frontend-design/SKILL.md +0 -0
  110. /package/{.agents → instructions}/skills/sdlc-regulatory/SKILL.md +0 -0
  111. /package/{.opencode/skill → instructions/skills}/senior-bitcoin-auditor/SKILL.md +0 -0
  112. /package/{.opencode/skill → instructions/skills}/senior-frontend-dev/SKILL.md +0 -0
  113. /package/{.opencode/skill → instructions/skills}/senior-qa/SKILL.md +0 -0
  114. /package/{.opencode/skill → instructions/skills}/senior-software-developer/SKILL.md +0 -0
  115. /package/{.opencode/skill → instructions/skills}/senior-solidity-auditor/SKILL.md +0 -0
  116. /package/{.opencode/skill → instructions/skills}/senior-ux-ui-designer/SKILL.md +0 -0
package/AGENTS.md CHANGED
@@ -1,7 +1,14 @@
1
1
  # agents-config
2
2
 
3
- A shared configuration repository for AI coding agents. Defines how
4
- `.claude/` (Claude Code) and `.opencode/` (opencode) are organized and how they reference each other.
3
+ A shared configuration repository for AI coding agents.
4
+
5
+ ## Primary instruction
6
+
7
+ Mandatory start-of-session checklist:
8
+ 1. Read the root AGENTS.md completely.
9
+ 2. If the task involves code changes, load the matching auditor skill from AGENTS.md's Audit Rule before implementation.
10
+ 3. Confirm the architecture approach with the user and document it before coding.
11
+ 4. Do not begin implementation until steps 1–3 are satisfied.
5
12
 
6
13
  ## Behavior
7
14
 
@@ -32,7 +39,7 @@ output.
32
39
  - General architecture / system design → `senior-software-architect`
33
40
  2. **Run the audit via the matching `xxx-auditor` skill.** Surface findings, severity, and concrete remediation steps.
34
41
  3. **If the required skill does not exist locally, create it first:**
35
- - Add `.opencode/skill/<xxx-auditor>/SKILL.md`
42
+ - Add `instructions/skills/<xxx-auditor>/SKILL.md`
36
43
  - Mirror to `.claude/skills/<xxx-auditor>/SKILL.md` when a Claude Code counterpart is maintained
37
44
  - Register the skill path in `opencode.json` if needed
38
45
  - Then execute the audit using the newly created skill.
@@ -49,11 +56,11 @@ for any feature/change that touches multiple modules or is medium/high risk.
49
56
 
50
57
  | Component | Path (opencode) | Claude mirror | Agent Skills mirror |
51
58
  |-----------------------|--------------------------------------------------------------------------------------|------------------------------------------------|-------------------------------------------|
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` |
59
+ | Methodology skill | `instructions/skills/sdlc-regulatory/SKILL.md` | `.claude/skills/sdlc-regulatory/SKILL.md` | `.agents/skills/sdlc-regulatory/SKILL.md` |
60
+ | Always-on rule | `instructions/rules/sdlc-gates.md` (register in `opencode.json`) | `.claude/rules/sdlc-gates.md` | `.agents/rules/sdlc-gates.md` |
61
+ | Orchestrator subagent | `instructions/agent/sdlc-orchestrator.md` | `.claude/agents/sdlc-orchestrator.md` | `.agents/agents/sdlc-orchestrator.md` |
62
+ | Role subagents (×9) | `instructions/agent/sdlc-{analyst,pm,architect,sm,dev,qa,security,reviewer,auditor}.md` | mirrored (Claude Code frontmatter, no `mode:`) | mirrored verbatim |
63
+ | `/sdlc` slash command | `instructions/command/sdlc.md` | `.claude/commands/sdlc.md` | `.agents/commands/sdlc.md` |
57
64
 
58
65
  ### SDLC chain
59
66
 
@@ -89,77 +96,42 @@ agents-config/
89
96
  ├── opencode.json # opencode project config (schema-pinned)
90
97
  ├── LICENSE
91
98
  ├── docs/ # Project documentation
92
- ├── research/ # Research and investigation materials
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
99
- ├── .claude/ # Claude Code project config
100
- │ ├── CLAUDE.md # Claude Code instructions (sources AGENTS.md)
101
- │ ├── CLAUDE.local.md # Personal overrides (gitignored)
102
- │ ├── settings.json # Permissions + config (committed)
103
- │ ├── settings.local.json # Personal permissions (gitignored)
104
- │ ├── rules/ # Always-loaded rule files
105
- │ │ ├── code-style.md
106
- │ │ ├── testing.md
107
- │ │ └── api-conventions.md
108
- │ ├── agents/ # Subagents (Claude Code .md format)
109
- │ │ ├── code-reviewer.md
110
- │ │ └── security-auditor.md
111
- │ ├── commands/ # Slash commands
112
- │ │ ├── review.md
113
- │ │ ├── fix-issue.md
114
- │ │ └── deploy.md
115
- │ └── skills/ # Skill folders, each with SKILL.md
116
- │ ├── security-review/
117
- │ │ └── SKILL.md
118
- │ └── deploy/
119
- │ └── SKILL.md
120
- └── .opencode/ # opencode project config
121
- ├── AGENTS.md # opencode-scoped instructions (loaded via opencode.json)
122
- ├── agent/ # Subagents (opencode .md format)
123
- ├── skill/ # Skill folders, each with SKILL.md
124
- ├── command/ # Slash commands
125
- └── plugin/ # Local plugins (*.ts / *.js)
99
+ ├── instructions/ # OpenCode-facing agents, commands, rules, and skills
100
+ │ ├── agent/
101
+ │ ├── command/
102
+ │ ├── rules/
103
+ │ └── skills/
126
104
  ```
127
105
 
128
106
  ## Linking
129
107
 
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
132
- `opencode.json` → `instructions` → `AGENTS.md`.
133
- - `.opencode/AGENTS.md` is opencode-specific instructions (loaded by
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.
145
- - The example `docs` subagent exists in both `.opencode/agent/docs.md` and
146
- `.claude/agents/docs.md`. Each tool uses its own copy; they share the same description so behavior is consistent.
108
+ OpenCode-facing content is organized under `instructions/` and loaded through
109
+ `opencode.json`. Keep configured paths aligned with the actual files; create
110
+ client-specific counterparts only for clients the component must support.
147
111
 
148
112
  ## Adding a new component
149
113
 
150
114
  | Component | opencode path | Claude Code path | Agent Skills path |
151
115
  |----------------|---------------------------------------|-------------------------------|-------------------------------|
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/` |
116
+ | Subagent | `instructions/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
117
+ | Skill | `instructions/skills/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
118
+ | Slash command | `instructions/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
119
+ | Plugin | `plugin/<n>.ts` | n/a | n/a |
120
+ | Always-on rule | `instructions/rules/<n>.md`, register in `opencode.json` | `.claude/rules/<n>.md` | `.agents/rules/<n>.md` |
121
+
122
+ ## Harness engineering
123
+
124
+ The `harness-engineering` rule and skill under `instructions/` provide guidance
125
+ for reliable agent workflows. Maintain client-specific counterparts when needed. Load the skill when designing or changing agent context,
126
+ tools, permissions, approvals, verification, or telemetry. The consuming agent host—not
127
+ these configuration files—must enforce authorization, isolation, approvals, and runtime
128
+ limits.
157
129
 
158
130
  ## Code Generation Pipeline
159
131
 
160
132
  To create an agent for code generation tasks:
161
133
 
162
- 1. **Define the agent** in `.opencode/agent/code-generator.md`:
134
+ 1. **Define the agent** in `instructions/agent/code-generator.md`:
163
135
  ```markdown
164
136
  ---
165
137
  description: Generates code based on specifications and requirements
@@ -178,7 +150,7 @@ To create an agent for code generation tasks:
178
150
  - Language-specific guidelines
179
151
  - Testing requirements
180
152
 
181
- 3. **Add skills** in `.opencode/skill/code-gen/SKILL.md`:
153
+ 3. **Add skills** in `instructions/skills/code-gen/SKILL.md`:
182
154
  ```markdown
183
155
  ---
184
156
  name: code-gen
@@ -190,7 +162,7 @@ To create an agent for code generation tasks:
190
162
  When generating code, follow these steps...
191
163
  ```
192
164
 
193
- 4. **Set up commands** in `.opencode/command/generate.md`:
165
+ 4. **Set up commands** in `instructions/command/generate.md`:
194
166
  ```markdown
195
167
  ---
196
168
  description: Generate code from specifications
package/ARCHITECTURE.md CHANGED
@@ -15,54 +15,15 @@ Published to npm as `@daochild/agents-config` and intended to be installed as a
15
15
  point their `AGENTS.md` at
16
16
  `node_modules/@daochild/agents-config/AGENTS.md` to inherit this repo's conventions.
17
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
18
  ## Architectural rules
56
19
 
57
20
  1. **`AGENTS.md` is the single source of truth.** Both opencode (via `opencode.json`
58
21
  → `instructions`) and Claude Code (via `.claude/CLAUDE.md` → `@AGENTS.md`) read it. Never duplicate layout/convention
59
22
  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).
23
+ 2. **Shared instruction sources.** OpenCode-facing agents, commands, rules, and skills are organized under
24
+ `instructions/{agent,command,rules,skills}/` and registered through `opencode.json`. Add `.claude/` and `.agents/`
25
+ counterparts for clients that need them, following the per-format differences in `AGENTS.md` (for example, Claude
26
+ Code subagents omit the `mode:` frontmatter field). Keep the source and any maintained counterparts synchronized.
66
27
  3. **Skills are the methodology layer; subagents are thin.** Subagent `.md` files hold the role description,
67
28
  responsibilities, and handoff protocol. Deep methodology (gate checklists, risk tables, compliance crosswalks) lives
68
29
  in skills (`<n>/SKILL.md`) so it can be loaded by any agent or reviewer.
@@ -73,7 +34,7 @@ agents-config (this repo)
73
34
  restart opencode. No hot reload.
74
35
  6. **No runtime *application* code.** This repo's "code" is configuration. The only JS is the
75
36
  opencode plugin host (`@opencode-ai/plugin` dependency), any
76
- `.opencode/plugin/*.ts|.js` the user adds, **and one constrained install-time file-pointer
37
+ `plugin/*.ts|.js` the user adds, **and one constrained install-time file-pointer
77
38
  helper (`scripts/postinstall.js`) permitted by [ADR 0002](docs/adr/0002-zero-edit-install.md)**.
78
39
  There is no `src/`, no build output, no deployable service, no long-running process. (Rule 6
79
40
  narrowed by ADR 0002 from "No runtime code" to "No runtime *application* code"; a single
@@ -81,24 +42,46 @@ agents-config (this repo)
81
42
 
82
43
  ## Key decisions
83
44
 
45
+ - **Dedicated harness flow (2026-10-27).** The user selected KISS: a thin
46
+ `harness-orchestrator` coordinates context, policy, execution, independent verification,
47
+ and feedback using the existing harness skill. A separate read-only `harness-verifier`
48
+ checks outcomes; neither role grants authority or replaces SDLC gates. The change is
49
+ medium risk with a 70% autonomy cap; human review and deployment remain pending.
50
+ Traceability id: `dedicated-harness-flow`.
51
+ - **Client loading and dispatch.** Use the discoverable `opencode.json` filename
52
+ (formerly `opencode.jsonp`) and explicitly register commands stored under
53
+ `instructions/command/`. Other hosts must load role instructions into supported
54
+ subagents; OpenCode configuration does not register named Copilot agent types.
55
+ Missing dispatch capability is a host limitation, not a failed engineering gate.
56
+ `experimental.subagent_depth: 3` permits the finite harness -> SDLC -> role
57
+ chain; the default single level would block it. The harness coordinator denies
58
+ direct side effects and restricts delegation; the verifier is read-only.
59
+ The nesting setting requires a compatible OpenCode version and live validation.
84
60
  - **Schema-pinned config.** `opencode.json` declares
85
61
  `"$schema": "https://opencode.ai/config.json"` for editor IntelliSense and validation against the opencode config
86
62
  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.
63
+ - **Client-specific frontmatter.** OpenCode agent files use `mode: subagent` (and optional `permission`). Claude Code
64
+ agent files omit `mode:`. `.agents/` counterparts retain OpenCode frontmatter.
65
+ - **Explicit skill discovery.** `opencode.json` lists `instructions/skills`; keep this path aligned with the actual
66
+ skill source directory when changing the layout.
67
+ - **External skill provenance.** The imported `security-audit` Agent Skill lives under
68
+ `.agents/skills/security-audit/`; `skills-lock.json` records its upstream source and computed hash. Keep it
69
+ documented separately from OpenCode's `instructions/skills` discovery path. See
70
+ [ADR 0003](docs/adr/0003-document-external-skill.md).
93
71
  - **SDLC regulatory framework.** The `sdlc-*` subagents + `sdlc-regulatory` skill +
94
72
  `sdlc-gates` rule implement the AI-Driven SDLC. The skill is the source of truth for the methodology (it superseded
95
73
  the deleted `SOW.md`). The orchestrator is the single entry point via the `/sdlc` command.
74
+ - **Harness engineering guidance.** The `harness-engineering` skill and always-on rule are
75
+ stored under `instructions/` for OpenCode and mirrored for other clients when needed. They describe context selection,
76
+ host-enforced policy, bounded execution, independent verification, and privacy-aware
77
+ observability. They are guidance only; consuming runtimes enforce permissions, approvals,
78
+ isolation, and execution limits.
96
79
 
97
80
  ## What must NOT be changed without human approval
98
81
 
99
82
  - `AGENTS.md` — layout and linking model (any change breaks both tools).
100
83
  - `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).
84
+ - The instruction-source layout and any maintained client counterparts; removing a counterpart can break that client.
102
85
  - The `sdlc-regulatory` skill's gate checklists and risk-autonomy table (these are the control surface; relaxing them is
103
86
  a high-risk change per the skill's own risk model).
104
87
  - **The `postinstall` script's contract (per [ADR 0002](docs/adr/0002-zero-edit-install.md))**:
@@ -140,4 +123,6 @@ agents-config (this repo)
140
123
  - `CONTRIBUTING.md` — how to add agents/skills/commands/rules.
141
124
  - `SECURITY.md` — security policy and the LLM security rule.
142
125
  - `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).
126
+ - `instructions/skills/sdlc-regulatory/SKILL.md` — AI-Driven SDLC methodology (source of truth for the SDLC controls).
127
+ - `instructions/skills/harness-engineering/SKILL.md` — shared agent reliability guidance; runtime enforcement remains the consuming host's responsibility.
128
+ - `docs/adr/0003-document-external-skill.md` — documents the source and discovery boundary for externally sourced skills.
package/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
package/CONTRIBUTING.md CHANGED
@@ -9,55 +9,55 @@ files** (agents, skills, commands, rules, plugins), not runtime code.
9
9
  ## Before you start
10
10
 
11
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.
12
+ 2. Read `ARCHITECTURE.md` — explains the instruction-source layout and what must not be changed without approval.
13
13
  3. Read `SECURITY.md` — the LLM security rule applies to every change.
14
14
  4. If your change touches the SDLC, load the `sdlc-regulatory` skill; if it is medium/high risk or spans multiple
15
15
  components, run it through `/sdlc`.
16
16
 
17
- ## Adding a component (the triple-mirror rule)
17
+ ## Adding a component
18
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.
19
+ Add OpenCode-facing components under `instructions/` and register them in `opencode.json` where required. When a
20
+ component must also work in Claude Code or Agent-Skills-compatible clients, maintain the corresponding mirrors listed
21
+ below. Do not assume a mirror directory exists; create the required target and keep its format consistent with that
22
+ client.
21
23
 
22
24
  | Component | opencode path | Claude Code path | Agent Skills path |
23
25
  |----------------|---------------------------------------|-------------------------------|-------------------------------|
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/` |
26
+ | Subagent | `instructions/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
27
+ | Skill | `instructions/skills/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
28
+ | Slash command | `instructions/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
29
+ | Plugin | `plugin/<n>.ts` | n/a | n/a |
30
+ | Always-on rule | `instructions/rules/<n>.md` | `.claude/rules/<n>.md` | `.agents/rules/<n>.md` |
29
31
 
30
32
  ### Format differences
31
33
 
32
34
  - **opencode subagent frontmatter** uses `mode: subagent` (and optional `permission`).
33
35
  - **Claude Code subagent frontmatter** omits the `mode:` field.
34
- - **`.agents/` mirrors** keep the opencode frontmatter verbatim.
36
+ - **`.agents/` mirrors** keep the OpenCode frontmatter verbatim.
35
37
  - **Skills** use the same `SKILL.md` format in all three locations.
36
38
 
37
39
  ## Workflow
38
40
 
39
41
  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/`.
42
+ 2. Make the OpenCode-facing change under `instructions/`.
43
+ 3. Add or update the `.claude/` counterpart (apply format differences above) and `.agents/` counterpart (verbatim) when those clients are in scope.
44
+ 4. If you added/changed an always-on rule, register its actual path in `opencode.json` `instructions` and add the file to `.claude/rules/` and `.agents/rules/` when those clients are in scope.
44
45
  5. If you added a subagent, register it under `agent` in `opencode.json` with a
45
- `prompt: "{file:./.opencode/agent/<n>.md}"` entry.
46
+ `prompt: "{file:./instructions/agent/<n>.md}"` entry.
46
47
  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
+ 7. Verify any maintained mirrors before committing (see the examples below).
48
49
 
49
50
  ## Verifying mirror consistency
50
51
 
51
- Before committing, confirm the three mirrors are consistent:
52
+ Before committing, confirm each maintained counterpart is consistent with the source:
52
53
 
53
54
  ```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
55
+ # .agents keeps OpenCode frontmatter; Claude Code subagents omit mode: subagent
56
+ diff -q instructions/agent/<n>.md .agents/agents/<n>.md
57
+ diff <(grep -v '^mode: subagent$' instructions/agent/<n>.md) .claude/agents/<n>.md
58
+ # skills share the same content
59
+ diff -q instructions/skills/<n>/SKILL.md .claude/skills/<n>/SKILL.md
60
+ diff -q instructions/skills/<n>/SKILL.md .agents/skills/<n>/SKILL.md
61
61
  ```
62
62
 
63
63
  ## Commit conventions
package/README.md CHANGED
@@ -7,9 +7,10 @@ The package is intended for production‑grade automation: version control, CI/C
7
7
  ## What's in the box
8
8
 
9
9
  - **Shared layout & conventions** — `AGENTS.md` is the single source of truth, inherited (not copied) by consuming projects.
10
- - **Triple-mirror model** — every subagent / skill / command / rule is mirrored across `.opencode/`, `.claude/`, and `.agents/` so it works in opencode, Claude Code, and any Agent-Skills-compatible client (see ADR 0001).
10
+ - **Shared instruction sources** — OpenCode-facing agents, commands, rules, and skills are organized under `instructions/`; `opencode.json` declares the paths used by OpenCode. Keep configured paths aligned with the files and maintain Claude Code or Agent Skills counterparts when required; see `AGENTS.md` and `CONTRIBUTING.md`.
11
11
  - **AI-Driven SDLC framework** — `sdlc-regulatory` skill + 10 `sdlc-*` subagents + `sdlc-gates` rule + `/sdlc` command. Gates run in order (requirement → architecture → implementation → testing → security → review → deployment → DoD), AI never self-validates, high-risk changes require human approval, and a compliance crosswalk covers EU AI Act / NIST AI RMF / ISO 42001 / SOC 2 / GDPR.
12
12
  - **Domain skills** — `senior-qa`, `senior-solidity-auditor`, `senior-bitcoin-auditor`, `senior-frontend-dev`, `senior-software-developer`, `senior-ux-ui-designer`, `archivarius`, `data-engineer`, `find-skills`, `frontend-design`.
13
+ - **Externally sourced skill** — `security-audit` is maintained at `.agents/skills/security-audit/` and sourced from `cloudflare/security-audit-skill`. Its source and computed hash are recorded in `skills-lock.json`. It follows the Agent Skills layout and is separate from OpenCode's `instructions/skills` discovery path.
13
14
  - **Always-on rules** — `programming-best-practices` and `sdlc-gates`.
14
15
  - **AI-readable contract** — `ARCHITECTURE.md`, `CONTRIBUTING.md`, `SECURITY.md`, `docs/` (business logic, implementation status, ADRs).
15
16
 
@@ -38,7 +39,7 @@ always exits `0` so it can never break your install. It only writes when
38
39
  The line it writes is:
39
40
 
40
41
  ```markdown
41
- Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.
42
+ Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — read in full and follow unless overridden below.
42
43
  ```
43
44
 
44
45
  If your project has no `AGENTS.md`, the script prints a notice and exits `0`
@@ -64,7 +65,7 @@ line at the top of your project's `AGENTS.md`, immediately after the title, so
64
65
  the agent inherits this package as its primary instructions source:
65
66
 
66
67
  ```markdown
67
- Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — follow unless overridden below.
68
+ Primary instructions: node_modules/@daochild/agents-config/AGENTS.md — read in full and follow unless overridden below.
68
69
  ```
69
70
 
70
71
  This manual path is the supported fallback and is runnable without the
@@ -75,6 +76,77 @@ This manual path is the supported fallback and is runnable without the
75
76
  Restart your agent session (opencode or Claude Code) so the new instructions
76
77
  take effect — config is loaded once at startup and is not hot-reloaded.
77
78
 
79
+ ## Read-only SDLC session diagnostic
80
+
81
+ ### Agent flows and loading
82
+
83
+ OpenCode loads the root `opencode.json` (previously misnamed `opencode.jsonp`).
84
+ Restart OpenCode after configuration changes. `/sdlc <requirement>` and
85
+ `/harness <task>` are explicitly registered there because `instructions/command/`
86
+ is not an automatically discovered command directory.
87
+ The configuration sets `experimental.subagent_depth` to 3 for the bounded
88
+ harness -> SDLC orchestrator -> role chain. The current schema defaults to one
89
+ level, which prevents subagent orchestrators from dispatching their children.
90
+ This setting is version-sensitive; use an OpenCode release supporting it.
91
+
92
+ `/harness` runs context -> policy -> execution -> independent verification ->
93
+ feedback. It uses the existing harness skill, delegates implementation through
94
+ the SDLC when required, and uses a separate read-only `harness-verifier`.
95
+ The consuming host must enforce permissions, approvals, isolation, and finite
96
+ execution budgets; configuration prose alone cannot provide these controls.
97
+ The harness coordinator denies direct execution and delegates only to `general`,
98
+ `sdlc-orchestrator`, and `harness-verifier`; the verifier denies execution and
99
+ delegation. These OpenCode permissions do not configure other agent hosts.
100
+
101
+ **If SDLC is blocked:** distinguish host capability from gate failure.
102
+ OpenCode agent registrations do not create named agent types in Copilot or
103
+ other hosts. Where supported, dispatch a general-purpose subagent with the
104
+ appropriate `instructions/agent/sdlc-<role>.md` instructions and keep developer,
105
+ security reviewer, reviewer, and auditor in distinct contexts. If the host
106
+ cannot dispatch independent agents, request human review instead of claiming
107
+ a gate passed. Missing approvals remain pending; missing deployment evidence
108
+ prevents production/DoD sign-off, not earlier authorized local work.
109
+
110
+ `npm run sdlc:check` intentionally denies subagents and shell commands. It checks
111
+ a read-only response, not the full SDLC flow; do not use it to prove role dispatch.
112
+
113
+ ### Running the diagnostic
114
+
115
+ Run a small documentation-analysis task through OpenCode and check whether the
116
+ response addresses the SDLC gates without changing the repository:
117
+
118
+ ```bash
119
+ npm run sdlc:check
120
+ # Optional: select another configured model, including a provider's free model
121
+ npm run sdlc:check -- --model provider/model
122
+ ```
123
+
124
+ The default model candidate is `opencode/beam-free`; model availability and
125
+ provider requirements can change, so use `--model` for a currently available
126
+ free model. OpenCode CLI and an authenticated provider are required.
127
+
128
+ The runner injects explicit read-only OpenCode permissions, denies shell and
129
+ subagent access, and hashes repository files before and after the session
130
+ (including ignored files, excluding `.git`). It writes one private
131
+ session directory under `~/.local/state/agents-config/sdlc-session-checks/`
132
+ containing `events.jsonl` and `summary.json`. These logs contain tool names,
133
+ statuses, observed SDLC subagents, and gate-mention checks only; they do not
134
+ store the prompt, response, tool arguments, or tool outputs. OpenCode itself
135
+ may retain its normal session history according to its own configuration.
136
+
137
+ `Assessment: PASS` means the diagnostic task completed, no file-write tool or
138
+ other disallowed tool was attempted, repository contents stayed unchanged, and
139
+ the response reported a risk classification plus a status for every gate. A
140
+ blocked shell attempt still makes the assessment fail, but the file snapshot
141
+ shows whether anything changed. This is a read-only smoke check, not proof that
142
+ an agent obeys policy in every session or that a gate was actually
143
+ approved/passed. The permission policy governs OpenCode tool calls, not
144
+ arbitrary side effects from external plugins or host processes; use an
145
+ OS-level read-only sandbox when those must be excluded as well. Run tests
146
+ without OpenCode using `npm test`. Gate labels/statuses and risk classification
147
+ are heuristic checks of the response, not independent validation that its
148
+ claims are accurate or that the underlying gates passed.
149
+
78
150
  ## License
79
151
 
80
152
  MIT
package/SECURITY.md CHANGED
@@ -54,6 +54,13 @@ Security concerns are therefore primarily:
54
54
  pinned and monitor advisories.
55
55
  - **Permission overreach** in `opencode.json` agent `permission` blocks — prefer
56
56
  `ask` over `allow` for `edit` and `bash` on any agent that touches production.
57
+ - **Model-only policy enforcement** — prompts and skills do not authorize actions or
58
+ isolate tools. The consuming host must check identity, scope, and arguments at each
59
+ side-effect boundary, fail closed when authorization is unclear, and pause for required
60
+ human approval.
61
+ - **Sensitive observability data** — agent traces can contain secrets or personal data.
62
+ Record only operational fields needed for diagnosis; redact sensitive values and apply
63
+ access and retention controls. Do not log private model reasoning by default.
57
64
  - **SDLC gate bypass** — any change that weakens a gate, removes a reviewer, or
58
65
  raises an autonomy cap is a high-risk security change requiring human approval.
59
66
 
@@ -75,5 +82,6 @@ lists. This policy does not replace legal review.
75
82
 
76
83
  - `AGENTS.md` → "Security Guidelines"
77
84
  - `sdlc-regulatory` skill → Security Gate checklist + compliance crosswalk
85
+ - `instructions/skills/harness-engineering/SKILL.md` → harness design guidance and host/runtime boundary
78
86
  - `CONTRIBUTING.md` → SDLC changes are high-risk
79
87
  - `.gitignore`, `.npmignore` — what is excluded from repo and package
@@ -25,7 +25,7 @@ configuration source** so that:
25
25
  | ID | Requirement | Status |
26
26
  |------|---------------------------------------------------------|--------------------------------------------------------------------------------------|
27
27
  | BR-1 | Single source of truth for agent layout and conventions | Met by `AGENTS.md` |
28
- | BR-2 | Works in both opencode and Claude Code from one config | Met by triple-mirror model |
28
+ | BR-2 | Works in both opencode and Claude Code from one config | Met by shared instruction sources and client-specific counterparts |
29
29
  | BR-3 | Skills are loadable expertise, reusable across agents | Met by `skills.paths` union in `opencode.json` |
30
30
  | BR-4 | SDLC gates are always-on, not opt-in | Met by `sdlc-gates` rule in `opencode.json` instructions + `.claude/rules/` |
31
31
  | BR-5 | AI never self-validates its own work | Met by separate `sdlc-reviewer` / `sdlc-security` / `sdlc-auditor` agents |
@@ -47,6 +47,12 @@ configuration source** so that:
47
47
 
48
48
  ## Scope of the SDLC framework
49
49
 
50
+ The dedicated `/harness` flow coordinates context, host policy, bounded execution,
51
+ independent verification, and feedback. It reuses the harness methodology and
52
+ routes applicable implementation work through SDLC rather than replacing its
53
+ gates. OpenCode must discover the root configuration and registered commands;
54
+ other clients must map role instructions to their own supported dispatch tools.
55
+
50
56
  The `sdlc-regulatory` skill + `sdlc-*` subagents + `sdlc-gates` rule implement the AI-Driven Software Development
51
57
  Lifecycle. The original specification lived in
52
58
  `SOW.md` and has been **fully absorbed into the `sdlc-regulatory` skill** (the skill header records that it supersedes