development-companion 1.0.0 → 1.1.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 CHANGED
@@ -128,6 +128,15 @@ Read `core/process.md` for the full phase guide.
128
128
  Role contracts live in `core/roles/`. The CLI installs them to `.companion/roles/` and
129
129
  generates native bindings where the harness supports subagents.
130
130
 
131
+ ### Orchestration in OpenCode
132
+
133
+ `devcomp init` installs `team-lead` with `mode: primary` and writes
134
+ `.opencode/opencode.json` with `default_agent: "team-lead"`. The 11 specialists are
135
+ subagents. New sessions start as the team lead, which delegates with the `subagent` tool;
136
+ Build and Plan remain available in the agent selector. If the project already has an
137
+ OpenCode config, the installer preserves it and `devcomp doctor` warns that
138
+ `default_agent` is not set.
139
+
131
140
  ## Skills and profiles
132
141
 
133
142
  Process skills are installed always:
package/RELEASE.md CHANGED
@@ -43,7 +43,7 @@ npm pack --pack-destination "$packdir"
43
43
  app=$(mktemp -d)
44
44
  cd "$app"
45
45
  npm init -y
46
- npm install "$packdir"/development-companion-1.0.0.tgz
46
+ npm install "$packdir"/development-companion-1.1.0.tgz
47
47
  ./node_modules/.bin/devcomp --version
48
48
  ./node_modules/.bin/devcomp init . --yes --harness opencode --profile web
49
49
  ./node_modules/.bin/devcomp doctor .
@@ -57,16 +57,31 @@ All checks must pass before publishing.
57
57
  npm publish --access public
58
58
  ```
59
59
 
60
- If npm asks for a one-time password, enter it from the authenticator. Do not paste it into
61
- a file, shell history, or chat.
60
+ If npm asks for a one-time password, enter it from the authenticator. If 2FA uses a
61
+ passkey or security key, npm prints an authentication URL and opens the browser; approve
62
+ with the passkey. Do not paste secrets into a file, shell history, or chat.
63
+
64
+ ### First publish and the `0.0.0-stage` placeholder
65
+
66
+ When a package does not exist yet, npm may create a temporary `0.0.0-stage` placeholder
67
+ while the real version is being processed. This is expected. Do not bump the version or
68
+ republish immediately. Wait a few minutes and verify:
69
+
70
+ ```bash
71
+ npm view development-companion version dist-tags
72
+ ```
73
+
74
+ The `latest` tag must point to `1.1.0`, not `0.0.0-stage`. If it still points to the
75
+ placeholder after several minutes, check the npmjs.com package page and the Staged
76
+ Packages tab before retrying.
62
77
 
63
78
  ## 5. Verify the published package
64
79
 
65
80
  ```bash
66
81
  cd "$(mktemp -d)"
67
- npx development-companion@1.0.0 --version
68
- npx development-companion@1.0.0 init . --yes --harness opencode --profile web
69
- npx development-companion@1.0.0 doctor .
82
+ npx development-companion@1.1.0 --version
83
+ npx development-companion@1.1.0 init . --yes --harness opencode --profile web
84
+ npx development-companion@1.1.0 doctor .
70
85
  ```
71
86
 
72
87
  Also verify the package page:
@@ -78,14 +93,14 @@ https://www.npmjs.com/package/development-companion
78
93
  ## 6. Tag and publish the source release
79
94
 
80
95
  ```bash
81
- git tag -a v1.0.0 -m "v1.0.0"
96
+ git tag -a v1.1.0 -m "v1.1.0"
82
97
  git push origin main --tags
83
98
  ```
84
99
 
85
100
  Create the release on Codeberg:
86
101
 
87
102
  ```text
