development-companion 1.2.1 → 1.3.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,
@@ -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.`);
@@ -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
 
@@ -233,6 +237,7 @@ async function cmdInit(args) {
233
237
  force
234
238
  });
235
239
 
240
+ const canonicalResults = installCanonical({ target: requested, force });
236
241
  const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
237
242
  const roleResults = installRoles({ target: requested, roles, force });
238
243
  const bindingResults = installBindings({ target: requested, adapter, roles, force });
@@ -268,6 +273,7 @@ async function cmdInit(args) {
268
273
  console.log(` ${file}: ${result.mode}${result.reason ? ` (${result.reason})` : ""}`);
269
274
  }
270
275
  console.log(` Skills: ${skillResults.filter((r) => r.status === "installed").length} installed, ${skillResults.filter((r) => r.status === "kept").length} kept`);
276
+ console.log(` Canonical files: ${canonicalResults.filter((r) => r.status === "installed").length} installed, ${canonicalResults.filter((r) => r.status === "kept").length} kept`);
271
277
  console.log(` Roles: ${roleResults.filter((r) => r.status === "installed").length} installed, ${roleResults.filter((r) => r.status === "kept").length} kept`);
272
278
  if (bindingResults.length) {
273
279
  console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
@@ -277,7 +283,7 @@ async function cmdInit(args) {
277
283
  }
278
284
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
279
285
  console.log("");
280
- console.log("Next: run `devcomp doctor` and start with the `project-discovery` skill.");
286
+ console.log("Next: run `devcomp doctor`; resolve any FAIL before starting with `project-discovery`.");
281
287
  }
282
288
 
283
289
  async function cmdAdd(args) {
@@ -357,6 +363,20 @@ async function cmdDoctor(args) {
357
363
  );
358
364
  add("roles", missingRoles.length ? "fail" : "pass", missingRoles.length ? `missing: ${missingRoles.join(", ")}` : `${manifest.roles.length} present`);
359
365
 
366
+ if (adapter?.agentDir && adapter.agentFormat) {
367
+ const extension = adapter.agentFormat === "toml" ? "toml" : "md";
368
+ const missingBindings = (manifest.roles ?? []).filter(
369
+ (role) => !existsSync(join(target, adapter.agentDir, `${role}.${extension}`))
370
+ );
371
+ add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
372
+ ? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
373
+ }
374
+
375
+ const missingCore = CANONICAL_FILES.filter((file) => !existsSync(join(target, ".companion", "core", file)));
376
+ add("canonical process", missingCore.length ? "fail" : "pass", missingCore.length
377
+ ? `missing: ${missingCore.join(", ")}; run devcomp update`
378
+ : `${CANONICAL_FILES.length} files present`);
379
+
360
380
  if (manifest.harness === "opencode") {
361
381
  const teamLeadPath = join(target, ".opencode", "agents", "team-lead.md");
362
382
  if (!existsSync(teamLeadPath)) {
@@ -366,28 +386,40 @@ async function cmdDoctor(args) {
366
386
  const primary = /^mode:\s*primary\s*$/m.test(content);
367
387
  add(
368
388
  "orchestrator",
369
- primary ? "pass" : "warn",
389
+ primary ? "pass" : "fail",
370
390
  primary
371
391
  ? "team-lead is a primary agent"
372
- : "team-lead is not primary; run `devcomp update --force` to enable orchestration"
392
+ : "team-lead is not primary; review local edits and run devcomp add role team-lead --force"
373
393
  );
394
+ const denies = (action) => new RegExp(`- action: ${action}\\s+resource: "\\*"\\s+effect: deny`).test(content);
395
+ const delegates = /- action: subagent\s+resource: "\*"\s+effect: allow/.test(content);
396
+ add("lead permissions", denies("edit") && denies("shell") && delegates ? "pass" : "fail",
397
+ denies("edit") && denies("shell") && delegates
398
+ ? "edits and shell denied; delegation allowed"
399
+ : "outdated team-lead binding; review local edits and run devcomp add role team-lead --force to replace it");
374
400
  }
375
401
 
376
- const configPath = join(target, ".opencode", "opencode.json");
402
+ const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
377
403
  let defaultAgent = null;
378
- if (existsSync(configPath)) {
404
+ for (const file of configPaths) {
405
+ const configPath = join(target, file);
406
+ if (!existsSync(configPath)) continue;
379
407
  try {
380
- defaultAgent = JSON.parse(readFileSync(configPath, "utf8")).default_agent;
408
+ const text = readFileSync(configPath, "utf8");
409
+ // JSONC comments and trailing commas are supported by OpenCode.
410
+ const clean = text.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
411
+ (match) => match.startsWith('"') ? match : "").replace(/,\s*([}\]])/g, "$1");
412
+ defaultAgent = JSON.parse(clean).default_agent ?? defaultAgent;
381
413
  } catch {
382
- defaultAgent = null;
414
+ add("OpenCode config", "fail", `cannot parse ${file}; check the config manually`);
383
415
  }
384
416
  }
385
417
  add(
386
418
  "default agent",
387
- defaultAgent === "team-lead" ? "pass" : "warn",
419
+ defaultAgent === "team-lead" ? "pass" : "fail",
388
420
  defaultAgent
389
421
  ? `default_agent=${defaultAgent}`
390
- : "not set; add default_agent=team-lead to start sessions as the orchestrator"
422
+ : "not set; set default_agent to team-lead in your existing OpenCode config, then start a new session"
391
423
  );
392
424
  }
393
425
 
@@ -396,17 +428,18 @@ async function cmdDoctor(args) {
396
428
  add("AGENTS.md", "fail", "missing");
397
429
  } else {
398
430
  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");
431
+ const managed = hasManagedBlock(content);
432
+ const current = managed && content.includes(".companion/core/process.md");
433
+ add("AGENTS.md", current ? "pass" : "fail", current ? "canonical process linked" :
434
+ "framework rules missing or outdated; run devcomp init --rules append (preserves existing rules)");
402
435
  }
403
436
 
404
437
  const claudePath = join(target, "CLAUDE.md");
405
438
  if (!existsSync(claudePath)) {
406
- add("CLAUDE.md", "warn", "missing; Claude Code will not import AGENTS.md");
439
+ add("CLAUDE.md", manifest.harness === "claude-code" ? "fail" : "warn", "missing; Claude Code will not import AGENTS.md");
407
440
  } else {
408
441
  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");
442
+ 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
443
  }
411
444
 
412
445
  const ignorePath = join(target, ".gitignore");
@@ -457,9 +490,17 @@ async function cmdUpdate(args) {
457
490
  const skills = manifest.skills ?? [];
458
491
  const roles = manifest.roles ?? [];
459
492
  const skillResults = installSkills({ target, adapter, skills, force });
493
+ installCanonical({ target, force });
460
494
  const roleResults = installRoles({ target, roles, force });
461
495
  installBindings({ target, adapter, roles, force });
462
496
  const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
497
+ const rulesPath = join(target, "AGENTS.md");
498
+ if (existsSync(rulesPath) && hasManagedBlock(readFileSync(rulesPath, "utf8"))) {
499
+ applyRules({ filePath: rulesPath, mode: "append", block: renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
500
+ projectName: basename(target), profile: manifest.profile, branching: manifest.branching,
501
+ docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
502
+ }) });
503
+ }
463
504
  manifest.packageVersion = VERSION;
464
505
  manifest.contentVersion = VERSION;
465
506
  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,8 +113,29 @@ 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() {
@@ -149,11 +170,11 @@ 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/\`.
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).
157
178
  6. Report to the user with evidence.
158
179
 
159
180
  A trivial one-line answer may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
@@ -247,17 +268,19 @@ 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
+ * Create `.opencode/opencode.json` with `default_agent: team-lead` only when the
272
+ * project has no existing OpenCode config at its root or inside `.opencode/`.
252
273
  */
253
274
  export function writeOpenCodeConfig(target) {
254
275
  const dir = join(target, ".opencode");
255
276
  const jsonPath = join(dir, "opencode.json");
256
277
  const jsoncPath = join(dir, "opencode.jsonc");
257
- if (existsSync(jsonPath) || existsSync(jsoncPath)) {
278
+ const existing = [jsonPath, jsoncPath, join(target, "opencode.json"), join(target, "opencode.jsonc")]
279
+ .find((path) => existsSync(path));
280
+ if (existing) {
258
281
  return {
259
282
  status: "kept",
260
- path: existsSync(jsonPath) ? jsonPath : jsoncPath,
283
+ path: existing,
261
284
  };
262
285
  }
263
286
  ensureDir(dir);
package/src/rules.mjs CHANGED
@@ -17,7 +17,8 @@ export function replaceManagedBlock(content, block) {
17
17
  const start = content.indexOf(START);
18
18
  const end = content.indexOf(END);
19
19
  if (start === -1 || end === -1 || end < start) return null;
20
- return `${content.slice(0, start)}${block}${content.slice(end + END.length)}`;
20
+ const suffix = content.slice(end + END.length);
21
+ return `${content.slice(0, start)}${block}${suffix.trim() ? suffix : "\n"}`;
21
22
  }
22
23
 
23
24
  export function appendBlock(content, block) {
@@ -27,6 +28,7 @@ export function appendBlock(content, block) {
27
28
  }
28
29
 
29
30
  export function applyRules({ filePath, mode, block, force = false }) {
31
+ block = block.trimEnd();
30
32
  const exists = existsSync(filePath);
31
33
  if (!exists) {
32
34
  writeFileSync(filePath, `${block}\n`, "utf8");
@@ -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,42 @@ 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
+ If the harness exposes a team lead, use it as the single accountable owner. In OpenCode,
27
+ `team-lead` is the default primary agent and MUST use the `subagent` tool to delegate; it
28
+ must not implement code or run shell commands itself. Its only writable paths are
29
+ `.companion/local/**` and `docs/companion/**`. In other harnesses, invoke the team lead
30
+ explicitly where supported; Pi has no native subagents, so follow the role workflow without
31
+ claiming delegation that did not occur.
22
32
 
23
33
  Profile: `{{profile}}`. Branching: `{{branching}}`.
24
34
 
25
35
  ## Non-negotiables
26
36
 
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
37
+ 1. **Working software first.** The first commit lands in the first work block. A session that
38
+ produces only documents, when the user asked for implementation, is a process failure.
39
+ 2. **One slice at a time, end-to-end.** No horizontal "finish the domain first" plans. WIP limit:
40
+ one slice per writer.
41
+ 3. **Planning budget:** the frame is one page and 30–60 minutes; total planning before the first
42
+ end-to-end slice is ≤ 10–15 % of the effort. A document that does not unblock code is deferred.
43
+ 4. Every finding and every completion needs evidence: file and snippet, command and output,
44
+ request, CVE, screenshot, or metric.
45
+ 5. Never read `.env` values. You may read key names from `.env.example` and check presence
31
46
  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.
47
+ 6. Do not commit secrets, local design documents, or `.companion/local/`.
48
+ 7. Keep the domain independent from frameworks and infrastructure. Ports and adapters.
49
+ 8. UI work requires screenshots at desktop and mobile widths and a vision-capable review.
50
+ 9. If a decision is missing, ask; do not invent requirements.
36
51
 
37
52
  ## Local documents
38
53
 
39
- Design documents, evidence, and reports live in `.companion/local/` and are ignored by
40
- git. The project manifest is `.companion/config.json`.
54
+ Design documents, evidence, and reports live in `{{docsDir}}`. This configured location
55
+ overrides default paths in skills and role examples. They are living notes, not phase gates.
56
+ The project manifest is `.companion/config.json`.
41
57
  <!-- development-companion:end -->