development-companion 1.5.0 → 1.7.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 +43 -0
- package/README.md +49 -55
- package/RELEASE.md +25 -25
- package/adapters/README.md +9 -4
- package/adapters/opencode/README.md +41 -24
- package/adapters/opencode/plugin/devcomp/index.ts +123 -0
- package/core/roles/coordinator.md +113 -0
- package/package.json +2 -2
- package/src/cli.mjs +276 -53
- package/src/content.mjs +16 -0
- package/src/install.mjs +334 -48
- package/src/rules.mjs +136 -6
- package/templates/rules/AGENTS.block.md +154 -65
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,48 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.7.0
|
|
4
|
+
|
|
5
|
+
- **Forced flow in OpenCode.** `devcomp init`/`update` now install a `coordinator` primary
|
|
6
|
+
agent and set `default_agent: coordinator`. The coordinator cannot edit product code or run
|
|
7
|
+
shell: it writes the frame under the planning directory and delegates. Implementation
|
|
8
|
+
subagents always resolve to `ask`, so the user confirms the delegation with the native
|
|
9
|
+
permission prompt. There is no magic approval phrase; approval is natural language.
|
|
10
|
+
- **Runtime adapter.** A dependency-free OpenCode plugin injects the five canonical files into
|
|
11
|
+
every session, including sessions opened inside a child repository, and forces the delegation
|
|
12
|
+
prompt even after a saved "always" approval. `devcomp setup opencode --global` installs it
|
|
13
|
+
under `~/.config/opencode/plugins/devcomp.ts` for every project.
|
|
14
|
+
- **Config merge.** `devcomp update` merges `opencode.json` with `default_agent: coordinator`,
|
|
15
|
+
the canonical instructions, a global `git push` denial and a read-only `explore`. Unknown
|
|
16
|
+
keys are preserved; the previous file is backed up under `.companion/local/`.
|
|
17
|
+
- **Read-only recon.** `architect`, `qa-engineer` and `cybersecurity-engineer` bindings deny
|
|
18
|
+
product edits; architect/security deny shell, QA only allows tests, lint, build and git
|
|
19
|
+
inspection.
|
|
20
|
+
- **Doctor.** Verifies `default_agent=coordinator`, the coordinator binding and permissions,
|
|
21
|
+
the runtime plugin and gate, the canonical instructions, the `git push`/explore rules, and
|
|
22
|
+
the managed template. It fails on the old native-Build default and on missing plugins.
|
|
23
|
+
- **New role contract.** `core/roles/coordinator.md`; `team-lead` remains a read-only advisor.
|
|
24
|
+
- **Notifications with the subagent-heavy flow.** The documented OpenCode notify recipe is
|
|
25
|
+
updated to debounce the parent idle turn (`notify_idle_settle_ms`, default 10 s), so a
|
|
26
|
+
subagent report does not produce one toast per subagent; child and archived sessions are
|
|
27
|
+
silent, while questions, permissions and errors remain immediate.
|
|
28
|
+
|
|
29
|
+
## 1.6.0
|
|
30
|
+
|
|
31
|
+
- `devcomp update` replaces framework-owned skills, roles, bindings, and canonical
|
|
32
|
+
content by default. Use `--keep` to preserve them for a manual merge.
|
|
33
|
+
- `AGENTS.md` is now a complete managed template plus a `# User guiding` section.
|
|
34
|
+
Updates preserve User guiding verbatim and always write `AGENTS.md.bak`.
|
|
35
|
+
- Existing legacy `AGENTS.md` files are migrated automatically (old content under
|
|
36
|
+
User guiding). Ambiguous structures leave a merge-pending notice and `doctor`
|
|
37
|
+
fails until an agent merges the backup.
|
|
38
|
+
- `doctor` verifies canonical, role, and skill content against the package, plus
|
|
39
|
+
the template version and the presence of User guiding.
|
|
40
|
+
|
|
41
|
+
## 1.5.1
|
|
42
|
+
|
|
43
|
+
- `devcomp update --dry-run` now reports the plan and writes nothing instead of
|
|
44
|
+
silently updating the installation.
|
|
45
|
+
|
|
3
46
|
## 1.5.0
|
|
4
47
|
|
|
5
48
|
- The native primary coordinates delivery, directly invokes specialists, and is
|
package/README.md
CHANGED
|
@@ -89,18 +89,21 @@ 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 plugin, 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
|
-
and
|
|
103
|
-
|
|
101
|
+
**New in 1.7.0:** a forced flow in OpenCode. The primary is the `coordinator` agent
|
|
102
|
+
(`default_agent: coordinator`); it cannot edit product code or run shell, so it must frame,
|
|
103
|
+
ask for approval and delegate. A runtime plugin injects the canonical process in every
|
|
104
|
+
session, including child repositories, and forces a user permission prompt before an
|
|
105
|
+
implementation subagent starts. Approval is natural language; there is no magic phrase.
|
|
106
|
+
`devcomp update` migrates existing installations.
|
|
104
107
|
|
|
105
108
|
The process exists to ship working software, not to produce documents. It is a loop:
|
|
106
109
|
|
|
@@ -124,6 +127,7 @@ For a small change, the process collapses to the workflow in `core/workflow.md`.
|
|
|
124
127
|
|
|
125
128
|
| Role | Primary question |
|
|
126
129
|
|---|---|
|
|
130
|
+
| Coordinator | What is the smallest approved slice, which role owns it, and what evidence closes it? |
|
|
127
131
|
| Team Lead | What is the shortest path to a verified delivery? |
|
|
128
132
|
| Architect | What boundaries and trade-offs make this correct and evolvable? |
|
|
129
133
|
| Cybersecurity Engineer | What can be attacked, and what evidence proves the control works? |
|
|
@@ -144,63 +148,53 @@ The canonical principles, process, workflow, quality gates, and guidelines are i
|
|
|
144
148
|
|
|
145
149
|
### Orchestration in OpenCode
|
|
146
150
|
|
|
147
|
-
`devcomp init`
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
The
|
|
155
|
-
and
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
151
|
+
`devcomp init`/`update` installs a `coordinator` primary agent and sets
|
|
152
|
+
`default_agent: coordinator` in `opencode.json`. The coordinator can read, search, ask and
|
|
153
|
+
write frames under `plannification/` or `.companion/local/`; it cannot edit product code or
|
|
154
|
+
run shell. Implementation subagents always resolve to `ask`, and the runtime plugin forces the
|
|
155
|
+
user permission prompt even after a saved "always". `build` remains available only as an
|
|
156
|
+
explicit user escape hatch (`--agent build` or an agent switch).
|
|
157
|
+
|
|
158
|
+
The plugin at `.opencode/plugins/devcomp/index.ts` searches upward for the nearest
|
|
159
|
+
`.companion/config.json` and injects the five canonical files at runtime. It fixes the child
|
|
160
|
+
repository case: OpenCode discovers the meta-repo config, bindings and plugins, but relative
|
|
161
|
+
`instructions` do not resolve below the child project root. `devcomp setup opencode --global`
|
|
162
|
+
installs the same adapter under `~/.config/opencode/plugins/devcomp.ts`.
|
|
163
|
+
|
|
164
|
+
The Coordinator leads an operational conversation (scope and observable acceptance) and a
|
|
165
|
+
technical conversation (choices, trade-offs, golden and dark paths). It presents a one-page
|
|
166
|
+
frame and asks for approval in natural language; the user's approval and the native delegation
|
|
167
|
+
prompt are the gate. Specialists return findings and evidence. Local notes capture approvals
|
|
168
|
+
and handoffs; Engram retains verified durable knowledge when enabled and available. See
|
|
159
169
|
[`core/guidelines/coordination.md`](core/guidelines/coordination.md).
|
|
160
170
|
|
|
161
171
|
### Working modes
|
|
162
172
|
|
|
163
173
|
| Mode | Primary agent | Use |
|
|
164
174
|
|---|---|---|
|
|
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. |
|
|
175
|
+
| **Coordinated** | `coordinator` | Default for every project; the coordinator frames, asks, delegates and verifies. |
|
|
176
|
+
| **Explicit escape hatch** | `build` | A routine change the user chooses to run directly; not the default and not a coordinator shortcut. |
|
|
169
177
|
|
|
170
178
|
**Migrating an existing install:**
|
|
171
179
|
|
|
172
|
-
Run
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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.
|
|
180
|
+
1. Run `devcomp update <project>` (without `--keep`). It refreshes skills, roles, bindings,
|
|
181
|
+
canonical content, the managed block, the runtime plugin and `opencode.json`; it preserves
|
|
182
|
+
`User guiding`, unknown config keys and a backup of the previous config under
|
|
183
|
+
`.companion/local/`.
|
|
184
|
+
2. Run `devcomp setup opencode --global` once per machine, so sessions outside a meta-repo also
|
|
185
|
+
load the adapter. The plugin no-ops in workspaces without `.companion/config.json`.
|
|
186
|
+
3. Start a **new** OpenCode session; an existing session keeps its previous agent. `doctor`
|
|
187
|
+
verifies the static setup; real behavior is verified in the new session.
|
|
188
|
+
4. Withhold or reject the implementation permission prompt and check that no product file is
|
|
189
|
+
edited. Then approve an implementation delegation and check that the specialist edits.
|
|
190
|
+
|
|
191
|
+
`devcomp update` replaces framework-owned content by default. Use `--keep` only for a manual
|
|
192
|
+
merge; it preserves bindings and the OpenCode config but also preserves stale behavior. Do not
|
|
193
|
+
use a blanket update as a shortcut around reviewing local customizations.
|
|
194
|
+
|
|
195
|
+
The runtime is the enforcement layer: prompts and permissions are installed by the CLI, and
|
|
196
|
+
the plugin plus the native permission prompt make the flow observable. A session can still
|
|
197
|
+
opt out explicitly with `build`; that is a user decision, not a silent fallback.
|
|
204
198
|
|
|
205
199
|
## Skills and profiles
|
|
206
200
|
|
package/RELEASE.md
CHANGED
|
@@ -101,44 +101,44 @@ https://www.npmjs.com/package/development-companion
|
|
|
101
101
|
## 6. Tag and publish the source release
|
|
102
102
|
|
|
103
103
|
```bash
|
|
104
|
-
git tag -a v1.
|
|
104
|
+
git tag -a v1.7.0 -m "v1.7.0"
|
|
105
105
|
git push origin main --tags
|
|
106
106
|
```
|
|
107
107
|
|
|
108
108
|
Create the release on Codeberg:
|
|
109
109
|
|
|
110
110
|
```text
|
|
111
|
-
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.
|
|
111
|
+
https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.7.0
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
-
Include the install command, supported harness tiers and migration
|
|
115
|
-
OpenCode's primary
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
114
|
+
Include the install command, supported harness tiers and the migration:
|
|
115
|
+
OpenCode's primary is the `coordinator` agent; it cannot edit product code or run shell.
|
|
116
|
+
`devcomp update` sets `default_agent: coordinator`, merges `opencode.json`, installs the
|
|
117
|
+
runtime plugin and the coordinator binding. `devcomp setup opencode --global` installs the
|
|
118
|
+
global adapter. The implementation delegation prompt is the approval gate; there is no magic
|
|
119
|
+
phrase. `--rules handoff` still creates a local backup and blocks `doctor` until a reviewed
|
|
120
|
+
merge.
|
|
119
121
|
|
|
120
122
|
Migration steps:
|
|
121
123
|
|
|
122
124
|
1. Follow the review and private backup checklist in
|
|
123
|
-
[Migrating
|
|
125
|
+
[Migrating an existing install](README.md#working-modes). Keep backups outside the
|
|
124
126
|
repository; never read/copy `.env` files.
|
|
125
|
-
2. `npx development-companion@1.
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
5.
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
customized content. `doctor` checks the managed block, not all project-specific rules;
|
|
141
|
-
review those separately for conflicts.
|
|
127
|
+
2. `npx development-companion@1.7.0 update <project>`. Review the managed-block diff and
|
|
128
|
+
merge customized rules from the backup. The update replaces skills, roles, bindings,
|
|
129
|
+
canonical content, the runtime plugin and `opencode.json`; it preserves `User guiding`,
|
|
130
|
+
unknown config keys and a config backup under `.companion/local/`.
|
|
131
|
+
3. Run `npx development-companion@1.7.0 setup opencode --global` once per machine so sessions
|
|
132
|
+
outside a meta-repo also load the adapter. The plugin no-ops without `.companion/config.json`.
|
|
133
|
+
4. Start a new OpenCode session; an existing session keeps its previous agent. Withhold the
|
|
134
|
+
implementation delegation prompt and verify no product file changes; approve it and verify
|
|
135
|
+
the specialist edits. `build` remains an explicit user escape hatch, not the default.
|
|
136
|
+
5. `npx development-companion@1.7.0 doctor <project>` must pass `default agent`, `coordinator`,
|
|
137
|
+
`runtime plugin`, `runtime gate`, `config instructions`, `config gate` and `delivery mode`.
|
|
138
|
+
|
|
139
|
+
Do not recommend `--keep` as a migration shortcut: it preserves stale bindings and config.
|
|
140
|
+
`doctor` checks the static setup, not the model's conversational compliance; verify behavior in
|
|
141
|
+
a new session.
|
|
142
142
|
|
|
143
143
|
## 7. If something is wrong
|
|
144
144
|
|
package/adapters/README.md
CHANGED
|
@@ -15,7 +15,9 @@ 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 and forces the implementation delegation prompt.
|
|
19
21
|
|
|
20
22
|
## Support tiers
|
|
21
23
|
|
|
@@ -72,6 +74,7 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
|
72
74
|
|
|
73
75
|
| Role | OpenCode | Claude Code | Codex |
|
|
74
76
|
|---|---|---|---|
|
|
77
|
+
| Coordinator | `.opencode/agents/coordinator.md` | — | — |
|
|
75
78
|
| Team Lead | `.opencode/agents/team-lead.md` | `.claude/agents/team-lead.md` | `.codex/agents/team-lead.toml` |
|
|
76
79
|
| Architect | `.opencode/agents/architect.md` | `.claude/agents/architect.md` | `.codex/agents/architect.toml` |
|
|
77
80
|
| Cybersecurity | `.opencode/agents/cybersecurity-engineer.md` | `.claude/agents/cybersecurity-engineer.md` | `.codex/agents/cybersecurity-engineer.toml` |
|
|
@@ -87,9 +90,11 @@ Roles are contracts in `.companion/roles/`. Bindings are thin:
|
|
|
87
90
|
|
|
88
91
|
Pi has no built-in subagents: use the role contract as a prompt template or invoke the
|
|
89
92
|
related skill.
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
+
In OpenCode the `coordinator` primary is the sole user interlocutor: it cannot edit product
|
|
94
|
+
code or run shell, it frames and asks for approval, and it delegates through the runtime
|
|
95
|
+
permission prompt. In the other harnesses the native primary follows the process in
|
|
96
|
+
`AGENTS.md`. The callable team lead is an advisor, not a dispatcher. OpenCode sets
|
|
97
|
+
`default_agent: coordinator`; the other adapters keep the native primary.
|
|
93
98
|
|
|
94
99
|
## Limitations by harness
|
|
95
100
|
|
|
@@ -37,24 +37,39 @@ 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
|
-
OpenCode
|
|
52
|
-
approval
|
|
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`, so the user confirms every implementation delegation
|
|
54
|
+
with OpenCode's permission prompt. The runtime plugin forces that prompt even after a saved
|
|
55
|
+
"always" approval. Read-only roles (`architect`, `qa-engineer`, `cybersecurity-engineer`)
|
|
56
|
+
deny product edits; architect and security deny shell, QA only allows tests, lint, build and
|
|
57
|
+
git inspection.
|
|
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/index.ts` injects the canonical files in
|
|
65
|
+
every session, including child repositories, and forces the delegation prompt. Verify real
|
|
66
|
+
behavior in a new session; `devcomp doctor` checks the static setup, not the model's
|
|
67
|
+
compliance.
|
|
68
|
+
|
|
69
|
+
The generated coordinator binding uses `mode: primary`, denies `edit` outside
|
|
70
|
+
`.companion/local/**`, `plannification/**` and `docs/companion/**`, denies `shell`, allows
|
|
71
|
+
read-only subagents during recon and asks for every implementation role. See
|
|
72
|
+
`src/install.mjs` for the exact template.
|
|
58
73
|
|
|
59
74
|
## Specialist example
|
|
60
75
|
|
|
@@ -137,13 +152,15 @@ README; do not enable nested delegation for the callable advisor.
|
|
|
137
152
|
|
|
138
153
|
- OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
|
|
139
154
|
binding thin and put durable policy in `core/`.
|
|
140
|
-
-
|
|
141
|
-
the
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
155
|
+
- The runtime plugin searches upward for `.companion/config.json`, so a child repository
|
|
156
|
+
inside the meta-repo tree inherits the process even when relative `instructions` do not
|
|
157
|
+
resolve. A child cloned outside that tree needs its own `devcomp init` or the global plugin
|
|
158
|
+
(`devcomp setup opencode --global`).
|
|
159
|
+
- Subagents start with fresh context when invoked. They read the planning directory and the
|
|
160
|
+
repository; they do not inherit the primary chat. Existing sessions keep their previous
|
|
161
|
+
selected agent; start a new session after migration.
|
|
162
|
+
- Permissions are enforced by the harness: the coordinator cannot edit product code or run
|
|
163
|
+
shell, implementation delegation asks the user, and read-only roles cannot touch product.
|
|
147
164
|
|
|
148
165
|
## References
|
|
149
166
|
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { Plugin } from "@opencode/plugin"
|
|
2
|
+
import { existsSync, readFileSync } from "node:fs"
|
|
3
|
+
import { dirname, join, resolve } from "node:path"
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Development Companion runtime adapter for OpenCode.
|
|
7
|
+
*
|
|
8
|
+
* Why this exists: AGENTS.md and opencode.json instructions are discovery-based. Sessions
|
|
9
|
+
* started inside a child repository do not resolve the meta-repo's relative instruction
|
|
10
|
+
* paths, and a configured install can pass doctor while the canonical process is absent from
|
|
11
|
+
* the model context. This plugin injects the canonical files on every primary request and
|
|
12
|
+
* forces an explicit user permission prompt for implementation subagents.
|
|
13
|
+
*
|
|
14
|
+
* It is intentionally dependency-free and project-scoped: it searches upward for the nearest
|
|
15
|
+
* .companion/config.json and does nothing when the workspace is not a devcomp project.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
const MARKER = "[devcomp-runtime]"
|
|
19
|
+
|
|
20
|
+
const CANONICAL = [
|
|
21
|
+
{ path: "core/process.md", heading: "# Development Process" },
|
|
22
|
+
{ path: "core/principles.md", heading: "# Engineering Principles" },
|
|
23
|
+
{ path: "core/quality-gates.md", heading: "# Quality Gates" },
|
|
24
|
+
{ path: "core/workflow.md", heading: "# Development Workflow" },
|
|
25
|
+
{ path: "core/guidelines/coordination.md", heading: "# Coordinated Delivery" }
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
const IMPLEMENTATION_AGENTS = new Set([
|
|
29
|
+
"mobile-engineer",
|
|
30
|
+
"backend-engineer",
|
|
31
|
+
"frontend-engineer",
|
|
32
|
+
"multiplatform-engineer",
|
|
33
|
+
"desktop-windows-engineer",
|
|
34
|
+
"desktop-macos-engineer",
|
|
35
|
+
"desktop-linux-engineer",
|
|
36
|
+
"sre-engineer",
|
|
37
|
+
"general"
|
|
38
|
+
])
|
|
39
|
+
|
|
40
|
+
type Manifest = {
|
|
41
|
+
packageVersion?: string
|
|
42
|
+
contentVersion?: string
|
|
43
|
+
docs?: string
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
type Companion = {
|
|
47
|
+
root: string
|
|
48
|
+
manifest: Manifest
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function findCompanion(start: string): Companion | null {
|
|
52
|
+
let dir = resolve(start)
|
|
53
|
+
while (true) {
|
|
54
|
+
const manifestPath = join(dir, ".companion", "config.json")
|
|
55
|
+
if (existsSync(manifestPath)) {
|
|
56
|
+
try {
|
|
57
|
+
return { root: dir, manifest: JSON.parse(readFileSync(manifestPath, "utf8")) as Manifest }
|
|
58
|
+
} catch {
|
|
59
|
+
return null
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
const parent = dirname(dir)
|
|
63
|
+
if (parent === dir) return null
|
|
64
|
+
dir = parent
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function systemText(event: unknown): string {
|
|
69
|
+
const parts = (event as { system?: Array<{ text?: string }> })?.system
|
|
70
|
+
if (!Array.isArray(parts)) return ""
|
|
71
|
+
return parts.map((part) => (typeof part?.text === "string" ? part.text : "")).join("\n")
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function banner(companion: Companion): string {
|
|
75
|
+
const version = companion.manifest.contentVersion ?? companion.manifest.packageVersion ?? "unknown"
|
|
76
|
+
const planning = companion.manifest.docs === "tracked" ? "docs/companion" : ".companion/local"
|
|
77
|
+
return `${MARKER} Development Companion ${version} loaded at runtime.
|
|
78
|
+
Project root: ${companion.root}
|
|
79
|
+
Planning: ${planning}
|
|
80
|
+
Gate: the Coordinator cannot edit product code. Implementation delegation always asks the user for permission; the Coordinator must present the frame and wait for approval in natural language before delegating.
|
|
81
|
+
If a relative \`.companion/core/...\` path does not exist in this workspace (for example, a child repository), use the content injected here; do not treat the missing path as a blocker.`
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function canonicalBlocks(companion: Companion, current: string): string[] {
|
|
85
|
+
const blocks: string[] = []
|
|
86
|
+
for (const file of CANONICAL) {
|
|
87
|
+
if (current.includes(file.heading)) continue
|
|
88
|
+
const path = join(companion.root, ".companion", file.path)
|
|
89
|
+
if (!existsSync(path)) continue
|
|
90
|
+
blocks.push(`--- ${file.path} ---\n${readFileSync(path, "utf8").trim()}`)
|
|
91
|
+
}
|
|
92
|
+
return blocks
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export default Plugin.define({
|
|
96
|
+
id: "devcomp-runtime",
|
|
97
|
+
async setup(ctx) {
|
|
98
|
+
const companion = findCompanion(ctx.location.directory)
|
|
99
|
+
if (!companion) return
|
|
100
|
+
|
|
101
|
+
await ctx.session.hook("context", (event) => {
|
|
102
|
+
const current = systemText(event)
|
|
103
|
+
const blocks = canonicalBlocks(companion, current)
|
|
104
|
+
const header = current.includes(MARKER) ? "" : banner(companion)
|
|
105
|
+
if (!header && blocks.length === 0) return
|
|
106
|
+
|
|
107
|
+
const text = [header, ...blocks].filter(Boolean).join("\n\n")
|
|
108
|
+
event.system.push({ type: "text", text })
|
|
109
|
+
})
|
|
110
|
+
|
|
111
|
+
await ctx.permission.hook("evaluate", (event) => {
|
|
112
|
+
if (event.action !== "subagent") return
|
|
113
|
+
const target = String(event.resources?.[0] ?? "")
|
|
114
|
+
if (!IMPLEMENTATION_AGENTS.has(target)) return
|
|
115
|
+
|
|
116
|
+
// Force a user prompt even if a previous "always" approval exists. The Coordinator
|
|
117
|
+
// cannot bypass the gate by saving a broad subagent rule.
|
|
118
|
+
event.effect = "ask"
|
|
119
|
+
event.message =
|
|
120
|
+
"Development Companion: implementation delegation requires the user's approval. Present the frame and wait for the user's decision."
|
|
121
|
+
})
|
|
122
|
+
}
|
|
123
|
+
})
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Role: Coordinator
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to the harness primary agent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Ship working increments through a predictable flow: frame, approval, delegation, evidence,
|
|
8
|
+
close. You are the **primary Coordinator and sole user interlocutor**. You own the result,
|
|
9
|
+
but you do not implement it yourself: you frame the smallest valuable slice, delegate it to
|
|
10
|
+
the applicable specialist, verify the evidence, and report.
|
|
11
|
+
|
|
12
|
+
The coordinator exists because a primary agent with unrestricted edit and shell tools can
|
|
13
|
+
bypass the process without noticing. Your binding denies product edits and shell commands;
|
|
14
|
+
that is intentional, not a limitation to work around.
|
|
15
|
+
|
|
16
|
+
## Use when
|
|
17
|
+
|
|
18
|
+
- Every session in a project that has this framework installed.
|
|
19
|
+
- A new project, MVP, or major change.
|
|
20
|
+
- Several specialties or agents must be coordinated.
|
|
21
|
+
- Requirements, scope, hosting, auth, or success criteria are unclear.
|
|
22
|
+
|
|
23
|
+
For a routine, in-scope change, the coordinator still frames one page, gets approval, and
|
|
24
|
+
delegates to the writer role. The user can explicitly opt out with a `build` session, but
|
|
25
|
+
that is a user decision, not a coordinator shortcut.
|
|
26
|
+
|
|
27
|
+
## Inputs
|
|
28
|
+
|
|
29
|
+
- The user's request and constraints.
|
|
30
|
+
- The repository, its conventions, and the canonical process under `.companion/core/`.
|
|
31
|
+
- Existing notes, ADRs, frames, and delivery documents.
|
|
32
|
+
- The branch convention and release process.
|
|
33
|
+
|
|
34
|
+
## Outputs
|
|
35
|
+
|
|
36
|
+
- A **running increment** in the repository, produced by the delegated writer.
|
|
37
|
+
- A one-page frame under `plannification/` or the configured `.companion/local/` directory.
|
|
38
|
+
- A verification record with command, output, test, screenshot, request, or metric.
|
|
39
|
+
- A close report: what shipped, what was verified, residual risk, and next slice.
|
|
40
|
+
|
|
41
|
+
## Operating checklist
|
|
42
|
+
|
|
43
|
+
1. **Operational conversation.** Agree on the problem, users, first observable slice, scope,
|
|
44
|
+
exclusions, constraints, and acceptance criteria. Ask only what can change the slice.
|
|
45
|
+
2. **Technical conversation.** Show conventions, viable options with trade-offs, a
|
|
46
|
+
recommendation, affected contracts, risks, rollback, and the verification plan. Include
|
|
47
|
+
golden and critical dark paths.
|
|
48
|
+
3. **Frame.** Write one page with scope, non-goals, observable acceptance criteria, risks,
|
|
49
|
+
and `Aprobado: pendiente`.
|
|
50
|
+
4. **Approval.** Present the frame and ask in natural language: «¿Apruebas el plan o tienes
|
|
51
|
+
observaciones?». If the user approves, record the approval, their words, and the date. If
|
|
52
|
+
they give observations, revise the frame and ask again. Do not require a magic phrase.
|
|
53
|
+
5. **Delegate.** Launch the applicable specialist with the frame path, approved scope,
|
|
54
|
+
files/areas, acceptance criteria, and required evidence. One writer per slice. The runtime
|
|
55
|
+
asks the user to confirm the implementation delegation; that permission prompt is the hard
|
|
56
|
+
gate.
|
|
57
|
+
6. **Verify.** Read the specialist's evidence. If a critical dark path is untested, record the
|
|
58
|
+
gap; do not call it a pass.
|
|
59
|
+
7. **Close.** Report what shipped, evidence, residual risk, and the next slice. Do not claim
|
|
60
|
+
"done", "tests pass", "secure", or "verified" without evidence.
|
|
61
|
+
|
|
62
|
+
## Routing
|
|
63
|
+
|
|
64
|
+
| Work | Subagent |
|
|
65
|
+
|---|---|
|
|
66
|
+
| Architecture, boundaries, ADRs | `architect` |
|
|
67
|
+
| Threat model, security review | `cybersecurity-engineer` |
|
|
68
|
+
| Test strategy, QA, accessibility, load | `qa-engineer` |
|
|
69
|
+
| UX, UI, web frontend | `frontend-engineer` |
|
|
70
|
+
| API, data, auth, backend | `backend-engineer` |
|
|
71
|
+
| Android and Wear OS | `mobile-engineer` |
|
|
72
|
+
| Cross-platform core | `multiplatform-engineer` |
|
|
73
|
+
| Native desktop | `desktop-*-engineer` |
|
|
74
|
+
| Deploy, observability, secrets | `sre-engineer` |
|
|
75
|
+
| Second opinion on scope or sequencing | `team-lead` |
|
|
76
|
+
|
|
77
|
+
## Boundaries
|
|
78
|
+
|
|
79
|
+
- You cannot edit product code or run shell commands. Your binding denies both. Write only
|
|
80
|
+
frames, notes, and evidence under the configured planning directory.
|
|
81
|
+
- You cannot launch an implementation specialist before the user approves the plan or without
|
|
82
|
+
the runtime permission prompt. Read-only roles (`architect`, `qa-engineer`,
|
|
83
|
+
`cybersecurity-engineer`, `team-lead`, `explore`) may run during recon.
|
|
84
|
+
- You cannot approve your own frame. Only the user's natural-language approval and their
|
|
85
|
+
permission decision count.
|
|
86
|
+
- Do not claim a delegation you did not perform. A delegation is real only if the native
|
|
87
|
+
delegation tool launched another agent.
|
|
88
|
+
- Do not accept a child that returns only a document when code was requested.
|
|
89
|
+
- **Stop the line:** if two consecutive delegations produce no running code, stop and tell the
|
|
90
|
+
user what is blocking, with options.
|
|
91
|
+
- Do not let two writers own the same files.
|
|
92
|
+
- Do not expand scope silently; surface the trade-off.
|
|
93
|
+
- Do not accept a high-risk change without independent security and QA verification.
|
|
94
|
+
|
|
95
|
+
## Handoff
|
|
96
|
+
|
|
97
|
+
As Coordinator, launch applicable native subagents with:
|
|
98
|
+
|
|
99
|
+
```markdown
|
|
100
|
+
**Role:** architect | cybersecurity | qa | frontend | backend | mobile | platform | sre
|
|
101
|
+
**Goal:** the smallest shippable outcome
|
|
102
|
+
**Frame:** path to the approved one-page frame
|
|
103
|
+
**Context:** files, decisions, constraints
|
|
104
|
+
**Authorization:** approved decisions, permitted paths and actions
|
|
105
|
+
**Deliverable:** implementation or verification, depending on phase
|
|
106
|
+
**Slice:** what must work end-to-end when this returns
|
|
107
|
+
**Verification:** command to run and output to return
|
|
108
|
+
**Return to Coordinator:** findings, evidence, golden/dark results, gaps and proposed durable learning
|
|
109
|
+
**Do not:** out-of-scope work, files to avoid, planning expansion
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
After the child returns, verify the evidence and either accept it or send a follow-up. Close
|
|
113
|
+
with the completion format in the `development-workflow` skill.
|