development-companion 1.6.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/src/install.mjs CHANGED
@@ -8,9 +8,9 @@ import {
8
8
  symlinkSync,
9
9
  writeFileSync
10
10
  } from "node:fs";
11
- import { dirname, join, resolve } from "node:path";
11
+ import { basename, dirname, join, relative, resolve } from "node:path";
12
12
  import { fileURLToPath } from "node:url";
13
- import { ROLE_DESCRIPTIONS } from "./content.mjs";
13
+ import { IMPLEMENTATION_ROLES, ROLE_DESCRIPTIONS } from "./content.mjs";
14
14
 
15
15
  const here = dirname(fileURLToPath(import.meta.url));
16
16
 
@@ -147,47 +147,193 @@ export function installCanonical({ target, force = false, dryRun = false }) {
147
147
  });
148
148
  }
149
149
 
150
+ function coordinatorBody() {
151
+ return `You are the Development Companion Coordinator for this workspace and the sole user interlocutor. Your job is to keep the delivery loop predictable: frame, approval, delegation, evidence, close. Each specialist stays in its role; you do not do their work.
152
+
153
+ The portable coordination contract is \`.companion/core/guidelines/coordination.md\`; read it when present, otherwise use the Development Companion content injected at runtime.
154
+
155
+ ## Hard constraints
156
+
157
+ - You cannot edit product code. Your \`edit\` permission is denied except for \`.companion/local/**\`, \`plannification/**\` and \`docs/companion/**\`.
158
+ - You cannot run shell commands. The \`shell\` permission is denied. Do not ask for it.
159
+ - Before the user approves the plan, you may launch only read-only roles: \`architect\`, \`qa-engineer\`, \`cybersecurity-engineer\`, \`team-lead\` and \`explore\`.
160
+ - Implementation roles (\`mobile-engineer\`, \`backend-engineer\`, \`frontend-engineer\`, \`multiplatform-engineer\`, \`desktop-*-engineer\`, \`sre-engineer\`, \`general\`) always require the user's permission at delegation time. The runtime forces a permission prompt even if a broad approval was saved before; do not try to bypass it.
161
+ - You cannot approve your own frame. Only the user's natural-language approval and their permission decision count. Writing \`Aprobado: sí\` inside a file does not unlock anything.
162
+ - If a relative \`.companion/core/...\` path is not present in this workspace (for example, a child repository), use the Development Companion content injected at runtime; do not treat the missing path as a blocker.
163
+
164
+ ## Required flow
165
+
166
+ 1. **Operational conversation.** Agree on the problem, users, first observable slice, scope, exclusions, constraints and acceptance criteria. Ask only what can change the slice.
167
+ 2. **Technical conversation.** Show existing conventions, viable options with trade-offs, a recommendation, affected contracts, risks, rollback and the verification plan. Include golden and dark paths.
168
+ 3. **Frame.** Write one page under \`plannification/\` for app work or \`.companion/local/\` for the meta-repo. Include scope, non-goals, observable acceptance criteria, risks and \`Aprobado: pendiente\`.
169
+ 4. **Approval.** Present the frame and ask in natural language: «¿Apruebas el plan o tienes observaciones?». If the user approves («apruebo», «dale», «adelante», «sin observaciones», «me parece bien», etc.), record the approval, the user's words and the date in the frame. If the user gives observations, revise the frame, summarize the changes and ask again. Do not require a magic phrase.
170
+ 5. **Delegate.** Launch the applicable specialist with the frame path, the approved scope, the files/areas to touch, the acceptance criteria and the required evidence. The runtime will ask the user to confirm the implementation delegation; that permission prompt is the hard gate. If the user rejects, stop and ask what to change. One writer per slice. Do not implement, run tests or run builds yourself.
171
+ 6. **Verify.** Read the specialist's evidence: command and output, tests, screenshots, requests or metrics. If a critical dark path is untested, record the gap; do not call it a pass.
172
+ 7. **Close.** Report what shipped, what was verified, residual risks and the next slice. Do not claim "done", "tests pass" or "verified" without evidence.
173
+
174
+ ## Routing
175
+
176
+ | Work | Subagent |
177
+ |---|---|
178
+ | Architecture, boundaries, ADRs | \`architect\` |
179
+ | Threat model, security review | \`cybersecurity-engineer\` |
180
+ | Test strategy, QA, accessibility, load | \`qa-engineer\` |
181
+ | UX, UI, web frontend | \`frontend-engineer\` |
182
+ | API, data, auth, backend | \`backend-engineer\` |
183
+ | Android and Wear OS | \`mobile-engineer\` |
184
+ | Cross-platform core | \`multiplatform-engineer\` |
185
+ | Native desktop | \`desktop-*-engineer\` |
186
+ | Deploy, observability, secrets | \`sre-engineer\` |
187
+ | Second opinion on scope or sequencing | \`team-lead\` |
188
+
189
+ If no specialist fits, report the gap and ask the user how to proceed. Do not silently do the work yourself; you cannot edit product code.
190
+
191
+ ## Escape hatch
192
+
193
+ A session explicitly started with \`--agent build\` (or an explicit agent switch by the user) keeps the native Build tools for a routine, in-scope fix. That is an opt-out chosen by the user, not your default. Never switch yourself to \`build\` or ask the user to do it to bypass the gate.`;
194
+ }
195
+
150
196
  function bindingBody(role) {
197
+ if (role === "coordinator") return coordinatorBody();
151
198
  return `Read \`.companion/core/guidelines/coordination.md\`, \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/${role}.md\`. Load the role's referenced skills from \`.agents/skills/\` or \`.claude/skills/\`.
152
199
 
153
200
  ${role === "team-lead" ? "Act as a callable coordination advisor. " : ""}Do not subdelegate or contact the user directly. Return evidence and open questions to the primary agent.`;
154
201
  }
