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