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 +82 -0
- package/README.md +133 -57
- package/RELEASE.md +49 -32
- package/adapters/README.md +15 -4
- package/adapters/opencode/README.md +116 -24
- package/adapters/opencode/plugin/devcomp/gates.mjs +688 -0
- package/adapters/opencode/plugin/devcomp/index.ts +603 -0
- 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 +171 -0
- 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 +211 -19
- package/src/content.mjs +16 -0
- package/src/install.mjs +397 -44
- 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 +117 -8
|
@@ -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
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
`default_agent: "team-lead"
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
-
|
|
141
|
-
the
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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
|
|