development-companion 1.6.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,87 @@
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
+
59
+ ## 1.7.0
60
+
61
+ - **Forced flow in OpenCode.** `devcomp init`/`update` now install a `coordinator` primary
62
+ agent and set `default_agent: coordinator`. The coordinator cannot edit product code or run
63
+ shell: it writes the frame under the planning directory and delegates. Implementation
64
+ subagents always resolve to `ask`, so the user confirms the delegation with the native
65
+ permission prompt. There is no magic approval phrase; approval is natural language.
66
+ - **Runtime adapter.** A dependency-free OpenCode plugin injects the five canonical files into
67
+ every session, including sessions opened inside a child repository, and forces the delegation
68
+ prompt even after a saved "always" approval. `devcomp setup opencode --global` installs it
69
+ under `~/.config/opencode/plugins/devcomp.ts` for every project.
70
+ - **Config merge.** `devcomp update` merges `opencode.json` with `default_agent: coordinator`,
71
+ the canonical instructions, a global `git push` denial and a read-only `explore`. Unknown
72
+ keys are preserved; the previous file is backed up under `.companion/local/`.
73
+ - **Read-only recon.** `architect`, `qa-engineer` and `cybersecurity-engineer` bindings deny
74
+ product edits; architect/security deny shell, QA only allows tests, lint, build and git
75
+ inspection.
76
+ - **Doctor.** Verifies `default_agent=coordinator`, the coordinator binding and permissions,
77
+ the runtime plugin and gate, the canonical instructions, the `git push`/explore rules, and
78
+ the managed template. It fails on the old native-Build default and on missing plugins.
79
+ - **New role contract.** `core/roles/coordinator.md`; `team-lead` remains a read-only advisor.
80
+ - **Notifications with the subagent-heavy flow.** The documented OpenCode notify recipe is
81
+ updated to debounce the parent idle turn (`notify_idle_settle_ms`, default 10 s), so a
82
+ subagent report does not produce one toast per subagent; child and archived sessions are
83
+ silent, while questions, permissions and errors remain immediate.
84
+
3
85
  ## 1.6.0
4
86
 
5
87
  - `devcomp update` replaces framework-owned skills, roles, bindings, and canonical
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
 
@@ -89,18 +89,28 @@ The managed block is delimited by `<!-- development-companion:start -->` and
89
89
 
90
90
  | Command | Purpose |
91
91
  |---|---|
92
- | `devcomp init [dir]` | Install the process, skills, roles, rules, and manifest. |
92
+ | `devcomp init [dir]` | Install the process, skills, roles, rules, runtime adapter, and manifest. |
93
93
  | `devcomp add <skill\|role\|profile> <name>` | Add content to an existing install. |
94
+ | `devcomp setup opencode --global` | Install the OpenCode runtime adapter for every project. |
94
95
  | `devcomp scaffold [dir]` | Generate the TypeScript reference monorepo. |
95
- | `devcomp doctor [dir]` | Check skills, roles, rules, branching, and Engram. |
96
- | `devcomp update [dir]` | Refresh installed content without overwriting local edits. |
96
+ | `devcomp doctor [dir]` | Check content, the coordinator binding, the runtime gates (plan, scope, destructive), scope lock, feature flow, and the config gate. |
97
+ | `devcomp update [dir]` | Refresh framework content, bindings, plugin, and OpenCode config. |
97
98
 
98
99
  ## The process
99
100
 
