development-companion 1.6.0 → 1.8.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.
@@ -17,6 +17,18 @@ what "working" means and how it will be proven.
17
17
  Do not write a 300-line test plan before the first commit. Define the **first five tests** that
18
18
  prove the walking skeleton and the riskiest failure path. Expand the plan as slices land.
19
19
 
20
+ For a feature, the test plan is part of the user-visible plan:
21
+
22
+ - **Golden paths:** the user-visible flows that prove the feature works end to end.
23
+ - **Dark paths:** denial, invalid input, timeout, partial failure, retry, rollback, empty state.
24
+ - For each case: level, observable expected result, exact command or step, and the artifact to
25
+ attach as evidence.
26
+ - Every critical dark case needs evidence or a declared gap before the feature closes. A green
27
+ unit suite is not an end-to-end result.
28
+
29
+ Use `templates/artifacts/11-feature-plan.md` and keep the test plan next to the development
30
+ plan so the user sees both before approving.
31
+
20
32
  ## When to use
21
33
 
22
34
  - Before implementing a feature or a new project.
package/src/cli.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
2
- import { basename, join, relative, resolve } from "node:path";
2
+ import { basename, dirname, 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";
@@ -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,
@@ -32,6 +35,7 @@ import {
32
35
  } from "./install.mjs";
33
36
  import {
34
37
  DOMAIN_SKILLS,
38
+ IMPLEMENTATION_ROLES,
35
39
  PROCESS_SKILLS,
36
40
  PROFILES,
37
41
  ROLES,
@@ -50,6 +54,7 @@ Usage:
50
54
  devcomp add <skill|role|profile> <name>
51
55
  devcomp doctor [dir] Check an installation
52
56
  devcomp update [dir] Refresh installed content
57
+ devcomp setup [opencode] --global Install the runtime adapter for every project
53
58
  devcomp scaffold [dir] Generate the TypeScript reference monorepo
54
59
 
55
60
  Init options:
@@ -69,9 +74,14 @@ Init options:
69
74
  --version, --help
70
75
 
71
76
  Update options:
72
- --keep Preserve skills, roles, bindings, and core instead of replacing them
77
+ --keep Preserve skills, roles, bindings, core, and OpenCode config instead of replacing them
73
78
  --dry-run Print the plan without writing
74
79
  --target <dir> Target directory
80
+
81
+ Setup options:
82
+ devcomp setup opencode --global Install the OpenCode runtime plugin for every project
83
+ --force Overwrite an existing global plugin
84
+ --dry-run Print the plan without writing
75
85
  `;
76
86
 
77
87
  function loadAdapter(name) {
@@ -278,7 +288,12 @@ async function cmdInit(args) {
278
288
  const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
279
289
  const roleResults = installRoles({ target: requested, roles, force });
280
290
  const bindingResults = installBindings({ target: requested, adapter, roles, force });
281
- const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(requested) : null;
291
+ const pluginResult = adapter.name === "opencode"
292
+ ? installPlugin({ target: requested, force, dryRun })
293
+ : null;
294
+ const openCodeConfig = adapter.name === "opencode"
295
+ ? writeOpenCodeConfig(requested, { dryRun })
296
+ : null;
282
297
  const ignore = ensureGitignore(requested, [".companion/local/", "AGENTS.md.bak"]);
283
298
 
284
299
  const manifest = {
@@ -315,8 +330,12 @@ async function cmdInit(args) {
315
330
  if (bindingResults.length) {
316
331
  console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
317
332
  }
333
+ if (pluginResult) {
334
+ console.log(` OpenCode plugin: ${pluginResult.status}`);
335
+ }
318
336
  if (openCodeConfig) {
319
337
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
338
+ if (openCodeConfig.reason) console.log(` ${openCodeConfig.reason}`);
320
339
  }
321
340
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
322
341
  console.log("");
@@ -407,18 +426,30 @@ async function cmdDoctor(args) {
407
426
 
408
427
  if (adapter?.agentDir && adapter.agentFormat) {
409
428
  const extension = adapter.agentFormat === "toml" ? "toml" : "md";
410
- const missingBindings = (manifest.roles ?? []).filter(
429
+ const bindingRoles = (manifest.roles ?? []).filter(
430
+ (role) => !(role === "coordinator" && adapter.name !== "opencode")
431
+ );
432
+ const missingBindings = bindingRoles.filter(
411
433
  (role) => !existsSync(join(target, adapter.agentDir, `${role}.${extension}`))
412
434
  );
413
435
  add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
414
- ? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
415
- const staleBindings = (manifest.roles ?? []).filter((role) => {
436
+ ? `missing: ${missingBindings.join(", ")}` : `${bindingRoles.length} present`);
437
+ const staleBindings = bindingRoles.filter((role) => {
416
438
  const file = join(target, adapter.agentDir, `${role}.${extension}`);
417
439
  return existsSync(file) && !readFileSync(file, "utf8").includes("coordination.md");
418
440
  });
419
441
  add("binding content", staleBindings.length ? "fail" : "pass", staleBindings.length
420
442
  ? `missing coordination.md: ${staleBindings.join(", ")}; run devcomp update`
421
443
  : "all bindings link coordination.md");
444
+ const scopedRoles = IMPLEMENTATION_ROLES.filter((role) =>
445
+ existsSync(join(target, adapter.agentDir, `${role}.${extension}`)));
446
+ const missingScopeLock = scopedRoles.filter((role) => {
447
+ const content = readFileSync(join(target, adapter.agentDir, `${role}.${extension}`), "utf8");
448
+ return !/Scope lock/i.test(content) || !/out-of-scope/i.test(content) || !/destructive/i.test(content);
449
+ });
450
+ add("scope lock", missingScopeLock.length ? "fail" : "pass", missingScopeLock.length
451
+ ? `missing scope lock: ${missingScopeLock.join(", ")}; run devcomp update`
452
+ : `${scopedRoles.length} implementation bindings enforce plan, scope and destructive stop`);
422
453
  }
423
454
 
424
455
  const missingCore = CANONICAL_FILES.filter((file) => !existsSync(join(target, ".companion", "core", file)));
@@ -467,7 +498,7 @@ async function cmdDoctor(args) {
467
498
  "orchestrator",
468
499
  callable ? "pass" : "fail",
469
500
  callable
470
- ? "team-lead is a callable advisor; native primary owns delivery"
501
+ ? "team-lead is a callable advisor; coordinator owns delivery"
471
502
  : `legacy primary team-lead binding; ${review}`
472
503
  );
473
504
 
@@ -501,8 +532,97 @@ async function cmdDoctor(args) {
501
532
  : `cannot verify team-lead permission restrictions; ${review}`);
502
533
  }
503
534
 
535
+ const coordinatorPath = join(target, ".opencode", "agents", "coordinator.md");
536
+ if (!existsSync(coordinatorPath)) {
537
+ add("coordinator", "fail", "binding missing; run devcomp update");
538
+ } else {
539
+ const content = readFileSync(coordinatorPath, "utf8");
540
+ const primary = /^mode:[ \t]*primary[ \t]*(?:#.*)?$/m.test(content);
541
+ const editsDenied = /- action:[ \t]*edit\s*\n\s*resource:[ \t]*"\*"\s*\n\s*effect:[ \t]*deny/m.test(content);
542
+ const shellDenied = /- action:[ \t]*shell\s*\n\s*resource:[ \t]*"\*"\s*\n\s*effect:[ \t]*deny/m.test(content);
543
+ const reconAllowed = /- action:[ \t]*subagent\s*\n\s*resource:[ \t]*"(?:architect|qa-engineer|cybersecurity-engineer)"\s*\n\s*effect:[ \t]*allow/m.test(content);
544
+ 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);
545
+ const valid = primary && editsDenied && shellDenied && reconAllowed && implementationAsked;
546
+ add("coordinator", valid ? "pass" : "fail", valid
547
+ ? "primary; product edits and shell denied; implementation delegation asks"
548
+ : "invalid coordinator binding; run devcomp update");
549
+ }
550
+
551
+ const localPlugin = join(target, ".opencode", "plugins", "devcomp", "index.ts");
552
+ const globalPlugin = join(homedir(), ".config", "opencode", "plugins", "devcomp", "index.ts");
553
+ const legacyGlobalPlugin = join(homedir(), ".config", "opencode", "plugins", "devcomp.ts");
554
+ const pluginPath = existsSync(localPlugin)
555
+ ? localPlugin
556
+ : existsSync(globalPlugin)
557
+ ? globalPlugin
558
+ : existsSync(legacyGlobalPlugin)
559
+ ? legacyGlobalPlugin
560
+ : null;
561
+ add("runtime plugin", pluginPath ? "pass" : "fail", pluginPath
562
+ ? pluginPath === localPlugin
563
+ ? `installed at ${relative(target, localPlugin)}`
564
+ : pluginPath === legacyGlobalPlugin
565
+ ? `legacy global adapter at ${legacyGlobalPlugin}; run devcomp setup opencode --global --force`
566
+ : `global adapter at ${globalPlugin}; run devcomp update for a repo-local copy`
567
+ : "missing; run devcomp update or devcomp setup opencode --global");
568
+ if (pluginPath) {
569
+ const pluginDir = dirname(pluginPath);
570
+ const gatesPath = join(pluginDir, "gates.mjs");
571
+ const plugin =
572
+ readFileSync(pluginPath, "utf8") +
573
+ (existsSync(gatesPath) ? `\n${readFileSync(gatesPath, "utf8")}` : "");
574
+ const injects = plugin.includes('session.hook("context"');
575
+ const gates = plugin.includes('permission.hook("evaluate"');
576
+ add("runtime gate", injects && gates ? "pass" : "fail", injects && gates
577
+ ? "injects the canonical process and evaluates permissions"
578
+ : "plugin does not implement injection + gate; run devcomp update");
579
+
580
+ const planGate = existsSync(gatesPath) &&
581
+ plugin.includes("devcomp:plan-gate") &&
582
+ plugin.includes("readPlanApproval") &&
583
+ plugin.includes("Aprobado") &&
584
+ plugin.includes('tool.hook("execute.before"');
585
+ add("plan gate", planGate ? "pass" : "fail", planGate
586
+ ? "implementation delegation requires an affirmative approved plan with a top-level Scope"
587
+ : "plugin does not enforce the plan gate; run devcomp update");
588
+
589
+ const scopeGate = existsSync(gatesPath) &&
590
+ plugin.includes("devcomp:scope-gate") &&
591
+ plugin.includes("inScope") &&
592
+ /["']edit["']/.test(plugin) &&
593
+ /["']write["']/.test(plugin) &&
594
+ /["']patch["']/.test(plugin);
595
+ add("scope gate", scopeGate ? "pass" : "fail", scopeGate
596
+ ? "edit, write, patch, apply_patch and multiedit stay inside the recorded Scope"
597
+ : "plugin does not enforce the scope gate; run devcomp update");
598
+
599
+ const destructive = plugin.includes("devcomp:destructive-guard") &&
600
+ plugin.includes("isDestructiveCommand") &&
601
+ plugin.includes('event.effect = "ask"') &&
602
+ plugin.includes("hard Git reset") &&
603
+ plugin.includes("volume deletion") &&
604
+ plugin.includes("infrastructure destruction");
605
+ add("destructive guard", destructive ? "pass" : "fail", destructive
606
+ ? "known destructive patterns always ask the user"
607
+ : "plugin does not force authorization for destructive commands; run devcomp update");
608
+ }
609
+
610
+ const localExists = existsSync(localPlugin);
611
+ const globalExists = existsSync(globalPlugin);
612
+ const legacyExists = existsSync(legacyGlobalPlugin);
613
+ if (legacyExists && (localExists || globalExists)) {
614
+ add("plugin coexistence", "fail",
615
+ "legacy global devcomp.ts coexists with the directory adapter; run devcomp setup opencode --global --force");
616
+ } else if (localExists && globalExists) {
617
+ add("plugin coexistence", "pass", "global adapter defers to the local plugin");
618
+ } else {
619
+ add("plugin coexistence", "pass", localExists ? "local adapter only" : globalExists ? "global adapter only" : "no adapter");
620
+ }
621
+
504
622
  const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
505
623
  let defaultAgent = null;
624
+ let openCodeConfig = null;
625
+ let openCodeConfigFile = null;
506
626
  for (const file of configPaths) {
507
627
  const configPath = join(target, file);
508
628
  if (!existsSync(configPath)) continue;
@@ -511,18 +631,40 @@ async function cmdDoctor(args) {
511
631
  // JSONC comments and trailing commas are supported by OpenCode.
512
632
  const clean = text.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
513
633
  (match) => match.startsWith('"') ? match : "").replace(/,\s*([}\]])/g, "$1");
514
- defaultAgent = JSON.parse(clean).default_agent ?? defaultAgent;
634
+ const parsed = JSON.parse(clean);
635
+ defaultAgent = parsed.default_agent ?? defaultAgent;
636
+ openCodeConfig = parsed;
637
+ openCodeConfigFile = file;
515
638
  } catch {
516
639
  add("OpenCode config", "fail", `cannot parse ${file}; check the config manually`);
517
640
  }
518
641
  }
519
642
  add(
520
643
  "default agent",
521
- defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
644
+ defaultAgent === "coordinator" ? "pass" : "fail",
522
645
  defaultAgent
523
646
  ? `default_agent=${defaultAgent}`
524
- : "not set; native Build remains the default"
647
+ : "missing; run devcomp update"
525
648
  );
649
+ if (openCodeConfig) {
650
+ const instructions = Array.isArray(openCodeConfig.instructions) ? openCodeConfig.instructions : [];
651
+ const missingInstructions = OPENCODE_INSTRUCTIONS.filter((entry) => !instructions.includes(entry));
652
+ add("config instructions", missingInstructions.length ? "fail" : "pass", missingInstructions.length
653
+ ? `missing: ${missingInstructions.join(", ")}; run devcomp update`
654
+ : `${OPENCODE_INSTRUCTIONS.length} canonical files`);
655
+ const rules = Array.isArray(openCodeConfig.permissions) ? openCodeConfig.permissions : [];
656
+ const pushDenied = rules.some((rule) =>
657
+ rule?.action === "shell" && rule?.resource === "git push *" && rule?.effect === "deny");
658
+ const exploreRules = openCodeConfig.agents?.explore?.permissions;
659
+ const exploreDenied = Array.isArray(exploreRules) && exploreRules.some((rule) =>
660
+ rule?.action === "shell" && rule?.resource === "*" && rule?.effect === "deny");
661
+ add("config gate", pushDenied && exploreDenied ? "pass" : "fail", pushDenied && exploreDenied
662
+ ? "git push denied; explore is read-only"
663
+ : `missing required rules in ${openCodeConfigFile}; run devcomp update`);
664
+ } else {
665
+ add("config instructions", "fail", "opencode.json missing; run devcomp update");
666
+ add("config gate", "fail", "opencode.json missing; run devcomp update");
667
+ }
526
668
  }
527
669
 
528
670
  const agentsPath = join(target, "AGENTS.md");
@@ -551,18 +693,34 @@ async function cmdDoctor(args) {
551
693
  const start = content.indexOf(START);
552
694
  const end = content.indexOf(END, start + START.length);
553
695
  const block = start !== -1 && end > start ? content.slice(start + START.length, end) : "";
554
- const normalized = block.replace(/[`*_]/g, "").replace(/\s+/g, " ");
696
+ const normalized = block.replace(/[`*]/g, "").replace(/\s+/g, " ");
555
697
  const staleLeadPrimary = /\bteam-lead is the default primary agent\b/i.test(normalized);
556
- const nativeBuild = /\bnative Build\b/i.test(normalized);
698
+ const staleNativeBuild = /\bnative Build is the default\b/i.test(normalized);
699
+ const coordinatorPrimary = /\bcoordinator\b/i.test(normalized) && /\bdefault_agent\b/i.test(normalized);
557
700
  add(
558
701
  "delivery mode",
559
- staleLeadPrimary ? "fail" : nativeBuild ? "pass" : "warn",
702
+ staleLeadPrimary || staleNativeBuild ? "fail" : coordinatorPrimary ? "pass" : "warn",
560
703
  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"
704
+ ? "stale team-lead-primary rules; run devcomp update"
705
+ : staleNativeBuild
706
+ ? "stale native Build default; run devcomp update"
707
+ : coordinatorPrimary
708
+ ? "coordinator is the default primary; implementation delegation asks the user"
709
+ : "managed block does not state the coordinator default; review it"
565
710
  );
711
+
712
+ const featureTokens = ["Working modes", "Feature intake", "Scope lock", "Goal continuity", "Escalation", "Aprobado"];
713
+ const missingFeature = featureTokens.filter((token) => !block.includes(token));
714
+ const featureFlow = missingFeature.length === 0 &&
715
+ /development plan/i.test(block) &&
716
+ /test plan/i.test(block) &&
717
+ /golden/i.test(block) &&
718
+ /(?:end-to-end|E2E)/i.test(block) &&
719
+ /Plan:/i.test(block) &&
720
+ /destructive/i.test(block);
721
+ add("feature flow", featureFlow ? "pass" : "fail", featureFlow
722
+ ? "modes, intake, plan, scope lock, continuity, escalation and destructive stop are documented"
723
+ : `managed block is missing: ${missingFeature.join(", ") || "development plan, test plan, golden/E2E or destructive rules"}; run devcomp update`);
566
724
  }
567
725
 
568
726
  const claudePath = join(target, "CLAUDE.md");
@@ -621,12 +779,19 @@ async function cmdUpdate(args) {
621
779
  const force = !keep;
622
780
  const dryRun = bool(args, "dry-run");
623
781
  const skills = manifest.skills ?? [];
624
- const roles = manifest.roles ?? [];
782
+ const roles = [...new Set([...(manifest.roles ?? []), ...ROLES])];
625
783
  const skillResults = installSkills({ target, adapter, skills, force, dryRun });
626
784
  const canonicalResults = installCanonical({ target, force, dryRun });
627
785
  const roleResults = installRoles({ target, roles, force, dryRun });
628
786
  installBindings({ target, adapter, roles, force, dryRun });
629
- const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
787
+ const pluginResult = adapter.name === "opencode"
788
+ ? installPlugin({ target, force, dryRun })
789
+ : null;
790
+ const openCodeConfig = adapter.name === "opencode"
791
+ ? keep
792
+ ? { status: "kept (--keep)", path: "opencode.json" }
793
+ : writeOpenCodeConfig(target, { dryRun })
794
+ : null;
630
795
 
631
796
  const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
632
797
  version: VERSION,
@@ -648,6 +813,7 @@ async function cmdUpdate(args) {
648
813
 
649
814
  manifest.packageVersion = VERSION;
650
815
  manifest.contentVersion = VERSION;
816
+ manifest.roles = roles;
651
817
  manifest.rules = { ...(manifest.rules ?? {}), "AGENTS.md": agentsResult.mode };
652
818
  writeManifest(target, manifest, { dryRun });
653
819
  const ignore = ensureGitignore(target, [".companion/local/", "AGENTS.md.bak"]);
@@ -657,8 +823,12 @@ async function cmdUpdate(args) {
657
823
  console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
658
824
  console.log(` Canonical: ${canonicalResults.filter((r) => r.status === "kept").length} kept, ${canonicalResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
659
825
  console.log(` AGENTS.md: ${agentsResult.mode}${agentsResult.backupPath ? ` (backup: ${relative(target, agentsResult.backupPath)})` : ""}`);
826
+ if (pluginResult) {
827
+ console.log(` OpenCode plugin: ${pluginResult.status}`);
828
+ }
660
829
  if (openCodeConfig) {
661
830
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
831
+ if (openCodeConfig.reason) console.log(` ${openCodeConfig.reason}`);
662
832
  }
663
833
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
664
834
  if (dryRun) console.log(" Dry run: no files were written.");
@@ -678,6 +848,27 @@ async function cmdUpdate(args) {
678
848
  }
679
849
  }
680
850
 
851
+ async function cmdSetup(args) {
852
+ const harness = args._[1] ?? "opencode";
853
+ if (harness !== "opencode") {
854
+ throw new Error(`global setup is only available for opencode; got "${harness}".`);
855
+ }
856
+ if (!bool(args, "global")) {
857
+ throw new Error("use `devcomp setup opencode --global` to install the runtime adapter for every project.");
858
+ }
859
+ const result = installGlobalPlugin({
860
+ home: homedir(),
861
+ force: bool(args, "force"),
862
+ dryRun: bool(args, "dry-run")
863
+ });
864
+ console.log(`OpenCode global plugin: ${result.status}${result.path ? ` (${result.path})` : ""}`);
865
+ if (result.reason) console.log(` ${result.reason}`);
866
+ if (result.backupPath) console.log(` Legacy backup: ${result.backupPath}`);
867
+ if (result.migrated) console.log(" Replaced the legacy single-file adapter; start a new session.");
868
+ console.log("New sessions in any devcomp project will load the runtime adapter; sessions outside a devcomp project are unaffected.");
869
+ if (["blocked", "missing", "skipped"].includes(result.status)) process.exitCode = 1;
870
+ }
871
+
681
872
  export async function main(argv) {
682
873
  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
683
874
  console.log(HELP);
@@ -693,6 +884,7 @@ export async function main(argv) {
693
884
  if (command === "add") return cmdAdd(args);
694
885
  if (command === "doctor") return cmdDoctor(args);
695
886
  if (command === "update") return cmdUpdate(args);
887
+ if (command === "setup") return cmdSetup(args);
696
888
  if (command === "scaffold") return scaffoldProject(args);
697
889
  throw new Error(`unknown command "${command}". Run "devcomp --help".`);
698
890
  }
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.",