development-companion 1.7.0 → 1.8.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/CHANGELOG.md +56 -0
- package/README.md +114 -32
- package/RELEASE.md +41 -24
- package/adapters/README.md +11 -5
- package/adapters/opencode/README.md +87 -12
- package/adapters/opencode/plugin/devcomp/gates.mjs +688 -0
- package/adapters/opencode/plugin/devcomp/index.ts +487 -7
- package/core/guidelines/coordination.md +138 -4
- package/core/process.md +141 -7
- package/core/quality-gates.md +41 -1
- package/core/roles/README.md +4 -1
- package/core/roles/backend-engineer.md +10 -0
- package/core/roles/coordinator.md +83 -25
- package/core/roles/desktop-linux-engineer.md +10 -0
- package/core/roles/desktop-macos-engineer.md +10 -0
- package/core/roles/desktop-windows-engineer.md +10 -0
- package/core/roles/frontend-engineer.md +10 -0
- package/core/roles/mobile-engineer.md +10 -0
- package/core/roles/multiplatform-engineer.md +10 -0
- package/core/roles/sre-engineer.md +10 -0
- package/core/workflow.md +62 -9
- package/package.json +1 -1
- package/skills/delivery-orchestration/SKILL.md +58 -3
- package/skills/development-workflow/SKILL.md +44 -8
- package/skills/test-strategy/SKILL.md +12 -0
- package/src/cli.mjs +86 -6
- package/src/install.mjs +106 -21
- package/templates/artifacts/01-operational-brief.md +14 -1
- package/templates/artifacts/11-feature-plan.md +83 -0
- package/templates/artifacts/README.md +8 -5
- package/templates/rules/AGENTS.block.md +99 -10
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,61 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.8.0
|
|
4
|
+
|
|
5
|
+
- **Final security hardening.** The local adapter never self-disables: only a copy under the
|
|
6
|
+
global OpenCode plugins directory may no-op when a project adapter exists, including symlinked
|
|
7
|
+
roots and case differences. A development-table plan requires `Step:` and a row whose Step and
|
|
8
|
+
declared agent match. Plans need a top-level `Scope:` and Test/Verification/Evidence content.
|
|
9
|
+
Read-only roles may write their reports in `.companion/local/**`, `plannification/**` and
|
|
10
|
+
`docs/companion/**`, but cannot rewrite the bound approved plan. Destructive detection adds
|
|
11
|
+
`git checkout .`/`<ref> -- <path>`, `DELETE ... WHERE n=n`, `aws s3 sync --delete` and
|
|
12
|
+
`docker compose down --volumes`. The approval mark is bound to the plan path and content
|
|
13
|
+
(revision guard); `--auto`/non-interactive bypasses the mark, revision guard and `ask` and is
|
|
14
|
+
documented as unsuitable for destructive or approval-required work.
|
|
15
|
+
- **Working modes and fast lane.** A query is answered without specialists; a small change uses
|
|
16
|
+
one writer and a short plan; a feature gets a user-visible plan; bug, refactor and incident
|
|
17
|
+
keep their own minimum rigor. `core/process.md`, `core/workflow.md`,
|
|
18
|
+
`core/quality-gates.md`, `core/guidelines/coordination.md` and the `AGENTS.md` block document
|
|
19
|
+
the modes and when to escalate.
|
|
20
|
+
- **Feature intake and plan.** New `templates/artifacts/11-feature-plan.md` with scope and
|
|
21
|
+
non-goals, a top-level `Scope:`, approach and trade-offs, a Development plan (steps, agents,
|
|
22
|
+
dependencies, parallelism, step `Scope`, evidence), a Test plan (golden and dark paths),
|
|
23
|
+
risks and rollback. A small change uses `01-operational-brief.md` with `Aprobado:` and
|
|
24
|
+
`Scope:`. The Coordinator shows the plan, iterates it with the user, and records an
|
|
25
|
+
affirmative `Aprobado:` only after approval.
|
|
26
|
+
- **Plan gate.** In OpenCode, an implementation delegation must include `Plan: <path>` and
|
|
27
|
+
`Scope: <globs>`; the plan must exist inside the workspace, be at least 200 characters,
|
|
28
|
+
declare a top-level `Scope:`, and carry an affirmative `Aprobado:`. The delegation scope must
|
|
29
|
+
be equal to or narrower than the plan. Missing or invalid delegations are rejected before
|
|
30
|
+
the subagent starts.
|
|
31
|
+
- **Scope gate and scope lock.** `edit`, `write`, `patch`, `apply_patch` and `multiedit` from a
|
|
32
|
+
delegated subagent must stay inside the recorded `Scope`; violations are denied with a
|
|
33
|
+
model-visible message. Read-only roles may write their own reports under the planning
|
|
34
|
+
directory. Specialist bindings carry the scope lock and must report out-of-scope findings
|
|
35
|
+
instead of implementing them. Shell writes remain a documented residual risk.
|
|
36
|
+
- **Session approval and goal continuity.** An affirmative natural-language approval from the
|
|
37
|
+
user marks the root session; approved plans no longer prompt for every subagent, and the
|
|
38
|
+
native `subagent: ask` remains the fallback. Questions, past/narrative forms and observation
|
|
39
|
+
language do not approve; observations revoke the mark. The mark is bound to the plan path and
|
|
40
|
+
content hash: editing the plan or switching plans revokes it until the user approves again.
|
|
41
|
+
Delegation instructions are not approvals. After approval the Coordinator continues to the
|
|
42
|
+
end-to-end path without routine confirmations and pauses only for catastrophic or
|
|
43
|
+
irreversible cases.
|
|
44
|
+
- **Destructive guard.** Known file deletion, database `DROP`/`TRUNCATE`/`DELETE` (including
|
|
45
|
+
`WHERE true`), volume/infrastructure destruction, `terraform apply -destroy`, `docker system
|
|
46
|
+
prune`, `rsync --del`, redirection truncation, `dd of=`, PowerShell `Remove-Item`, and one
|
|
47
|
+
level of `bash -c`/`eval` resolve to `ask`, even after an "always" approval. The permission
|
|
48
|
+
message is generic and never prints secrets; shell writes remain a residual risk.
|
|
49
|
+
- **Doctor.** New checks for the plan gate, scope gate, scope lock, destructive guard, plugin
|
|
50
|
+
coexistence and feature flow. The global setup installs `devcomp/index.ts` + `gates.mjs`; a
|
|
51
|
+
legacy global adapter is backed up and removed only with `--force`, and the global adapter
|
|
52
|
+
no-ops when the project has its own copy.
|
|
53
|
+
- **Tests.** New gate unit tests (affirmative plan approval, session approval and observation
|
|
54
|
+
revocation, plan revision binding, plan scope bounding and minimum content, plan/path
|
|
55
|
+
traversal, symlink nearest ancestor, scope globs, edit/write/patch/multiedit paths,
|
|
56
|
+
destructive wrappers and patterns, pending-scope ambiguity) plus CLI/content coverage and a
|
|
57
|
+
persistent-server session for plan revision, observation revocation and orphan scope.
|
|
58
|
+
|
|
3
59
|
## 1.7.0
|
|
4
60
|
|
|
5
61
|
- **Forced flow in OpenCode.** `devcomp init`/`update` now install a `coordinator` primary
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Development Companion
|
|
2
2
|
|
|
3
|
-
One installable development process for AI coding agents: **
|
|
3
|
+
One installable development process for AI coding agents: **13 roles**, **18 skills**, and
|
|
4
4
|
a CLI that adapts the same canonical base to OpenCode, Claude Code, Codex, Pi, and other
|
|
5
5
|
harnesses.
|
|
6
6
|
|
|
@@ -93,17 +93,24 @@ The managed block is delimited by `<!-- development-companion:start -->` and
|
|
|
93
93
|
| `devcomp add <skill\|role\|profile> <name>` | Add content to an existing install. |
|
|
94
94
|
| `devcomp setup opencode --global` | Install the OpenCode runtime adapter for every project. |
|
|
95
95
|
| `devcomp scaffold [dir]` | Generate the TypeScript reference monorepo. |
|
|
96
|
-
| `devcomp doctor [dir]` | Check content, the coordinator binding, the runtime
|
|
96
|
+
| `devcomp doctor [dir]` | Check content, the coordinator binding, the runtime gates (plan, scope, destructive), scope lock, feature flow, and the config gate. |
|
|
97
97
|
| `devcomp update [dir]` | Refresh framework content, bindings, plugin, and OpenCode config. |
|
|
98
98
|
|
|
99
99
|
## The process
|
|
100
100
|
|
|
101
|
-
**New in 1.
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
`
|
|
101
|
+
**New in 1.8.0:** a fast lane and a visible feature plan. A query is answered without
|
|
102
|
+
specialists; a small change uses one writer and a short plan; a new feature gets a user-visible
|
|
103
|
+
plan with a development plan (agents, dependencies, parallelism, `Scope`) and a test plan
|
|
104
|
+
(golden and dark paths) before code. After approval the Coordinator continues to the end-to-end
|
|
105
|
+
path without routine confirmations. The OpenCode runtime enforces the plan gate (`Plan:` +
|
|
106
|
+
`Scope:` + `Aprobado:`), the scope gate (`edit`/`write`/`patch` inside `Scope`), the session
|
|
107
|
+
approval mark, and a destructive-command guard for known patterns.
|
|
108
|
+
|
|
109
|
+
**Since 1.7.0:** the primary is the `coordinator` agent (`default_agent: coordinator`); it
|
|
110
|
+
cannot edit product code or run shell, so it must frame, ask for approval and delegate. A
|
|
111
|
+
runtime plugin injects the canonical process in every session, including child repositories.
|
|
112
|
+
Approval is natural language; there is no magic phrase. `devcomp update` migrates existing
|
|
113
|
+
installations.
|
|
107
114
|
|
|
108
115
|
The process exists to ship working software, not to produce documents. It is a loop:
|
|
109
116
|
|
|
@@ -123,6 +130,39 @@ skill.
|
|
|
123
130
|
|
|
124
131
|
For a small change, the process collapses to the workflow in `core/workflow.md`.
|
|
125
132
|
|
|
133
|
+
## Working modes and feature plan
|
|
134
|
+
|
|
135
|
+
| Mode | Use for | Minimum artifact | Agents | Authorization |
|
|
136
|
+
|---|---|---|---|---|
|
|
137
|
+
| Query | Question, explanation, read-only investigation | None | Coordinator only | None |
|
|
138
|
+
| Small change | Confined, low-risk fix | Short operational brief with `Aprobado:` and `Scope:` | One writer | Natural language + delegation permission |
|
|
139
|
+
| Feature | New capability or behavior change | Feature plan with Development plan and Test plan | Read-only planning + writers | User-approved plan |
|
|
140
|
+
| Bug | Reproducible failure | Reproduction + failing test + fix + regression | One writer (+ QA if critical) | Short brief with Aprobado/Scope |
|
|
141
|
+
| Refactor | No behavior change | Baseline tests + reversible steps | One writer | Short brief with Aprobado/Scope |
|
|
142
|
+
| Incident | Production down, data or security | Stabilize first; postmortem after | Coordinator + SRE/security | Coordinator talks to the user |
|
|
143
|
+
|
|
144
|
+
A feature plan is user-visible. The template
|
|
145
|
+
([`templates/artifacts/11-feature-plan.md`](templates/artifacts/11-feature-plan.md)) contains
|
|
146
|
+
scope and non-goals, a top-level `Scope:`, approach and trade-offs, Development plan, Test plan
|
|
147
|
+
with golden and dark paths, evidence, risks and rollback. A small change uses
|
|
148
|
+
[`01-operational-brief.md`](templates/artifacts/01-operational-brief.md) with its own
|
|
149
|
+
`Aprobado:` and `Scope:`. The Coordinator records an affirmative `Aprobado:` only after the
|
|
150
|
+
user approves. Every implementation delegation carries `Plan: <path>` and `Scope: <globs>`
|
|
151
|
+
equal to or narrower than the plan.
|
|
152
|
+
|
|
153
|
+
After approval the plan is the execution contract: the Coordinator verifies each report and
|
|
154
|
+
continues to the end-to-end path without asking for routine confirmation. It pauses only for a
|
|
155
|
+
catastrophic or irreversible operation, data loss, critical security, a requirement conflict,
|
|
156
|
+
or an invalidated plan. A feature is not closed until the agreed end-to-end path runs and every
|
|
157
|
+
golden and critical dark case has evidence or a declared gap.
|
|
158
|
+
|
|
159
|
+
Specialists execute only their step and touch only files inside `Scope`. An unrequested
|
|
160
|
+
improvement is a scope violation: report it, do not implement it. Read-only roles may write
|
|
161
|
+
their own reports under the planning directory; their binding denies product edits. Known
|
|
162
|
+
destructive operations (file deletion, database drops or truncation, volume or infrastructure
|
|
163
|
+
destruction) require the user's explicit authorization, separate from the plan approval; shell
|
|
164
|
+
writes remain a residual risk.
|
|
165
|
+
|
|
126
166
|
## Roles
|
|
127
167
|
|
|
128
168
|
| Role | Primary question |
|
|
@@ -151,24 +191,57 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
|
|
|
151
191
|
`devcomp init`/`update` installs a `coordinator` primary agent and sets
|
|
152
192
|
`default_agent: coordinator` in `opencode.json`. The coordinator can read, search, ask and
|
|
153
193
|
write frames under `plannification/` or `.companion/local/`; it cannot edit product code or
|
|
154
|
-
run shell. Implementation subagents
|
|
155
|
-
|
|
156
|
-
explicit user escape hatch (`--agent build` or an agent
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
`.
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
194
|
+
run shell. Implementation subagents resolve to `ask` by default; the runtime plugin allows an
|
|
195
|
+
approved in-session delegation without a per-subagent prompt and keeps `ask` as the fallback.
|
|
196
|
+
`build` remains available only as an explicit user escape hatch (`--agent build` or an agent
|
|
197
|
+
switch).
|
|
198
|
+
|
|
199
|
+
The plugin at `.opencode/plugins/devcomp/index.ts` (with `gates.mjs`) searches upward for the
|
|
200
|
+
nearest `.companion/config.json` and injects the five canonical files at runtime. It fixes the
|
|
201
|
+
child repository case: OpenCode discovers the meta-repo config, bindings and plugins, but
|
|
202
|
+
relative `instructions` do not resolve below the child project root. It also enforces:
|
|
203
|
+
|
|
204
|
+
- **Plan gate:** an implementation delegation needs `Plan: <path>` and `Scope: <globs>`; the
|
|
205
|
+
plan must exist inside the workspace, be at least 200 characters, declare a top-level
|
|
206
|
+
`Scope:`, include Test/Verification/Evidence content, and carry an affirmative `Aprobado:`.
|
|
207
|
+
A plan with a development table requires `Step:` and a row whose Step and declared agent
|
|
208
|
+
match; only a table-less brief falls back to the top-level Scope. The delegation `Scope:`
|
|
209
|
+
must be equal to or narrower than the plan.
|
|
210
|
+
- **Scope gate:** `edit`, `write`, `patch`, `apply_patch` and `multiedit` must stay inside the
|
|
211
|
+
recorded `Scope` of the child session. Read-only roles write only their report paths
|
|
212
|
+
(`.companion/local/**`, `plannification/**`, `docs/companion/**`); they cannot rewrite the
|
|
213
|
+
bound approved plan. Shell writes are a documented residual risk and the diff review is the
|
|
214
|
+
other layer.
|
|
215
|
+
- **Session approval:** a natural-language approval from the user marks the root session, so
|
|
216
|
+
the approved plan does not prompt for every subagent. Questions and past/narrative forms do
|
|
217
|
+
not approve; observations revoke the mark. The approval is bound to the plan path and content
|
|
218
|
+
hash: editing the plan or using a different plan in the session rejects the delegation until
|
|
219
|
+
the user approves again. The binding is created by the first approved delegation, and an
|
|
220
|
+
unrelated approval can re-bind it; present and delegate the approved plan first. `--auto` or
|
|
221
|
+
a non-interactive harness bypasses the session mark, the revision guard and the `ask`; do not
|
|
222
|
+
use it for destructive or approval-required work. The mark lives in memory; a reload or a new
|
|
223
|
+
session asks again. The native `subagent: ask` is the fallback.
|
|
224
|
+
- **Destructive guard:** known file-deletion, database-drop/truncation, volume and
|
|
225
|
+
infrastructure patterns resolve to `ask`, even after an "always" approval. The message is
|
|
226
|
+
generic and never prints secrets. Shell writes remain a residual risk and need the user's
|
|
227
|
+
explicit authorization.
|
|
228
|
+
|
|
229
|
+
`devcomp setup opencode --global` installs the same adapter under
|
|
230
|
+
`~/.config/opencode/plugins/devcomp/`; with `--force` it backs up and removes the legacy
|
|
231
|
+
single-file `devcomp.ts` adapter. A global adapter no-ops when the project has its own copy, and
|
|
232
|
+
`doctor` fails if a legacy global file coexists with it. A direct specialist session
|
|
233
|
+
(`--agent backend-engineer`) has no parent delegation and is not scope-gated; it is an
|
|
234
|
+
explicit escape hatch, like `build`. In OpenCode v2.3.2 the `execute` catalog does not expose
|
|
235
|
+
`subagent`, so nested delegation is not available; re-test on upgrades.
|
|
163
236
|
|
|
164
237
|
The Coordinator leads an operational conversation (scope and observable acceptance) and a
|
|
165
|
-
technical conversation (choices, trade-offs, golden and dark paths). It presents
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
238
|
+
technical conversation (choices, trade-offs, golden and dark paths). It presents the plan and
|
|
239
|
+
asks for approval in natural language. Specialists return findings, evidence and a scope
|
|
240
|
+
confirmation. Local notes capture approvals and handoffs; Engram retains verified durable
|
|
241
|
+
knowledge when enabled and available. See
|
|
169
242
|
[`core/guidelines/coordination.md`](core/guidelines/coordination.md).
|
|
170
243
|
|
|
171
|
-
###
|
|
244
|
+
### Agent modes
|
|
172
245
|
|
|
173
246
|
| Mode | Primary agent | Use |
|
|
174
247
|
|---|---|---|
|
|
@@ -178,23 +251,28 @@ and handoffs; Engram retains verified durable knowledge when enabled and availab
|
|
|
178
251
|
**Migrating an existing install:**
|
|
179
252
|
|
|
180
253
|
1. Run `devcomp update <project>` (without `--keep`). It refreshes skills, roles, bindings,
|
|
181
|
-
canonical content, the managed block, the runtime plugin
|
|
182
|
-
`User guiding`, unknown config keys and a backup of the
|
|
183
|
-
`.companion/local/`.
|
|
184
|
-
2. Run `devcomp setup opencode --global` once per machine
|
|
185
|
-
|
|
254
|
+
canonical content, the managed block, the runtime plugin (`index.ts` + `gates.mjs`) and
|
|
255
|
+
`opencode.json`; it preserves `User guiding`, unknown config keys and a backup of the
|
|
256
|
+
previous config under `.companion/local/`.
|
|
257
|
+
2. Run `devcomp setup opencode --global` once per machine; if a legacy single-file adapter is
|
|
258
|
+
present, rerun with `--force` so it is backed up to `devcomp.ts.bak` and removed before the
|
|
259
|
+
gated adapter is installed. The plugin no-ops in workspaces without
|
|
260
|
+
`.companion/config.json`.
|
|
186
261
|
3. Start a **new** OpenCode session; an existing session keeps its previous agent. `doctor`
|
|
187
262
|
verifies the static setup; real behavior is verified in the new session.
|
|
188
|
-
4.
|
|
189
|
-
|
|
263
|
+
4. Approve a plan in natural language, delegate with `Plan:` and `Scope:`, and check that the
|
|
264
|
+
specialist edits inside `Scope` without a per-subagent prompt. Then try a delegation without
|
|
265
|
+
`Plan:` and an edit outside `Scope`; both must be rejected. Try a destructive command and
|
|
266
|
+
check that a known destructive pattern asks even after an "always" approval; shell writes still
|
|
267
|
+
need an explicit authorization.
|
|
190
268
|
|
|
191
269
|
`devcomp update` replaces framework-owned content by default. Use `--keep` only for a manual
|
|
192
270
|
merge; it preserves bindings and the OpenCode config but also preserves stale behavior. Do not
|
|
193
271
|
use a blanket update as a shortcut around reviewing local customizations.
|
|
194
272
|
|
|
195
|
-
The runtime is the enforcement layer: prompts and permissions are installed by the
|
|
196
|
-
|
|
197
|
-
|
|
273
|
+
The runtime is the enforcement layer: prompts, scopes and permissions are installed by the
|
|
274
|
+
CLI, and the plugin makes the flow observable. A session can still opt out explicitly with
|
|
275
|
+
`build`; that is a user decision, not a silent fallback.
|
|
198
276
|
|
|
199
277
|
## Skills and profiles
|
|
200
278
|
|
|
@@ -267,6 +345,10 @@ steps for your harness. The files remain the source of truth.
|
|
|
267
345
|
screenshot.
|
|
268
346
|
- **No secrets** in the repository, logs, screenshots, or reports.
|
|
269
347
|
- **Least privilege** for subagents; read-only reviewers where the harness allows it.
|
|
348
|
+
- **Scope lock** on implementation subagents; out-of-scope findings are reported, not shipped.
|
|
349
|
+
- **Explicit authorization** for destructive operations, separate from the plan approval; the
|
|
350
|
+
runtime forces the prompt for known patterns even after an "always" approval, and shell
|
|
351
|
+
writes remain a residual risk.
|
|
270
352
|
- **UI reviewed with screenshots** at desktop and mobile widths, using a vision-capable
|
|
271
353
|
model.
|
|
272
354
|
|
package/RELEASE.md
CHANGED
|
@@ -33,7 +33,9 @@ npm publish --dry-run
|
|
|
33
33
|
|
|
34
34
|
`npm run pack:check` must show `bin/`, `src/`, `skills/`, `core/`, `templates/`,
|
|
35
35
|
`adapters/`, `README.md`, and `LICENSE`, and must not include `plannification/`, `test/`,
|
|
36
|
-
`node_modules/`, or local evidence.
|
|
36
|
+
`node_modules/`, or local evidence. The tarball must include
|
|
37
|
+
`templates/artifacts/11-feature-plan.md` and
|
|
38
|
+
`adapters/opencode/plugin/devcomp/gates.mjs`.
|
|
37
39
|
|
|
38
40
|
## 3. Verify an install from the tarball
|
|
39
41
|
|
|
@@ -43,7 +45,7 @@ npm pack --pack-destination "$packdir"
|
|
|
43
45
|
app=$(mktemp -d)
|
|
44
46
|
cd "$app"
|
|
45
47
|
npm init -y
|
|
46
|
-
npm install "$packdir"/development-companion-1.
|
|
48
|
+
npm install "$packdir"/development-companion-1.8.0.tgz
|
|
47
49
|
./node_modules/.bin/devcomp --version
|
|
48
50
|
./node_modules/.bin/devcomp init . --yes --harness opencode --profile web
|
|
49
51
|
./node_modules/.bin/devcomp doctor .
|
|
@@ -55,9 +57,12 @@ For coordination changes, also exercise a fresh agent session: give it a
|
|
|
55
57
|
non-trivial task with a decision to make. On the golden path, the primary
|
|
56
58
|
delegates read-only work, presents options, receives explicit approval, and
|
|
57
59
|
then delegates implementation and verification. On the dark path, withhold
|
|
58
|
-
or deny approval and confirm that no implementation starts.
|
|
59
|
-
|
|
60
|
-
|
|
60
|
+
or deny approval and confirm that no implementation starts. For 1.8.0, also
|
|
61
|
+
verify that a delegation without `Plan:`/`Scope:` is rejected, an edit outside
|
|
62
|
+
`Scope` is denied, and a destructive command asks again after an "always"
|
|
63
|
+
approval. If Engram is unavailable, confirm that local evidence remains and the
|
|
64
|
+
primary does not claim a successful save. The CLI smoke test is not a substitute
|
|
65
|
+
for this check.
|
|
61
66
|
|
|
62
67
|
## 4. Publish
|
|
63
68
|
|
|
@@ -79,7 +84,7 @@ republish immediately. Wait a few minutes and verify:
|
|
|
79
84
|
npm view development-companion version dist-tags
|
|
80
85
|
```
|
|
81
86
|
|
|
82
|
-
The `latest` tag must point to `1.
|
|
87
|
+
The `latest` tag must point to `1.8.0`, not `0.0.0-stage`. If it still points to the
|
|
83
88
|
placeholder after several minutes, check the npmjs.com package page and the Staged
|
|
84
89
|
Packages tab before retrying.
|
|
85
90
|
|
|
@@ -87,9 +92,9 @@ Packages tab before retrying.
|
|
|
87
92
|
|
|
88
93
|
```bash
|
|
89
94
|
cd "$(mktemp -d)"
|
|
90
|
-
npx development-companion@1.
|
|
91
|
-
npx development-companion@1.
|
|
92
|
-
npx development-companion@1.
|
|
95
|
+
npx development-companion@1.8.0 --version
|
|
96
|
+
npx development-companion@1.8.0 init . --yes --harness opencode --profile web
|
|
97
|
+
npx development-companion@1.8.0 doctor .
|
|
93
98
|
```
|
|
94
99
|
|
|
95
100
|
Also verify the package page:
|
|
@@ -101,40 +106,52 @@ https://www.npmjs.com/package/development-companion
|
|
|
101
106
|
## 6. Tag and publish the source release
|
|
102
107
|
|
|
103
108
|
```bash
|
|
104
|
-
git tag -a v1.
|
|
109
|
+
git tag -a v1.8.0 -m "v1.8.0"
|
|
105
110
|
git push origin main --tags
|
|
106
111
|
```
|
|
107
112
|
|
|
108
113
|
Create the release on Codeberg:
|
|
109
114
|
|
|
110
115
|
```text
|
|
111
|
-
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.
|
|
116
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.8.0
|
|
112
117
|
```
|
|
113
118
|
|
|
114
119
|
Include the install command, supported harness tiers and the migration:
|
|
115
120
|
OpenCode's primary is the `coordinator` agent; it cannot edit product code or run shell.
|
|
116
121
|
`devcomp update` sets `default_agent: coordinator`, merges `opencode.json`, installs the
|
|
117
|
-
runtime plugin and the coordinator binding.
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
122
|
+
runtime plugin (`index.ts` + `gates.mjs`) and the coordinator binding.
|
|
123
|
+
`devcomp setup opencode --global` installs the global adapter; `--force` backs up and removes a
|
|
124
|
+
legacy single-file `devcomp.ts`. A feature gets a user-visible plan with a Development plan and
|
|
125
|
+
Test plan; the plan gate requires `Plan:` and `Scope:`, a plan inside the workspace, a top-level
|
|
126
|
+
`Scope:`, an affirmative `Aprobado:` and a delegation scope inside the plan. The scope gate
|
|
127
|
+
keeps `edit`/`write`/`patch`/`apply_patch`/`multiedit` inside `Scope`, and known destructive
|
|
128
|
+
patterns always ask. Approval is natural language; there is no magic phrase. `--rules handoff`
|
|
129
|
+
still creates a local backup and blocks `doctor` until a reviewed merge.
|
|
121
130
|
|
|
122
131
|
Migration steps:
|
|
123
132
|
|
|
124
133
|
1. Follow the review and private backup checklist in
|
|
125
|
-
[Migrating an existing install](README.md#
|
|
134
|
+
[Migrating an existing install](README.md#agent-modes). Keep backups outside the
|
|
126
135
|
repository; never read/copy `.env` files.
|
|
127
|
-
2. `npx development-companion@1.
|
|
136
|
+
2. `npx development-companion@1.8.0 update <project>`. Review the managed-block diff and
|
|
128
137
|
merge customized rules from the backup. The update replaces skills, roles, bindings,
|
|
129
138
|
canonical content, the runtime plugin and `opencode.json`; it preserves `User guiding`,
|
|
130
139
|
unknown config keys and a config backup under `.companion/local/`.
|
|
131
|
-
3. Run `npx development-companion@1.
|
|
132
|
-
outside a meta-repo also load the adapter.
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
140
|
+
3. Run `npx development-companion@1.8.0 setup opencode --global` once per machine so sessions
|
|
141
|
+
outside a meta-repo also load the adapter. If a legacy `devcomp.ts` exists, rerun with
|
|
142
|
+
`--force` so the legacy file is backed up to `devcomp.ts.bak` and removed before the gated
|
|
143
|
+
directory adapter is installed. The plugin no-ops without `.companion/config.json`, and the
|
|
144
|
+
global adapter no-ops when the project has its own copy.
|
|
145
|
+
4. Start a new OpenCode session; an existing session keeps its previous agent. Approve the plan
|
|
146
|
+
in natural language, delegate with `Plan:` and `Scope:`, and verify the specialist edits
|
|
147
|
+
inside the scope without a prompt per subagent. Then verify that a delegation without
|
|
148
|
+
`Plan:`, a delegation whose `Scope` exceeds the plan, a plan without a `Scope:` and an edit
|
|
149
|
+
outside `Scope` are rejected, and that a known destructive command asks even after an
|
|
150
|
+
"always" approval. `build` remains an explicit user escape hatch, not the default.
|
|
151
|
+
5. `npx development-companion@1.8.0 doctor <project>` must pass `default agent`, `coordinator`,
|
|
152
|
+
`runtime plugin`, `runtime gate`, `plan gate`, `scope gate`, `scope lock`,
|
|
153
|
+
`destructive guard`, `plugin coexistence`, `feature flow`, `config instructions`, `config gate` and
|
|
154
|
+
`delivery mode`.
|
|
138
155
|
|
|
139
156
|
Do not recommend `--keep` as a migration shortcut: it preserves stale bindings and config.
|
|
140
157
|
`doctor` checks the static setup, not the model's conversational compliance; verify behavior in
|
package/adapters/README.md
CHANGED
|
@@ -17,7 +17,10 @@ from the agent's workspace (including nested repositories). A preserved rules fi
|
|
|
17
17
|
the companion block or a pending rules merge is a failure, not proof of an active installation.
|
|
18
18
|
OpenCode installs a `coordinator` primary agent and sets `default_agent: coordinator`; legacy
|
|
19
19
|
`default_agent: team-lead`/`build` values are migrated by `devcomp update`. The runtime plugin
|
|
20
|
-
injects the canonical process
|
|
20
|
+
injects the canonical process, enforces the plan gate (`Plan:` + `Scope:` + affirmative
|
|
21
|
+
`Aprobado:` + Test/Verification/Evidence content + table step/agent match + delegation scope
|
|
22
|
+
inside the plan), the scope gate (`edit`/`write`/`patch` inside `Scope`, read-only report paths
|
|
23
|
+
allowed) and the destructive-command guard.
|
|
21
24
|
|
|
22
25
|
## Support tiers
|
|
23
26
|
|
|
@@ -91,10 +94,13 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
|
91
94
|
Pi has no built-in subagents: use the role contract as a prompt template or invoke the
|
|
92
95
|
related skill.
|
|
93
96
|
In OpenCode the `coordinator` primary is the sole user interlocutor: it cannot edit product
|
|
94
|
-
code or run shell, it frames and asks for approval, and it delegates
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
97
|
+
code or run shell, it frames and asks for approval, and it delegates with `Plan:` and `Scope:`.
|
|
98
|
+
After a natural-language approval, the runtime allows an approved delegation without a prompt
|
|
99
|
+
per subagent; the native permission remains the fallback. In the other harnesses the native
|
|
100
|
+
primary follows the process in `AGENTS.md`. The callable team lead is an advisor, not a
|
|
101
|
+
dispatcher. OpenCode sets `default_agent: coordinator`; the other adapters keep the native
|
|
102
|
+
primary. Specialist bindings carry the scope lock; the runtime scope gate is OpenCode-only and
|
|
103
|
+
shell writes remain a documented residual risk.
|
|
98
104
|
|
|
99
105
|
## Limitations by harness
|
|
100
106
|
|
|
@@ -50,26 +50,48 @@ up under `.companion/local/`. An old `default_agent: "team-lead"` or `"build"` i
|
|
|
50
50
|
review the diff and start a new session.
|
|
51
51
|
|
|
52
52
|
The coordinator's binding denies `edit` outside the planning directories and denies `shell`.
|
|
53
|
-
Implementation roles resolve to `ask
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
deny product edits; architect and security deny shell,
|
|
57
|
-
git inspection.
|
|
53
|
+
Implementation roles resolve to `ask` by default, so the user confirms a delegation until the
|
|
54
|
+
session has an approval mark. The runtime plugin allows an approved in-session delegation
|
|
55
|
+
without a prompt per subagent and keeps `ask` as the fallback. Read-only roles (`architect`,
|
|
56
|
+
`qa-engineer`, `cybersecurity-engineer`) deny product edits; architect and security deny shell,
|
|
57
|
+
QA only allows tests, lint, build and git inspection.
|
|
58
58
|
|
|
59
59
|
OpenCode does not route by intent by itself. The coordinator follows the routing and approval
|
|
60
60
|
gates in the coordination guide and is the sole user interlocutor. All generated subagents
|
|
61
61
|
deny `subagent` to avoid nested routing. `build` is available only as an explicit user escape
|
|
62
62
|
hatch, not as the default.
|
|
63
63
|
|
|
64
|
-
The runtime plugin at `.opencode/plugins/devcomp
|
|
65
|
-
every session, including child repositories, and
|
|
66
|
-
|
|
67
|
-
|
|
64
|
+
The runtime plugin at `.opencode/plugins/devcomp/` (with `gates.mjs`) injects the canonical
|
|
65
|
+
files in every session, including child repositories, and enforces the delivery contract:
|
|
66
|
+
|
|
67
|
+
- **Plan gate:** an implementation delegation needs `Plan: <path>` and `Scope: <globs>`; the
|
|
68
|
+
plan must exist inside the workspace, be at least 200 characters, declare a top-level
|
|
69
|
+
`Scope:`, and carry an affirmative `Aprobado:`. The delegation scope must be equal to or
|
|
70
|
+
narrower than the plan.
|
|
71
|
+
- **Scope gate:** `edit`, `write`, `patch`, `apply_patch` and `multiedit` stay inside the
|
|
72
|
+
recorded `Scope` of the child session. It also evaluates the `edit` permission with the
|
|
73
|
+
affected paths. Read-only roles may write their own reports under the planning directory;
|
|
74
|
+
their binding denies product edits.
|
|
75
|
+
- **Session approval:** an affirmative natural-language approval from the user marks the root
|
|
76
|
+
session, so the approved plan does not prompt for every subagent; questions and past/narrative
|
|
77
|
+
forms do not approve, and observations revoke the mark. The approval comes from the user
|
|
78
|
+
prompt, not from a file or a tool. The native prompt is the fallback.
|
|
79
|
+
- **Destructive guard:** known file-deletion, database-drop/truncation, volume and
|
|
80
|
+
infrastructure patterns resolve to `ask`, even after an "always" approval. Wrappers such as
|
|
81
|
+
`bash -c`/`eval` are unwrapped once. The message is generic and never prints secrets. Shell
|
|
82
|
+
writes remain a residual risk and need the user's explicit authorization.
|
|
83
|
+
|
|
84
|
+
`devcomp setup opencode --global` installs the same adapter under
|
|
85
|
+
`~/.config/opencode/plugins/devcomp/`; `--force` backs up and removes a legacy single-file
|
|
86
|
+
`devcomp.ts`. The global adapter no-ops when the project has its own
|
|
87
|
+
`.opencode/plugins/devcomp/index.ts`, and `doctor` fails if a legacy global file coexists with
|
|
88
|
+
it. Verify real behavior in a new session; `devcomp doctor` checks the static setup, not the
|
|
89
|
+
model's compliance.
|
|
68
90
|
|
|
69
91
|
The generated coordinator binding uses `mode: primary`, denies `edit` outside
|
|
70
92
|
`.companion/local/**`, `plannification/**` and `docs/companion/**`, denies `shell`, allows
|
|
71
|
-
read-only subagents during recon and asks for every implementation role
|
|
72
|
-
`src/install.mjs` for the exact template.
|
|
93
|
+
read-only subagents during recon and asks for every implementation role until the session has
|
|
94
|
+
an approval mark. See `src/install.mjs` for the exact template.
|
|
73
95
|
|
|
74
96
|
## Specialist example
|
|
75
97
|
|
|
@@ -156,11 +178,64 @@ README; do not enable nested delegation for the callable advisor.
|
|
|
156
178
|
inside the meta-repo tree inherits the process even when relative `instructions` do not
|
|
157
179
|
resolve. A child cloned outside that tree needs its own `devcomp init` or the global plugin
|
|
158
180
|
(`devcomp setup opencode --global`).
|
|
181
|
+
- A plan must exist inside the workspace, be at least 200 characters, declare a top-level
|
|
182
|
+
`Scope:`, include Test/Verification/Evidence content, and carry an affirmative `Aprobado:` (`sí`, `si`, `yes`, `approved`, `aprobado`,
|
|
183
|
+
`dale`, `adelante`, `ok`). "not yet", "maybe", "wait", "0" and similar are rejected. A
|
|
184
|
+
second plan in the same session needs its own `Aprobado:`; the coordinator must ask again.
|
|
185
|
+
- The delegation `Scope:` must be equal to or narrower than the plan's top-level `Scope:`;
|
|
186
|
+
`src/**` allows `src/ui/**` or `src/file.ts`, but never `**`. A plan without a `Scope:` is
|
|
187
|
+
rejected. A plan with a development table requires `Step:` and a row whose Step and declared
|
|
188
|
+
agent match; only a table-less brief uses the top-level Scope.
|
|
189
|
+
- Session approval accepts common affirmative phrases, including a bare "ok"; questions
|
|
190
|
+
(`¿está aprobado?`), past/narrative forms ("aprobado en otra sesión") and observation
|
|
191
|
+
language ("tengo observaciones", "cambia", "revisa") do not approve. Observation or
|
|
192
|
+
rejection messages clear the mark. A delegation instruction with `Plan:`/`Scope:` never
|
|
193
|
+
approves or clears.
|
|
194
|
+
- The session approval is bound to the plan path and content hash. Editing an approved plan or
|
|
195
|
+
using a different plan in the same session revokes the mark and the plan gate rejects the
|
|
196
|
+
delegation; ask the user to approve the new plan. The binding is created by the first
|
|
197
|
+
approved delegation after the approval message, so present and delegate the approved plan
|
|
198
|
+
first. An unrelated approval can re-bind it; treat only the plan decision as approval. The
|
|
199
|
+
binding and mark live in memory, so a plugin reload, a new session or a restart asks again.
|
|
200
|
+
`--auto` or a non-interactive run bypasses the mark, the revision guard and the `ask`; do not
|
|
201
|
+
use it for destructive or approval-required work. The native `subagent: ask` prompt is the
|
|
202
|
+
fallback.
|
|
203
|
+
- The scope gate covers `edit`, `write`, `patch`, `apply_patch` and `multiedit`. A shell
|
|
204
|
+
command that writes files can evade it; the diff review and the destructive guard are the
|
|
205
|
+
other layers. Hardening shell scope is a follow-up.
|
|
206
|
+
- Read-only roles (`architect`, `qa-engineer`, `cybersecurity-engineer`, `team-lead`) are not
|
|
207
|
+
scope-gated for their report paths (`.companion/local/**`, `plannification/**`,
|
|
208
|
+
`docs/companion/**`), and their binding denies product edits. They cannot rewrite the bound
|
|
209
|
+
approved plan; the plugin denies that edit even inside an allowed report path.
|
|
210
|
+
- The destructive guard is a best-effort pattern list for known forms (including wrappers such
|
|
211
|
+
as `bash -c`/`eval`, `/bin/rm`, PowerShell `Remove-Item`, `terraform apply -destroy`,
|
|
212
|
+
`docker system prune`, `rsync --del`, redirection truncation and `dd of=`). It may ask for a
|
|
213
|
+
safe command or miss an unlisted one; the specialist's report and the user's explicit
|
|
214
|
+
authorization remain the other layer. It never includes the command or secrets in the
|
|
215
|
+
permission message. Shell writes remain a residual risk.
|
|
216
|
+
- Parallel subagents of the same role are mapped to their delegation by the call ID and child
|
|
217
|
+
session ID; if the result does not expose the child ID, exactly one matching delegation may
|
|
218
|
+
be claimed. More than one is ambiguous and fails closed. A child continued with a follow-up
|
|
219
|
+
delegation keeps its first scope; start a new child for a different scope.
|
|
220
|
+
- A global adapter directory no-ops when the project has its own
|
|
221
|
+
`.opencode/plugins/devcomp/index.ts`, so hooks are not duplicated. A legacy flat
|
|
222
|
+
`~/.config/opencode/plugins/devcomp.ts` is not safe to keep next to the local plugin;
|
|
223
|
+
`doctor` fails and `devcomp setup opencode --global --force` backs it up and removes it.
|
|
224
|
+
- A **direct specialist session** (`opencode run --agent backend-engineer`, or an explicit
|
|
225
|
+
agent switch) has no parent delegation and is not scope-gated. It is an explicit escape
|
|
226
|
+
hatch like `build`, not the default flow; the user chooses it and the plan/scope contract is
|
|
227
|
+
then documented in the prompt or the session notes.
|
|
228
|
+
- **Nested `subagent` via `execute`:** in OpenCode v2.3.2 the Code Mode catalog exposes only
|
|
229
|
+
`opencode` and `browser`; `tools.subagent` is not callable (the call returns
|
|
230
|
+
`Unknown tool 'subagent'`). Re-test after an OpenCode upgrade. If a future version exposes
|
|
231
|
+
it, the permission hook can still stop the action, but the plan gate cannot inspect the
|
|
232
|
+
nested delegation prompt; treat it as a residual until the adapter hooks that surface.
|
|
159
233
|
- Subagents start with fresh context when invoked. They read the planning directory and the
|
|
160
234
|
repository; they do not inherit the primary chat. Existing sessions keep their previous
|
|
161
235
|
selected agent; start a new session after migration.
|
|
162
236
|
- Permissions are enforced by the harness: the coordinator cannot edit product code or run
|
|
163
|
-
shell, implementation delegation asks the
|
|
237
|
+
shell, implementation delegation asks until the session approval is observed, and read-only
|
|
238
|
+
roles cannot touch product.
|
|
164
239
|
|
|
165
240
|
## References
|
|
166
241
|
|