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 +9 -0
- package/RELEASE.md +23 -8
- package/adapters/opencode/README.md +64 -26
- package/package.json +1 -1
- package/src/cli.mjs +43 -0
- package/src/install.mjs +58 -8
- package/templates/rules/AGENTS.block.md +4 -0
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.
|
|
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.
|
|
61
|
-
|
|
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.
|
|
68
|
-
npx development-companion@1.
|
|
69
|
-
npx development-companion@1.
|
|
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.
|
|
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.
|
|
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
|
-
##
|
|
36
|
+
## Agents
|
|
37
37
|
|
|
38
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
"
|
|
53
|
-
|
|
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
|
-
|
|
64
|
-
`
|
|
65
|
-
|
|
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
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
"
|
|
74
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
84
|
-
|
|
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
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
|
|
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
|
-
${
|
|
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
|