development-companion 1.2.1 → 1.4.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/README.md +53 -32
- package/RELEASE.md +12 -9
- package/adapters/README.md +10 -2
- package/adapters/opencode/README.md +29 -32
- package/core/principles.md +21 -0
- package/core/process.md +126 -159
- package/core/quality-gates.md +21 -13
- package/core/roles/team-lead.md +50 -30
- package/core/workflow.md +16 -3
- package/package.json +1 -1
- package/skills/architecture-design/SKILL.md +7 -0
- package/skills/delivery-orchestration/SKILL.md +65 -67
- package/skills/development-workflow/SKILL.md +2 -0
- package/skills/incremental-delivery/SKILL.md +116 -0
- package/skills/project-discovery/SKILL.md +23 -3
- package/skills/test-strategy/SKILL.md +7 -2
- package/skills/ux-design/SKILL.md +43 -11
- package/src/cli.mjs +78 -26
- package/src/content.mjs +1 -0
- package/src/install.mjs +40 -33
- package/src/rules.mjs +31 -5
- package/templates/artifacts/01-operational-brief.md +17 -3
- package/templates/artifacts/06-delivery-plan.md +26 -5
- package/templates/rules/AGENTS.block.md +49 -18
package/src/cli.mjs
CHANGED
|
@@ -4,9 +4,11 @@ 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, renderTemplate } from "./rules.mjs";
|
|
7
|
+
import { applyRules, ensureGitignore, hasManagedBlock, renderTemplate } from "./rules.mjs";
|
|
8
8
|
import {
|
|
9
|
+
CANONICAL_FILES,
|
|
9
10
|
ensureDir,
|
|
11
|
+
installCanonical,
|
|
10
12
|
installBindings,
|
|
11
13
|
installRoles,
|
|
12
14
|
installSkills,
|
|
@@ -43,7 +45,7 @@ Init options:
|
|
|
43
45
|
--harness <name> Force the harness adapter (auto by default)
|
|
44
46
|
--profile <name> ${Object.keys(PROFILES).join(" | ")}
|
|
45
47
|
--skills <a,b> Extra skills to install
|
|
46
|
-
--rules <mode> keep | append | replace (existing
|
|
48
|
+
--rules <mode> keep | append | handoff | replace (existing rules)
|
|
47
49
|
--branching <name> gitflow | gitlab-flow | trunk-based | github-flow | custom
|
|
48
50
|
--docs <mode> local | tracked
|
|
49
51
|
--memory <mode> engram | none
|
|
@@ -86,8 +88,8 @@ function printPlan(plan) {
|
|
|
86
88
|
|
|
87
89
|
function normalizeMode(value, fallback) {
|
|
88
90
|
if (!value || value === true) return fallback;
|
|
89
|
-
if (!["keep", "append", "replace"].includes(value)) {
|
|
90
|
-
throw new Error(`invalid rules mode "${value}". Use keep, append, or replace.`);
|
|
91
|
+
if (!["keep", "append", "handoff", "replace"].includes(value)) {
|
|
92
|
+
throw new Error(`invalid rules mode "${value}". Use keep, append, handoff, or replace.`);
|
|
91
93
|
}
|
|
92
94
|
return value;
|
|
93
95
|
}
|
|
@@ -149,6 +151,7 @@ async function cmdInit(args) {
|
|
|
149
151
|
const skills = resolveSkills(profile, list(args, "skills"));
|
|
150
152
|
const roles = [...ROLES];
|
|
151
153
|
const docs = flag(args, "docs", "local");
|
|
154
|
+
if (!["local", "tracked"].includes(docs)) throw new Error(`invalid docs mode "${docs}". Use local or tracked.`);
|
|
152
155
|
const memory = flag(args, "memory", "none");
|
|
153
156
|
const mode = flag(args, "mode", "copy");
|
|
154
157
|
if (!["copy", "symlink"].includes(mode)) throw new Error(`invalid mode "${mode}". Use copy or symlink.`);
|
|
@@ -156,7 +159,7 @@ async function cmdInit(args) {
|
|
|
156
159
|
const rulesFlag = flag(args, "rules");
|
|
157
160
|
const rules = {
|
|
158
161
|
"AGENTS.md": normalizeMode(rulesFlag, "keep"),
|
|
159
|
-
"CLAUDE.md": normalizeMode(rulesFlag, "keep")
|
|
162
|
+
"CLAUDE.md": rulesFlag === "handoff" ? "keep" : normalizeMode(rulesFlag, "keep")
|
|
160
163
|
};
|
|
161
164
|
if (!yes && !rulesFlag) {
|
|
162
165
|
for (const file of ["AGENTS.md", "CLAUDE.md"]) {
|
|
@@ -164,7 +167,7 @@ async function cmdInit(args) {
|
|
|
164
167
|
if (!exists) continue;
|
|
165
168
|
rules[file] = await choose(
|
|
166
169
|
`${file} already exists. What should I do?`,
|
|
167
|
-
["keep", "append", "replace"],
|
|
170
|
+
file === "AGENTS.md" ? ["keep", "handoff", "append", "replace"] : ["keep", "append", "replace"],
|
|
168
171
|
"keep"
|
|
169
172
|
);
|
|
170
173
|
}
|
|
@@ -215,7 +218,8 @@ async function cmdInit(args) {
|
|
|
215
218
|
const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
|
|
216
219
|
projectName,
|
|
217
220
|
profile,
|
|
218
|
-
branching
|
|
221
|
+
branching,
|
|
222
|
+
docsDir: docs === "tracked" ? "docs/companion/" : ".companion/local/"
|
|
219
223
|
});
|
|
220
224
|
const claudeBlock = readTemplate("templates/rules/CLAUDE.block.md").trim();
|
|
221
225
|
|
|
@@ -224,15 +228,24 @@ async function cmdInit(args) {
|
|
|
224
228
|
filePath: join(requested, "AGENTS.md"),
|
|
225
229
|
mode: rules["AGENTS.md"],
|
|
226
230
|
block: agentsBlock,
|
|
227
|
-
force
|
|
231
|
+
force,
|
|
232
|
+
backupPath: join(requested, ".companion", "local", "rules-backup", "AGENTS.md")
|
|
228
233
|
});
|
|
234
|
+
if (["error", "blocked"].includes(rulesResult["AGENTS.md"].mode)) {
|
|
235
|
+
throw new Error(`AGENTS.md: ${rulesResult["AGENTS.md"].reason}`);
|
|
236
|
+
}
|
|
229
237
|
rulesResult["CLAUDE.md"] = applyRules({
|
|
230
238
|
filePath: join(requested, "CLAUDE.md"),
|
|
231
239
|
mode: rules["CLAUDE.md"],
|
|
232
240
|
block: claudeBlock,
|
|
233
|
-
force
|
|
241
|
+
force,
|
|
242
|
+
backupPath: join(requested, ".companion", "local", "rules-backup", "CLAUDE.md")
|
|
234
243
|
});
|
|
244
|
+
if (["error", "blocked"].includes(rulesResult["CLAUDE.md"].mode)) {
|
|
245
|
+
throw new Error(`CLAUDE.md: ${rulesResult["CLAUDE.md"].reason}`);
|
|
246
|
+
}
|
|
235
247
|
|
|
248
|
+
const canonicalResults = installCanonical({ target: requested, force });
|
|
236
249
|
const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
|
|
237
250
|
const roleResults = installRoles({ target: requested, roles, force });
|
|
238
251
|
const bindingResults = installBindings({ target: requested, adapter, roles, force });
|
|
@@ -268,6 +281,7 @@ async function cmdInit(args) {
|
|
|
268
281
|
console.log(` ${file}: ${result.mode}${result.reason ? ` (${result.reason})` : ""}`);
|
|
269
282
|
}
|
|
270
283
|
console.log(` Skills: ${skillResults.filter((r) => r.status === "installed").length} installed, ${skillResults.filter((r) => r.status === "kept").length} kept`);
|
|
284
|
+
console.log(` Canonical files: ${canonicalResults.filter((r) => r.status === "installed").length} installed, ${canonicalResults.filter((r) => r.status === "kept").length} kept`);
|
|
271
285
|
console.log(` Roles: ${roleResults.filter((r) => r.status === "installed").length} installed, ${roleResults.filter((r) => r.status === "kept").length} kept`);
|
|
272
286
|
if (bindingResults.length) {
|
|
273
287
|
console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
|
|
@@ -277,7 +291,7 @@ async function cmdInit(args) {
|
|
|
277
291
|
}
|
|
278
292
|
if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
|
|
279
293
|
console.log("");
|
|
280
|
-
console.log("Next: run `devcomp doctor
|
|
294
|
+
console.log("Next: run `devcomp doctor`; resolve rules merge or legacy agent FAIL before starting work.");
|
|
281
295
|
}
|
|
282
296
|
|
|
283
297
|
async function cmdAdd(args) {
|
|
@@ -357,37 +371,63 @@ async function cmdDoctor(args) {
|
|
|
357
371
|
);
|
|
358
372
|
add("roles", missingRoles.length ? "fail" : "pass", missingRoles.length ? `missing: ${missingRoles.join(", ")}` : `${manifest.roles.length} present`);
|
|
359
373
|
|
|
374
|
+
if (adapter?.agentDir && adapter.agentFormat) {
|
|
375
|
+
const extension = adapter.agentFormat === "toml" ? "toml" : "md";
|
|
376
|
+
const missingBindings = (manifest.roles ?? []).filter(
|
|
377
|
+
(role) => !existsSync(join(target, adapter.agentDir, `${role}.${extension}`))
|
|
378
|
+
);
|
|
379
|
+
add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
|
|
380
|
+
? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
const missingCore = CANONICAL_FILES.filter((file) => !existsSync(join(target, ".companion", "core", file)));
|
|
384
|
+
add("canonical process", missingCore.length ? "fail" : "pass", missingCore.length
|
|
385
|
+
? `missing: ${missingCore.join(", ")}; run devcomp update`
|
|
386
|
+
: `${CANONICAL_FILES.length} files present`);
|
|
387
|
+
|
|
360
388
|
if (manifest.harness === "opencode") {
|
|
361
389
|
const teamLeadPath = join(target, ".opencode", "agents", "team-lead.md");
|
|
362
390
|
if (!existsSync(teamLeadPath)) {
|
|
363
391
|
add("orchestrator", "fail", "team-lead binding missing");
|
|
364
392
|
} else {
|
|
365
393
|
const content = readFileSync(teamLeadPath, "utf8");
|
|
366
|
-
const
|
|
394
|
+
const callable = /^mode:\s*subagent\s*$/m.test(content);
|
|
367
395
|
add(
|
|
368
396
|
"orchestrator",
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
? "team-lead is
|
|
372
|
-
: "team-lead
|
|
397
|
+
callable ? "pass" : "fail",
|
|
398
|
+
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"
|
|
373
401
|
);
|
|
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");
|
|
374
408
|
}
|
|
375
409
|
|
|
376
|
-
const
|
|
410
|
+
const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
|
|
377
411
|
let defaultAgent = null;
|
|
378
|
-
|
|
412
|
+
for (const file of configPaths) {
|
|
413
|
+
const configPath = join(target, file);
|
|
414
|
+
if (!existsSync(configPath)) continue;
|
|
379
415
|
try {
|
|
380
|
-
|
|
416
|
+
const text = readFileSync(configPath, "utf8");
|
|
417
|
+
// JSONC comments and trailing commas are supported by OpenCode.
|
|
418
|
+
const clean = text.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
|
|
419
|
+
(match) => match.startsWith('"') ? match : "").replace(/,\s*([}\]])/g, "$1");
|
|
420
|
+
defaultAgent = JSON.parse(clean).default_agent ?? defaultAgent;
|
|
381
421
|
} catch {
|
|
382
|
-
|
|
422
|
+
add("OpenCode config", "fail", `cannot parse ${file}; check the config manually`);
|
|
383
423
|
}
|
|
384
424
|
}
|
|
385
425
|
add(
|
|
386
426
|
"default agent",
|
|
387
|
-
defaultAgent === "team-lead" ? "
|
|
427
|
+
defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
|
|
388
428
|
defaultAgent
|
|
389
429
|
? `default_agent=${defaultAgent}`
|
|
390
|
-
: "not set;
|
|
430
|
+
: "not set; native Build remains the default"
|
|
391
431
|
);
|
|
392
432
|
}
|
|
393
433
|
|
|
@@ -396,17 +436,21 @@ async function cmdDoctor(args) {
|
|
|
396
436
|
add("AGENTS.md", "fail", "missing");
|
|
397
437
|
} else {
|
|
398
438
|
const content = readFileSync(agentsPath, "utf8");
|
|
399
|
-
const managed = content
|
|
400
|
-
const
|
|
401
|
-
|
|
439
|
+
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");
|
|
402
446
|
}
|
|
403
447
|
|
|
404
448
|
const claudePath = join(target, "CLAUDE.md");
|
|
405
449
|
if (!existsSync(claudePath)) {
|
|
406
|
-
add("CLAUDE.md", "warn", "missing; Claude Code will not import AGENTS.md");
|
|
450
|
+
add("CLAUDE.md", manifest.harness === "claude-code" ? "fail" : "warn", "missing; Claude Code will not import AGENTS.md");
|
|
407
451
|
} else {
|
|
408
452
|
const content = readFileSync(claudePath, "utf8");
|
|
409
|
-
add("CLAUDE.md", content.includes("@AGENTS.md") ? "pass" : "warn", content.includes("@AGENTS.md") ? "imports AGENTS.md" : "does not import AGENTS.md");
|
|
453
|
+
add("CLAUDE.md", content.includes("@AGENTS.md") ? "pass" : manifest.harness === "claude-code" ? "fail" : "warn", content.includes("@AGENTS.md") ? "imports AGENTS.md" : "does not import AGENTS.md");
|
|
410
454
|
}
|
|
411
455
|
|
|
412
456
|
const ignorePath = join(target, ".gitignore");
|
|
@@ -457,9 +501,17 @@ async function cmdUpdate(args) {
|
|
|
457
501
|
const skills = manifest.skills ?? [];
|
|
458
502
|
const roles = manifest.roles ?? [];
|
|
459
503
|
const skillResults = installSkills({ target, adapter, skills, force });
|
|
504
|
+
installCanonical({ target, force });
|
|
460
505
|
const roleResults = installRoles({ target, roles, force });
|
|
461
506
|
installBindings({ target, adapter, roles, force });
|
|
462
507
|
const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
|
|
508
|
+
const rulesPath = join(target, "AGENTS.md");
|
|
509
|
+
if (existsSync(rulesPath) && hasManagedBlock(readFileSync(rulesPath, "utf8"))) {
|
|
510
|
+
applyRules({ filePath: rulesPath, mode: "append", block: renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
|
|
511
|
+
projectName: basename(target), profile: manifest.profile, branching: manifest.branching,
|
|
512
|
+
docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
|
|
513
|
+
}) });
|
|
514
|
+
}
|
|
463
515
|
manifest.packageVersion = VERSION;
|
|
464
516
|
manifest.contentVersion = VERSION;
|
|
465
517
|
writeManifest(target, manifest);
|
package/src/content.mjs
CHANGED
package/src/install.mjs
CHANGED
|
@@ -113,21 +113,42 @@ export function installRoles({ target, roles, force = false }) {
|
|
|
113
113
|
return results;
|
|
114
114
|
}
|
|
115
115
|
|
|
116
|
+
export const CANONICAL_FILES = [
|
|
117
|
+
"principles.md",
|
|
118
|
+
"process.md",
|
|
119
|
+
"workflow.md",
|
|
120
|
+
"quality-gates.md",
|
|
121
|
+
...readdirSync(join(packageRoot(), "core", "guidelines"))
|
|
122
|
+
.filter((file) => file.endsWith(".md"))
|
|
123
|
+
.map((file) => `guidelines/${file}`)
|
|
124
|
+
];
|
|
125
|
+
|
|
126
|
+
export function installCanonical({ target, force = false }) {
|
|
127
|
+
return CANONICAL_FILES.map((file) => {
|
|
128
|
+
const source = join(packageRoot(), "core", file);
|
|
129
|
+
const destination = join(target, ".companion", "core", file);
|
|
130
|
+
if (existsSync(destination) && !force) return { file, status: "kept" };
|
|
131
|
+
ensureDir(dirname(destination));
|
|
132
|
+
copyFileSync(source, destination);
|
|
133
|
+
return { file, status: "installed" };
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
|
|
116
137
|
function bindingBody(role) {
|
|
117
|
-
return `Read \`.companion/roles/${role}.md\` and follow
|
|
138
|
+
return `Read \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/${role}.md\` and follow them. Load the skills it references from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
|
|
118
139
|
}
|
|
119
140
|
|
|
120
141
|
function openCodeLeadBody() {
|
|
121
|
-
return `You are
|
|
142
|
+
return `You are a callable coordination specialist. The native primary agent remains accountable to the user and retains its normal tools.
|
|
122
143
|
|
|
123
144
|
## Mandatory routing
|
|
124
145
|
|
|
125
146
|
- You do not implement, edit code, run shell commands, or produce specialist artifacts.
|
|
126
147
|
- Your only writable paths are \`.companion/local/**\` and \`docs/companion/**\`.
|
|
127
|
-
-
|
|
148
|
+
- When asked to coordinate work needing multiple specialists, delegate with the \`subagent\` tool.
|
|
128
149
|
- A delegation is real only if you call \`subagent\`. Never claim a delegation you did not perform.
|
|
129
150
|
- Launch independent specialists in parallel; serialize only when one depends on another.
|
|
130
|
-
-
|
|
151
|
+
- Report to the primary agent; it speaks to the user and verifies your evidence.
|
|
131
152
|
- If a child returns without evidence, send it back with a bounded follow-up.
|
|
132
153
|
|
|
133
154
|
## Routing
|
|
@@ -149,19 +170,19 @@ function openCodeLeadBody() {
|
|
|
149
170
|
|
|
150
171
|
## Flow
|
|
151
172
|
|
|
152
|
-
1. Read the request and \`.companion/roles/team-lead.md\`.
|
|
173
|
+
1. Read the request, \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/team-lead.md\`.
|
|
153
174
|
2. Decide the route and the bounded deliverable.
|
|
154
175
|
3. Call \`subagent\` with goal, context, deliverable, verification, and do-not.
|
|
155
176
|
4. Review the child's evidence; ask for fixes if needed.
|
|
156
|
-
5. Write only your own plan/closure documents under \`.companion/local
|
|
157
|
-
6. Report to the
|
|
177
|
+
5. Write only your own plan/closure documents under the configured docs directory in \`AGENTS.md\` (\`.companion/local/\` by default, \`docs/companion/\` when tracked).
|
|
178
|
+
6. Report to the primary agent with evidence.
|
|
158
179
|
|
|
159
|
-
A
|
|
180
|
+
A read-only recommendation may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
|
|
160
181
|
}
|
|
161
182
|
|
|
162
183
|
function openCodeBinding(role) {
|
|
163
184
|
const isLead = role === "team-lead";
|
|
164
|
-
const mode =
|
|
185
|
+
const mode = "subagent";
|
|
165
186
|
const body = isLead ? openCodeLeadBody() : bindingBody(role);
|
|
166
187
|
const permissions = isLead
|
|
167
188
|
? [
|
|
@@ -247,32 +268,18 @@ export function installBindings({ target, adapter, roles, force = false }) {
|
|
|
247
268
|
}
|
|
248
269
|
|
|
249
270
|
/**
|
|
250
|
-
*
|
|
251
|
-
*
|
|
271
|
+
* Leave the harness default and existing configuration alone. The process is
|
|
272
|
+
* installed as instructions, not as a replacement for the native Build agent.
|
|
252
273
|
*/
|
|
253
274
|
export function writeOpenCodeConfig(target) {
|
|
254
|
-
const
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
}
|
|
263
|
-
ensureDir(dir);
|
|
264
|
-
writeText(
|
|
265
|
-
jsonPath,
|
|
266
|
-
`${JSON.stringify(
|
|
267
|
-
{
|
|
268
|
-
$schema: "https://opencode.ai/config.json",
|
|
269
|
-
default_agent: "team-lead",
|
|
270
|
-
},
|
|
271
|
-
null,
|
|
272
|
-
2,
|
|
273
|
-
)}\n`,
|
|
274
|
-
);
|
|
275
|
-
return { status: "created", path: jsonPath };
|
|
275
|
+
const existing = [
|
|
276
|
+
join(target, ".opencode", "opencode.json"),
|
|
277
|
+
join(target, ".opencode", "opencode.jsonc"),
|
|
278
|
+
join(target, "opencode.json"),
|
|
279
|
+
join(target, "opencode.jsonc")
|
|
280
|
+
]
|
|
281
|
+
.find((path) => existsSync(path));
|
|
282
|
+
return { status: existing ? "kept" : "native default (no config written)", path: existing ?? "OpenCode default" };
|
|
276
283
|
}
|
|
277
284
|
|
|
278
285
|
export function writeManifest(target, manifest) {
|
package/src/rules.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { existsSync, readFileSync, writeFileSync } from "node:fs";
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { basename, dirname, relative } from "node:path";
|
|
2
3
|
|
|
3
4
|
export const START = "<!-- development-companion:start -->";
|
|
4
5
|
export const END = "<!-- development-companion:end -->";
|
|
@@ -17,7 +18,8 @@ export function replaceManagedBlock(content, block) {
|
|
|
17
18
|
const start = content.indexOf(START);
|
|
18
19
|
const end = content.indexOf(END);
|
|
19
20
|
if (start === -1 || end === -1 || end < start) return null;
|
|
20
|
-
|
|
21
|
+
const suffix = content.slice(end + END.length);
|
|
22
|
+
return `${content.slice(0, start)}${block}${suffix.trim() ? suffix : "\n"}`;
|
|
21
23
|
}
|
|
22
24
|
|
|
23
25
|
export function appendBlock(content, block) {
|
|
@@ -26,7 +28,12 @@ export function appendBlock(content, block) {
|
|
|
26
28
|
return `${trimmed}\n\n${block}\n`;
|
|
27
29
|
}
|
|
28
30
|
|
|
29
|
-
|
|
31
|
+
function mergeNotice(filePath, backupPath) {
|
|
32
|
+
return `# Project rules merge pending\n\nThe original AGENTS.md is backed up at \`${relative(dirname(filePath), backupPath)}\`. Before coding, compare it with this file and merge business rules, commands, tools and constraints into one coherent AGENTS.md. Preserve both sets of requirements; resolve conflicts with the user. Remove this notice only after reviewing the backup. Do not commit this pending file or its local backup: the original rules would be absent on other machines.\n\n`;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export function applyRules({ filePath, mode, block, force = false, backupPath }) {
|
|
36
|
+
block = block.trimEnd();
|
|
30
37
|
const exists = existsSync(filePath);
|
|
31
38
|
if (!exists) {
|
|
32
39
|
writeFileSync(filePath, `${block}\n`, "utf8");
|
|
@@ -38,12 +45,31 @@ export function applyRules({ filePath, mode, block, force = false }) {
|
|
|
38
45
|
return { mode: "kept", changed: false, reason: "keep requested" };
|
|
39
46
|
}
|
|
40
47
|
|
|
48
|
+
if (mode === "handoff") {
|
|
49
|
+
if (!backupPath || hasManagedBlock(current)) {
|
|
50
|
+
return { mode: "error", changed: false, reason: "handoff requires a backup path and unmerged original rules" };
|
|
51
|
+
}
|
|
52
|
+
if (existsSync(backupPath) && readFileSync(backupPath, "utf8") !== current) {
|
|
53
|
+
return { mode: "error", changed: false, reason: "backup differs; merge existing backup before retrying" };
|
|
54
|
+
}
|
|
55
|
+
mkdirSync(dirname(backupPath), { recursive: true });
|
|
56
|
+
if (!existsSync(backupPath)) writeFileSync(backupPath, current, { encoding: "utf8", flag: "wx" });
|
|
57
|
+
writeFileSync(filePath, `${mergeNotice(filePath, backupPath)}${block}\n`, "utf8");
|
|
58
|
+
return { mode: "handoff", changed: true, reason: "original backed up; agent merge pending" };
|
|
59
|
+
}
|
|
60
|
+
|
|
41
61
|
if (mode === "replace") {
|
|
42
62
|
if (!force) {
|
|
43
63
|
return { mode: "blocked", changed: false, reason: "replace requires --force" };
|
|
44
64
|
}
|
|
45
|
-
|
|
46
|
-
|
|
65
|
+
if (!backupPath) return { mode: "error", changed: false, reason: "replace requires a backup path" };
|
|
66
|
+
if (existsSync(backupPath) && readFileSync(backupPath, "utf8") !== current) {
|
|
67
|
+
return { mode: "error", changed: false, reason: "backup differs; merge existing backup before retrying" };
|
|
68
|
+
}
|
|
69
|
+
mkdirSync(dirname(backupPath), { recursive: true });
|
|
70
|
+
if (!existsSync(backupPath)) writeFileSync(backupPath, current, { encoding: "utf8", flag: "wx" });
|
|
71
|
+
writeFileSync(filePath, `${basename(filePath) === "AGENTS.md" ? mergeNotice(filePath, backupPath) : ""}${block}\n`, "utf8");
|
|
72
|
+
return { mode: "replaced", changed: true, reason: `original backed up at ${relative(dirname(filePath), backupPath)}` };
|
|
47
73
|
}
|
|
48
74
|
|
|
49
75
|
if (mode === "append") {
|
|
@@ -1,19 +1,28 @@
|
|
|
1
1
|
# Operational brief
|
|
2
2
|
|
|
3
|
+
> Maximum one page. This brief unblocks the first slice, not the whole product.
|
|
4
|
+
|
|
3
5
|
## Problem and users
|
|
4
6
|
|
|
5
7
|
## Goals and success metrics
|
|
6
8
|
|
|
9
|
+
## First end-to-end slice
|
|
10
|
+
|
|
11
|
+
- Input:
|
|
12
|
+
- Process:
|
|
13
|
+
- Observable output:
|
|
14
|
+
- Acceptance criteria (one or two sentences):
|
|
15
|
+
|
|
7
16
|
## Scope
|
|
8
17
|
|
|
9
|
-
### In scope
|
|
18
|
+
### In scope for this slice
|
|
10
19
|
|
|
11
20
|
### Out of scope
|
|
12
21
|
|
|
13
|
-
## Existing artifacts
|
|
14
|
-
|
|
15
22
|
## Constraints
|
|
16
23
|
|
|
24
|
+
## Existing artifacts
|
|
25
|
+
|
|
17
26
|
## Hosting and third parties
|
|
18
27
|
|
|
19
28
|
## Data and privacy
|
|
@@ -29,6 +38,11 @@
|
|
|
29
38
|
|
|
30
39
|
## Definition of done
|
|
31
40
|
|
|
41
|
+
## Planning budget
|
|
42
|
+
|
|
43
|
+
- Time spent on this brief:
|
|
44
|
+
- Deferred decisions and the slice that will unblock them:
|
|
45
|
+
|
|
32
46
|
## Open questions
|
|
33
47
|
|
|
34
48
|
## Approval
|
|
@@ -1,13 +1,24 @@
|
|
|
1
1
|
# Delivery plan
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> One page for the first three slices. If it does not fit, the scope is too broad.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## First vertical slice
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Input:
|
|
8
|
+
- Process:
|
|
9
|
+
- Observable output:
|
|
10
|
+
- Acceptance criteria:
|
|
11
|
+
- Verification command:
|
|
12
|
+
|
|
13
|
+
## Slices
|
|
14
|
+
|
|
15
|
+
| Slice | Owner | Observable result | Verification | Depends on |
|
|
8
16
|
|---|---|---|---|---|
|
|
9
17
|
|
|
10
|
-
##
|
|
18
|
+
## WIP limit
|
|
19
|
+
|
|
20
|
+
- One slice per writer.
|
|
21
|
+
- Parallel work only for read-only tasks or disjoint files.
|
|
11
22
|
|
|
12
23
|
## Branch and release flow
|
|
13
24
|
|
|
@@ -15,15 +26,25 @@
|
|
|
15
26
|
|
|
16
27
|
| Gate | Evidence | Accepted by |
|
|
17
28
|
|---|---|---|
|
|
29
|
+
| Frame | One-page brief confirmed | User |
|
|
30
|
+
| Skeleton | End-to-end path + one test + commit | Team Lead |
|
|
31
|
+
| Slice | Acceptance criteria + tests + demo + commit | Team Lead |
|
|
32
|
+
| Release | Security/QA findings closed; install verified | User |
|
|
18
33
|
|
|
19
34
|
## Risks
|
|
20
35
|
|
|
21
36
|
| Risk | Impact | Mitigation | Owner |
|
|
22
37
|
|---|---|---|---|
|
|
23
38
|
|
|
39
|
+
## Delivery log
|
|
40
|
+
|
|
41
|
+
| Date | Slice | Commit | Tests | Next |
|
|
42
|
+
|---|---|---|---|---|
|
|
43
|
+
|
|
24
44
|
## Status
|
|
25
45
|
|
|
46
|
+
- Last commit:
|
|
26
47
|
- Done:
|
|
27
48
|
- In progress:
|
|
28
49
|
- Blocked:
|
|
29
|
-
- Next
|
|
50
|
+
- Next slice:
|
|
@@ -3,7 +3,12 @@
|
|
|
3
3
|
|
|
4
4
|
This project uses the Development Companion process. Read these files before working:
|
|
5
5
|
|
|
6
|
-
- `.companion/
|
|
6
|
+
- `.companion/core/process.md` — delivery loop and gates.
|
|
7
|
+
- `.companion/core/principles.md` — non-negotiable engineering rules.
|
|
8
|
+
- `.companion/core/quality-gates.md` — evidence and completion criteria.
|
|
9
|
+
- `.companion/core/workflow.md` — workflow for individual changes.
|
|
10
|
+
- `.companion/core/guidelines/` — discipline-specific guidance.
|
|
11
|
+
- `.companion/roles/team-lead.md` — delivery owner and orchestration.
|
|
7
12
|
- `.companion/roles/architect.md` — boundaries, patterns, and ADRs.
|
|
8
13
|
- `.companion/roles/cybersecurity-engineer.md` — threat model and security review.
|
|
9
14
|
- `.companion/roles/qa-engineer.md` — test strategy and verification.
|
|
@@ -11,31 +16,57 @@ This project uses the Development Companion process. Read these files before wor
|
|
|
11
16
|
|
|
12
17
|
## Workflow
|
|
13
18
|
|
|
14
|
-
Use the `development-workflow` skill for non-trivial work
|
|
15
|
-
|
|
16
|
-
delivery plan → implementation → security verification → QA → deployment → closure.
|
|
19
|
+
Use the `development-workflow` skill for non-trivial work and the `incremental-delivery` skill
|
|
20
|
+
when the plan starts growing faster than the code. For a new project or a major change:
|
|
17
21
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
+
```text
|
|
23
|
+
frame (one page) → walking skeleton → slice loop → verify → release → close
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The native harness agent is the single accountable delivery owner: apply the Team Lead
|
|
27
|
+
contract without losing native edit, shell, skills, or delegation tools. Invoke the
|
|
28
|
+
`team-lead` specialist for substantial coordination when useful, not for every routine
|
|
29
|
+
slice. In OpenCode use native Build by default; the callable `team-lead` is a restricted
|
|
30
|
+
subagent. In harnesses without subagents, follow the role yourself; never claim a
|
|
31
|
+
delegation you did not perform.
|
|
32
|
+
|
|
33
|
+
## Project rules integration
|
|
34
|
+
|
|
35
|
+
Before implementation, reconcile these process instructions with existing project/business
|
|
36
|
+
rules into one coherent `AGENTS.md`: project identity and domain → commands and toolchain →
|
|
37
|
+
architecture and conventions → delivery workflow and roles → verification and safety.
|
|
38
|
+
Keep unique facts from both sources; identify stale or conflicting instructions and ask the
|
|
39
|
+
user before discarding them. Do not blindly append or treat a backup as active instructions.
|
|
40
|
+
If `# Project rules merge pending` appears above, read the named local backup, perform the
|
|
41
|
+
merge and remove the notice only after review; run `devcomp doctor` again.
|
|
42
|
+
|
|
43
|
+
For each new project or material change, detect its language, stack and available harness
|
|
44
|
+
capabilities. Review `AGENTS.md` with the user where needed and update it through the harness,
|
|
45
|
+
not by guessing from the CLI.
|
|
22
46
|
|
|
23
47
|
Profile: `{{profile}}`. Branching: `{{branching}}`.
|
|
24
48
|
|
|
25
49
|
## Non-negotiables
|
|
26
50
|
|
|
27
|
-
1.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
51
|
+
1. **Working software first.** The first commit lands in the first work block. A session that
|
|
52
|
+
produces only documents, when the user asked for implementation, is a process failure.
|
|
53
|
+
2. **One slice at a time, end-to-end.** No horizontal "finish the domain first" plans. WIP limit:
|
|
54
|
+
one slice per writer.
|
|
55
|
+
3. **Planning budget:** the frame is one page and 30–60 minutes; total planning before the first
|
|
56
|
+
end-to-end slice is ≤ 10–15 % of the effort. A document that does not unblock code is deferred.
|
|
57
|
+
4. Every finding and every completion needs evidence: file and snippet, command and output,
|
|
58
|
+
request, CVE, screenshot, or metric.
|
|
59
|
+
5. Never read `.env` values. You may read key names from `.env.example` and check presence
|
|
31
60
|
without printing values.
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
61
|
+
6. Do not commit secrets, local design documents, or `.companion/local/`.
|
|
62
|
+
7. Keep the domain independent from frameworks and infrastructure. Ports and adapters.
|
|
63
|
+
8. UI work needs target-device screenshots, a vision-capable review, and (for multi-screen
|
|
64
|
+
flows) an interactive prototype exercised in Play/presentation before approval and code.
|
|
65
|
+
9. If a decision is missing, ask; do not invent requirements.
|
|
36
66
|
|
|
37
67
|
## Local documents
|
|
38
68
|
|
|
39
|
-
Design documents, evidence, and reports live in `.
|
|
40
|
-
|
|
69
|
+
Design documents, evidence, and reports live in `{{docsDir}}`. This configured location
|
|
70
|
+
overrides default paths in skills and role examples. They are living notes, not phase gates.
|
|
71
|
+
The project manifest is `.companion/config.json`.
|
|
41
72
|
<!-- development-companion:end -->
|