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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.5.0",
3
+ "version": "1.7.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -29,7 +29,7 @@
29
29
  "README.md",
30
30
  "CHANGELOG.md",
31
31
  "LICENSE",
32
- "RELEASE.md"
32
+ "RELEASE.md"
33
33
  ],
34
34
  "engines": {
35
35
  "node": ">=22"
package/src/cli.mjs CHANGED
@@ -1,17 +1,31 @@
1
1
  import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
2
- import { basename, join, resolve } from "node:path";
2
+ import { basename, join, relative, resolve } from "node:path";
3
3
  import { homedir } from "node:os";
4
4
  import { parseArgs, flag, bool, list } from "./args.mjs";
5
5
  import { ask, choose, confirm } from "./prompt.mjs";
6
6
  import { detectRepo, detectBranching } from "./detect.mjs";
7
- import { applyRules, ensureGitignore, hasManagedBlock, renderTemplate, START, END } from "./rules.mjs";
7
+ import {
8
+ applyAgentsFile,
9
+ applyRules,
10
+ ensureGitignore,
11
+ hasManagedBlock,
12
+ MERGE_PENDING,
13
+ renderTemplate,
14
+ START,
15
+ END,
16
+ templateVersion,
17
+ USER_GUIDING
18
+ } from "./rules.mjs";
8
19
  import {
9
20
  CANONICAL_FILES,
10
21
  ensureDir,
11
22
  installCanonical,
12
23
  installBindings,
24
+ installGlobalPlugin,
25
+ installPlugin,
13
26
  installRoles,
14
27
  installSkills,
28
+ OPENCODE_INSTRUCTIONS,
15
29
  packageRoot,
16
30
  readManifest,
17
31
  readTemplate,
@@ -39,13 +53,14 @@ Usage:
39
53
  devcomp add <skill|role|profile> <name>
40
54
  devcomp doctor [dir] Check an installation
41
55
  devcomp update [dir] Refresh installed content
56
+ devcomp setup [opencode] --global Install the runtime adapter for every project
42
57
  devcomp scaffold [dir] Generate the TypeScript reference monorepo
43
58
 
44
59
  Init options:
45
60
  --harness <name> Force the harness adapter (auto by default)
46
61
  --profile <name> ${Object.keys(PROFILES).join(" | ")}
47
62
  --skills <a,b> Extra skills to install
48
- --rules <mode> keep | append | handoff | replace (existing rules)
63
+ --rules <mode> migrate | keep | handoff | replace (existing AGENTS.md)
49
64
  --branching <name> gitflow | gitlab-flow | trunk-based | github-flow | custom
50
65
  --docs <mode> local | tracked
51
66
  --memory <mode> engram | none
@@ -53,9 +68,19 @@ Init options:
53
68
  --layout <mode> monorepo | single (scaffold)
54
69
  --dry-run Print the plan without writing
55
70
  --force Allow replace/overwrite
56
- --yes Non-interactive; rules default to keep
71
+ --yes Non-interactive; migrate existing AGENTS.md with a backup
57
72
  --target <dir> Target directory for add/doctor/update
58
73
  --version, --help
74
+
75
+ Update options:
76
+ --keep Preserve skills, roles, bindings, core, and OpenCode config instead of replacing them
77
+ --dry-run Print the plan without writing
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
59
84
  `;
60
85
 
61
86
  function loadAdapter(name) {
@@ -94,6 +119,13 @@ function normalizeMode(value, fallback) {
94
119
  return value;
95
120
  }
96
121
 
122
+ function normalizeAgentsMode(value, fallback) {
123
+ if (!value || value === true) return fallback;
124
+ if (["append", "migrate", "update"].includes(value)) return "update";
125
+ if (["keep", "handoff", "replace"].includes(value)) return value;
126
+ throw new Error(`invalid rules mode "${value}". Use migrate, keep, handoff, or replace.`);
127
+ }
128
+
97
129
  async function cmdInit(args) {
98
130
  const requested = args._[1] ? resolve(args._[1]) : process.cwd();
99
131
  const dryRun = bool(args, "dry-run");
@@ -158,18 +190,23 @@ async function cmdInit(args) {
158
190
 
159
191
  const rulesFlag = flag(args, "rules");
160
192
  const rules = {
161
- "AGENTS.md": normalizeMode(rulesFlag, "keep"),
193
+ "AGENTS.md": normalizeAgentsMode(rulesFlag, "update"),
162
194
  "CLAUDE.md": rulesFlag === "handoff" ? "keep" : normalizeMode(rulesFlag, "keep")
163
195
  };
164
196
  if (!yes && !rulesFlag) {
165
197
  for (const file of ["AGENTS.md", "CLAUDE.md"]) {
166
198
  const exists = file === "AGENTS.md" ? detected.rules.agents : detected.rules.claude;
167
199
  if (!exists) continue;
168
- rules[file] = await choose(
169
- `${file} already exists. What should I do?`,
170
- file === "AGENTS.md" ? ["keep", "handoff", "append", "replace"] : ["keep", "append", "replace"],
171
- "keep"
172
- );
200
+ rules[file] = file === "AGENTS.md"
201
+ ? normalizeAgentsMode(
202
+ await choose(
203
+ "AGENTS.md already exists. How should the framework rules be installed?",
204
+ ["migrate", "keep", "handoff", "replace"],
205
+ "migrate"
206
+ ),
207
+ "update"
208
+ )
209
+ : await choose("CLAUDE.md already exists. What should I do?", ["keep", "append", "replace"], "keep");
173
210
  }
174
211
  }
175
212
 
@@ -216,6 +253,7 @@ async function cmdInit(args) {
216
253
 
217
254
  const projectName = basename(requested);
218
255
  const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
256
+ version: VERSION,
219
257
  projectName,
220
258
  profile,
221
259
  branching,
@@ -224,12 +262,12 @@ async function cmdInit(args) {
224
262
  const claudeBlock = readTemplate("templates/rules/CLAUDE.block.md").trim();
225
263
 
226
264
  const rulesResult = {};
227
- rulesResult["AGENTS.md"] = applyRules({
265
+ rulesResult["AGENTS.md"] = applyAgentsFile({
228
266
  filePath: join(requested, "AGENTS.md"),
229
267
  mode: rules["AGENTS.md"],
230
268
  block: agentsBlock,
231
269
  force,
232
- backupPath: join(requested, ".companion", "local", "rules-backup", "AGENTS.md")
270
+ backupPath: join(requested, "AGENTS.md.bak")
233
271
  });
234
272
  if (["error", "blocked"].includes(rulesResult["AGENTS.md"].mode)) {
235
273
  throw new Error(`AGENTS.md: ${rulesResult["AGENTS.md"].reason}`);
@@ -249,8 +287,13 @@ async function cmdInit(args) {
249
287
  const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
250
288
  const roleResults = installRoles({ target: requested, roles, force });
251
289
  const bindingResults = installBindings({ target: requested, adapter, roles, force });
252
- const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(requested) : null;
253
- const ignore = ensureGitignore(requested, [".companion/local/"]);
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;
296
+ const ignore = ensureGitignore(requested, [".companion/local/", "AGENTS.md.bak"]);
254
297
 
255
298
  const manifest = {
256
299
  schemaVersion: 1,
@@ -286,12 +329,21 @@ async function cmdInit(args) {
286
329
  if (bindingResults.length) {
287
330
  console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
288
331
  }
332
+ if (pluginResult) {
333
+ console.log(` OpenCode plugin: ${pluginResult.status}`);
334
+ }
289
335
  if (openCodeConfig) {
290
336
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
337
+ if (openCodeConfig.reason) console.log(` ${openCodeConfig.reason}`);
291
338
  }
292
339
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
293
340
  console.log("");
294
- console.log("Next: run `devcomp doctor`; resolve rules merge or legacy agent FAIL before starting work.");
341
+ if (rulesResult["AGENTS.md"]?.mode === "merge-pending") {
342
+ console.log("ACTION REQUIRED: the previous AGENTS.md is at AGENTS.md.bak and the new file has a merge-pending notice.");
343
+ console.log("Start an agent session and ask it to merge AGENTS.md.bak into the User guiding section, then run `devcomp doctor`.");
344
+ } else {
345
+ console.log("Next: run `devcomp doctor`. Review the User guiding section; an automatic migration needs no agent merge.");
346
+ }
295
347
  }
296
348
 
297
349
  async function cmdAdd(args) {
@@ -373,17 +425,55 @@ async function cmdDoctor(args) {
373
425
 
374
426
  if (adapter?.agentDir && adapter.agentFormat) {
375
427
  const extension = adapter.agentFormat === "toml" ? "toml" : "md";
376
- const missingBindings = (manifest.roles ?? []).filter(
428
+ const bindingRoles = (manifest.roles ?? []).filter(
429
+ (role) => !(role === "coordinator" && adapter.name !== "opencode")
430
+ );
431
+ const missingBindings = bindingRoles.filter(
377
432
  (role) => !existsSync(join(target, adapter.agentDir, `${role}.${extension}`))
378
433
  );
379
434
  add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
380
- ? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
435
+ ? `missing: ${missingBindings.join(", ")}` : `${bindingRoles.length} present`);
436
+ const staleBindings = bindingRoles.filter((role) => {
437
+ const file = join(target, adapter.agentDir, `${role}.${extension}`);
438
+ return existsSync(file) && !readFileSync(file, "utf8").includes("coordination.md");
439
+ });
440
+ add("binding content", staleBindings.length ? "fail" : "pass", staleBindings.length
441
+ ? `missing coordination.md: ${staleBindings.join(", ")}; run devcomp update`
442
+ : "all bindings link coordination.md");
381
443
  }
382
444
 
383
445
  const missingCore = CANONICAL_FILES.filter((file) => !existsSync(join(target, ".companion", "core", file)));
384
446
  add("canonical process", missingCore.length ? "fail" : "pass", missingCore.length
385
447
  ? `missing: ${missingCore.join(", ")}; run devcomp update`
386
448
  : `${CANONICAL_FILES.length} files present`);
449
+ const staleCore = CANONICAL_FILES.filter((file) => {
450
+ const installed = join(target, ".companion", "core", file);
451
+ const expected = join(packageRoot(), "core", file);
452
+ return existsSync(installed) && existsSync(expected) && readFileSync(installed, "utf8") !== readFileSync(expected, "utf8");
453
+ });
454
+ add("canonical content", staleCore.length ? "fail" : "pass", staleCore.length
455
+ ? `stale or modified: ${staleCore.join(", ")}; run devcomp update`
456
+ : "matches package content");
457
+
458
+ const staleRoles = (manifest.roles ?? []).filter((role) => {
459
+ const installed = join(target, ".companion", "roles", `${role}.md`);
460
+ const expected = join(packageRoot(), "core", "roles", `${role}.md`);
461
+ return existsSync(installed) && existsSync(expected) && readFileSync(installed, "utf8") !== readFileSync(expected, "utf8");
462
+ });
463
+ add("role content", staleRoles.length ? "fail" : "pass", staleRoles.length
464
+ ? `stale or modified: ${staleRoles.join(", ")}; run devcomp update`
465
+ : "matches package content");
466
+
467
+ if (adapter) {
468
+ const staleSkills = (manifest.skills ?? []).filter((skill) => {
469
+ const installed = join(target, adapter.skillsDir, skill, "SKILL.md");
470
+ const expected = join(packageRoot(), "skills", skill, "SKILL.md");
471
+ return existsSync(installed) && existsSync(expected) && readFileSync(installed, "utf8") !== readFileSync(expected, "utf8");
472
+ });
473
+ add("skill content", staleSkills.length ? "fail" : "pass", staleSkills.length
474
+ ? `stale or modified: ${staleSkills.join(", ")}; run devcomp update`
475
+ : "matches package content");
476
+ }
387
477
 
388
478
  if (manifest.harness === "opencode") {
389
479
  const teamLeadPath = join(target, ".opencode", "agents", "team-lead.md");
@@ -398,7 +488,7 @@ async function cmdDoctor(args) {
398
488
  "orchestrator",
399
489
  callable ? "pass" : "fail",
400
490
  callable
401
- ? "team-lead is a callable advisor; native primary owns delivery"
491
+ ? "team-lead is a callable advisor; coordinator owns delivery"
402
492
  : `legacy primary team-lead binding; ${review}`
403
493
  );
404
494
 
@@ -432,8 +522,43 @@ async function cmdDoctor(args) {
432
522
  : `cannot verify team-lead permission restrictions; ${review}`);
433
523
  }
434
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
+
435
558
  const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
436
559
  let defaultAgent = null;
560
+ let openCodeConfig = null;
561
+ let openCodeConfigFile = null;
437
562
  for (const file of configPaths) {
438
563
  const configPath = join(target, file);
439
564
  if (!existsSync(configPath)) continue;
@@ -442,49 +567,82 @@ async function cmdDoctor(args) {
442
567
  // JSONC comments and trailing commas are supported by OpenCode.
443
568
  const clean = text.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
444
569
  (match) => match.startsWith('"') ? match : "").replace(/,\s*([}\]])/g, "$1");
445
- 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;
446
574
  } catch {
447
575
  add("OpenCode config", "fail", `cannot parse ${file}; check the config manually`);
448
576
  }
449
577
  }
450
578
  add(
451
579
  "default agent",
452
- defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
580
+ defaultAgent === "coordinator" ? "pass" : "fail",
453
581
  defaultAgent
454
582
  ? `default_agent=${defaultAgent}`
455
- : "not set; native Build remains the default"
583
+ : "missing; run devcomp update"
456
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
+ }
457
604
  }
458
605
 
459
606
  const agentsPath = join(target, "AGENTS.md");
460
607
  if (!existsSync(agentsPath)) {
461
- add("AGENTS.md", "fail", "missing");
608
+ add("AGENTS.md", "fail", "missing; run devcomp update");
462
609
  } else {
463
610
  const content = readFileSync(agentsPath, "utf8");
464
611
  const managed = hasManagedBlock(content);
465
- const pending = content.split("<!-- development-companion:start -->")[0].includes("# Project rules merge pending");
466
- const current = managed && content.includes(".companion/core/process.md") && !pending;
467
- add("AGENTS.md", current ? "pass" : "fail", current ? "canonical process linked" :
468
- pending
469
- ? "merge the original from .companion/local/rules-backup/ into AGENTS.md and remove pending notice after review"
470
- : "framework rules missing or outdated; ask the harness agent to merge the rules, or use devcomp init --rules handoff");
612
+ const pending = content.includes(MERGE_PENDING) || content.split(START)[0].includes("# Project rules merge pending");
613
+ const guiding = content.includes(USER_GUIDING);
614
+ const tpl = templateVersion(content);
615
+ const current = managed && guiding && !pending && tpl === VERSION;
616
+ add("AGENTS.md", current ? "pass" : "fail",
617
+ current
618
+ ? `managed template ${tpl} + User guiding`
619
+ : pending
620
+ ? "merge pending: read AGENTS.md.bak, merge it into User guiding, remove the notice, run devcomp doctor"
621
+ : !managed
622
+ ? "managed block missing; run devcomp update"
623
+ : !guiding
624
+ ? "User guiding section missing; run devcomp update"
625
+ : `template ${tpl ?? "unknown"} != ${VERSION}; run devcomp update`);
471
626
 
472
627
  // Check the installed process block, not project notes or migration history.
473
628
  // Published legacy rules use inline code and may wrap sentences across lines.
474
629
  const start = content.indexOf(START);
475
630
  const end = content.indexOf(END, start + START.length);
476
631
  const block = start !== -1 && end > start ? content.slice(start + START.length, end) : "";
477
- const normalized = block.replace(/[`*_]/g, "").replace(/\s+/g, " ");
632
+ const normalized = block.replace(/[`*]/g, "").replace(/\s+/g, " ");
478
633
  const staleLeadPrimary = /\bteam-lead is the default primary agent\b/i.test(normalized);
479
- 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);
480
636
  add(
481
637
  "delivery mode",
482
- staleLeadPrimary ? "fail" : nativeBuild ? "pass" : "warn",
638
+ staleLeadPrimary || staleNativeBuild ? "fail" : coordinatorPrimary ? "pass" : "warn",
483
639
  staleLeadPrimary
484
- ? "stale team-lead-primary rules; run devcomp init --rules append or merge the new block"
485
- : nativeBuild
486
- ? "native Build is the default; team-lead is a callable subagent"
487
- : "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"
488
646
  );
489
647
  }
490
648
 
@@ -540,31 +698,95 @@ async function cmdUpdate(args) {
540
698
  const manifest = readManifest(target);
541
699
  if (!manifest) throw new Error("no installation found; run `devcomp init` first.");
542
700
  const adapter = loadAdapter(manifest.harness);
543
- const force = bool(args, "force");
701
+ const keep = bool(args, "keep");
702
+ const force = !keep;
703
+ const dryRun = bool(args, "dry-run");
544
704
  const skills = manifest.skills ?? [];
545
- const roles = manifest.roles ?? [];
546
- const skillResults = installSkills({ target, adapter, skills, force });
547
- installCanonical({ target, force });
548
- const roleResults = installRoles({ target, roles, force });
549
- installBindings({ target, adapter, roles, force });
550
- const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
551
- const rulesPath = join(target, "AGENTS.md");
552
- if (existsSync(rulesPath) && hasManagedBlock(readFileSync(rulesPath, "utf8"))) {
553
- applyRules({ filePath: rulesPath, mode: "append", block: renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
554
- projectName: basename(target), profile: manifest.profile, branching: manifest.branching,
555
- docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
556
- }) });
705
+ const roles = [...new Set([...(manifest.roles ?? []), ...ROLES])];
706
+ const skillResults = installSkills({ target, adapter, skills, force, dryRun });
707
+ const canonicalResults = installCanonical({ target, force, dryRun });
708
+ const roleResults = installRoles({ target, roles, force, dryRun });
709
+ installBindings({ target, adapter, roles, force, dryRun });
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;
718
+
719
+ const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
720
+ version: VERSION,
721
+ projectName: basename(target),
722
+ profile: manifest.profile,
723
+ branching: manifest.branching,
724
+ docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
725
+ });
726
+ const agentsResult = applyAgentsFile({
727
+ filePath: join(target, "AGENTS.md"),
728
+ mode: "update",
729
+ block: agentsBlock,
730
+ backupPath: join(target, "AGENTS.md.bak"),
731
+ dryRun
732
+ });
733
+ if (["blocked", "error"].includes(agentsResult.mode)) {
734
+ throw new Error(`AGENTS.md: ${agentsResult.reason ?? agentsResult.mode}`);
557
735
  }
736
+
558
737
  manifest.packageVersion = VERSION;
559
738
  manifest.contentVersion = VERSION;
560
- writeManifest(target, manifest);
561
- console.log(`Updated to ${VERSION}.`);
562
- console.log(` Skills: ${skillResults.filter((r) => r.status === "kept").length} kept, ${skillResults.filter((r) => r.status === "installed").length} added`);
563
- console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter((r) => r.status === "installed").length} added`);
739
+ manifest.roles = roles;
740
+ manifest.rules = { ...(manifest.rules ?? {}), "AGENTS.md": agentsResult.mode };
741
+ writeManifest(target, manifest, { dryRun });
742
+ const ignore = ensureGitignore(target, [".companion/local/", "AGENTS.md.bak"]);
743
+ const changed = (r) => ["installed", "would-install", "overwritten", "would-overwrite"].includes(r.status);
744
+ console.log(`${dryRun ? "Would update" : "Updated"} to ${VERSION}.`);
745
+ console.log(` Skills: ${skillResults.filter((r) => r.status === "kept").length} kept, ${skillResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
746
+ console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
747
+ console.log(` Canonical: ${canonicalResults.filter((r) => r.status === "kept").length} kept, ${canonicalResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
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
+ }
564
752
  if (openCodeConfig) {
565
753
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
754
+ if (openCodeConfig.reason) console.log(` ${openCodeConfig.reason}`);
755
+ }
756
+ if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
757
+ if (dryRun) console.log(" Dry run: no files were written.");
758
+ console.log("");
759
+ if (agentsResult.mode === "merge-pending") {
760
+ console.log("ACTION REQUIRED: AGENTS.md has a merge-pending notice. Start an agent session and ask it");
761
+ console.log("to merge AGENTS.md.bak into the User guiding section, then run `devcomp doctor`.");
762
+ } else if (agentsResult.mode === "migrated") {
763
+ console.log("AGENTS.md migrated automatically: the previous content is under User guiding.");
764
+ console.log("Review it and run `devcomp doctor`; no agent merge is required.");
765
+ } else if (agentsResult.mode === "unchanged") {
766
+ console.log("AGENTS.md is already current; the User guiding section was preserved.");
767
+ console.log("Run `devcomp doctor`.");
768
+ } else {
769
+ console.log("AGENTS.md managed block updated; the User guiding section was preserved.");
770
+ console.log("Run `devcomp doctor`.");
566
771
  }
567
- console.log(" Existing files are preserved; use --force to overwrite.");
772
+ }
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.");
568
790
  }
569
791
 
570
792
  export async function main(argv) {
@@ -582,6 +804,7 @@ export async function main(argv) {
582
804
  if (command === "add") return cmdAdd(args);
583
805
  if (command === "doctor") return cmdDoctor(args);
584
806
  if (command === "update") return cmdUpdate(args);
807
+ if (command === "setup") return cmdSetup(args);
585
808
  if (command === "scaffold") return scaffoldProject(args);
586
809
  throw new Error(`unknown command "${command}". Run "devcomp --help".`);
587
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.",