88
- https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.0.0
103
+ https://codeberg.org/rockmadehome/development-companion/releases/new?tag=v1.1.0
89
104
  ```
90
105
 
91
106
  Include the install command, the supported harness tiers, and the breaking changes from
@@ -33,24 +33,53 @@ ln -s /path/to/development-companion/skills/code-review .agents/skills/code-revi
33
33
 
34
34
  Verify with the `skill` tool or ask OpenCode to list available skills.
35
35
 
36
- ## Subagents
36
+ ## Agents
37
37
 
38
- Define project subagents in `.opencode/agents/<name>.md`. The file name becomes the
39
- agent name. Required frontmatter: `description`. Use `mode: subagent` for specialists.
38
+ `devcomp init` writes one Markdown agent per role in `.opencode/agents/`:
40
39
 
41
- Example `.opencode/agents/qa-engineer.md`:
40
+ - `team-lead.md` — `mode: primary`, so it appears in the OpenCode agent selector.
41
+ - The 11 specialists — `mode: subagent`, launched by the team lead through the
42
+ `subagent` tool.
43
+
44
+ It also creates `.opencode/opencode.json` with:
45
+
46
+ ```json
47
+ {
48
+ "$schema": "https://opencode.ai/config.json",
49
+ "default_agent": "team-lead"
50
+ }
51
+ ```
52
+
53
+ New sessions start as `team-lead`; Build and Plan remain available in the selector. If the
54
+ project already has `.opencode/opencode.json` or `.opencode/opencode.jsonc`, the installer
55
+ preserves it and `devcomp doctor` warns that `default_agent` is not set.
56
+
57
+ OpenCode does not route by intent by itself. The team-lead prompt explicitly instructs the
58
+ model to delegate with the `subagent` tool; the model chooses the specialist. For
59
+ deterministic routing you would need an OpenCode plugin.
60
+
61
+ ## Specialist example
42
62
 
43
63
  ```markdown
44
64
  ---
45
65
  description: Reviews diffs for correctness, security, data risks, and missing tests. Use before merging or when the user asks for a code review.
46
66
  mode: subagent
47
- permission:
48
- edit: deny
49
- shell:
50
- "*": ask
51
- "git diff *": allow
52
- "git log *": allow
53
- "git status *": allow
67
+ permissions:
68
+ - action: edit
69
+ resource: "*"
70
+ effect: deny
71
+ - action: shell
72
+ resource: "*"
73
+ effect: ask
74
+ - action: shell
75
+ resource: "git diff *"
76
+ effect: allow
77
+ - action: shell
78
+ resource: "git log *"
79
+ effect: allow
80
+ - action: shell
81
+ resource: "git status *"
82
+ effect: allow
54
83
  ---
55
84
 
56
85
  You are the Development Companion QA engineer.
@@ -60,30 +89,39 @@ is available in the workspace. Report findings by severity with file and line
60
89
  references. Do not edit files. Do not approve without evidence.
61
90
  ```
62
91
 
63
- For a team-lead, use `mode: primary` if you want it selectable with Tab, or
64
- `mode: subagent` if it should be delegated to. Restrict which subagents it can spawn
65
- with `permission.task`:
92
+ OpenCode V2 uses **`permissions`** (plural), an ordered list of
93
+ `action` / `resource` / `effect` rules. The legacy OpenCode V1 shape (`permission`,
94
+ `permission.task`, boolean maps) is not used in new bindings.
95
+
96
+ ## Team lead example
97
+
98
+ The generated binding restricts nothing by default, but it can be narrowed:
66
99
 
67
100
  ```yaml
