development-companion 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +229 -2
- package/RELEASE.md +107 -0
- package/adapters/README.md +113 -0
- package/adapters/claude-code/README.md +81 -0
- package/adapters/claude-code/adapter.json +10 -0
- package/adapters/cline/adapter.json +9 -0
- package/adapters/codex/README.md +80 -0
- package/adapters/codex/adapter.json +9 -0
- package/adapters/copilot-cli/adapter.json +9 -0
- package/adapters/cursor/adapter.json +9 -0
- package/adapters/gemini-cli/adapter.json +9 -0
- package/adapters/generic/adapter.json +9 -0
- package/adapters/opencode/README.md +89 -0
- package/adapters/opencode/adapter.json +9 -0
- package/adapters/pi/README.md +83 -0
- package/adapters/pi/adapter.json +9 -0
- package/adapters/windsurf/adapter.json +9 -0
- package/bin/devcomp.mjs +8 -0
- package/core/guidelines/backend.md +103 -0
- package/core/guidelines/collaboration.md +78 -0
- package/core/guidelines/frontend.md +106 -0
- package/core/guidelines/security.md +90 -0
- package/core/guidelines/testing.md +90 -0
- package/core/principles.md +208 -0
- package/core/process.md +224 -0
- package/core/quality-gates.md +192 -0
- package/core/roles/README.md +55 -0
- package/core/roles/architect.md +75 -0
- package/core/roles/backend-engineer.md +74 -0
- package/core/roles/cybersecurity-engineer.md +55 -0
- package/core/roles/desktop-linux-engineer.md +50 -0
- package/core/roles/desktop-macos-engineer.md +50 -0
- package/core/roles/desktop-windows-engineer.md +50 -0
- package/core/roles/frontend-engineer.md +72 -0
- package/core/roles/mobile-engineer.md +50 -0
- package/core/roles/multiplatform-engineer.md +49 -0
- package/core/roles/orchestrator.md +69 -0
- package/core/roles/qa-engineer.md +69 -0
- package/core/roles/reviewer.md +77 -0
- package/core/roles/sre-engineer.md +51 -0
- package/core/roles/team-lead.md +67 -0
- package/core/workflow.md +169 -0
- package/package.json +53 -4
- package/skills/architecture-design/SKILL.md +116 -0
- package/skills/backend-development/SKILL.md +127 -0
- package/skills/code-review/SKILL.md +144 -0
- package/skills/delivery-orchestration/SKILL.md +119 -0
- package/skills/deployment-sre/SKILL.md +111 -0
- package/skills/desktop-development/SKILL.md +51 -0
- package/skills/development-workflow/SKILL.md +158 -0
- package/skills/frontend-development/SKILL.md +136 -0
- package/skills/linux-development/SKILL.md +44 -0
- package/skills/macos-development/SKILL.md +45 -0
- package/skills/mobile-development/SKILL.md +60 -0
- package/skills/multiplatform-development/SKILL.md +45 -0
- package/skills/project-discovery/SKILL.md +122 -0
- package/skills/security-review/SKILL.md +109 -0
- package/skills/test-strategy/SKILL.md +109 -0
- package/skills/ux-design/SKILL.md +108 -0
- package/skills/windows-development/SKILL.md +45 -0
- package/src/args.mjs +42 -0
- package/src/cli.mjs +449 -0
- package/src/content.mjs +72 -0
- package/src/detect.mjs +119 -0
- package/src/install.mjs +186 -0
- package/src/prompt.mjs +35 -0
- package/src/rules.mjs +83 -0
- package/src/scaffold.mjs +433 -0
- package/templates/artifacts/01-operational-brief.md +37 -0
- package/templates/artifacts/02-architecture.md +33 -0
- package/templates/artifacts/03-threat-model.md +29 -0
- package/templates/artifacts/04-test-plan.md +35 -0
- package/templates/artifacts/05-ux-spec.md +31 -0
- package/templates/artifacts/06-delivery-plan.md +29 -0
- package/templates/artifacts/07-security-report.md +25 -0
- package/templates/artifacts/08-qa-report.md +32 -0
- package/templates/artifacts/09-runbook.md +43 -0
- package/templates/artifacts/10-closure.md +25 -0
- package/templates/artifacts/README.md +17 -0
- package/templates/rules/AGENTS.block.md +36 -0
- package/templates/rules/CLAUDE.block.md +3 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Eduardo Grendi Molina
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,230 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Development Companion
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
One installable development process for AI coding agents: **12 roles**, **17 skills**, and
|
|
4
|
+
a CLI that adapts the same canonical base to OpenCode, Claude Code, Codex, Pi, and other
|
|
5
|
+
harnesses.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx development-companion@latest init
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
`devcomp init` detects the repository and harness, installs the process, and leaves your
|
|
12
|
+
existing `AGENTS.md` and `CLAUDE.md` intact unless you choose otherwise.
|
|
13
|
+
|
|
14
|
+
## Why
|
|
15
|
+
|
|
16
|
+
Coding agents are powerful but inconsistent. Each harness has its own rules file, skill
|
|
17
|
+
format, and subagent mechanism. Copying prompts between them creates drift: one harness
|
|
18
|
+
gets the latest review checklist, another keeps an outdated one.
|
|
19
|
+
|
|
20
|
+
Development Companion separates the process from the harness:
|
|
21
|
+
|
|
22
|
+
| Layer | Responsibility |
|
|
23
|
+
|---|---|
|
|
24
|
+
| **Process** | Discovery, architecture, security, QA, UX, delivery, deployment, closure. |
|
|
25
|
+
| **Roles** | Who decides, who delivers, and who verifies. |
|
|
26
|
+
| **Skills** | How each discipline is executed, with evidence. |
|
|
27
|
+
| **CLI** | Detects, installs, adapts, and diagnoses. |
|
|
28
|
+
|
|
29
|
+
The same canonical content is installed everywhere. Adapters only translate paths and
|
|
30
|
+
formats.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
### New or existing repository
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx development-companion@latest init
|
|
38
|
+
# or
|
|
39
|
+
npm create development-companion@latest
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Useful flags:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npx development-companion init . \
|
|
46
|
+
--harness opencode \
|
|
47
|
+
--profile web \
|
|
48
|
+
--rules append \
|
|
49
|
+
--branching trunk-based \
|
|
50
|
+
--docs local \
|
|
51
|
+
--memory engram
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
| Flag | Effect |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `--harness <name>` | Force the adapter; `auto` detects it. |
|
|
57
|
+
| `--profile <name>` | `web`, `backend`, `mobile`, `desktop`, `cross-platform`, `full`. |
|
|
58
|
+
| `--skills <a,b>` | Add specific skills. |
|
|
59
|
+
| `--rules keep\|append\|replace` | Policy for existing `AGENTS.md`/`CLAUDE.md`. |
|
|
60
|
+
| `--branching <name>` | `gitflow`, `gitlab-flow`, `trunk-based`, `github-flow`, `custom`. |
|
|
61
|
+
| `--docs local\|tracked` | Keep design docs local or version them in `docs/companion/`. |
|
|
62
|
+
| `--memory engram\|none` | Recommend Engram for cross-session memory. |
|
|
63
|
+
| `--mode copy\|symlink` | How skills are installed. |
|
|
64
|
+
| `--dry-run` | Print the plan without writing. |
|
|
65
|
+
| `--yes` | Non-interactive; rules default to `keep`. |
|
|
66
|
+
|
|
67
|
+
### Rules are never overwritten silently
|
|
68
|
+
|
|
69
|
+
If `AGENTS.md` or `CLAUDE.md` already exists, the CLI asks:
|
|
70
|
+
|
|
71
|
+
- **keep** — leave the file untouched;
|
|
72
|
+
- **append** — add a managed block, preserving your rules;
|
|
73
|
+
- **replace** — replace the file, with explicit confirmation.
|
|
74
|
+
|
|
75
|
+
The managed block is delimited by `<!-- development-companion:start -->` and
|
|
76
|
+
`<!-- development-companion:end -->`, so updates are idempotent.
|
|
77
|
+
|
|
78
|
+
### Commands
|
|
79
|
+
|
|
80
|
+
| Command | Purpose |
|
|
81
|
+
|---|---|
|
|
82
|
+
| `devcomp init [dir]` | Install the process, skills, roles, rules, and manifest. |
|
|
83
|
+
| `devcomp add <skill\|role\|profile> <name>` | Add content to an existing install. |
|
|
84
|
+
| `devcomp scaffold [dir]` | Generate the TypeScript reference monorepo. |
|
|
85
|
+
| `devcomp doctor [dir]` | Check skills, roles, rules, branching, and Engram. |
|
|
86
|
+
| `devcomp update [dir]` | Refresh installed content without overwriting local edits. |
|
|
87
|
+
|
|
88
|
+
## The process
|
|
89
|
+
|
|
90
|
+
For a new project or a major change:
|
|
91
|
+
|
|
92
|
+
```text
|
|
93
|
+
0 Bootstrap
|
|
94
|
+
→ 1 Operational discovery (Team Lead)
|
|
95
|
+
→ 2 Architecture + security (Architect ∥ Cybersecurity)
|
|
96
|
+
→ 3 Test strategy (QA)
|
|
97
|
+
→ 4 UX/UI (Frontend)
|
|
98
|
+
→ 5 Delivery plan (Team Lead)
|
|
99
|
+
→ 6 Implementation (specialists)
|
|
100
|
+
→ 7 Security verification (Cybersecurity)
|
|
101
|
+
→ 8 QA verification (QA)
|
|
102
|
+
→ 9 Deployment (SRE)
|
|
103
|
+
→ 10 Closure (Team Lead)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Each phase has an owner, an artifact in `.companion/local/`, and a gate with evidence.
|
|
107
|
+
For a small change, the process collapses to the workflow in `core/workflow.md`.
|
|
108
|
+
|
|
109
|
+
Read `core/process.md` for the full phase guide.
|
|
110
|
+
|
|
111
|
+
## Roles
|
|
112
|
+
|
|
113
|
+
| Role | Primary question |
|
|
114
|
+
|---|---|
|
|
115
|
+
| Team Lead | What is the shortest path to a verified delivery? |
|
|
116
|
+
| Architect | What boundaries and trade-offs make this correct and evolvable? |
|
|
117
|
+
| Cybersecurity Engineer | What can be attacked, and what evidence proves the control works? |
|
|
118
|
+
| QA Engineer | How could this fail, and what proves it does not? |
|
|
119
|
+
| Frontend Engineer | Is the interface accessible, fast, and maintainable? |
|
|
120
|
+
| Backend Engineer | Are the API, data, and failure modes correct and secure? |
|
|
121
|
+
| Mobile Engineer | Does it respect the device, store, and offline reality? |
|
|
122
|
+
| Desktop Windows Engineer | Does it install, integrate, and update natively on Windows? |
|
|
123
|
+
| Desktop macOS Engineer | Is it sandboxed, signed, and notarized correctly? |
|
|
124
|
+
| Desktop Linux Engineer | Does it respect distributions, Wayland/X11, and packaging? |
|
|
125
|
+
| Multiplatform Engineer | Is the core shared and the edge adapted per platform? |
|
|
126
|
+
| SRE Engineer | Is it deployed, observable, and recoverable? |
|
|
127
|
+
|
|
128
|
+
Role contracts live in `core/roles/`. The CLI installs them to `.companion/roles/` and
|
|
129
|
+
generates native bindings where the harness supports subagents.
|
|
130
|
+
|
|
131
|
+
## Skills and profiles
|
|
132
|
+
|
|
133
|
+
Process skills are installed always:
|
|
134
|
+
|
|
135
|
+
`project-discovery`, `architecture-design`, `test-strategy`, `ux-design`,
|
|
136
|
+
`delivery-orchestration`, `security-review`, `deployment-sre`, `development-workflow`,
|
|
137
|
+
`code-review`.
|
|
138
|
+
|
|
139
|
+
Domain skills are installed by profile:
|
|
140
|
+
|
|
141
|
+
| Profile | Skills |
|
|
142
|
+
|---|---|
|
|
143
|
+
| `web` | frontend, backend |
|
|
144
|
+
| `backend` | backend |
|
|
145
|
+
| `mobile` | mobile, frontend |
|
|
146
|
+
| `desktop` | desktop + Windows/macOS/Linux |
|
|
147
|
+
| `cross-platform` | multiplatform, desktop, frontend |
|
|
148
|
+
| `full` | all domain skills |
|
|
149
|
+
|
|
150
|
+
Every skill is self-contained and follows the [Agent Skills](https://agentskills.io)
|
|
151
|
+
specification.
|
|
152
|
+
|
|
153
|
+
## Harness support
|
|
154
|
+
|
|
155
|
+
| Tier | Harnesses | Commitment |
|
|
156
|
+
|---|---|---|
|
|
157
|
+
| 1 | OpenCode, Claude Code, Codex, Pi | Verified per release |
|
|
158
|
+
| 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort, generated |
|
|
159
|
+
| 3 | Any harness that reads `AGENTS.md` or accepts a prompt pack | Generic fallback |
|
|
160
|
+
|
|
161
|
+
Adapters are data: rules file, skills directory, agent directory, and limitations.
|
|
162
|
+
|
|
163
|
+
## Local design documents
|
|
164
|
+
|
|
165
|
+
By default, discovery, architecture, test plans, evidence, and reports live in
|
|
166
|
+
`.companion/local/`, which is ignored by git. Only `.companion/config.json` is tracked.
|
|
167
|
+
|
|
168
|
+
If you want the design to travel with the repository:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
npx development-companion init . --docs tracked
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
That moves the artifacts to `docs/companion/`.
|
|
175
|
+
|
|
176
|
+
## Memory: Engram (optional)
|
|
177
|
+
|
|
178
|
+
The process works without memory. If Engram is available, it stores decisions, findings,
|
|
179
|
+
and session summaries between sessions. `devcomp doctor` detects it and prints the setup
|
|
180
|
+
steps for your harness. The files remain the source of truth.
|
|
181
|
+
|
|
182
|
+
## Security rules built in
|
|
183
|
+
|
|
184
|
+
- **Never read `.env` values.** Only key names and presence checks.
|
|
185
|
+
- **Evidence per finding:** file and snippet, command and output, request, CVE, or
|
|
186
|
+
screenshot.
|
|
187
|
+
- **No secrets** in the repository, logs, screenshots, or reports.
|
|
188
|
+
- **Least privilege** for subagents; read-only reviewers where the harness allows it.
|
|
189
|
+
- **UI reviewed with screenshots** at desktop and mobile widths, using a vision-capable
|
|
190
|
+
model.
|
|
191
|
+
|
|
192
|
+
## Scaffold
|
|
193
|
+
|
|
194
|
+
`devcomp scaffold` generates a TypeScript reference monorepo:
|
|
195
|
+
|
|
196
|
+
- `apps/web`: React + Vite;
|
|
197
|
+
- `apps/api`: Node + Fastify;
|
|
198
|
+
- `packages/domain`, `application`, `contracts`;
|
|
199
|
+
- PostgreSQL in Docker;
|
|
200
|
+
- Vitest and Playwright;
|
|
201
|
+
- a runnable walking skeleton, not business logic.
|
|
202
|
+
|
|
203
|
+
The domain has no framework or infrastructure imports. Ports and adapters keep the
|
|
204
|
+
implementation replaceable.
|
|
205
|
+
|
|
206
|
+
## Develop this package
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
npm test
|
|
210
|
+
npm run pack:check
|
|
211
|
+
node bin/devcomp.mjs --help
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Requirements: Node >= 22. No runtime dependencies, no `postinstall`, no telemetry.
|
|
215
|
+
|
|
216
|
+
## Repository layout
|
|
217
|
+
|
|
218
|
+
```text
|
|
219
|
+
bin/ CLI entrypoint
|
|
220
|
+
src/ CLI implementation
|
|
221
|
+
core/ principles, process, quality gates, roles, guidelines
|
|
222
|
+
skills/ Agent Skills
|
|
223
|
+
templates/ rules and artifact templates
|
|
224
|
+
adapters/ harness metadata and guides
|
|
225
|
+
test/ CLI tests
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT. See `LICENSE`.
|
package/RELEASE.md
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Release checklist
|
|
2
|
+
|
|
3
|
+
This project publishes to npm. The package name is `development-companion`; the binary is
|
|
4
|
+
`devcomp`.
|
|
5
|
+
|
|
6
|
+
## 1. Prerequisites
|
|
7
|
+
|
|
8
|
+
- Node >= 22.
|
|
9
|
+
- An npm account with access to the `development-companion` package.
|
|
10
|
+
- 2FA enabled on npm (recommended).
|
|
11
|
+
- A clean git tree on the release commit.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm whoami
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
If this fails, authenticate first:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm login
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Never store the npm token in the repository. Use your local npm credentials or a CI
|
|
24
|
+
secret with the smallest possible scope.
|
|
25
|
+
|
|
26
|
+
## 2. Verify before publishing
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm test
|
|
30
|
+
npm run pack:check
|
|
31
|
+
npm publish --dry-run
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`npm run pack:check` must show `bin/`, `src/`, `skills/`, `core/`, `templates/`,
|
|
35
|
+
`adapters/`, `README.md`, and `LICENSE`, and must not include `plannification/`, `test/`,
|
|
36
|
+
`node_modules/`, or local evidence.
|
|
37
|
+
|
|
38
|
+
## 3. Verify an install from the tarball
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
packdir=$(mktemp -d)
|
|
42
|
+
npm pack --pack-destination "$packdir"
|
|
43
|
+
app=$(mktemp -d)
|
|
44
|
+
cd "$app"
|
|
45
|
+
npm init -y
|
|
46
|
+
npm install "$packdir"/development-companion-1.0.0.tgz
|
|
47
|
+
./node_modules/.bin/devcomp --version
|
|
48
|
+
./node_modules/.bin/devcomp init . --yes --harness opencode --profile web
|
|
49
|
+
./node_modules/.bin/devcomp doctor .
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
All checks must pass before publishing.
|
|
53
|
+
|
|
54
|
+
## 4. Publish
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm publish --access public
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
If npm asks for a one-time password, enter it from the authenticator. Do not paste it into
|
|
61
|
+
a file, shell history, or chat.
|
|
62
|
+
|
|
63
|
+
## 5. Verify the published package
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
cd "$(mktemp -d)"
|
|
67
|
+
npx development-companion@1.0.0 --version
|
|
68
|
+
npx development-companion@1.0.0 init . --yes --harness opencode --profile web
|
|
69
|
+
npx development-companion@1.0.0 doctor .
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Also verify the package page:
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
https://www.npmjs.com/package/development-companion
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## 6. Tag and publish the source release
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
git tag -a v1.0.0 -m "v1.0.0"
|
|
82
|
+
git push origin main --tags
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Create the release on Codeberg:
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.0.0
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Include the install command, the supported harness tiers, and the breaking changes from
|
|
92
|
+
v0.1.
|
|
93
|
+
|
|
94
|
+
## 7. If something is wrong
|
|
95
|
+
|
|
96
|
+
- **Bad metadata or README:** publish a patch release (`1.0.1`).
|
|
97
|
+
- **Bad code:** publish a patch release with the fix.
|
|
98
|
+
- **Security issue:** deprecate the affected version and publish a fix; do not rely on
|
|
99
|
+
unpublishing, which is time-limited and breaks consumers.
|
|
100
|
+
- **Accidental secret:** rotate it immediately, deprecate the version, and follow the
|
|
101
|
+
incident process. Do not rewrite published history silently.
|
|
102
|
+
|
|
103
|
+
## 8. After release
|
|
104
|
+
|
|
105
|
+
- Confirm `npx development-companion@latest` resolves to the new version.
|
|
106
|
+
- Run `devcomp init` and `doctor` in a clean repository.
|
|
107
|
+
- Update `plannification/05-roadmap.md` and the session summary.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Adapters
|
|
2
|
+
|
|
3
|
+
Adapters are **thin translations** from the canonical process to a specific harness. They
|
|
4
|
+
must not contain engineering policy that exists nowhere else.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npx development-companion@latest init --harness <name>
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The CLI reads `adapters/<name>/adapter.json`, installs skills into the adapter's skills
|
|
13
|
+
directory, writes `AGENTS.md`/`CLAUDE.md` with keep/append/replace, and generates native
|
|
14
|
+
agent bindings where the harness supports them.
|
|
15
|
+
|
|
16
|
+
## Support tiers
|
|
17
|
+
|
|
18
|
+
| Tier | Harness | Commitment |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| 1 | OpenCode, Claude Code, Codex, Pi | Installation and discovery verified per release |
|
|
21
|
+
| 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort adapter; verify against the installed version |
|
|
22
|
+
| 3 | Any other harness | `AGENTS.md` + skills copy or prompt pack |
|
|
23
|
+
|
|
24
|
+
"Any harness" means any harness that can read repository files or accept a prompt pack.
|
|
25
|
+
Tier 1 is the verified promise; Tier 2 is best-effort.
|
|
26
|
+
|
|
27
|
+
## Adapter metadata
|
|
28
|
+
|
|
29
|
+
Each adapter declares its paths and limitations:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"name": "opencode",
|
|
34
|
+
"tier": 1,
|
|
35
|
+
"rulesFile": "AGENTS.md",
|
|
36
|
+
"skillsDir": ".agents/skills",
|
|
37
|
+
"agentDir": ".opencode/agents",
|
|
38
|
+
"agentFormat": "markdown",
|
|
39
|
+
"limitations": ["Subagent permissions must be declared in each binding."]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
| Field | Meaning |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `rulesFile` | Project rules file the harness reads. |
|
|
46
|
+
| `rulesImport` | Import line for harnesses like Claude Code (`@AGENTS.md`). |
|
|
47
|
+
| `skillsDir` | Where Agent Skills are installed. |
|
|
48
|
+
| `agentDir` | Where subagent bindings are generated, if supported. |
|
|
49
|
+
| `agentFormat` | `markdown` or `toml`. |
|
|
50
|
+
| `limitations` | What the adapter cannot guarantee. |
|
|
51
|
+
|
|
52
|
+
## Rules installation
|
|
53
|
+
|
|
54
|
+
`AGENTS.md` and `CLAUDE.md` are installed in every target:
|
|
55
|
+
|
|
56
|
+
- If they do not exist, the CLI creates them.
|
|
57
|
+
- If they exist, the CLI asks **keep**, **append**, or **replace**.
|
|
58
|
+
- `append` uses a managed block with
|
|
59
|
+
`<!-- development-companion:start -->` / `<!-- development-companion:end -->`.
|
|
60
|
+
- `replace` requires explicit confirmation or `--force`.
|
|
61
|
+
- `--yes` defaults to `keep` for existing files.
|
|
62
|
+
|
|
63
|
+
## Binding roles
|
|
64
|
+
|
|
65
|
+
Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
66
|
+
|
|
67
|
+
| Role | OpenCode | Claude Code | Codex |
|
|
68
|
+
|---|---|---|---|
|
|
69
|
+
| Team Lead | `.opencode/agents/team-lead.md` | `.claude/agents/team-lead.md` | `.codex/agents/team-lead.toml` |
|
|
70
|
+
| Architect | `.opencode/agents/architect.md` | `.claude/agents/architect.md` | `.codex/agents/architect.toml` |
|
|
71
|
+
| Cybersecurity | `.opencode/agents/cybersecurity-engineer.md` | `.claude/agents/cybersecurity-engineer.md` | `.codex/agents/cybersecurity-engineer.toml` |
|
|
72
|
+
| QA | `.opencode/agents/qa-engineer.md` | `.claude/agents/qa-engineer.md` | `.codex/agents/qa-engineer.toml` |
|
|
73
|
+
| Frontend | `.opencode/agents/frontend-engineer.md` | `.claude/agents/frontend-engineer.md` | `.codex/agents/frontend-engineer.toml` |
|
|
74
|
+
| Backend | `.opencode/agents/backend-engineer.md` | `.claude/agents/backend-engineer.md` | `.codex/agents/backend-engineer.toml` |
|
|
75
|
+
| Mobile | `.opencode/agents/mobile-engineer.md` | `.claude/agents/mobile-engineer.md` | `.codex/agents/mobile-engineer.toml` |
|
|
76
|
+
| Windows | `.opencode/agents/desktop-windows-engineer.md` | `.claude/agents/desktop-windows-engineer.md` | `.codex/agents/desktop-windows-engineer.toml` |
|
|
77
|
+
| macOS | `.opencode/agents/desktop-macos-engineer.md` | `.claude/agents/desktop-macos-engineer.md` | `.codex/agents/desktop-macos-engineer.toml` |
|
|
78
|
+
| Linux | `.opencode/agents/desktop-linux-engineer.md` | `.claude/agents/desktop-linux-engineer.md` | `.codex/agents/desktop-linux-engineer.toml` |
|
|
79
|
+
| Multiplatform | `.opencode/agents/multiplatform-engineer.md` | `.claude/agents/multiplatform-engineer.md` | `.codex/agents/multiplatform-engineer.toml` |
|
|
80
|
+
| SRE | `.opencode/agents/sre-engineer.md` | `.claude/agents/sre-engineer.md` | `.codex/agents/sre-engineer.toml` |
|
|
81
|
+
|
|
82
|
+
Pi has no built-in subagents: use the role contract as a prompt template or invoke the
|
|
83
|
+
related skill.
|
|
84
|
+
|
|
85
|
+
## Limitations by harness
|
|
86
|
+
|
|
87
|
+
| Harness | Limitation |
|
|
88
|
+
|---|---|
|
|
89
|
+
| Pi | No built-in subagents or plan mode. |
|
|
90
|
+
| Codex | Agents inherit sandbox/approval from the parent. |
|
|
91
|
+
| Claude Code | Requires `CLAUDE.md` importing `AGENTS.md`. |
|
|
92
|
+
| OpenCode | Permissions must be declared in the binding. |
|
|
93
|
+
| Tier 2 | Paths and formats vary by version; verify before relying on them. |
|
|
94
|
+
|
|
95
|
+
## Rules for adapter authors
|
|
96
|
+
|
|
97
|
+
1. **Translate, don't fork.** If the harness needs a new rule, add it to `core/` first.
|
|
98
|
+
2. **Keep bindings short.** Reference the role; do not paste it.
|
|
99
|
+
3. **Respect permissions.** Reviewers and QA should be read-only where possible.
|
|
100
|
+
4. **Verify against current docs.** Harness paths and frontmatter change.
|
|
101
|
+
5. **Document limitations.** Do not pretend a harness supports a feature it lacks.
|
|
102
|
+
|
|
103
|
+
## Validation
|
|
104
|
+
|
|
105
|
+
After installing:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
devcomp doctor
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Then ask the harness to list skills and confirm the process skills appear. Invoke one
|
|
112
|
+
skill explicitly and confirm `AGENTS.md` or `CLAUDE.md` is being read. For subagents,
|
|
113
|
+
confirm the agent appears and has the intended permissions.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Claude Code Adapter
|
|
2
|
+
|
|
3
|
+
Claude Code reads `CLAUDE.md` and supports the Agent Skills specification and custom
|
|
4
|
+
subagents.
|
|
5
|
+
|
|
6
|
+
## Rules
|
|
7
|
+
|
|
8
|
+
Claude Code does not read `AGENTS.md` directly. Keep a `CLAUDE.md` at the project root
|
|
9
|
+
that imports it:
|
|
10
|
+
|
|
11
|
+
```markdown
|
|
12
|
+
@AGENTS.md
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Then keep the canonical rules in `AGENTS.md`. If the project cannot use imports, copy
|
|
16
|
+
the relevant sections into `CLAUDE.md`, but prefer the import to avoid drift.
|
|
17
|
+
|
|
18
|
+
## Skills
|
|
19
|
+
|
|
20
|
+
Claude Code loads project skills from `.claude/skills/<name>/SKILL.md`. It supports
|
|
21
|
+
symlinked skill folders.
|
|
22
|
+
|
|
23
|
+
Recommended install:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
mkdir -p .claude
|
|
27
|
+
ln -s /path/to/development-companion/skills .claude/skills
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
If `.claude/skills` already exists, link individual skills:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
mkdir -p .claude/skills
|
|
34
|
+
ln -s /path/to/development-companion/skills/development-workflow .claude/skills/development-workflow
|
|
35
|
+
ln -s /path/to/development-companion/skills/frontend-development .claude/skills/frontend-development
|
|
36
|
+
ln -s /path/to/development-companion/skills/backend-development .claude/skills/backend-development
|
|
37
|
+
ln -s /path/to/development-companion/skills/code-review .claude/skills/code-review
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Invoke a skill with `/development-workflow` or let Claude select it from the
|
|
41
|
+
description. Use `/skills` to inspect what loaded.
|
|
42
|
+
|
|
43
|
+
## Subagents
|
|
44
|
+
|
|
45
|
+
Define project subagents in `.claude/agents/<name>.md`. Required frontmatter:
|
|
46
|
+
`name` and `description`. Restrict tools for QA engineers.
|
|
47
|
+
|
|
48
|
+
Example `.claude/agents/qa-engineer.md`:
|
|
49
|
+
|
|
50
|
+
```markdown
|
|
51
|
+
---
|
|
52
|
+
name: qa-engineer
|
|
53
|
+
description: Reviews diffs for correctness, security, data risks, and missing tests. Use before merging or when the user asks for a code review.
|
|
54
|
+
tools: Read, Grep, Glob, Bash
|
|
55
|
+
model: sonnet
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
You are the Development Companion QA engineer.
|
|
59
|
+
|
|
60
|
+
Load and follow the `code-review` skill. Report findings by severity with file and
|
|
61
|
+
line references. Do not edit files. Do not approve without evidence.
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Example permissions for a read-only QA engineer: keep `Edit` and `Write` out of `tools`.
|
|
65
|
+
`Bash` can still run commands; constrain it with project permission rules if needed.
|
|
66
|
+
|
|
67
|
+
Repeat the pattern for the other roles in `core/roles/`. Use the `skills` frontmatter
|
|
68
|
+
field to preload a specific skill into a subagent when useful.
|
|
69
|
+
|
|
70
|
+
## Limitations
|
|
71
|
+
|
|
72
|
+
- Claude Code-specific frontmatter (`tools`, `model`, `permissionMode`, `skills`) is
|
|
73
|
+
not portable. Keep it only in the binding.
|
|
74
|
+
- Subagent definitions are not shared with other harnesses; the canonical role is.
|
|
75
|
+
- Claude Code may load personal skills that shadow project skills. Check `/skills` if
|
|
76
|
+
a skill does not appear to be the expected version.
|
|
77
|
+
|
|
78
|
+
## References
|
|
79
|
+
|
|
80
|
+
- Skills: <https://code.claude.com/docs/en/skills>
|
|
81
|
+
- Subagents: <https://code.claude.com/docs/en/sub-agents>
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "claude-code",
|
|
3
|
+
"tier": 1,
|
|
4
|
+
"rulesFile": "CLAUDE.md",
|
|
5
|
+
"rulesImport": "@AGENTS.md",
|
|
6
|
+
"skillsDir": ".claude/skills",
|
|
7
|
+
"agentDir": ".claude/agents",
|
|
8
|
+
"agentFormat": "markdown",
|
|
9
|
+
"limitations": ["CLAUDE.md must import AGENTS.md; skills in .claude/skills."]
|
|
10
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Codex Adapter
|
|
2
|
+
|
|
3
|
+
Codex reads `AGENTS.md`, supports Agent Skills, and supports custom subagents.
|
|
4
|
+
|
|
5
|
+
## Rules
|
|
6
|
+
|
|
7
|
+
Place `AGENTS.md` at the project root. Codex discovers it automatically. Keep the
|
|
8
|
+
canonical rules there; do not duplicate them in a Codex-only file.
|
|
9
|
+
|
|
10
|
+
## Skills
|
|
11
|
+
|
|
12
|
+
Codex scans `.agents/skills` from the working directory up to the repository root.
|
|
13
|
+
Symlinked skill folders are supported.
|
|
14
|
+
|
|
15
|
+
Recommended install:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
mkdir -p .agents
|
|
19
|
+
ln -s /path/to/development-companion/skills .agents/skills
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
If `.agents/skills` already exists, link individual skills:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
mkdir -p .agents/skills
|
|
26
|
+
ln -s /path/to/development-companion/skills/development-workflow .agents/skills/development-workflow
|
|
27
|
+
ln -s /path/to/development-companion/skills/frontend-development .agents/skills/frontend-development
|
|
28
|
+
ln -s /path/to/development-companion/skills/backend-development .agents/skills/backend-development
|
|
29
|
+
ln -s /path/to/development-companion/skills/code-review .agents/skills/code-review
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Use `/skills` or `$skill-name` to inspect and invoke skills. Codex can also select a
|
|
33
|
+
skill automatically from its description.
|
|
34
|
+
|
|
35
|
+
> Custom prompts are deprecated. Use skills for reusable workflows.
|
|
36
|
+
|
|
37
|
+
## Subagents
|
|
38
|
+
|
|
39
|
+
Codex custom agents are standalone TOML files in `.codex/agents/<name>.toml` (project)
|
|
40
|
+
or `~/.codex/agents/` (personal). Required fields: `name`, `description`,
|
|
41
|
+
`developer_instructions`.
|
|
42
|
+
|
|
43
|
+
Example `.codex/agents/qa-engineer.toml`:
|
|
44
|
+
|
|
45
|
+
```toml
|
|
46
|
+
name = "qa-engineer"
|
|
47
|
+
description = "Reviews diffs for correctness, security, data risks, and missing tests. Use before merging or when the user asks for a code review."
|
|
48
|
+
model_reasoning_effort = "high"
|
|
49
|
+
developer_instructions = """
|
|
50
|
+
You are the Development Companion QA engineer.
|
|
51
|
+
Load and follow the code-review skill.
|
|
52
|
+
Report findings by severity with file and line references.
|
|
53
|
+
Do not edit files. Do not approve without evidence.
|
|
54
|
+
"""
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Repeat the pattern for the other roles in `core/roles/`.
|
|
58
|
+
|
|
59
|
+
To make delegation explicit, add to `AGENTS.md`:
|
|
60
|
+
|
|
61
|
+
```markdown
|
|
62
|
+
For reviews, delegate to the `qa-engineer` agent. For architecture decisions, use the
|
|
63
|
+
`architect` agent. Do not run multiple write agents on the same files.
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Custom agents inherit the parent's permissions, provider, and MCP servers. A custom
|
|
67
|
+
agent file cannot override sandbox or approval settings.
|
|
68
|
+
|
|
69
|
+
## Limitations
|
|
70
|
+
|
|
71
|
+
- Codex custom agents use TOML, not Markdown. Keep the binding short and point to the
|
|
72
|
+
canonical role or skill.
|
|
73
|
+
- Subagent activity consumes additional tokens; use it for bounded, independent work.
|
|
74
|
+
- Skills inherit from the parent; a custom agent can disable specific skills.
|
|
75
|
+
|
|
76
|
+
## References
|
|
77
|
+
|
|
78
|
+
- AGENTS.md: <https://learn.chatgpt.com/docs/agent-configuration/agents-md>
|
|
79
|
+
- Skills: <https://developers.openai.com/codex/skills>
|
|
80
|
+
- Subagents: <https://learn.chatgpt.com/docs/agent-configuration/subagents>
|