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/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 AGENTS.md/CLAUDE.md)
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` and start with the `project-discovery` skill.");
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 primary = /^mode:\s*primary\s*$/m.test(content);
394
+ const callable = /^mode:\s*subagent\s*$/m.test(content);
367
395
  add(
368
396
  "orchestrator",
369
- primary ? "pass" : "warn",
370
- primary
371
- ? "team-lead is a primary agent"
372
- : "team-lead is not primary; run `devcomp update --force` to enable orchestration"
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 configPath = join(target, ".opencode", "opencode.json");
410
+ const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
377
411
  let defaultAgent = null;
378
- if (existsSync(configPath)) {
412
+ for (const file of configPaths) {
413
+ const configPath = join(target, file);
414
+ if (!existsSync(configPath)) continue;
379
415
  try {
380
- defaultAgent = JSON.parse(readFileSync(configPath, "utf8")).default_agent;
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
- defaultAgent = null;
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" ? "pass" : "warn",
427
+ defaultAgent === "team-lead" ? "fail" : defaultAgent && defaultAgent !== "build" ? "warn" : "pass",
388
428
  defaultAgent
389
429
  ? `default_agent=${defaultAgent}`
390
- : "not set; add default_agent=team-lead to start sessions as the orchestrator"
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.includes("development-companion:start");
400
- const kept = manifest.rules?.["AGENTS.md"] === "kept";
401
- add("AGENTS.md", managed ? "pass" : kept ? "warn" : "fail", managed ? "managed block present" : kept ? "kept by policy; block not installed" : "managed block missing");
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
@@ -7,6 +7,7 @@ export const PROCESS_SKILLS = [
7
7
  "security-review",
8
8
  "deployment-sre",
9
9
  "development-workflow",
10
+ "incremental-delivery",
10
11
  "code-review"
11
12
  ];
12
13
 
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 it. Load the skills it references from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
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 the primary orchestrator for this OpenCode session. The user talks only to you.
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
- - Every non-trivial request MUST be delegated with the \`subagent\` tool.
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
- - Only you speak to the user. Specialists report to you; verify their evidence before accepting it.
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 user with evidence.
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 trivial one-line answer may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
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 = isLead ? "primary" : "subagent";
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
- * Crea `.opencode/opencode.json` con `default_agent: team-lead` si no existe ya una
251
- * configuración local de OpenCode. No sobrescribe configuración existente.
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 dir = join(target, ".opencode");
255
- const jsonPath = join(dir, "opencode.json");
256
- const jsoncPath = join(dir, "opencode.jsonc");
257
- if (existsSync(jsonPath) || existsSync(jsoncPath)) {
258
- return {
259
- status: "kept",
260
- path: existsSync(jsonPath) ? jsonPath : jsoncPath,
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
- return `${content.slice(0, start)}${block}${content.slice(end + END.length)}`;
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
- export function applyRules({ filePath, mode, block, force = false }) {
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
- writeFileSync(filePath, `${block}\n`, "utf8");
46
- return { mode: "replaced", changed: true, reason: "replace requested" };
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
- ## Milestones
3
+ > One page for the first three slices. If it does not fit, the scope is too broad.
4
4
 
5
- ## Tasks
5
+ ## First vertical slice
6
6
 
7
- | Task | Owner | Output | Verification | Depends on |
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
- ## Parallel tracks
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 checkpoint:
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/roles/team-lead.md` — process owner and orchestration.
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. For a new project or a major
15
- change, follow the process: discovery → architecture + security → test strategy → UX →
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
- If the harness exposes a team lead (OpenCode: `team-lead`, the default primary agent), use
19
- it as the single accountable owner. The team lead MUST delegate specialist work with the
20
- `subagent` tool and verify the evidence; it must not implement code or run shell commands
21
- itself. Its only writable paths are `.companion/local/**` and `docs/companion/**`.
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. Do not start implementing before discovery and architecture are accepted.
28
- 2. Every finding and every completion needs evidence: file and snippet, command and
29
- output, request, CVE, screenshot, or metric.
30
- 3. Never read `.env` values. You may read key names from `.env.example` and check presence
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
- 4. Do not commit secrets, local design documents, or `.companion/local/`.
33
- 5. Keep the domain independent from frameworks and infrastructure. Ports and adapters.
34
- 6. UI work requires screenshots at desktop and mobile widths and a vision-capable review.
35
- 7. If a decision is missing, ask; do not invent requirements.
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 `.companion/local/` and are ignored by
40
- git. The project manifest is `.companion/config.json`.
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 -->