68
- permission:
69
- task:
70
- "*": deny
71
- "architect": allow
72
- "frontend-engineer": allow
73
- "backend-engineer": allow
74
- "qa-engineer": allow
101
+ ---
102
+ description: Leads discovery, planning, delegation, and closure.
103
+ mode: primary
104
+ permissions:
105
+ - action: subagent
106
+ resource: "*"
107
+ effect: allow
108
+ ---
75
109
  ```
76
110
 
77
- Repeat the pattern for the other roles in `core/roles/`.
111
+ To restrict which specialists the team lead may launch, replace `"*"` with explicit
112
+ `resource` entries such as `architect`, `qa-engineer`, or `mobile-engineer`. The last
113
+ matching rule wins.
78
114
 
79
115
  ## Limitations
80
116
 
81
117
  - OpenCode subagents use Markdown frontmatter, not the canonical role format. Keep the
82
118
  binding thin and put durable policy in `core/`.
83
- - Permissions are enforced by the harness; do not rely on prompt instructions alone
84
- for read-only review.
119
+ - The team lead starts with fresh context in a new session. It reads
120
+ `.companion/local/` and the repository; it does not inherit the previous chat.
121
+ - Permissions are enforced by the harness; do not rely on prompt instructions alone for
122
+ read-only review.
85
123
 
86
124
  ## References
87
125
 
88
- - Skills: <https://opencode.ai/docs/skills/>
89
- - Agents: <https://opencode.ai/docs/agents/>
126
+ - Skills: <https://opencode.ai/v2/docs/skills>
127
+ - Agents: <https://opencode.ai/v2/docs/agents>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "development-companion",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Harness-neutral development process, roles, and skills for AI coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/cli.mjs CHANGED
@@ -14,6 +14,7 @@ import {
14
14
  readManifest,
15
15
  readTemplate,
16
16
  writeManifest,
17
+ writeOpenCodeConfig,
17
18
  writeText
18
19
  } from "./install.mjs";
19
20
  import {
@@ -235,6 +236,7 @@ async function cmdInit(args) {
235
236
  const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
236
237
  const roleResults = installRoles({ target: requested, roles, force });
237
238
  const bindingResults = installBindings({ target: requested, adapter, roles, force });
239
+ const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(requested) : null;
238
240
  const ignore = ensureGitignore(requested, [".companion/local/"]);
239
241
 
240
242
  const manifest = {
@@ -270,6 +272,9 @@ async function cmdInit(args) {
270
272
  if (bindingResults.length) {
271
273
  console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
272
274
  }
275
+ if (openCodeConfig) {
276
+ console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
277
+ }
273
278
  if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
274
279
  console.log("");
275
280
  console.log("Next: run `devcomp doctor` and start with the `project-discovery` skill.");
@@ -352,6 +357,40 @@ async function cmdDoctor(args) {
352
357
  );
353
358
  add("roles", missingRoles.length ? "fail" : "pass", missingRoles.length ? `missing: ${missingRoles.join(", ")}` : `${manifest.roles.length} present`);
354
359
 
360
+ if (manifest.harness === "opencode") {
361
+ const teamLeadPath = join(target, ".opencode", "agents", "team-lead.md");
362
+ if (!existsSync(teamLeadPath)) {
363
+ add("orchestrator", "fail", "team-lead binding missing");
364
+ } else {
365
+ const content = readFileSync(teamLeadPath, "utf8");
366
+ const primary = /^mode:\s*primary\s*$/m.test(content);
367
+ add(
368
+ "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"
373
+ );
374
+ }
375
+
376
+ const configPath = join(target, ".opencode", "opencode.json");
377
+ let defaultAgent = null;
378
+ if (existsSync(configPath)) {
379
+ try {
380
+ defaultAgent = JSON.parse(readFileSync(configPath, "utf8")).default_agent;
381
+ } catch {
382
+ defaultAgent = null;
383
+ }
384
+ }
385
+ add(
386
+ "default agent",
387
+ defaultAgent === "team-lead" ? "pass" : "warn",
388
+ defaultAgent
389
+ ? `default_agent=${defaultAgent}`
390
+ : "not set; add default_agent=team-lead to start sessions as the orchestrator"
391
+ );
392
+ }
393
+
355
394
  const agentsPath = join(target, "AGENTS.md");
356
395
  if (!existsSync(agentsPath)) {
357
396
  add("AGENTS.md", "fail", "missing");
@@ -420,12 +459,16 @@ async function cmdUpdate(args) {
420
459
  const skillResults = installSkills({ target, adapter, skills, force });
421
460
  const roleResults = installRoles({ target, roles, force });
422
461
  installBindings({ target, adapter, roles, force });
462
+ const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
423
463
  manifest.packageVersion = VERSION;
424
464
  manifest.contentVersion = VERSION;
425
465
  writeManifest(target, manifest);
426
466
  console.log(`Updated to ${VERSION}.`);
427
467
  console.log(` Skills: ${skillResults.filter((r) => r.status === "kept").length} kept, ${skillResults.filter((r) => r.status === "installed").length} added`);
428
468
  console.log(` Roles: ${roleResults.filter((r) => r.status === "kept").length} kept, ${roleResults.filter((r) => r.status === "installed").length} added`);
469
+ if (openCodeConfig) {
470
+ console.log(` OpenCode config: ${openCodeConfig.status} (${openCodeConfig.path})`);
471
+ }
429
472
  console.log(" Existing files are preserved; use --force to overwrite.");
430
473
  }
431
474
 
package/src/install.mjs CHANGED
@@ -10,7 +10,7 @@ import {
10
10
  } from "node:fs";
11
11
  import { dirname, join, resolve } from "node:path";
12
12
  import { fileURLToPath } from "node:url";
13
- import { ROLE_DESCRIPTIONS } from "./content.mjs";
13
+ import { ROLE_DESCRIPTIONS, ROLES } from "./content.mjs";
14
14
 
15
15
  const here = dirname(fileURLToPath(import.meta.url));
16
16
 
@@ -113,18 +113,39 @@ export function installRoles({ target, roles, force = false }) {
113
113
  return results;
114
114
  }
115
115
 
116
+ const SPECIALIST_ROLES = ROLES.filter((role) => role !== "team-lead");
117
+
116
118
  function bindingBody(role) {
117
119
  return `Read \`.companion/roles/${role}.md\` and follow it. Load the skills it references from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
118
120
  }
119
121
 
120
- function openCodeBinding(role) {
121
- return `---
122
- description: ${ROLE_DESCRIPTIONS[role] ?? role}
123
- mode: subagent
124
- ---
122
+ function openCodeLeadBody() {
123
+ return `You are the primary orchestrator for this OpenCode session. Read \`.companion/roles/team-lead.md\` and follow it. Delegate specialist work with the \`subagent\` tool; do not do the specialists' deep work yourself.
125
124
 
126
- ${bindingBody(role)}
127
- `;
125
+ Available specialists: ${SPECIALIST_ROLES.join(", ")}.
126
+
127
+ Load the skills referenced by the role from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
128
+ }
129
+
130
+ function openCodeBinding(role) {
131
+ const isLead = role === "team-lead";
132
+ const mode = isLead ? "primary" : "subagent";
133
+ const body = isLead ? openCodeLeadBody() : bindingBody(role);
134
+ const frontmatter = [
135
+ "---",
136
+ `description: ${ROLE_DESCRIPTIONS[role] ?? role}`,
137
+ `mode: ${mode}`,
138
+ ...(isLead
139
+ ? [
140
+ "permissions:",
141
+ " - action: subagent",
142
+ ' resource: "*"',
143
+ " effect: allow",
144
+ ]
145
+ : []),
146
+ "---",
147
+ ].join("\n");
148
+ return `${frontmatter}\n\n${body}\n`;
128
149
  }
