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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "development-companion",
|
|
3
|
-
"version": "1.
|
|
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
|
-
|
|
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 {
|
|
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>
|
|
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;
|
|
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":
|
|
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] =
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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"] =
|
|
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, "
|
|
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
|
|
253
|
-
|
|
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
|
-
|
|
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
|
|
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(", ")}` : `${
|
|
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;
|
|
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
|
-
|
|
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 === "
|
|
580
|
+
defaultAgent === "coordinator" ? "pass" : "fail",
|
|
453
581
|
defaultAgent
|
|
454
582
|
? `default_agent=${defaultAgent}`
|
|
455
|
-
: "
|
|
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.
|
|
466
|
-
const
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
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(/[`*
|
|
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
|
|
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" :
|
|
638
|
+
staleLeadPrimary || staleNativeBuild ? "fail" : coordinatorPrimary ? "pass" : "warn",
|
|
483
639
|
staleLeadPrimary
|
|
484
|
-
? "stale team-lead-primary rules; run devcomp
|
|
485
|
-
:
|
|
486
|
-
? "native Build
|
|
487
|
-
:
|
|
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
|
|
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
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
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
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
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
|
-
|
|
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.",
|