development-companion 1.4.1 → 1.6.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/core/workflow.md CHANGED
@@ -23,18 +23,9 @@ Identify the task type and the minimum rigor it needs.
23
23
  If the task mixes types, split it. Do not ship a refactor and a behavior change in
24
24
  the same unreviewable diff.
25
25
 
26
- **First-commit rule:** for a new feature or project, create the thinnest runnable path before
27
- expanding the design. A plan that does not produce a commit is not progress.
28
-
29
- ## Phase 0.5 — First commit
30
-
31
- Before deep recon or a full plan, ask: *what is the smallest end-to-end path that can run?*
32
-
33
- - Wire the real entry point to a fake or minimal implementation.
34
- - Get one command and one test working.
35
- - Commit.
36
-
37
- Then use the rest of this workflow to deepen that path slice by slice.
26
+ For non-trivial work the Coordinator follows `core/guidelines/coordination.md`
27
+ for delegation, operational and technical conversations, and the approval gate.
28
+ Do not use the first-commit rule to skip approval.
38
29
 
39
30
  ## Phase 1 — Recon
40
31
 
@@ -95,6 +86,8 @@ Keep the plan proportional. A 40-file plan for a 5-line fix is a smell.
95
86
 
96
87
  ## Phase 4 — Implement
97
88
 
89
+ - After approval, get the smallest end-to-end path and one test running before
90
+ expanding the design. Keep the first commit in the first implementation block.
98
91
  - Follow the plan; if reality contradicts it, stop and revise the plan.
99
92
  - Match local patterns before introducing new abstractions.
100
93
  - Keep commits/checkpoints logical and reversible.
@@ -177,6 +170,6 @@ Do not pad the report. Do not claim success you did not verify.
177
170
  | Risk | Workflow |
178
171
  |---|---|
179
172
  | Low (typo, docs, one-line fix) | Recon → change → check → report |
180
- | Medium (feature in one layer) | Brief → plan → implement → tests → self-review |
173
+ | Medium (feature in one layer) | Brief → technical approval → implement → tests → review |
181
174
  | High (cross-layer, data, auth, public API) | Full workflow + independent review + rollback plan |
182
175
  | Incident | Stabilize first, then diagnose, fix, add regression coverage, write a short postmortem |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.4.1",
3
+ "version": "1.6.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -27,8 +27,9 @@
27
27
  "templates/",
28
28
  "adapters/",
29
29
  "README.md",
30
+ "CHANGELOG.md",
30
31
  "LICENSE",
31
- "RELEASE.md"
32
+ "RELEASE.md"
32
33
  ],
