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 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: **12 roles**, **18 skills**, and
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 plugin, and the config gate. |
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.7.0:** a forced flow in OpenCode. The primary is the `coordinator` agent
102
- (`default_agent: coordinator`); it cannot edit product code or run shell, so it must frame,
103
- ask for approval and delegate. A runtime plugin injects the canonical process in every
104
- session, including child repositories, and forces a user permission prompt before an
105
- implementation subagent starts. Approval is natural language; there is no magic phrase.
106
- `devcomp update` migrates existing installations.
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 always resolve to `ask`, and the runtime plugin forces the
155
- user permission prompt even after a saved "always". `build` remains available only as an
156
- explicit user escape hatch (`--agent build` or an agent switch).
157
-
158
- The plugin at `.opencode/plugins/devcomp/index.ts` searches upward for the nearest
159
- `.companion/config.json` and injects the five canonical files at runtime. It fixes the child
160
- repository case: OpenCode discovers the meta-repo config, bindings and plugins, but relative
161
- `instructions` do not resolve below the child project root. `devcomp setup opencode --global`
162
- installs the same adapter under `~/.config/opencode/plugins/devcomp.ts`.
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 a one-page
166
- frame and asks for approval in natural language; the user's approval and the native delegation
167
- prompt are the gate. Specialists return findings and evidence. Local notes capture approvals
168
- and handoffs; Engram retains verified durable knowledge when enabled and available. See
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
- ### Working modes
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 and `opencode.json`; it preserves
182
- `User guiding`, unknown config keys and a backup of the previous config under
183
- `.companion/local/`.
184
- 2. Run `devcomp setup opencode --global` once per machine, so sessions outside a meta-repo also
185
- load the adapter. The plugin no-ops in workspaces without `.companion/config.json`.
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. Withhold or reject the implementation permission prompt and check that no product file is
189
- edited. Then approve an implementation delegation and check that the specialist edits.
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 CLI, and
196
- the plugin plus the native permission prompt make the flow observable. A session can still
197
- opt out explicitly with `build`; that is a user decision, not a silent fallback.
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.5.0.tgz
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. If Engram is
59
- unavailable, confirm that local evidence remains and the primary does not
60
- claim a successful save. The CLI smoke test is not a substitute for this check.
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.5.0`, not `0.0.0-stage`. If it still points to the
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.5.0 --version
91
- npx development-companion@1.5.0 init . --yes --harness opencode --profile web
92
- npx development-companion@1.5.0 doctor .
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.7.0 -m "v1.7.0"
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.7.0
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. `devcomp setup opencode --global` installs the
118
- global adapter. The implementation delegation prompt is the approval gate; there is no magic
119
- phrase. `--rules handoff` still creates a local backup and blocks `doctor` until a reviewed
120
- merge.
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#working-modes). Keep backups outside the
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.7.0 update <project>`. Review the managed-block diff and
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.7.0 setup opencode --global` once per machine so sessions
132
- outside a meta-repo also load the adapter. The plugin no-ops without `.companion/config.json`.
133
- 4. Start a new OpenCode session; an existing session keeps its previous agent. Withhold the
134
- implementation delegation prompt and verify no product file changes; approve it and verify
135
- the specialist edits. `build` remains an explicit user escape hatch, not the default.
136
- 5. `npx development-companion@1.7.0 doctor <project>` must pass `default agent`, `coordinator`,
137
- `runtime plugin`, `runtime gate`, `config instructions`, `config gate` and `delivery mode`.
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
@@ -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 and forces the implementation delegation prompt.
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 through the runtime
95
- permission prompt. In the other harnesses the native primary follows the process in
96
- `AGENTS.md`. The callable team lead is an advisor, not a dispatcher. OpenCode sets
97
- `default_agent: coordinator`; the other adapters keep the native primary.
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`, so the user confirms every implementation delegation
54
- with OpenCode's permission prompt. The runtime plugin forces that prompt even after a saved
55
- "always" approval. Read-only roles (`architect`, `qa-engineer`, `cybersecurity-engineer`)
56
- deny product edits; architect and security deny shell, QA only allows tests, lint, build and
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/index.ts` injects the canonical files in
65
- every session, including child repositories, and forces the delegation prompt. Verify real
66
- behavior in a new session; `devcomp doctor` checks the static setup, not the model's
67
- compliance.
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. See
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 user, and read-only roles cannot touch product.
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