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/cli.mjs CHANGED
@@ -21,8 +21,11 @@ import {
21
21
  ensureDir,
22
22
  installCanonical,
23
23
  installBindings,
24
+ installGlobalPlugin,
25
+ installPlugin,
24
26
  installRoles,
25
27
  installSkills,
28
+ OPENCODE_INSTRUCTIONS,
26
29
  packageRoot,
27
30
  readManifest,
28
31
  readTemplate,
@@ -50,6 +53,7 @@ Usage:
50
53
  devcomp add <skill|role|profile> <name>
51
54
  devcomp doctor [dir] Check an installation
52
55
  devcomp update [dir] Refresh installed content
56
+ devcomp setup [opencode] --global Install the runtime adapter for every project
53
57
  devcomp scaffold [dir] Generate the TypeScript reference monorepo
54
58
 
55
59
  Init options:
@@ -69,9 +73,14 @@ Init options:
69
73
  --version, --help
70
74
 
71
75
  Update options:
72
- --keep Preserve skills, roles, bindings, and core instead of replacing them
76
+ --keep Preserve skills, roles, bindings, core, and OpenCode config instead of replacing them
73
77
  --dry-run Print the plan without writing
74
78
  --target <dir> Target directory
79
+
80
+ Setup options:
81
+ devcomp setup opencode --global Install the OpenCode runtime plugin for every project
82
+ --force Overwrite an existing global plugin
83
+ --dry-run Print the plan without writing
75
84
  `;
76
85
 
77
86
  function loadAdapter(name) {
@@ -278,7 +287,12 @@ async function cmdInit(args) {
278
287
  const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
279
288
  const roleResults = installRoles({ target: requested, roles, force });
280
289
  const bindingResults = installBindings({ target: requested, adapter, roles, force });
281
- const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(requested) : null;
290
+ const pluginResult = adapter.name === "opencode"
291
+ ? installPlugin({ target: requested, force, dryRun })
292
+ : null;
293
+ const openCodeConfig = adapter.name === "opencode"
294
+ ? writeOpenCodeConfig(requested, { dryRun })
295
+ : null;
282
296
  const ignore = ensureGitignore(requested, [".companion/local/", "AGENTS.md.bak"]);
283
297
 
284
298
  const manifest = {
@@ -315,8 +329,12 @@ async function cmdInit(args) {
315
329
  if (bindingResults.length) {
316
330
  console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
317
331
  }
332
+ if (pluginResult) {
333
+ console.log(` OpenCode plugin: ${pluginResult.status}`);
334
+ }
318
335
  if (openCodeConfig) {
319
336
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
337
+ if (openCodeConfig.reason) console.log(` ${openCodeConfig.reason}`);
320
338
  }
321
339
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
322
340
  console.log("");
@@ -407,12 +425,15 @@ async function cmdDoctor(args) {
407
425
 
408
426
  if (adapter?.agentDir && adapter.agentFormat) {
409
427
  const extension = adapter.agentFormat === "toml" ? "toml" : "md";
410
- const missingBindings = (manifest.roles ?? []).filter(
428
+ const bindingRoles = (manifest.roles ?? []).filter(
429
+ (role) => !(role === "coordinator" && adapter.name !== "opencode")
430
+ );
431
+ const missingBindings = bindingRoles.filter(
411
432
  (role) => !existsSync(join(target, adapter.agentDir, `${role}.${extension}`))
412
433
  );
413
434
  add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
414
- ? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
415
- const staleBindings = (manifest.roles ?? []).filter((role) => {
435
+ ? `missing: ${missingBindings.join(", ")}` : `${bindingRoles.length} present`);
436
+ const staleBindings = bindingRoles.filter((role) => {
416
437
  const file = join(target, adapter.agentDir, `${role}.${extension}`);
417
438
  return existsSync(file) && !readFileSync(file, "utf8").includes("coordination.md");
418
439
  });
@@ -467,7 +488,7 @@ async function cmdDoctor(args) {
467
488
  "orchestrator",
468
489
  callable ? "pass" : "fail",
469
490
  callable
470
- ? "team-lead is a callable advisor; native primary owns delivery"
491
+ ? "team-lead is a callable advisor; coordinator owns delivery"
471
492
  : `legacy primary team-lead binding; ${review}`
472
493
  );
473
494
 
@@ -501,8 +522,43 @@ async function cmdDoctor(args) {
501
522
  : `cannot verify team-lead permission restrictions; ${review}`);
502
523
  }
503
524
 
525
+ const coordinatorPath = join(target, ".opencode", "agents", "coordinator.md");
526
+ if (!existsSync(coordinatorPath)) {
527
+ add("coordinator", "fail", "binding missing; run devcomp update");
528
+ } else {
529
+ const content = readFileSync(coordinatorPath, "utf8");
530
+ const primary = /^mode:[ \t]*primary[ \t]*(?:#.*)?$/m.test(content);
531
+ const editsDenied = /- action:[ \t]*edit\s*\n\s*resource:[ \t]*"\*"\s*\n\s*effect:[ \t]*deny/m.test(content);
532
+ const shellDenied = /- action:[ \t]*shell\s*\n\s*resource:[ \t]*"\*"\s*\n\s*effect:[ \t]*deny/m.test(content);
533
+ const reconAllowed = /- action:[ \t]*subagent\s*\n\s*resource:[ \t]*"(?:architect|qa-engineer|cybersecurity-engineer)"\s*\n\s*effect:[ \t]*allow/m.test(content);
534
+ const implementationAsked = /- action:[ \t]*subagent\s*\n\s*resource:[ \t]*"(?:mobile-engineer|backend-engineer|frontend-engineer)"\s*\n\s*effect:[ \t]*ask/m.test(content);
535
+ const valid = primary && editsDenied && shellDenied && reconAllowed && implementationAsked;
536
+ add("coordinator", valid ? "pass" : "fail", valid
537
+ ? "primary; product edits and shell denied; implementation delegation asks"
538
+ : "invalid coordinator binding; run devcomp update");
539
+ }
540
+
541
+ const localPlugin = join(target, ".opencode", "plugins", "devcomp", "index.ts");
542
+ const globalPlugin = join(homedir(), ".config", "opencode", "plugins", "devcomp.ts");
543
+ const pluginPath = existsSync(localPlugin) ? localPlugin : existsSync(globalPlugin) ? globalPlugin : null;
544
+ add("runtime plugin", pluginPath ? "pass" : "fail", pluginPath
545
+ ? pluginPath === localPlugin
546
+ ? `installed at ${relative(target, localPlugin)}`
547
+ : `global adapter at ${globalPlugin}; run devcomp update for a repo-local copy`
548
+ : "missing; run devcomp update or devcomp setup opencode --global");
549
+ if (pluginPath) {
550
+ const plugin = readFileSync(pluginPath, "utf8");
551
+ const injects = plugin.includes('session.hook("context"');
552
+ const gates = plugin.includes('permission.hook("evaluate"');
553
+ add("runtime gate", injects && gates ? "pass" : "fail", injects && gates
554
+ ? "injects the canonical process and forces the delegation prompt"
555
+ : "plugin does not implement injection + gate; run devcomp update");
556
+ }
557
+
504
558
  const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
505
559
  let defaultAgent = null;
560
+ let openCodeConfig = null;
561
+ let openCodeConfigFile = null;
506
562
  for (const file of configPaths) {
507
563
  const configPath = join(target, file);
508
564
  if (!existsSync(configPath)) continue;
@@ -511,18 +567,40 @@ async function cmdDoctor(args) {
511
567
  // JSONC comments and trailing commas are supported by OpenCode.
512
568
  const clean = text.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
513
569
  (match) => match.startsWith('"') ? match : "").replace(/,\s*([}\]])/g, "$1");
514
- defaultAgent = JSON.parse(clean).default_agent ?? defaultAgent;
570
+ const parsed = JSON.parse(clean);
571
+ defaultAgent = parsed.default_agent ?? defaultAgent;
572
+ openCodeConfig = parsed;
573
+ openCodeConfigFile = file;
515
574
  } catch {
516
575
  add("OpenCode config", "fail", `cannot parse ${file}; check the config manually`);
517
576
  }
518
577
  }
519
578
  add(
520
579
  "default agent",
521
- defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
580
+ defaultAgent === "coordinator" ? "pass" : "fail",
522
581
  defaultAgent
523
582
  ? `default_agent=${defaultAgent}`
524
- : "not set; native Build remains the default"
583
+ : "missing; run devcomp update"
525
584
  );
585
+ if (openCodeConfig) {
586
+ const instructions = Array.isArray(openCodeConfig.instructions) ? openCodeConfig.instructions : [];
587
+ const missingInstructions = OPENCODE_INSTRUCTIONS.filter((entry) => !instructions.includes(entry));
588
+ add("config instructions", missingInstructions.length ? "fail" : "pass", missingInstructions.length
589
+ ? `missing: ${missingInstructions.join(", ")}; run devcomp update`
590
+ : `${OPENCODE_INSTRUCTIONS.length} canonical files`);
591
+ const rules = Array.isArray(openCodeConfig.permissions) ? openCodeConfig.permissions : [];
592
+ const pushDenied = rules.some((rule) =>
593
+ rule?.action === "shell" && rule?.resource === "git push *" && rule?.effect === "deny");
594
+ const exploreRules = openCodeConfig.agents?.explore?.permissions;
595
+ const exploreDenied = Array.isArray(exploreRules) && exploreRules.some((rule) =>
596
+ rule?.action === "shell" && rule?.resource === "*" && rule?.effect === "deny");
597
+ add("config gate", pushDenied && exploreDenied ? "pass" : "fail", pushDenied && exploreDenied
598
+ ? "git push denied; explore is read-only"
599
+ : `missing required rules in ${openCodeConfigFile}; run devcomp update`);
600
+ } else {
601
+ add("config instructions", "fail", "opencode.json missing; run devcomp update");
602
+ add("config gate", "fail", "opencode.json missing; run devcomp update");
603
+ }
526
604
  }
527
605
 
528
606
  const agentsPath = join(target, "AGENTS.md");
@@ -551,17 +629,20 @@ async function cmdDoctor(args) {
551
629
  const start = content.indexOf(START);
552
630
  const end = content.indexOf(END, start + START.length);
553
631
  const block = start !== -1 && end > start ? content.slice(start + START.length, end) : "";
554
- const normalized = block.replace(/[`*_]/g, "").replace(/\s+/g, " ");
632
+ const normalized = block.replace(/[`*]/g, "").replace(/\s+/g, " ");
555
633
  const staleLeadPrimary = /\bteam-lead is the default primary agent\b/i.test(normalized);
556
- const nativeBuild = /\bnative Build\b/i.test(normalized);
634
+ const staleNativeBuild = /\bnative Build is the default\b/i.test(normalized);
635
+ const coordinatorPrimary = /\bcoordinator\b/i.test(normalized) && /\bdefault_agent\b/i.test(normalized);
557
636
  add(
558
637
  "delivery mode",
559
- staleLeadPrimary ? "fail" : nativeBuild ? "pass" : "warn",
638
+ staleLeadPrimary || staleNativeBuild ? "fail" : coordinatorPrimary ? "pass" : "warn",
560
639
  staleLeadPrimary
561
- ? "stale team-lead-primary rules; run devcomp init --rules append or merge the new block"
562
- : nativeBuild
563
- ? "native Build is the default; team-lead is a callable subagent"
564
- : "managed block does not state the default agent; review it"
640
+ ? "stale team-lead-primary rules; run devcomp update"
641
+ : staleNativeBuild
642
+ ? "stale native Build default; run devcomp update"
643
+ : coordinatorPrimary
644
+ ? "coordinator is the default primary; implementation delegation asks the user"
645
+ : "managed block does not state the coordinator default; review it"
565
646
  );
566
647
  }
567
648
 
@@ -621,12 +702,19 @@ async function cmdUpdate(args) {
621
702
  const force = !keep;
622
703
  const dryRun = bool(args, "dry-run");
623
704
  const skills = manifest.skills ?? [];
624
- const roles = manifest.roles ?? [];
705
+ const roles = [...new Set([...(manifest.roles ?? []), ...ROLES])];
625
706
  const skillResults = installSkills({ target, adapter, skills, force, dryRun });
626
707
  const canonicalResults = installCanonical({ target, force, dryRun });
627
708
  const roleResults = installRoles({ target, roles, force, dryRun });
628
709
  installBindings({ target, adapter, roles, force, dryRun });
629
- const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
710
+ const pluginResult = adapter.name === "opencode"
711
+ ? installPlugin({ target, force, dryRun })
712
+ : null;
713
+ const openCodeConfig = adapter.name === "opencode"
714
+ ? keep
715
+ ? { status: "kept (--keep)", path: "opencode.json" }
716
+ : writeOpenCodeConfig(target, { dryRun })
717
+ : null;
630
718
 
631
719
  const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
632
720
  version: VERSION,
@@ -648,6 +736,7 @@ async function cmdUpdate(args) {
648
736
 
649
737
  manifest.packageVersion = VERSION;
650
738
  manifest.contentVersion = VERSION;
739
+ manifest.roles = roles;
651
740
  manifest.rules = { ...(manifest.rules ?? {}), "AGENTS.md": agentsResult.mode };
652
741
  writeManifest(target, manifest, { dryRun });
653
742
  const ignore = ensureGitignore(target, [".companion/local/", "AGENTS.md.bak"]);
@@ -657,8 +746,12 @@ async function cmdUpdate(args) {
657
746
  console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
658
747
  console.log(` Canonical: ${canonicalResults.filter((r) => r.status === "kept").length} kept, ${canonicalResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
659
748
  console.log(` AGENTS.md: ${agentsResult.mode}${agentsResult.backupPath ? ` (backup: ${relative(target, agentsResult.backupPath)})` : ""}`);
749
+ if (pluginResult) {
750
+ console.log(` OpenCode plugin: ${pluginResult.status}`);
751
+ }
660
752
  if (openCodeConfig) {
661
753
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
754
+ if (openCodeConfig.reason) console.log(` ${openCodeConfig.reason}`);
662
755
  }
663
756
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
664
757
  if (dryRun) console.log(" Dry run: no files were written.");
@@ -678,6 +771,24 @@ async function cmdUpdate(args) {
678
771
  }
679
772
  }
680
773
 
774
+ async function cmdSetup(args) {
775
+ const harness = args._[1] ?? "opencode";
776
+ if (harness !== "opencode") {
777
+ throw new Error(`global setup is only available for opencode; got "${harness}".`);
778
+ }
779
+ if (!bool(args, "global")) {
780
+ throw new Error("use `devcomp setup opencode --global` to install the runtime adapter for every project.");
781
+ }
782
+ const result = installGlobalPlugin({
783
+ home: homedir(),
784
+ force: bool(args, "force"),
785
+ dryRun: bool(args, "dry-run")
786
+ });
787
+ console.log(`OpenCode global plugin: ${result.status}${result.path ? ` (${result.path})` : ""}`);
788
+ if (result.reason) console.log(` ${result.reason}`);
789
+ console.log("New sessions in any devcomp project will load the runtime adapter; sessions outside a devcomp project are unaffected.");
790
+ }
791
+
681
792
  export async function main(argv) {
682
793
  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
683
794
  console.log(HELP);
@@ -693,6 +804,7 @@ export async function main(argv) {
693
804
  if (command === "add") return cmdAdd(args);
694
805
  if (command === "doctor") return cmdDoctor(args);
695
806
  if (command === "update") return cmdUpdate(args);
807
+ if (command === "setup") return cmdSetup(args);
696
808
  if (command === "scaffold") return scaffoldProject(args);
697
809
  throw new Error(`unknown command "${command}". Run "devcomp --help".`);
698
810
  }
package/src/content.mjs CHANGED
@@ -32,6 +32,7 @@ export const PROFILES = {
32
32
  };
33
33
 
34
34
  export const ROLES = [
35
+ "coordinator",
35
36
  "team-lead",
36
37
  "architect",
37
38
  "cybersecurity-engineer",
@@ -46,7 +47,22 @@ export const ROLES = [
46
47
  "sre-engineer"
47
48
  ];
48
49
 
50
+ // Roles that may run during recon before the plan is approved. Their bindings deny product
51
+ // edits and, except for QA's test allowlist, shell commands.
52
+ export const READ_ONLY_ROLES = [
53
+ "team-lead",
54
+ "architect",
55
+ "cybersecurity-engineer",
56
+ "qa-engineer"
57
+ ];
58
+
59
+ // Roles that write product code. The runtime forces a user permission prompt for these.
60
+ export const IMPLEMENTATION_ROLES = ROLES.filter(
61
+ (role) => role !== "coordinator" && !READ_ONLY_ROLES.includes(role)
62
+ );
63
+
49
64
  export const ROLE_DESCRIPTIONS = {
65
+ coordinator: "Primary Coordinator. Owns the conversation, frame, approval gate and delegation; cannot edit product code or run shell.",
50
66
  "team-lead": "Advises the primary on scope, sequencing, and delivery risks. Reports to the primary without subdelegating.",
51
67
  architect: "Defines boundaries, patterns, infrastructure, and ADRs. Use before implementation and for structural changes.",
52
68
  "cybersecurity-engineer": "Builds the threat model and verifies security with evidence. Use during architecture and before release.",