development-companion 0.0.0-stage → 1.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 (82) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +238 -2
  3. package/RELEASE.md +122 -0
  4. package/adapters/README.md +113 -0
  5. package/adapters/claude-code/README.md +81 -0
  6. package/adapters/claude-code/adapter.json +10 -0
  7. package/adapters/cline/adapter.json +9 -0
  8. package/adapters/codex/README.md +80 -0
  9. package/adapters/codex/adapter.json +9 -0
  10. package/adapters/copilot-cli/adapter.json +9 -0
  11. package/adapters/cursor/adapter.json +9 -0
  12. package/adapters/gemini-cli/adapter.json +9 -0
  13. package/adapters/generic/adapter.json +9 -0
  14. package/adapters/opencode/README.md +127 -0
  15. package/adapters/opencode/adapter.json +9 -0
  16. package/adapters/pi/README.md +83 -0
  17. package/adapters/pi/adapter.json +9 -0
  18. package/adapters/windsurf/adapter.json +9 -0
  19. package/bin/devcomp.mjs +8 -0
  20. package/core/guidelines/backend.md +103 -0
  21. package/core/guidelines/collaboration.md +78 -0
  22. package/core/guidelines/frontend.md +106 -0
  23. package/core/guidelines/security.md +90 -0
  24. package/core/guidelines/testing.md +90 -0
  25. package/core/principles.md +208 -0
  26. package/core/process.md +224 -0
  27. package/core/quality-gates.md +192 -0
  28. package/core/roles/README.md +55 -0
  29. package/core/roles/architect.md +75 -0
  30. package/core/roles/backend-engineer.md +74 -0
  31. package/core/roles/cybersecurity-engineer.md +55 -0
  32. package/core/roles/desktop-linux-engineer.md +50 -0
  33. package/core/roles/desktop-macos-engineer.md +50 -0
  34. package/core/roles/desktop-windows-engineer.md +50 -0
  35. package/core/roles/frontend-engineer.md +72 -0
  36. package/core/roles/mobile-engineer.md +50 -0
  37. package/core/roles/multiplatform-engineer.md +49 -0
  38. package/core/roles/orchestrator.md +69 -0
  39. package/core/roles/qa-engineer.md +69 -0
  40. package/core/roles/reviewer.md +77 -0
  41. package/core/roles/sre-engineer.md +51 -0
  42. package/core/roles/team-lead.md +67 -0
  43. package/core/workflow.md +169 -0
  44. package/package.json +53 -4
  45. package/skills/architecture-design/SKILL.md +116 -0
  46. package/skills/backend-development/SKILL.md +127 -0
  47. package/skills/code-review/SKILL.md +144 -0
  48. package/skills/delivery-orchestration/SKILL.md +119 -0
  49. package/skills/deployment-sre/SKILL.md +111 -0
  50. package/skills/desktop-development/SKILL.md +51 -0
  51. package/skills/development-workflow/SKILL.md +158 -0
  52. package/skills/frontend-development/SKILL.md +136 -0
  53. package/skills/linux-development/SKILL.md +44 -0
  54. package/skills/macos-development/SKILL.md +45 -0
  55. package/skills/mobile-development/SKILL.md +60 -0
  56. package/skills/multiplatform-development/SKILL.md +45 -0
  57. package/skills/project-discovery/SKILL.md +122 -0
  58. package/skills/security-review/SKILL.md +109 -0
  59. package/skills/test-strategy/SKILL.md +109 -0
  60. package/skills/ux-design/SKILL.md +108 -0
  61. package/skills/windows-development/SKILL.md +45 -0
  62. package/src/args.mjs +42 -0
  63. package/src/cli.mjs +492 -0
  64. package/src/content.mjs +72 -0
  65. package/src/detect.mjs +119 -0
  66. package/src/install.mjs +236 -0
  67. package/src/prompt.mjs +35 -0
  68. package/src/rules.mjs +83 -0
  69. package/src/scaffold.mjs +433 -0
  70. package/templates/artifacts/01-operational-brief.md +37 -0
  71. package/templates/artifacts/02-architecture.md +33 -0
  72. package/templates/artifacts/03-threat-model.md +29 -0
  73. package/templates/artifacts/04-test-plan.md +35 -0
  74. package/templates/artifacts/05-ux-spec.md +31 -0
  75. package/templates/artifacts/06-delivery-plan.md +29 -0
  76. package/templates/artifacts/07-security-report.md +25 -0
  77. package/templates/artifacts/08-qa-report.md +32 -0
  78. package/templates/artifacts/09-runbook.md +43 -0
  79. package/templates/artifacts/10-closure.md +25 -0
  80. package/templates/artifacts/README.md +17 -0
  81. package/templates/rules/AGENTS.block.md +40 -0
  82. 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,239 @@