33
34
  "engines": {
34
35
  "node": ">=22"
@@ -82,6 +82,13 @@ For non-trivial work, state:
82
82
 
83
83
  Keep the plan proportional to the change.
84
84
 
85
+ For non-trivial work, the primary agent coordinates the operational and technical
86
+ conversations, with native specialist input where available. Only the primary
87
+ agent asks the user to explicitly approve the scope, acceptance criteria and
88
+ technical approach. Include golden and critical dark paths in verification.
89
+ Keep implementation blocked while approval is pending or the approved approach
90
+ needs a material change.
91
+
85
92
  ### 5. Implement
86
93
 
87
94
  - Follow the plan; revise it if reality contradicts it.
@@ -40,6 +40,9 @@ too broad: cut it.
40
40
 
41
41
  ## Procedure
42
42
 
43
+ Only the primary agent acting as Coordinator conducts these conversations
44
+ with the user. Specialists return findings and questions to that agent.
45
+
43
46
  ### 1. Operational discovery
44
47
 
45
48
  Ask one topic at a time. Record answers verbatim where they matter.
@@ -76,6 +79,8 @@ Ask one topic at a time. Record answers verbatim where they matter.
76
79
  ### 2. Technical discovery
77
80
 
78
81
  Only after the operational picture is clear.
82
+ Ask applicable specialists for read-only input and synthesize their options,
83
+ trade-offs, risks, and golden/dark verification paths.
79
84
 
80
85
  - Stack and versions: verify the latest stable release; do not invent version numbers.
81
86
  - Repository layout: monorepo or single repo; workspace tool.
@@ -91,7 +96,8 @@ Only after the operational picture is clear.
91
96
 
92
97
  - Summarize the brief in the user's language.
93
98
  - List assumptions, unknowns, and decisions that need the user.
94
- - Do not proceed to architecture while a blocking question is open.
99
+ - Record explicit user approval of the scoped approach before implementation.
100
+ A blocking question, rejection, or silence keeps the affected work pending.
95
101
 
96
102
  ## Output
97
103
 
@@ -124,12 +130,12 @@ Write `.companion/local/01-operational-brief.md` with:
124
130
  ## Open questions
125
131
  ```
126
132
 
127
- Add a short technical addendum if the discovery already covered stack decisions.
133
+ Record the technical options and approval reference in the brief or a linked ADR.
128
134
 
129
135
  ## Verification
130
136
 
131
137
  - Every section has an answer or an explicit "unknown".
132
- - The user confirmed the brief.
138
+ - The user explicitly approved the scope, acceptance criteria, and technical approach.
133
139
  - The branch convention is recorded with its source: detected, user, or default.
134
140
  - No acceptance criterion is untestable.
135
141
  - No secret values were read or printed.
@@ -109,6 +109,10 @@ the flow, not network calls, recording, authentication or persistent data.
109
109
 
110
110
  ### 8. Get approval
111
111
 
112
+ The primary agent presents the prototype and collects user approval. A UX
113
+ specialist returns the prototype, observed interactions and open questions to
114
+ the primary instead of asking the user directly.
115
+
112
116
  Present the flow, states, screenshots, and prototype entry point. Ask for explicit
113
117
  approval or a concrete change. Do not start implementation from an unapproved mockup;
114
118
  after approval hand off the validated states and interactions to the implementation role
package/src/cli.mjs CHANGED
@@ -1,10 +1,21 @@
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,
@@ -45,7 +56,7 @@ Init options:
45
56
  --harness <name> Force the harness adapter (auto by default)
46
57
  --profile <name> ${Object.keys(PROFILES).join(" | ")}
47
58
  --skills <a,b> Extra skills to install
48
- --rules <mode> keep | append | handoff | replace (existing rules)
59
+ --rules <mode> migrate | keep | handoff | replace (existing AGENTS.md)
49
60
  --branching <name> gitflow | gitlab-flow | trunk-based | github-flow | custom
50
61
  --docs <mode> local | tracked
51
62
  --memory <mode> engram | none
@@ -53,9 +64,14 @@ Init options:
53
64
  --layout <mode> monorepo | single (scaffold)
54
65
  --dry-run Print the plan without writing
55
66
  --force Allow replace/overwrite
56
- --yes Non-interactive; rules default to keep
67
+ --yes Non-interactive; migrate existing AGENTS.md with a backup
57
68
  --target <dir> Target directory for add/doctor/update
58
69
  --version, --help
70
+
71
+ Update options:
72
+ --keep Preserve skills, roles, bindings, and core instead of replacing them
73
+ --dry-run Print the plan without writing
74
+ --target <dir> Target directory
59
75
  `;
60
76
 
61
77
  function loadAdapter(name) {
@@ -94,6 +110,13 @@ function normalizeMode(value, fallback) {
94
110
  return value;
95
111
  }
96
112
 
113
+ function normalizeAgentsMode(value, fallback) {
114
+ if (!value || value === true) return fallback;
115
+ if (["append", "migrate", "update"].includes(value)) return "update";
116
+ if (["keep", "handoff", "replace"].includes(value)) return value;
117
+ throw new Error(`invalid rules mode "${value}". Use migrate, keep, handoff, or replace.`);
118
+ }
119
+
97
120
  async function cmdInit(args) {
98
121
  const requested = args._[1] ? resolve(args._[1]) : process.cwd();
99
122
  const dryRun = bool(args, "dry-run");
@@ -158,18 +181,23 @@ async function cmdInit(args) {
158
181
 
159
182
  const rulesFlag = flag(args, "rules");
160
183
  const rules = {
161
- "AGENTS.md": normalizeMode(rulesFlag, "keep"),
184
+ "AGENTS.md": normalizeAgentsMode(rulesFlag, "update"),
162
185
  "CLAUDE.md": rulesFlag === "handoff" ? "keep" : normalizeMode(rulesFlag, "keep")
163
186
  };
164
187
  if (!yes && !rulesFlag) {
165
188
  for (const file of ["AGENTS.md", "CLAUDE.md"]) {
166
189
  const exists = file === "AGENTS.md" ? detected.rules.agents : detected.rules.claude;
167
190
  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
- );
191
+ rules[file] = file === "AGENTS.md"
192
+ ? normalizeAgentsMode(
193
+ await choose(
194
+ "AGENTS.md already exists. How should the framework rules be installed?",
195
+ ["migrate", "keep", "handoff", "replace"],
196
+ "migrate"
197
+ ),
198
+ "update"
199
+ )
200
+ : await choose("CLAUDE.md already exists. What should I do?", ["keep", "append", "replace"], "keep");
173
201
  }
174
202
  }
175
203
 
@@ -216,6 +244,7 @@ async function cmdInit(args) {
216
244
 
217
245
  const projectName = basename(requested);
218
246
  const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
247
+ version: VERSION,
219
248
  projectName,
220
249
  profile,
221
250
  branching,
@@ -224,12 +253,12 @@ async function cmdInit(args) {
224
253
  const claudeBlock = readTemplate("templates/rules/CLAUDE.block.md").trim();
225
254
 
226
255
  const rulesResult = {};
227
- rulesResult["AGENTS.md"] = applyRules({
256
+ rulesResult["AGENTS.md"] = applyAgentsFile({
228
257
  filePath: join(requested, "AGENTS.md"),
229
258
  mode: rules["AGENTS.md"],
230
259
  block: agentsBlock,
231
260
  force,
232
- backupPath: join(requested, ".companion", "local", "rules-backup", "AGENTS.md")
261
+ backupPath: join(requested, "AGENTS.md.bak")
233
262
  });
234
263
  if (["error", "blocked"].includes(rulesResult["AGENTS.md"].mode)) {
235
264
  throw new Error(`AGENTS.md: ${rulesResult["AGENTS.md"].reason}`);
@@ -250,7 +279,7 @@ async function cmdInit(args) {
250
279
  const roleResults = installRoles({ target: requested, roles, force });
251
280
  const bindingResults = installBindings({ target: requested, adapter, roles, force });
252
281
  const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(requested) : null;
253
- const ignore = ensureGitignore(requested, [".companion/local/"]);
282
+ const ignore = ensureGitignore(requested, [".companion/local/", "AGENTS.md.bak"]);
254
283
 
255
284
  const manifest = {
256
285
  schemaVersion: 1,
@@ -291,7 +320,12 @@ async function cmdInit(args) {
291
320
  }
292
321
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
293
322
  console.log("");
294
- console.log("Next: run `devcomp doctor`; resolve rules merge or legacy agent FAIL before starting work.");
323
+ if (rulesResult["AGENTS.md"]?.mode === "merge-pending") {
324
+ console.log("ACTION REQUIRED: the previous AGENTS.md is at AGENTS.md.bak and the new file has a merge-pending notice.");
325
+ console.log("Start an agent session and ask it to merge AGENTS.md.bak into the User guiding section, then run `devcomp doctor`.");
326
+ } else {
327
+ console.log("Next: run `devcomp doctor`. Review the User guiding section; an automatic migration needs no agent merge.");
328
+ }
295
329
  }
296
330
 
297
331
  async function cmdAdd(args) {
@@ -378,12 +412,47 @@ async function cmdDoctor(args) {
378
412
  );
379
413
  add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
380
414
  ? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
415
+ const staleBindings = (manifest.roles ?? []).filter((role) => {
416
+ const file = join(target, adapter.agentDir, `${role}.${extension}`);
417
+ return existsSync(file) && !readFileSync(file, "utf8").includes("coordination.md");
418
+ });
419
+ add("binding content", staleBindings.length ? "fail" : "pass", staleBindings.length
420
+ ? `missing coordination.md: ${staleBindings.join(", ")}; run devcomp update`
421
+ : "all bindings link coordination.md");
381
422
  }
382
423
 
383
424
  const missingCore = CANONICAL_FILES.filter((file) => !existsSync(join(target, ".companion", "core", file)));
384
425
  add("canonical process", missingCore.length ? "fail" : "pass", missingCore.length
385
426
  ? `missing: ${missingCore.join(", ")}; run devcomp update`
386
427
  : `${CANONICAL_FILES.length} files present`);
428
+ const staleCore = CANONICAL_FILES.filter((file) => {
429
+ const installed = join(target, ".companion", "core", file);
430
+ const expected = join(packageRoot(), "core", file);
431
+ return existsSync(installed) && existsSync(expected) && readFileSync(installed, "utf8") !== readFileSync(expected, "utf8");
432
+ });
433
+ add("canonical content", staleCore.length ? "fail" : "pass", staleCore.length
434
+ ? `stale or modified: ${staleCore.join(", ")}; run devcomp update`
435
+ : "matches package content");
436
+
437
+ const staleRoles = (manifest.roles ?? []).filter((role) => {
438
+ const installed = join(target, ".companion", "roles", `${role}.md`);
439
+ const expected = join(packageRoot(), "core", "roles", `${role}.md`);
440
+ return existsSync(installed) && existsSync(expected) && readFileSync(installed, "utf8") !== readFileSync(expected, "utf8");
441
+ });
442
+ add("role content", staleRoles.length ? "fail" : "pass", staleRoles.length
443
+ ? `stale or modified: ${staleRoles.join(", ")}; run devcomp update`
444
+ : "matches package content");
445
+
446
+ if (adapter) {
447
+ const staleSkills = (manifest.skills ?? []).filter((skill) => {
448
+ const installed = join(target, adapter.skillsDir, skill, "SKILL.md");
449
+ const expected = join(packageRoot(), "skills", skill, "SKILL.md");
450
+ return existsSync(installed) && existsSync(expected) && readFileSync(installed, "utf8") !== readFileSync(expected, "utf8");
451
+ });
452
+ add("skill content", staleSkills.length ? "fail" : "pass", staleSkills.length
453
+ ? `stale or modified: ${staleSkills.join(", ")}; run devcomp update`
454
+ : "matches package content");
455
+ }
387
456
 
388
457
  if (manifest.harness === "opencode") {
389
458
  const teamLeadPath = join(target, ".opencode", "agents", "team-lead.md");
@@ -391,20 +460,45 @@ async function cmdDoctor(args) {
391
460
  add("orchestrator", "fail", "team-lead binding missing");
392
461
  } else {
393
462
  const content = readFileSync(teamLeadPath, "utf8");
394
- const callable = /^mode:\s*subagent\s*$/m.test(content);
463
+ const frontmatter = content.match(/^---[ \t]*\r?\n((?:[^\n]*\n)*?)---[ \t]*(?:\r?\n|$)/)?.[1] ?? "";
464
+ const callable = /^mode:[ \t]*(?:subagent|"subagent"|'subagent')[ \t]*(?:#.*)?$/m.test(frontmatter);
465
+ const review = "review local edits before running devcomp add role team-lead --force (replaces the role and binding)";
395
466
  add(
396
467
  "orchestrator",
397
468
  callable ? "pass" : "fail",
398
469
  callable
399
- ? "team-lead is callable; native primary owns delivery"
400
- : "legacy primary team-lead binding; review local edits and run devcomp add role team-lead --force"
470
+ ? "team-lead is a callable advisor; native primary owns delivery"
471
+ : `legacy primary team-lead binding; ${review}`
401
472
  );
402
- const denies = (action) => new RegExp(`- action: ${action}\\s+resource: "\\*"\\s+effect: deny`).test(content);
403
- const delegates = /- action: subagent\s+resource: "\*"\s+effect: allow/.test(content);
404
- add("lead permissions", denies("edit") && denies("shell") && delegates ? "pass" : "fail",
405
- denies("edit") && denies("shell") && delegates
406
- ? "edits and shell denied; delegation allowed"
407
- : "outdated team-lead binding; review local edits and run devcomp add role team-lead --force to replace it");
473
+
474
+ // Inspect the binding's block-list format, not examples in the Markdown body.
475
+ const block = frontmatter.match(/^permissions:[ \t]*(?:#[^\r\n]*)?\r?\n((?:[^\S\r\n]*\r?\n|[ \t-][^\r\n]*\r?\n)*)/m)?.[1] ?? "";
476
+ const rule = /^[ \t]*-[ \t]+action:[ \t]*(.+?)[ \t]*\r?\n[ \t]+resource:[ \t]*(.+?)[ \t]*\r?\n[ \t]+effect:[ \t]*(.+?)[ \t]*\r?$/gm;
477
+ const scalar = (value) => value.match(/^(?:"([^"\\]*)"|'([^']*)'|([^\s"'#]+))[ \t]*(?:#.*)?$/)
478
+ ?.slice(1).find((part) => part !== undefined);
479
+ const parsed = Array.from(block.matchAll(rule), (match) => match.slice(1).map(scalar));
480
+ const permissions = parsed.filter(([action, resource, effect]) =>
481
+ action && resource && ["allow", "ask", "deny"].includes(effect));
482
+ const unsupported = permissions.length !== parsed.length ||
483
+ block.replace(rule, "").split(/\r?\n/).some((line) => !/^[ \t]*(?:#.*)?$/.test(line));
484
+ const denies = (action) => permissions.some(([a, resource, effect]) =>
485
+ a === action && resource === "*" && effect === "deny");
486
+ const targetsSubagents = (action) => {
487
+ const pattern = action.replace(/[.*+?^${}()|[\]\\]/g, (char) =>
488
+ char === "*" ? ".*" : char === "?" ? "." : `\\${char}`);
489
+ return new RegExp(`^${pattern}$`).test("subagent");
490
+ };
491
+ const denySubagentsAt = permissions.findLastIndex(([action, resource, effect]) =>
492
+ targetsSubagents(action) && resource === "*" && effect === "deny");
493
+ const delegates = permissions.slice(denySubagentsAt + 1).some(([action, , effect]) =>
494
+ targetsSubagents(action) && (effect === "allow" || effect === "ask"));
495
+ const restricted = !unsupported && denies("edit") && denies("shell") && denySubagentsAt >= 0 && !delegates;
496
+ add("lead permissions", restricted ? "pass" : "fail",
497
+ restricted
498
+ ? "edit and shell restrictions present; subdelegation denied"
499
+ : delegates
500
+ ? `legacy team-lead binding permits subdelegation; ${review}`
501
+ : `cannot verify team-lead permission restrictions; ${review}`);
408
502
  }
409
503
 
410
504
  const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
@@ -433,16 +527,24 @@ async function cmdDoctor(args) {
433
527
 
434
528
  const agentsPath = join(target, "AGENTS.md");
435
529
  if (!existsSync(agentsPath)) {
436
- add("AGENTS.md", "fail", "missing");
530
+ add("AGENTS.md", "fail", "missing; run devcomp update");
437
531
  } else {
438
532
  const content = readFileSync(agentsPath, "utf8");
439
533
  const managed = hasManagedBlock(content);
440
- const pending = content.split("<!-- development-companion:start -->")[0].includes("# Project rules merge pending");
441
- const current = managed && content.includes(".companion/core/process.md") && !pending;
442
- add("AGENTS.md", current ? "pass" : "fail", current ? "canonical process linked" :
443
- pending
444
- ? "merge the original from .companion/local/rules-backup/ into AGENTS.md and remove pending notice after review"
445
- : "framework rules missing or outdated; ask the harness agent to merge the rules, or use devcomp init --rules handoff");
534
+ const pending = content.includes(MERGE_PENDING) || content.split(START)[0].includes("# Project rules merge pending");
535
+ const guiding = content.includes(USER_GUIDING);
536
+ const tpl = templateVersion(content);
537
+ const current = managed && guiding && !pending && tpl === VERSION;
538
+ add("AGENTS.md", current ? "pass" : "fail",
539
+ current
540
+ ? `managed template ${tpl} + User guiding`
541
+ : pending
542
+ ? "merge pending: read AGENTS.md.bak, merge it into User guiding, remove the notice, run devcomp doctor"
543
+ : !managed
544
+ ? "managed block missing; run devcomp update"
545
+ : !guiding
546
+ ? "User guiding section missing; run devcomp update"
547
+ : `template ${tpl ?? "unknown"} != ${VERSION}; run devcomp update`);
446
548
 
447
549
  // Check the installed process block, not project notes or migration history.
448
550
  // Published legacy rules use inline code and may wrap sentences across lines.
@@ -515,31 +617,65 @@ async function cmdUpdate(args) {
515
617
  const manifest = readManifest(target);
516
618
  if (!manifest) throw new Error("no installation found; run `devcomp init` first.");
517
619
  const adapter = loadAdapter(manifest.harness);
518
- const force = bool(args, "force");
620
+ const keep = bool(args, "keep");
621
+ const force = !keep;
622
+ const dryRun = bool(args, "dry-run");
519
623
  const skills = manifest.skills ?? [];
520
624
  const roles = manifest.roles ?? [];
521
- const skillResults = installSkills({ target, adapter, skills, force });
522
- installCanonical({ target, force });
523
- const roleResults = installRoles({ target, roles, force });
524
- installBindings({ target, adapter, roles, force });
625
+ const skillResults = installSkills({ target, adapter, skills, force, dryRun });
626
+ const canonicalResults = installCanonical({ target, force, dryRun });
627
+ const roleResults = installRoles({ target, roles, force, dryRun });
628
+ installBindings({ target, adapter, roles, force, dryRun });
525
629
  const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
526
- const rulesPath = join(target, "AGENTS.md");
527
- if (existsSync(rulesPath) && hasManagedBlock(readFileSync(rulesPath, "utf8"))) {
528
- applyRules({ filePath: rulesPath, mode: "append", block: renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
529
- projectName: basename(target), profile: manifest.profile, branching: manifest.branching,
530
- docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
531
- }) });
630
+
631
+ const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
632
+ version: VERSION,
633
+ projectName: basename(target),
634
+ profile: manifest.profile,
635
+ branching: manifest.branching,
636
+ docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
637
+ });
638
+ const agentsResult = applyAgentsFile({
639
+ filePath: join(target, "AGENTS.md"),
640
+ mode: "update",
641
+ block: agentsBlock,
642
+ backupPath: join(target, "AGENTS.md.bak"),
643
+ dryRun
644
+ });
645
+ if (["blocked", "error"].includes(agentsResult.mode)) {
646
+ throw new Error(`AGENTS.md: ${agentsResult.reason ?? agentsResult.mode}`);
532
647
  }
648
+
533
649
  manifest.packageVersion = VERSION;
534
650
  manifest.contentVersion = VERSION;
535
- writeManifest(target, manifest);
536
- console.log(`Updated to ${VERSION}.`);
537
- console.log(` Skills: ${skillResults.filter((r) => r.status === "kept").length} kept, ${skillResults.filter((r) => r.status === "installed").length} added`);
538
- console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter((r) => r.status === "installed").length} added`);
651
+ manifest.rules = { ...(manifest.rules ?? {}), "AGENTS.md": agentsResult.mode };
652
+ writeManifest(target, manifest, { dryRun });
653
+ const ignore = ensureGitignore(target, [".companion/local/", "AGENTS.md.bak"]);
654
+ const changed = (r) => ["installed", "would-install", "overwritten", "would-overwrite"].includes(r.status);
655
+ console.log(`${dryRun ? "Would update" : "Updated"} to ${VERSION}.`);
656
+ console.log(` Skills: ${skillResults.filter((r) => r.status === "kept").length} kept, ${skillResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
657
+ console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
658
+ console.log(` Canonical: ${canonicalResults.filter((r) => r.status === "kept").length} kept, ${canonicalResults.filter(changed).length} ${dryRun ? "to replace" : "replaced"}`);
659
+ console.log(` AGENTS.md: ${agentsResult.mode}${agentsResult.backupPath ? ` (backup: ${relative(target, agentsResult.backupPath)})` : ""}`);
539
660
  if (openCodeConfig) {
540
661
  console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
541
662
  }
542
- console.log(" Existing files are preserved; use --force to overwrite.");
663
+ if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
664
+ if (dryRun) console.log(" Dry run: no files were written.");
665
+ console.log("");
666
+ if (agentsResult.mode === "merge-pending") {
667
+ console.log("ACTION REQUIRED: AGENTS.md has a merge-pending notice. Start an agent session and ask it");
668
+ console.log("to merge AGENTS.md.bak into the User guiding section, then run `devcomp doctor`.");
669
+ } else if (agentsResult.mode === "migrated") {
670
+ console.log("AGENTS.md migrated automatically: the previous content is under User guiding.");
671
+ console.log("Review it and run `devcomp doctor`; no agent merge is required.");
672
+ } else if (agentsResult.mode === "unchanged") {
673
+ console.log("AGENTS.md is already current; the User guiding section was preserved.");
674
+ console.log("Run `devcomp doctor`.");
675
+ } else {
676
+ console.log("AGENTS.md managed block updated; the User guiding section was preserved.");
677
+ console.log("Run `devcomp doctor`.");
678
+ }
543
679
  }
544
680
 
545
681
  export async function main(argv) {
package/src/content.mjs CHANGED
@@ -47,7 +47,7 @@ export const ROLES = [
47
47
  ];
48
48
 
49
49
  export const ROLE_DESCRIPTIONS = {
50
- "team-lead": "Leads discovery, planning, delegation, and closure. Use at project start or when coordinating multiple specialists.",
50
+ "team-lead": "Advises the primary on scope, sequencing, and delivery risks. Reports to the primary without subdelegating.",
51
51
  architect: "Defines boundaries, patterns, infrastructure, and ADRs. Use before implementation and for structural changes.",
52
52
  "cybersecurity-engineer": "Builds the threat model and verifies security with evidence. Use during architecture and before release.",
53
53
  "qa-engineer": "Defines the test strategy before development and verifies afterward. Use before implementation and before closure.",