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.
@@ -37,24 +37,61 @@ Verify with the `skill` tool or ask OpenCode to list available skills.
37
37
 
38
38
  `devcomp init` writes one Markdown agent per role in `.opencode/agents/`:
39
39
 
40
+ - `coordinator.md` — `mode: primary`, the default agent. It can read, search and write
41
+ frames under the planning directory, but it cannot edit product code or run shell. It
42
+ delegates with the native `subagent` tool.
40
43
  - `team-lead.md` — callable `mode: subagent` for advice on scope and sequencing.
41
- - The 11 specialists — `mode: subagent`, launched directly by the native primary.
42
-
43
- It does not set `default_agent` or write `.opencode/opencode.json`: native Build
44
- retains its tools and applies the Team Lead workflow from `AGENTS.md`. Existing
45
- OpenCode configuration is preserved. For an old install with
46
- `default_agent: "team-lead"`, remove that field or set `"build"` after reviewing
47
- the existing configuration; review and refresh the old binding, then open a new
48
- session. Existing project rules should be merged by the harness agent, or placed
49
- in a backed-up pending handoff with `init --rules handoff`.
50
-
51
- OpenCode does not route by intent by itself. The primary follows the routing and
52
- approval gates in the coordination guide and is the sole user interlocutor. The
53
- callable advisor denies code edits and shell. All generated roles deny `subagent`
54
- to avoid nested routing; the native Build agent keeps its delegation tools.
55
-
56
- Instructions alone cannot guarantee that a model followed the workflow: verify real
57
- agent behavior in a new session, not only `devcomp doctor`.
44
+ - The 11 specialists — `mode: subagent`, launched by the coordinator.
45
+
46
+ `devcomp init`/`update` also writes/merges `opencode.json` with
47
+ `default_agent: "coordinator"`, the five canonical instruction files, a global `git push`
48
+ denial and a read-only `explore`. Unknown keys are preserved and the previous file is backed
49
+ up under `.companion/local/`. An old `default_agent: "team-lead"` or `"build"` is replaced;
50
+ review the diff and start a new session.
51
+
52
+ The coordinator's binding denies `edit` outside the planning directories and denies `shell`.
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
+
59
+ OpenCode does not route by intent by itself. The coordinator follows the routing and approval
60
+ gates in the coordination guide and is the sole user interlocutor. All generated subagents
61
+ deny `subagent` to avoid nested routing. `build` is available only as an explicit user escape
62
+ hatch, not as the default.
63
+
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.
90
+
91
+ The generated coordinator binding uses `mode: primary`, denies `edit` outside
92
+ `.companion/local/**`, `plannification/**` and `docs/companion/**`, denies `shell`, allows
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.
58
95
 
59
96
  ## Specialist example
60
97
 
@@ -137,13 +174,68 @@ README; do not enable nested delegation for the callable advisor.
137
174
 
138
175
  - OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
139
176
  binding thin and put durable policy in `core/`.
140
- - Install separately from the working repository root when an app is a nested repository;
141
- the parent repo's rules, skills and agent definitions may not be discovered.
142
- - The callable lead starts with fresh context when invoked. It reads
143
- `.companion/local/` and the repository; it does not inherit the primary chat. Existing
144
- sessions keep their previous selected agent; start a new session after migration.
145
- - Permissions are enforced by the harness; the generated binding blocks direct code edits
146
- and shell commands from the team lead.
177
+ - The runtime plugin searches upward for `.companion/config.json`, so a child repository
178
+ inside the meta-repo tree inherits the process even when relative `instructions` do not
179
+ resolve. A child cloned outside that tree needs its own `devcomp init` or the global plugin
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.
233
+ - Subagents start with fresh context when invoked. They read the planning directory and the
234
+ repository; they do not inherit the primary chat. Existing sessions keep their previous
235
+ selected agent; start a new session after migration.
236
+ - Permissions are enforced by the harness: the coordinator cannot edit product code or run
237
+ shell, implementation delegation asks until the session approval is observed, and read-only
238
+ roles cannot touch product.
147
239
 
148
240
  ## References
149
241