1
- # Temporary Holding Version
1
+ # Development Companion
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ ### Orchestration in OpenCode
132
+
133
+ `devcomp init` installs `team-lead` with `mode: primary` and writes
134
+ `.opencode/opencode.json` with `default_agent: "team-lead"`. The 11 specialists are
135
+ subagents. New sessions start as the team lead, which delegates with the `subagent` tool;
136
+ Build and Plan remain available in the agent selector. If the project already has an
137
+ OpenCode config, the installer preserves it and `devcomp doctor` warns that
138
+ `default_agent` is not set.
139
+
140
+ ## Skills and profiles
141
+
142
+ Process skills are installed always:
143
+
144
+ `project-discovery`, `architecture-design`, `test-strategy`, `ux-design`,
145
+ `delivery-orchestration`, `security-review`, `deployment-sre`, `development-workflow`,
146
+ `code-review`.
147
+
148
+ Domain skills are installed by profile:
149
+
150
+ | Profile | Skills |
151
+ |---|---|
152
+ | `web` | frontend, backend |
153
+ | `backend` | backend |
154
+ | `mobile` | mobile, frontend |
155
+ | `desktop` | desktop + Windows/macOS/Linux |
156
+ | `cross-platform` | multiplatform, desktop, frontend |
157
+ | `full` | all domain skills |
158
+
159
+ Every skill is self-contained and follows the [Agent Skills](https://agentskills.io)
160
+ specification.
161
+
162
+ ## Harness support
163
+
164
+ | Tier | Harnesses | Commitment |
165
+ |---|---|---|
166
+ | 1 | OpenCode, Claude Code, Codex, Pi | Verified per release |
167
+ | 2 | Cursor, Gemini CLI, Copilot CLI, Windsurf, Cline | Best-effort, generated |
168
+ | 3 | Any harness that reads `AGENTS.md` or accepts a prompt pack | Generic fallback |
169
+
170
+ Adapters are data: rules file, skills directory, agent directory, and limitations.
171
+
172
+ ## Local design documents
173
+
174
+ By default, discovery, architecture, test plans, evidence, and reports live in
175
+ `.companion/local/`, which is ignored by git. Only `.companion/config.json` is tracked.
176
+
177
+ If you want the design to travel with the repository:
178
+
179
+ ```bash
180
+ npx development-companion init . --docs tracked
181
+ ```
182
+
183
+ That moves the artifacts to `docs/companion/`.
184
+
185
+ ## Memory: Engram (optional)
186
+
187
+ The process works without memory. If Engram is available, it stores decisions, findings,
188
+ and session summaries between sessions. `devcomp doctor` detects it and prints the setup
189
+ steps for your harness. The files remain the source of truth.
190
+
191
+ ## Security rules built in
192
+
193
+ - **Never read `.env` values.** Only key names and presence checks.
194
+ - **Evidence per finding:** file and snippet, command and output, request, CVE, or
195
+ screenshot.
196
+ - **No secrets** in the repository, logs, screenshots, or reports.
197
+ - **Least privilege** for subagents; read-only reviewers where the harness allows it.
198
+ - **UI reviewed with screenshots** at desktop and mobile widths, using a vision-capable
199
+ model.
200
+
201
+ ## Scaffold
202
+
203
+ `devcomp scaffold` generates a TypeScript reference monorepo:
204
+
205
+ - `apps/web`: React + Vite;
206
+ - `apps/api`: Node + Fastify;
207
+ - `packages/domain`, `application`, `contracts`;
208
+ - PostgreSQL in Docker;
209
+ - Vitest and Playwright;
210
+ - a runnable walking skeleton, not business logic.
211
+
212
+ The domain has no framework or infrastructure imports. Ports and adapters keep the
213
+ implementation replaceable.
214
+
215
+ ## Develop this package
216
+
217
+ ```bash
218
+ npm test
219
+ npm run pack:check
220
+ node bin/devcomp.mjs --help
221
+ ```
222
+
223
+ Requirements: Node >= 22. No runtime dependencies, no `postinstall`, no telemetry.
224
+
225
+ ## Repository layout
226
+
227
+ ```text
228
+ bin/ CLI entrypoint
229
+ src/ CLI implementation
230
+ core/ principles, process, quality gates, roles, guidelines
231
+ skills/ Agent Skills
232
+ templates/ rules and artifact templates
233
+ adapters/ harness metadata and guides
234
+ test/ CLI tests
235
+ ```
236
+
237
+ ## License
238
+
239
+ MIT. See `LICENSE`.
package/RELEASE.md ADDED
@@ -0,0 +1,122 @@
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.1.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. If 2FA uses a
61
+ passkey or security key, npm prints an authentication URL and opens the browser; approve
62
+ with the passkey. Do not paste secrets into a file, shell history, or chat.
63
+
64
+ ### First publish and the `0.0.0-stage` placeholder
65
+
66
+ When a package does not exist yet, npm may create a temporary `0.0.0-stage` placeholder
67
+ while the real version is being processed. This is expected. Do not bump the version or
68
+ republish immediately. Wait a few minutes and verify:
69
+
70
+ ```bash
71
+ npm view development-companion version dist-tags
72
+ ```
73
+
74
+ The `latest` tag must point to `1.1.0`, not `0.0.0-stage`. If it still points to the
75
+ placeholder after several minutes, check the npmjs.com package page and the Staged
76
+ Packages tab before retrying.
77
+
78
+ ## 5. Verify the published package
79
+
80
+ ```bash
81
+ cd "$(mktemp -d)"
82
+ npx development-companion@1.1.0 --version
83
+ npx development-companion@1.1.0 init . --yes --harness opencode --profile web
84
+ npx development-companion@1.1.0 doctor .
85
+ ```
86
+
87
+ Also verify the package page:
88
+
89
+ ```text
90
+ https://www.npmjs.com/package/development-companion
91
+ ```
92
+
93
+ ## 6. Tag and publish the source release
94
+
95
+ ```bash
96
+ git tag -a v1.1.0 -m "v1.1.0"
97
+ git push origin main --tags
98
+ ```
99
+
100
+ Create the release on Codeberg:
101
+
102
+ ```text
103
+ https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.1.0
104
+ ```
105
+
106
+ Include the install command, the supported harness tiers, and the breaking changes from
107
+ v0.1.
108
+
109
+ ## 7. If something is wrong
110
+
111
+ - **Bad metadata or README:** publish a patch release (`1.0.1`).
112
+ - **Bad code:** publish a patch release with the fix.
113
+ - **Security issue:** deprecate the affected version and publish a fix; do not rely on
114
+ unpublishing, which is time-limited and breaks consumers.
115
+ - **Accidental secret:** rotate it immediately, deprecate the version, and follow the
116
+ incident process. Do not rewrite published history silently.
117
+
118
+ ## 8. After release
119
+
120
+ - Confirm `npx development-companion@latest` resolves to the new version.
121
+ - Run `devcomp init` and `doctor` in a clean repository.
122
+ - 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,9 @@
1
+ {
2
+ "name": "cline",
3
+ "tier": 2,
4
+ "rulesFile": "AGENTS.md",
5
+ "skillsDir": ".agents/skills",
6
+ "agentDir": null,
7
+ "agentFormat": null,
8
+ "limitations": ["Best-effort: Cline may require .clinerules for project rules."]
9
+ }
@@ -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>
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "codex",
3
+ "tier": 1,
4
+ "rulesFile": "AGENTS.md",
5
+ "skillsDir": ".agents/skills",
6
+ "agentDir": ".codex/agents",
7
+ "agentFormat": "toml",
8
+ "limitations": ["Custom agents inherit sandbox and approval policy from the parent."]
9
+ }