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/CHANGELOG.md +29 -0
- package/README.md +40 -24
- package/RELEASE.md +24 -15
- package/adapters/README.md +3 -2
- package/adapters/opencode/README.md +14 -15
- package/core/guidelines/coordination.md +78 -0
- package/core/principles.md +3 -3
- package/core/process.md +9 -6
- package/core/quality-gates.md +2 -2
- package/core/roles/architect.md +6 -5
- package/core/roles/qa-engineer.md +3 -2
- package/core/roles/team-lead.md +17 -15
- package/core/workflow.md +6 -13
- package/package.json +3 -2
- package/skills/development-workflow/SKILL.md +7 -0
- package/skills/project-discovery/SKILL.md +9 -3
- package/skills/ux-design/SKILL.md +4 -0
- package/src/cli.mjs +182 -46
- package/src/content.mjs +1 -1
- package/src/install.mjs +27 -49
- package/src/rules.mjs +136 -6
- package/templates/artifacts/01-operational-brief.md +9 -1
- package/templates/rules/AGENTS.block.md +124 -52
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
|
-
|
|
27
|
-
|
|
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 →
|
|
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.
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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 {
|
|
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>
|
|
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;
|
|
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":
|
|
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] =
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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"] =
|
|
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, "
|
|
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
|
-
|
|
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
|
|
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
|
-
:
|
|
470
|
+
? "team-lead is a callable advisor; native primary owns delivery"
|
|
471
|
+
: `legacy primary team-lead binding; ${review}`
|
|
401
472
|
);
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
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.
|
|
441
|
-
const
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
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
|
|
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
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
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
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
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(
|
|
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": "
|
|
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.",
|