100
- **New in 1.5.0:** direct specialist delegation through the primary agent,
101
- explicit approval of scope and technical approach, and evidence for golden
102
- and dark paths with optional Engram persistence. Existing installations should
103
- follow the [migration steps](#working-modes).
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.
104
114
 
105
115
  The process exists to ship working software, not to produce documents. It is a loop:
106
116
 
@@ -120,10 +130,44 @@ skill.
120
130
 
121
131
  For a small change, the process collapses to the workflow in `core/workflow.md`.
122
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
+
123
166
  ## Roles
124
167
 
125
168
  | Role | Primary question |
126
169
  |---|---|
170
+ | Coordinator | What is the smallest approved slice, which role owns it, and what evidence closes it? |
127
171
  | Team Lead | What is the shortest path to a verified delivery? |
128
172
  | Architect | What boundaries and trade-offs make this correct and evolvable? |
129
173
  | Cybersecurity Engineer | What can be attacked, and what evidence proves the control works? |
@@ -144,63 +188,91 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
144
188
 
145
189
  ### Orchestration in OpenCode
146
190
 
147
- `devcomp init` preserves OpenCode's native Build default and any existing OpenCode config.
148
- The native primary acts as Coordinator and is the only agent that addresses the user.
149
- It launches applicable roles directly for non-trivial work: read-only input, approved
150
- implementation, independent verification, and authorized release. The callable
151
- `team-lead` is an advisor; its binding denies shell and subdelegation and restricts edits
152
- to companion notes.
153
-
154
- The Coordinator leads an operational conversation (scope and observable acceptance)
155
- and a technical conversation (choices, trade-offs, golden paths and dark paths). It
156
- records explicit approval before implementation. Specialists return findings and evidence
157
- to the Coordinator. Local notes capture approvals and handoffs; Engram retains relevant,
158
- verified durable knowledge when enabled and available. See
191
+ `devcomp init`/`update` installs a `coordinator` primary agent and sets
192
+ `default_agent: coordinator` in `opencode.json`. The coordinator can read, search, ask and
193
+ write frames under `plannification/` or `.companion/local/`; it cannot edit product code or
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.
236
+
237
+ The Coordinator leads an operational conversation (scope and observable acceptance) and a
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
159
242
  [`core/guidelines/coordination.md`](core/guidelines/coordination.md).
160
243
 
161
- ### Working modes
244
+ ### Agent modes
162
245
 
163
246
  | Mode | Primary agent | Use |
164
247
  |---|---|---|
165
- | **Short workflow** | native primary | Routine changes in scope that introduce no new decision. |
166
- | **Coordinated** | native primary | Direct specialist delegation for non-trivial work; the primary owns gates and communication. |
167
- | **Single-agent fallback** | native primary | Disclose unavailable delegation; never claim independent review. |
168
- | **Legacy (do not use)** | `team-lead` as primary | A read-only lead blocks direct implementation and confuses the workflow. |
248
+ | **Coordinated** | `coordinator` | Default for every project; the coordinator frames, asks, delegates and verifies. |
249
+ | **Explicit escape hatch** | `build` | A routine change the user chooses to run directly; not the default and not a coordinator shortcut. |
169
250
 
170
251
  **Migrating an existing install:**
171
252
 
172
- Run the following with Development Companion 1.5.0 (use `node bin/devcomp.mjs`
173
- from the source checkout to verify before publication).
174
-
175
- 1. Review local customizations and make a private backup outside the repository of
176
- `AGENTS.md`, `CLAUDE.md`, `.companion/core/`, `.companion/roles/`, `.agents/skills/`,
177
- `.opencode/agents/` and existing OpenCode configuration. Do not publish the backup
178
- or read/copy `.env` files.
179
- 2. `devcomp update <project>` (without `--force`). This installs missing content,
180
- including the coordination guide, and refreshes the managed block while keeping
181
- existing skills, core documents, roles and bindings. Review the diff, recover
182
- any custom text from inside the old managed block, and merge changes manually
183
- into preserved files that conflict with the new coordination contract.
184
- 3. In the existing `opencode.json`/`opencode.jsonc` at the project root or in `.opencode/`,
185
- remove `"default_agent": "team-lead"` or set it to `"build"`, preserving other settings.
186
- 4. If `.opencode/agents/team-lead.md` uses `mode: primary` or allows subdelegation,
187
- merge the updated binding and role manually. Or, after backing up both files,
188
- regenerate them with `devcomp add role team-lead --target <project> --force`.
189
- This command overwrites both files without backup. Reapply compatible customizations;
190
- keep `mode: subagent` and deny `subagent`. Apply step 3 only if the old default exists.
191
- 5. Start a new OpenCode session (the current one keeps the old agent).
192
- 6. `devcomp doctor <project>` checks the installed process, rules and OpenCode binding.
193
- Then use a new session to verify actual behavior: the primary delegates and asks
194
- for approval; withhold or reject it and check that implementation does not start.
195
-
196
- Do not use a blanket `update --force` as a migration shortcut: it deletes installed
197
- skill directories and replaces roles, core documents and bindings, including local
198
- customizations. `doctor` checks the managed process block; separately review any
199
- project-specific instructions outside it for conflicts.
200
-
201
- The CLI installs prompts and permissions; it does not enforce conversational approval
202
- as a runtime interlock. A harness may display that subagents ran even though only the
203
- Coordinator addresses the user.
253
+ 1. Run `devcomp update <project>` (without `--keep`). It refreshes skills, roles, bindings,
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`.
261
+ 3. Start a **new** OpenCode session; an existing session keeps its previous agent. `doctor`
262
+ verifies the static setup; real behavior is verified in the new session.
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.
268
+
269
+ `devcomp update` replaces framework-owned content by default. Use `--keep` only for a manual
270
+ merge; it preserves bindings and the OpenCode config but also preserves stale behavior. Do not
271
+ use a blanket update as a shortcut around reviewing local customizations.
272
+
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.
204
276
 
205
277
  ## Skills and profiles
206
278
 
@@ -273,6 +345,10 @@ steps for your harness. The files remain the source of truth.
273
345
  screenshot.
274
346
  - **No secrets** in the repository, logs, screenshots, or reports.
275
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.
276
352
  - **UI reviewed with screenshots** at desktop and mobile widths, using a vision-capable
277
353
  model.
278
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,44 +106,56 @@ 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.5.0 -m "v1.5.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.5.0
116
+ https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.8.0
112
117
  ```
113
118
 
114
- Include the install command, supported harness tiers and migration from earlier releases:
115
- OpenCode's primary delegates directly. Existing projects must review bindings with
116
- nested delegation and any legacy `default_agent`. `--rules handoff` creates a
117
- local backup and blocks `doctor` until a human-reviewed merge. Do not commit pending
118
- rules while their backup exists only on the installing machine.
119
+ Include the install command, supported harness tiers and the migration:
120
+ OpenCode's primary is the `coordinator` agent; it cannot edit product code or run shell.
121
+ `devcomp update` sets `default_agent: coordinator`, merges `opencode.json`, installs the
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.
119
130
 
120
131
  Migration steps:
121
132
 
122
133
  1. Follow the review and private backup checklist in
123
- [Migrating a legacy install](README.md#working-modes). Keep backups outside the
134
+ [Migrating an existing install](README.md#agent-modes). Keep backups outside the
124
135
  repository; never read/copy `.env` files.
125
- 2. `npx development-companion@1.5.0 update <project>` **without `--force`**. Review the
126
- managed-block diff and merge customized rules from the backup. Compare preserved
127
- skills, core documents, roles and bindings with the release; merge needed updates.
128
- 3. Remove `"default_agent": "team-lead"` or set it to `"build"` in the existing
129
- root or `.opencode/` `opencode.json(c)`, preserving other settings.
130
- 4. Only after backing up and reviewing the lead role and binding, regenerate them
131
- if the binding still says `mode: primary` or allows subdelegation:
132
- `npx development-companion@1.5.0 add role team-lead --target <project> --force`.
133
- This overwrites both files without backup; merge compatible customizations afterward.
134
- 5. Start a new OpenCode session. If you need to roll back the rules, restore
135
- the reviewed backups; installing an older CLI does not revert generated files.
136
- 6. `npx development-companion@1.5.0 doctor <project>` must pass `default agent` and
136
+ 2. `npx development-companion@1.8.0 update <project>`. Review the managed-block diff and
137
+ merge customized rules from the backup. The update replaces skills, roles, bindings,
138
+ canonical content, the runtime plugin and `opencode.json`; it preserves `User guiding`,
139
+ unknown config keys and a config backup under `.companion/local/`.
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
137
154
  `delivery mode`.
138
155
 
139
- Do not recommend blanket `update --force`: it deletes skill directories and overwrites
140
- customized content. `doctor` checks the managed block, not all project-specific rules;
141
- review those separately for conflicts.
156
+ Do not recommend `--keep` as a migration shortcut: it preserves stale bindings and config.
157
+ `doctor` checks the static setup, not the model's conversational compliance; verify behavior in
158
+ a new session.
142
159
 
143
160
  ## 7. If something is wrong
144
161
 
@@ -15,7 +15,12 @@ agent bindings where the harness supports them.
15
15
  It also installs canonical process documents in `.companion/core/`. Run `devcomp doctor`
16
16
  from the agent's workspace (including nested repositories). A preserved rules file without
17
17
  the companion block or a pending rules merge is a failure, not proof of an active installation.
18
- OpenCode retains its native primary agent; legacy `default_agent: team-lead` needs migration.
18
+ OpenCode installs a `coordinator` primary agent and sets `default_agent: coordinator`; legacy
19
+ `default_agent: team-lead`/`build` values are migrated by `devcomp update`. The runtime plugin
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.
19
24
 
20
25
  ## Support tiers
21
26
 
@@ -72,6 +77,7 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
72
77
 
73
78
  | Role | OpenCode | Claude Code | Codex |
74
79
  |---|---|---|---|
80
+ | Coordinator | `.opencode/agents/coordinator.md` | — | — |
75
81
  | Team Lead | `.opencode/agents/team-lead.md` | `.claude/agents/team-lead.md` | `.codex/agents/team-lead.toml` |
76
82
  | Architect | `.opencode/agents/architect.md` | `.claude/agents/architect.md` | `.codex/agents/architect.toml` |
77
83
  | Cybersecurity | `.opencode/agents/cybersecurity-engineer.md` | `.claude/agents/cybersecurity-engineer.md` | `.codex/agents/cybersecurity-engineer.toml` |
@@ -87,9 +93,14 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
87
93
 
88
94
  Pi has no built-in subagents: use the role contract as a prompt template or invoke the
89
95
  related skill.
90
- The harness-native primary is the sole user interlocutor and delegates directly through
91
- the process in `AGENTS.md`. The callable team lead is an advisor, not a dispatcher.
92
- OpenCode does not change its default agent.
96
+ In OpenCode the `coordinator` primary is the sole user interlocutor: it cannot edit product
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.
93
104
 
94
105
  ## Limitations by harness
95
106