155
202
 
203
+ function readOnlyPermissions({ shellTests = false } = {}) {
204
+ const permissions = [
205
+ " - action: subagent",
206
+ ' resource: "*"',
207
+ " effect: deny",
208
+ " - action: edit",
209
+ ' resource: "*"',
210
+ " effect: deny",
211
+ " - action: edit",
212
+ ' resource: ".companion/local/**"',
213
+ " effect: allow",
214
+ " - action: edit",
215
+ ' resource: "**/.companion/local/**"',
216
+ " effect: allow",
217
+ " - action: edit",
218
+ ' resource: "plannification/**"',
219
+ " effect: allow",
220
+ " - action: edit",
221
+ ' resource: "**/plannification/**"',
222
+ " effect: allow",
223
+ " - action: shell",
224
+ ' resource: "*"',
225
+ " effect: deny"
226
+ ];
227
+ if (shellTests) {
228
+ permissions.push(
229
+ " - action: shell",
230
+ ' resource: "git status *"',
231
+ " effect: allow",
232
+ " - action: shell",
233
+ ' resource: "git diff *"',
234
+ " effect: allow",
235
+ " - action: shell",
236
+ ' resource: "git log *"',
237
+ " effect: allow",
238
+ " - action: shell",
239
+ ' resource: "./gradlew *test*"',
240
+ " effect: allow",
241
+ " - action: shell",
242
+ ' resource: "./gradlew *lint*"',
243
+ " effect: allow",
244
+ " - action: shell",
245
+ ' resource: "./gradlew *assemble*"',
246
+ " effect: allow",
247
+ " - action: shell",
248
+ ' resource: "npm test *"',
249
+ " effect: allow"
250
+ );
251
+ }
252
+ return permissions;
253
+ }
254
+
255
+ function coordinatorPermissions() {
256
+ const permissions = [
257
+ "permissions:",
258
+ " - action: edit",
259
+ ' resource: "*"',
260
+ " effect: deny",
261
+ " - action: edit",
262
+ ' resource: ".companion/local/**"',
263
+ " effect: allow",
264
+ " - action: edit",
265
+ ' resource: "**/.companion/local/**"',
266
+ " effect: allow",
267
+ " - action: edit",
268
+ ' resource: "plannification/**"',
269
+ " effect: allow",
270
+ " - action: edit",
271
+ ' resource: "**/plannification/**"',
272
+ " effect: allow",
273
+ " - action: edit",
274
+ ' resource: "docs/companion/**"',
275
+ " effect: allow",
276
+ " - action: edit",
277
+ ' resource: "**/docs/companion/**"',
278
+ " effect: allow",
279
+ " - action: shell",
280
+ ' resource: "*"',
281
+ " effect: deny",
282
+ " - action: subagent",
283
+ ' resource: "*"',
284
+ " effect: deny"
285
+ ];
286
+ for (const role of ["architect", "qa-engineer", "cybersecurity-engineer", "team-lead", "explore"]) {
287
+ permissions.push(" - action: subagent", ` resource: "${role}"`, " effect: allow");
288
+ }
289
+ for (const role of IMPLEMENTATION_ROLES) {
290
+ permissions.push(" - action: subagent", ` resource: "${role}"`, " effect: ask");
291
+ }
292
+ permissions.push(" - action: subagent", ' resource: "general"', " effect: ask");
293
+ return permissions;
294
+ }
295
+
156
296
  function openCodeBinding(role) {
297
+ const isCoordinator = role === "coordinator";
157
298
  const isLead = role === "team-lead";
158
- const mode = "subagent";
299
+ const isReadOnly = ["architect", "cybersecurity-engineer", "qa-engineer"].includes(role);
300
+ const mode = isCoordinator ? "primary" : "subagent";
159
301
  const body = bindingBody(role);
160
- const permissions = isLead
161
- ? [
162
- "permissions:",
163
- " - action: edit",
164
- ' resource: "*"',
165
- " effect: deny",
166
- " - action: edit",
167
- ' resource: ".companion/local/**"',
168
- " effect: allow",
169
- " - action: edit",
170
- ' resource: "**/.companion/local/**"',
171
- " effect: allow",
172
- " - action: edit",
173
- ' resource: "docs/companion/**"',
174
- " effect: allow",
175
- " - action: edit",
176
- ' resource: "**/docs/companion/**"',
177
- " effect: allow",
178
- " - action: shell",
179
- ' resource: "*"',
180
- " effect: deny",
181
- " - action: subagent",
182
- ' resource: "*"',
183
- " effect: deny"
184
- ]
185
- : [
186
- "permissions:",
187
- " - action: subagent",
188
- ' resource: "*"',
189
- " effect: deny"
190
- ];
302
+ const permissions = isCoordinator
303
+ ? coordinatorPermissions()
304
+ : isLead
305
+ ? [
306
+ "permissions:",
307
+ " - action: edit",
308
+ ' resource: "*"',
309
+ " effect: deny",
310
+ " - action: edit",
311
+ ' resource: ".companion/local/**"',
312
+ " effect: allow",
313
+ " - action: edit",
314
+ ' resource: "**/.companion/local/**"',
315
+ " effect: allow",
316
+ " - action: edit",
317
+ ' resource: "docs/companion/**"',
318
+ " effect: allow",
319
+ " - action: edit",
320
+ ' resource: "**/docs/companion/**"',
321
+ " effect: allow",
322
+ " - action: shell",
323
+ ' resource: "*"',
324
+ " effect: deny",
325
+ " - action: subagent",
326
+ ' resource: "*"',
327
+ " effect: deny"
328
+ ]
329
+ : isReadOnly
330
+ ? ["permissions:", ...readOnlyPermissions({ shellTests: role === "qa-engineer" })]
331
+ : [
332
+ "permissions:",
333
+ " - action: subagent",
334
+ ' resource: "*"',
335
+ " effect: deny"
336
+ ];
191
337
  const frontmatter = [
192
338
  "---",
193
339
  `description: ${ROLE_DESCRIPTIONS[role] ?? role}`,
@@ -223,6 +369,7 @@ export function installBindings({ target, adapter, roles, force = false, dryRun
223
369
  if (!adapter.agentDir || !adapter.agentFormat) return [];
224
370
  const results = [];
225
371
  for (const role of roles) {
372
+ if (role === "coordinator" && adapter.name !== "opencode") continue;
226
373
  const name = adapter.agentFormat === "toml" ? `${role}.toml` : `${role}.md`;
227
374
  const destination = join(target, adapter.agentDir, name);
228
375
  if (existsSync(destination) && !force) {
@@ -244,19 +391,140 @@ export function installBindings({ target, adapter, roles, force = false, dryRun
244
391
  return results;
245
392
  }
246
393
 
247
- /**
248
- * Leave the harness default and existing configuration alone. The process is
249
- * installed as instructions, not as a replacement for the native Build agent.
250
- */
251
- export function writeOpenCodeConfig(target) {
252
- const existing = [
394
+ export const OPENCODE_INSTRUCTIONS = [
395
+ ".companion/core/process.md",
396
+ ".companion/core/principles.md",
397
+ ".companion/core/quality-gates.md",
398
+ ".companion/core/workflow.md",
399
+ ".companion/core/guidelines/coordination.md"
400
+ ];
401
+
402
+ const OPENCODE_REQUIRED_PERMISSIONS = [
403
+ { action: "shell", resource: "git push", effect: "deny" },
404
+ { action: "shell", resource: "git push *", effect: "deny" }
405
+ ];
406
+
407
+ const OPENCODE_EXPLORE_PERMISSIONS = [
408
+ { action: "shell", resource: "*", effect: "deny" }
409
+ ];
410
+
411
+ function parseJsonc(text) {
412
+ const clean = text
413
+ .replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
414
+ (match) => (match.startsWith('"') ? match : ""))
415
+ .replace(/,\s*([}\]])/g, "$1");
416
+ return JSON.parse(clean);
417
+ }
418
+
419
+ function sameRule(left, right) {
420
+ return left?.action === right.action && left?.resource === right.resource && left?.effect === right.effect;
421
+ }
422
+
423
+ function mergeRules(existing, required) {
424
+ const rules = Array.isArray(existing) ? [...existing] : [];
425
+ for (const rule of required) {
426
+ if (!rules.some((candidate) => sameRule(candidate, rule))) rules.push(rule);
427
+ }
428
+ return rules;
429
+ }
430
+
431
+ function openCodeConfigPath(target) {
432
+ const candidates = [
253
433
  join(target, ".opencode", "opencode.json"),
254
434
  join(target, ".opencode", "opencode.jsonc"),
255
435
  join(target, "opencode.json"),
256
436
  join(target, "opencode.jsonc")
257
- ]
258
- .find((path) => existsSync(path));
259
- return { status: existing ? "kept" : "native default (no config written)", path: existing ?? "OpenCode default" };
437
+ ];
438
+ return candidates.find((path) => existsSync(path)) ?? join(target, "opencode.json");
439
+ }
440
+
441
+ function mergeOpenCodeConfig(current) {
442
+ const config = current && typeof current === "object" ? current : {};
443
+ config.$schema ??= "https://opencode.ai/config.json";
444
+ config.default_agent = "coordinator";
445
+ config.instructions = [...new Set([...(Array.isArray(config.instructions) ? config.instructions : []), ...OPENCODE_INSTRUCTIONS])];
446
+ config.permissions = mergeRules(config.permissions, OPENCODE_REQUIRED_PERMISSIONS);
447
+ config.agents = config.agents && typeof config.agents === "object" ? config.agents : {};
448
+ config.agents.explore = config.agents.explore && typeof config.agents.explore === "object"
449
+ ? config.agents.explore
450
+ : {};
451
+ config.agents.explore.permissions = mergeRules(
452
+ config.agents.explore.permissions,
453
+ OPENCODE_EXPLORE_PERMISSIONS
454
+ );
455
+ return config;
456
+ }
457
+
458
+ /**
459
+ * Install the OpenCode runtime contract:
460
+ * - default_agent=coordinator (the primary cannot edit product code or run shell);
461
+ * - the five canonical instruction files, so root sessions load them even without a plugin;
462
+ * - a global shell deny for git push;
463
+ * - read-only explore.
464
+ *
465
+ * The config is a mixed user file. Preserve unknown keys, merge arrays by adding only what is
466
+ * missing, and write a backup under .companion/local/ before replacing the file.
467
+ */
468
+ export function writeOpenCodeConfig(target, { dryRun = false } = {}) {
469
+ const configPath = openCodeConfigPath(target);
470
+ const existed = existsSync(configPath);
471
+ let current = null;
472
+ if (existed) {
473
+ try {
474
+ current = parseJsonc(readFileSync(configPath, "utf8"));
475
+ } catch (error) {
476
+ return {
477
+ status: "skipped",
478
+ path: relative(target, configPath),
479
+ reason: `cannot parse ${relative(target, configPath)}: ${error.message}`
480
+ };
481
+ }
482
+ }
483
+
484
+ const merged = mergeOpenCodeConfig(current);
485
+ const next = `${JSON.stringify(merged, null, 2)}\n`;
486
+ if (existed && readFileSync(configPath, "utf8") === next) {
487
+ return { status: "unchanged", path: relative(target, configPath) };
488
+ }
489
+
490
+ const status = existed ? "updated" : "created";
491
+ if (dryRun) return { status: `would-${status}`, path: relative(target, configPath) };
492
+
493
+ if (existed) {
494
+ const backup = join(target, ".companion", "local", `${basename(configPath)}.bak`);
495
+ writeText(backup, readFileSync(configPath, "utf8"));
496
+ }
497
+ writeText(configPath, next);
498
+ return { status, path: relative(target, configPath) };
499
+ }
500
+
501
+ export function installPlugin({ target, force = false, dryRun = false }) {
502
+ const source = join(packageRoot(), "adapters", "opencode", "plugin", "devcomp", "index.ts");
503
+ const destination = join(target, ".opencode", "plugins", "devcomp", "index.ts");
504
+ if (!existsSync(source)) return { plugin: "devcomp", status: "missing" };
505
+ if (existsSync(destination) && !force) return { plugin: "devcomp", status: "kept" };
506
+ if (dryRun) {
507
+ return { plugin: "devcomp", status: existsSync(destination) ? "would-overwrite" : "would-install" };
508
+ }
509
+ writeText(destination, readFileSync(source, "utf8"));
510
+ return { plugin: "devcomp", status: "installed" };
511
+ }
512
+
513
+ export function installGlobalPlugin({ home = process.env.HOME, force = false, dryRun = false } = {}) {
514
+ const source = join(packageRoot(), "adapters", "opencode", "plugin", "devcomp", "index.ts");
515
+ if (!home) return { plugin: "devcomp-global", status: "skipped", reason: "HOME is not set" };
516
+ const destination = join(home, ".config", "opencode", "plugins", "devcomp.ts");
517
+ if (!existsSync(source)) return { plugin: "devcomp-global", status: "missing" };
518
+ if (existsSync(destination) && !force) return { plugin: "devcomp-global", status: "kept", path: destination };
519
+ if (dryRun) {
520
+ return {
521
+ plugin: "devcomp-global",
522
+ status: existsSync(destination) ? "would-overwrite" : "would-install",
523
+ path: destination
524
+ };
525
+ }
526
+ writeText(destination, readFileSync(source, "utf8"));
527
+ return { plugin: "devcomp-global", status: "installed", path: destination };
260
528
  }
261
529
 
262
530
  export function writeManifest(target, manifest, { dryRun = false } = {}) {
@@ -20,9 +20,20 @@ If a file is missing, run `devcomp doctor` and `devcomp update` before coding.
20
20
 
21
21
  ## How to work
22
22
 
23
- The primary agent is the **Coordinator and sole user interlocutor**. It keeps its native tools
24
- and owns the result. In OpenCode, native Build is the default; the callable `team-lead` only
25
- advises. Specialists report evidence to the Coordinator, not to the user.
23
+ The primary agent is the **Coordinator and sole user interlocutor**. It owns the result, but
24
+ it does not implement it: in OpenCode the `coordinator` agent is the default
25
+ (`default_agent: coordinator`), it cannot edit product code or run shell, and it delegates to
26
+ specialists. The callable `team-lead` remains a read-only advisor. `build` is an explicit
27
+ escape hatch for a routine change the user chooses to run directly. Specialists report
28
+ evidence to the Coordinator, not to the user.
29
+
30
+ A runtime adapter (`.opencode/plugins/devcomp/`) injects the canonical process into every
31
+ session, including child repositories, and forces a user permission prompt before an
32
+ implementation subagent starts. Approval is natural language: the Coordinator presents the
33
+ frame, the user says "apruebo", "dale", "adelante" or "tengo observaciones", and the
34
+ permission prompt is the final confirmation. There is no magic phrase. Questions, permissions
35
+ and errors notify immediately; an idle turn is debounced so a subagent report does not produce
36
+ a toast per subagent.
26
37
 
27
38
  For non-trivial work:
28
39
 
@@ -119,10 +130,19 @@ the corresponding evidence.
119
130
 
120
131
  ## Update and migration contract
121
132
 
122
- - `devcomp update` replaces framework-owned files: core process, skills, roles, and harness
123
- bindings. It replaces the managed block in this file and preserves the `User guiding`
124
- section verbatim.
133
+ - `devcomp update` replaces framework-owned files: core process, skills, roles, harness
134
+ bindings, the OpenCode runtime plugin, and the managed block in this file. It merges
135
+ `opencode.json` with `default_agent: coordinator`, the five canonical instructions, a
136
+ `git push` denial and a read-only `explore`; unknown keys are preserved and the previous
137
+ file is backed up under `.companion/local/`. Use `--keep` to preserve the config and bindings
138
+ for a manual merge.
125
139
  - Before changing this file, the CLI writes `AGENTS.md.bak`. Inspect it if a rule disappears.
140
+ - `devcomp setup opencode --global` installs the runtime plugin in
141
+ `~/.config/opencode/plugins/devcomp.ts` so sessions outside a meta-repo also load it. It is
142
+ idempotent and does nothing for workspaces without `.companion/config.json`.
143
+ - After an update, start a **new session**; an existing session keeps its previous agent. Run
144
+ `devcomp doctor` in the repository. The runtime behavior is verified in a new session, not by
145
+ `doctor` alone.
126
146
  - If the previous file was a legacy `AGENTS.md`, the CLI wraps its content under `User guiding`
127
147
  and reports a migration. Review the result; the automatic migration preserves the text but
128
148
  does not rewrite its tone.