129
150
 
130
151
  function claudeBinding(role) {
@@ -169,6 +190,35 @@ export function installBindings({ target, adapter, roles, force = false }) {
169
190
  return results;
170
191
  }
171
192
 
193
+ /**
194
+ * Crea `.opencode/opencode.json` con `default_agent: team-lead` si no existe ya una
195
+ * configuración local de OpenCode. No sobrescribe configuración existente.
196
+ */
197
+ export function writeOpenCodeConfig(target) {
198
+ const dir = join(target, ".opencode");
199
+ const jsonPath = join(dir, "opencode.json");
200
+ const jsoncPath = join(dir, "opencode.jsonc");
201
+ if (existsSync(jsonPath) || existsSync(jsoncPath)) {
202
+ return {
203
+ status: "kept",
204
+ path: existsSync(jsonPath) ? jsonPath : jsoncPath,
205
+ };
206
+ }
207
+ ensureDir(dir);
208
+ writeText(
209
+ jsonPath,
210
+ `${JSON.stringify(
211
+ {
212
+ $schema: "https://opencode.ai/config.json",
213
+ default_agent: "team-lead",
214
+ },
215
+ null,
216
+ 2,
217
+ )}\n`,
218
+ );
219
+ return { status: "created", path: jsonPath };
220
+ }
221
+
172
222
  export function writeManifest(target, manifest) {
173
223
  const path = join(target, ".companion", "config.json");
174
224
  writeText(path, `${JSON.stringify(manifest, null, 2)}\n`);
@@ -15,6 +15,10 @@ Use the `development-workflow` skill for non-trivial work. For a new project or
15
15
  change, follow the process: discovery → architecture + security → test strategy → UX →
16
16
  delivery plan → implementation → security verification → QA → deployment → closure.
17
17
 
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 delegates to the specialist subagents
20
+ and closes with evidence; it does not do their deep work itself.
21
+
18
22
  Profile: `{{profile}}`. Branching: `{{branching}}`.
19
23
 
20
24
  ## Non-negotiables