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
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: **
|
|
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
|
|
96
|
-
| `devcomp update [dir]` | Refresh
|
|
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.
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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`
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
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
|
-
###
|
|
244
|
+
### Agent modes
|
|
162
245
|
|
|
163
246
|
| Mode | Primary agent | Use |
|
|
164
247
|
|---|---|---|
|
|
165
|
-
| **
|
|
166
|
-
| **
|
|
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
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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.
|
|
48
|
+
npm install "$packdir"/development-companion-1.8.0.tgz
|
|
47
49
|
./node_modules/.bin/devcomp --version
|
|
48
50
|
./node_modules/.bin/devcomp init . --yes --harness opencode --profile web
|
|
49
51
|
./node_modules/.bin/devcomp doctor .
|
|
@@ -55,9 +57,12 @@ For coordination changes, also exercise a fresh agent session: give it a
|
|
|
55
57
|
non-trivial task with a decision to make. On the golden path, the primary
|
|
56
58
|
delegates read-only work, presents options, receives explicit approval, and
|
|
57
59
|
then delegates implementation and verification. On the dark path, withhold
|
|
58
|
-
or deny approval and confirm that no implementation starts.
|
|
59
|
-
|
|
60
|
-
|
|
60
|
+
or deny approval and confirm that no implementation starts. For 1.8.0, also
|
|
61
|
+
verify that a delegation without `Plan:`/`Scope:` is rejected, an edit outside
|
|
62
|
+
`Scope` is denied, and a destructive command asks again after an "always"
|
|
63
|
+
approval. If Engram is unavailable, confirm that local evidence remains and the
|
|
64
|
+
primary does not claim a successful save. The CLI smoke test is not a substitute
|
|
65
|
+
for this check.
|
|
61
66
|
|
|
62
67
|
## 4. Publish
|
|
63
68
|
|
|
@@ -79,7 +84,7 @@ republish immediately. Wait a few minutes and verify:
|
|
|
79
84
|
npm view development-companion version dist-tags
|
|
80
85
|
```
|
|
81
86
|
|
|
82
|
-
The `latest` tag must point to `1.
|
|
87
|
+
The `latest` tag must point to `1.8.0`, not `0.0.0-stage`. If it still points to the
|
|
83
88
|
placeholder after several minutes, check the npmjs.com package page and the Staged
|
|
84
89
|
Packages tab before retrying.
|
|
85
90
|
|
|
@@ -87,9 +92,9 @@ Packages tab before retrying.
|
|
|
87
92
|
|
|
88
93
|
```bash
|
|
89
94
|
cd "$(mktemp -d)"
|
|
90
|
-
npx development-companion@1.
|
|
91
|
-
npx development-companion@1.
|
|
92
|
-
npx development-companion@1.
|
|
95
|
+
npx development-companion@1.8.0 --version
|
|
96
|
+
npx development-companion@1.8.0 init . --yes --harness opencode --profile web
|
|
97
|
+
npx development-companion@1.8.0 doctor .
|
|
93
98
|
```
|
|
94
99
|
|
|
95
100
|
Also verify the package page:
|
|
@@ -101,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.
|
|
109
|
+
git tag -a v1.8.0 -m "v1.8.0"
|
|
105
110
|
git push origin main --tags
|
|
106
111
|
```
|
|
107
112
|
|
|
108
113
|
Create the release on Codeberg:
|
|
109
114
|
|
|
110
115
|
```text
|
|
111
|
-
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.
|
|
116
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.8.0
|
|
112
117
|
```
|
|
113
118
|
|
|
114
|
-
Include the install command, supported harness tiers and migration
|
|
115
|
-
OpenCode's primary
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
|
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.
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
|
140
|
-
|
|
141
|
-
|
|
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
|
|
package/adapters/README.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
|