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/CHANGELOG.md +26 -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 +1 -1
- package/src/cli.mjs +130 -18
- package/src/content.mjs +16 -0
- package/src/install.mjs +311 -43
- package/templates/rules/AGENTS.block.md +26 -6
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
|
|
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
|
|
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
|
|
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(", ")}` : `${
|
|
415
|
-
const staleBindings =
|
|
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;
|
|
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
|
-
|
|
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 === "
|
|
580
|
+
defaultAgent === "coordinator" ? "pass" : "fail",
|
|
522
581
|
defaultAgent
|
|
523
582
|
? `default_agent=${defaultAgent}`
|
|
524
|
-
: "
|
|
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(/[`*
|
|
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
|
|
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" :
|
|
638
|
+
staleLeadPrimary || staleNativeBuild ? "fail" : coordinatorPrimary ? "pass" : "warn",
|
|
560
639
|
staleLeadPrimary
|
|
561
|
-
? "stale team-lead-primary rules; run devcomp
|
|
562
|
-
:
|
|
563
|
-
? "native Build
|
|
564
|
-
:
|
|
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
|
|
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.",
|