development-companion 1.6.0 → 1.7.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/CHANGELOG.md +26 -0
- package/README.md +49 -55
- package/RELEASE.md +25 -25
- package/adapters/README.md +9 -4
- package/adapters/opencode/README.md +41 -24
- package/adapters/opencode/plugin/devcomp/index.ts +123 -0
- package/core/roles/coordinator.md +113 -0
- package/package.json +1 -1
- package/src/cli.mjs +130 -18
- package/src/content.mjs +16 -0
- package/src/install.mjs +311 -43
- package/templates/rules/AGENTS.block.md +26 -6
package/src/install.mjs
CHANGED
|
@@ -8,9 +8,9 @@ import {
|
|
|
8
8
|
symlinkSync,
|
|
9
9
|
writeFileSync
|
|
10
10
|
} from "node:fs";
|
|
11
|
-
import { dirname, join, resolve } from "node:path";
|
|
11
|
+
import { basename, dirname, join, relative, resolve } from "node:path";
|
|
12
12
|
import { fileURLToPath } from "node:url";
|
|
13
|
-
import { ROLE_DESCRIPTIONS } from "./content.mjs";
|
|
13
|
+
import { IMPLEMENTATION_ROLES, ROLE_DESCRIPTIONS } from "./content.mjs";
|
|
14
14
|
|
|
15
15
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
16
16
|
|
|
@@ -147,47 +147,193 @@ export function installCanonical({ target, force = false, dryRun = false }) {
|
|
|
147
147
|
});
|
|
148
148
|
}
|
|
149
149
|
|
|
150
|
+
function coordinatorBody() {
|
|
151
|
+
return `You are the Development Companion Coordinator for this workspace and the sole user interlocutor. Your job is to keep the delivery loop predictable: frame, approval, delegation, evidence, close. Each specialist stays in its role; you do not do their work.
|
|
152
|
+
|
|
153
|
+
The portable coordination contract is \`.companion/core/guidelines/coordination.md\`; read it when present, otherwise use the Development Companion content injected at runtime.
|
|
154
|
+
|
|
155
|
+
## Hard constraints
|
|
156
|
+
|
|
157
|
+
- You cannot edit product code. Your \`edit\` permission is denied except for \`.companion/local/**\`, \`plannification/**\` and \`docs/companion/**\`.
|
|
158
|
+
- You cannot run shell commands. The \`shell\` permission is denied. Do not ask for it.
|
|
159
|
+
- Before the user approves the plan, you may launch only read-only roles: \`architect\`, \`qa-engineer\`, \`cybersecurity-engineer\`, \`team-lead\` and \`explore\`.
|
|
160
|
+
- Implementation roles (\`mobile-engineer\`, \`backend-engineer\`, \`frontend-engineer\`, \`multiplatform-engineer\`, \`desktop-*-engineer\`, \`sre-engineer\`, \`general\`) always require the user's permission at delegation time. The runtime forces a permission prompt even if a broad approval was saved before; do not try to bypass it.
|
|
161
|
+
- You cannot approve your own frame. Only the user's natural-language approval and their permission decision count. Writing \`Aprobado: sí\` inside a file does not unlock anything.
|
|
162
|
+
- If a relative \`.companion/core/...\` path is not present in this workspace (for example, a child repository), use the Development Companion content injected at runtime; do not treat the missing path as a blocker.
|
|
163
|
+
|
|
164
|
+
## Required flow
|
|
165
|
+
|
|
166
|
+
1. **Operational conversation.** Agree on the problem, users, first observable slice, scope, exclusions, constraints and acceptance criteria. Ask only what can change the slice.
|
|
167
|
+
2. **Technical conversation.** Show existing conventions, viable options with trade-offs, a recommendation, affected contracts, risks, rollback and the verification plan. Include golden and dark paths.
|
|
168
|
+
3. **Frame.** Write one page under \`plannification/\` for app work or \`.companion/local/\` for the meta-repo. Include scope, non-goals, observable acceptance criteria, risks and \`Aprobado: pendiente\`.
|
|
169
|
+
4. **Approval.** Present the frame and ask in natural language: «¿Apruebas el plan o tienes observaciones?». If the user approves («apruebo», «dale», «adelante», «sin observaciones», «me parece bien», etc.), record the approval, the user's words and the date in the frame. If the user gives observations, revise the frame, summarize the changes and ask again. Do not require a magic phrase.
|
|
170
|
+
5. **Delegate.** Launch the applicable specialist with the frame path, the approved scope, the files/areas to touch, the acceptance criteria and the required evidence. The runtime will ask the user to confirm the implementation delegation; that permission prompt is the hard gate. If the user rejects, stop and ask what to change. One writer per slice. Do not implement, run tests or run builds yourself.
|
|
171
|
+
6. **Verify.** Read the specialist's evidence: command and output, tests, screenshots, requests or metrics. If a critical dark path is untested, record the gap; do not call it a pass.
|
|
172
|
+
7. **Close.** Report what shipped, what was verified, residual risks and the next slice. Do not claim "done", "tests pass" or "verified" without evidence.
|
|
173
|
+
|
|
174
|
+
## Routing
|
|
175
|
+
|
|
176
|
+
| Work | Subagent |
|
|
177
|
+
|---|---|
|
|
178
|
+
| Architecture, boundaries, ADRs | \`architect\` |
|
|
179
|
+
| Threat model, security review | \`cybersecurity-engineer\` |
|
|
180
|
+
| Test strategy, QA, accessibility, load | \`qa-engineer\` |
|
|
181
|
+
| UX, UI, web frontend | \`frontend-engineer\` |
|
|
182
|
+
| API, data, auth, backend | \`backend-engineer\` |
|
|
183
|
+
| Android and Wear OS | \`mobile-engineer\` |
|
|
184
|
+
| Cross-platform core | \`multiplatform-engineer\` |
|
|
185
|
+
| Native desktop | \`desktop-*-engineer\` |
|
|
186
|
+
| Deploy, observability, secrets | \`sre-engineer\` |
|
|
187
|
+
| Second opinion on scope or sequencing | \`team-lead\` |
|
|
188
|
+
|
|
189
|
+
If no specialist fits, report the gap and ask the user how to proceed. Do not silently do the work yourself; you cannot edit product code.
|
|
190
|
+
|
|
191
|
+
## Escape hatch
|
|
192
|
+
|
|
193
|
+
A session explicitly started with \`--agent build\` (or an explicit agent switch by the user) keeps the native Build tools for a routine, in-scope fix. That is an opt-out chosen by the user, not your default. Never switch yourself to \`build\` or ask the user to do it to bypass the gate.`;
|
|
194
|
+
}
|
|
195
|
+
|
|
150
196
|
function bindingBody(role) {
|
|
197
|
+
if (role === "coordinator") return coordinatorBody();
|
|
151
198
|
return `Read \`.companion/core/guidelines/coordination.md\`, \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/${role}.md\`. Load the role's referenced skills from \`.agents/skills/\` or \`.claude/skills/\`.
|
|
152
199
|
|
|
153
200
|
${role === "team-lead" ? "Act as a callable coordination advisor. " : ""}Do not subdelegate or contact the user directly. Return evidence and open questions to the primary agent.`;
|
|
154
201
|
}
|
|
155
202
|
|
|
203
|
+
function readOnlyPermissions({ shellTests = false } = {}) {
|
|
204
|
+
const permissions = [
|
|
205
|
+
" - action: subagent",
|
|
206
|
+
' resource: "*"',
|
|
207
|
+
" effect: deny",
|
|
208
|
+
" - action: edit",
|
|
209
|
+
' resource: "*"',
|
|
210
|
+
" effect: deny",
|
|
211
|
+
" - action: edit",
|
|
212
|
+
' resource: ".companion/local/**"',
|
|
213
|
+
" effect: allow",
|
|
214
|
+
" - action: edit",
|
|
215
|
+
' resource: "**/.companion/local/**"',
|
|
216
|
+
" effect: allow",
|
|
217
|
+
" - action: edit",
|
|
218
|
+
' resource: "plannification/**"',
|
|
219
|
+
" effect: allow",
|
|
220
|
+
" - action: edit",
|
|
221
|
+
' resource: "**/plannification/**"',
|
|
222
|
+
" effect: allow",
|
|
223
|
+
" - action: shell",
|
|
224
|
+
' resource: "*"',
|
|
225
|
+
" effect: deny"
|
|
226
|
+
];
|
|
227
|
+
if (shellTests) {
|
|
228
|
+
permissions.push(
|
|
229
|
+
" - action: shell",
|
|
230
|
+
' resource: "git status *"',
|
|
231
|
+
" effect: allow",
|
|
232
|
+
" - action: shell",
|
|
233
|
+
' resource: "git diff *"',
|
|
234
|
+
" effect: allow",
|
|
235
|
+
" - action: shell",
|
|
236
|
+
' resource: "git log *"',
|
|
237
|
+
" effect: allow",
|
|
238
|
+
" - action: shell",
|
|
239
|
+
' resource: "./gradlew *test*"',
|
|
240
|
+
" effect: allow",
|
|
241
|
+
" - action: shell",
|
|
242
|
+
' resource: "./gradlew *lint*"',
|
|
243
|
+
" effect: allow",
|
|
244
|
+
" - action: shell",
|
|
245
|
+
' resource: "./gradlew *assemble*"',
|
|
246
|
+
" effect: allow",
|
|
247
|
+
" - action: shell",
|
|
248
|
+
' resource: "npm test *"',
|
|
249
|
+
" effect: allow"
|
|
250
|
+
);
|
|
251
|
+
}
|
|
252
|
+
return permissions;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
function coordinatorPermissions() {
|
|
256
|
+
const permissions = [
|
|
257
|
+
"permissions:",
|
|
258
|
+
" - action: edit",
|
|
259
|
+
' resource: "*"',
|
|
260
|
+
" effect: deny",
|
|
261
|
+
" - action: edit",
|
|
262
|
+
' resource: ".companion/local/**"',
|
|
263
|
+
" effect: allow",
|
|
264
|
+
" - action: edit",
|
|
265
|
+
' resource: "**/.companion/local/**"',
|
|
266
|
+
" effect: allow",
|
|
267
|
+
" - action: edit",
|
|
268
|
+
' resource: "plannification/**"',
|
|
269
|
+
" effect: allow",
|
|
270
|
+
" - action: edit",
|
|
271
|
+
' resource: "**/plannification/**"',
|
|
272
|
+
" effect: allow",
|
|
273
|
+
" - action: edit",
|
|
274
|
+
' resource: "docs/companion/**"',
|
|
275
|
+
" effect: allow",
|
|
276
|
+
" - action: edit",
|
|
277
|
+
' resource: "**/docs/companion/**"',
|
|
278
|
+
" effect: allow",
|
|
279
|
+
" - action: shell",
|
|
280
|
+
' resource: "*"',
|
|
281
|
+
" effect: deny",
|
|
282
|
+
" - action: subagent",
|
|
283
|
+
' resource: "*"',
|
|
284
|
+
" effect: deny"
|
|
285
|
+
];
|
|
286
|
+
for (const role of ["architect", "qa-engineer", "cybersecurity-engineer", "team-lead", "explore"]) {
|
|
287
|
+
permissions.push(" - action: subagent", ` resource: "${role}"`, " effect: allow");
|
|
288
|
+
}
|
|
289
|
+
for (const role of IMPLEMENTATION_ROLES) {
|
|
290
|
+
permissions.push(" - action: subagent", ` resource: "${role}"`, " effect: ask");
|
|
291
|
+
}
|
|
292
|
+
permissions.push(" - action: subagent", ' resource: "general"', " effect: ask");
|
|
293
|
+
return permissions;
|
|
294
|
+
}
|
|
295
|
+
|
|
156
296
|
function openCodeBinding(role) {
|
|
297
|
+
const isCoordinator = role === "coordinator";
|
|
157
298
|
const isLead = role === "team-lead";
|
|
158
|
-
const
|
|
299
|
+
const isReadOnly = ["architect", "cybersecurity-engineer", "qa-engineer"].includes(role);
|
|
300
|
+
const mode = isCoordinator ? "primary" : "subagent";
|
|
159
301
|
const body = bindingBody(role);
|
|
160
|
-
const permissions =
|
|
161
|
-
?
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
:
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
302
|
+
const permissions = isCoordinator
|
|
303
|
+
? coordinatorPermissions()
|
|
304
|
+
: isLead
|
|
305
|
+
? [
|
|
306
|
+
"permissions:",
|
|
307
|
+
" - action: edit",
|
|
308
|
+
' resource: "*"',
|
|
309
|
+
" effect: deny",
|
|
310
|
+
" - action: edit",
|
|
311
|
+
' resource: ".companion/local/**"',
|
|
312
|
+
" effect: allow",
|
|
313
|
+
" - action: edit",
|
|
314
|
+
' resource: "**/.companion/local/**"',
|
|
315
|
+
" effect: allow",
|
|
316
|
+
" - action: edit",
|
|
317
|
+
' resource: "docs/companion/**"',
|
|
318
|
+
" effect: allow",
|
|
319
|
+
" - action: edit",
|
|
320
|
+
' resource: "**/docs/companion/**"',
|
|
321
|
+
" effect: allow",
|
|
322
|
+
" - action: shell",
|
|
323
|
+
' resource: "*"',
|
|
324
|
+
" effect: deny",
|
|
325
|
+
" - action: subagent",
|
|
326
|
+
' resource: "*"',
|
|
327
|
+
" effect: deny"
|
|
328
|
+
]
|
|
329
|
+
: isReadOnly
|
|
330
|
+
? ["permissions:", ...readOnlyPermissions({ shellTests: role === "qa-engineer" })]
|
|
331
|
+
: [
|
|
332
|
+
"permissions:",
|
|
333
|
+
" - action: subagent",
|
|
334
|
+
' resource: "*"',
|
|
335
|
+
" effect: deny"
|
|
336
|
+
];
|
|
191
337
|
const frontmatter = [
|
|
192
338
|
"---",
|
|
193
339
|
`description: ${ROLE_DESCRIPTIONS[role] ?? role}`,
|
|
@@ -223,6 +369,7 @@ export function installBindings({ target, adapter, roles, force = false, dryRun
|
|
|
223
369
|
if (!adapter.agentDir || !adapter.agentFormat) return [];
|
|
224
370
|
const results = [];
|
|
225
371
|
for (const role of roles) {
|
|
372
|
+
if (role === "coordinator" && adapter.name !== "opencode") continue;
|
|
226
373
|
const name = adapter.agentFormat === "toml" ? `${role}.toml` : `${role}.md`;
|
|
227
374
|
const destination = join(target, adapter.agentDir, name);
|
|
228
375
|
if (existsSync(destination) && !force) {
|
|
@@ -244,19 +391,140 @@ export function installBindings({ target, adapter, roles, force = false, dryRun
|
|
|
244
391
|
return results;
|
|
245
392
|
}
|
|
246
393
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
394
|
+
export const OPENCODE_INSTRUCTIONS = [
|
|
395
|
+
".companion/core/process.md",
|
|
396
|
+
".companion/core/principles.md",
|
|
397
|
+
".companion/core/quality-gates.md",
|
|
398
|
+
".companion/core/workflow.md",
|
|
399
|
+
".companion/core/guidelines/coordination.md"
|
|
400
|
+
];
|
|
401
|
+
|
|
402
|
+
const OPENCODE_REQUIRED_PERMISSIONS = [
|
|
403
|
+
{ action: "shell", resource: "git push", effect: "deny" },
|
|
404
|
+
{ action: "shell", resource: "git push *", effect: "deny" }
|
|
405
|
+
];
|
|
406
|
+
|
|
407
|
+
const OPENCODE_EXPLORE_PERMISSIONS = [
|
|
408
|
+
{ action: "shell", resource: "*", effect: "deny" }
|
|
409
|
+
];
|
|
410
|
+
|
|
411
|
+
function parseJsonc(text) {
|
|
412
|
+
const clean = text
|
|
413
|
+
.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
|
|
414
|
+
(match) => (match.startsWith('"') ? match : ""))
|
|
415
|
+
.replace(/,\s*([}\]])/g, "$1");
|
|
416
|
+
return JSON.parse(clean);
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
function sameRule(left, right) {
|
|
420
|
+
return left?.action === right.action && left?.resource === right.resource && left?.effect === right.effect;
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
function mergeRules(existing, required) {
|
|
424
|
+
const rules = Array.isArray(existing) ? [...existing] : [];
|
|
425
|
+
for (const rule of required) {
|
|
426
|
+
if (!rules.some((candidate) => sameRule(candidate, rule))) rules.push(rule);
|
|
427
|
+
}
|
|
428
|
+
return rules;
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
function openCodeConfigPath(target) {
|
|
432
|
+
const candidates = [
|
|
253
433
|
join(target, ".opencode", "opencode.json"),
|
|
254
434
|
join(target, ".opencode", "opencode.jsonc"),
|
|
255
435
|
join(target, "opencode.json"),
|
|
256
436
|
join(target, "opencode.jsonc")
|
|
257
|
-
]
|
|
258
|
-
|
|
259
|
-
|
|
437
|
+
];
|
|
438
|
+
return candidates.find((path) => existsSync(path)) ?? join(target, "opencode.json");
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
function mergeOpenCodeConfig(current) {
|
|
442
|
+
const config = current && typeof current === "object" ? current : {};
|
|
443
|
+
config.$schema ??= "https://opencode.ai/config.json";
|
|
444
|
+
config.default_agent = "coordinator";
|
|
445
|
+
config.instructions = [...new Set([...(Array.isArray(config.instructions) ? config.instructions : []), ...OPENCODE_INSTRUCTIONS])];
|
|
446
|
+
config.permissions = mergeRules(config.permissions, OPENCODE_REQUIRED_PERMISSIONS);
|
|
447
|
+
config.agents = config.agents && typeof config.agents === "object" ? config.agents : {};
|
|
448
|
+
config.agents.explore = config.agents.explore && typeof config.agents.explore === "object"
|
|
449
|
+
? config.agents.explore
|
|
450
|
+
: {};
|
|
451
|
+
config.agents.explore.permissions = mergeRules(
|
|
452
|
+
config.agents.explore.permissions,
|
|
453
|
+
OPENCODE_EXPLORE_PERMISSIONS
|
|
454
|
+
);
|
|
455
|
+
return config;
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
/**
|
|
459
|
+
* Install the OpenCode runtime contract:
|
|
460
|
+
* - default_agent=coordinator (the primary cannot edit product code or run shell);
|
|
461
|
+
* - the five canonical instruction files, so root sessions load them even without a plugin;
|
|
462
|
+
* - a global shell deny for git push;
|
|
463
|
+
* - read-only explore.
|
|
464
|
+
*
|
|
465
|
+
* The config is a mixed user file. Preserve unknown keys, merge arrays by adding only what is
|
|
466
|
+
* missing, and write a backup under .companion/local/ before replacing the file.
|
|
467
|
+
*/
|
|
468
|
+
export function writeOpenCodeConfig(target, { dryRun = false } = {}) {
|
|
469
|
+
const configPath = openCodeConfigPath(target);
|
|
470
|
+
const existed = existsSync(configPath);
|
|
471
|
+
let current = null;
|
|
472
|
+
if (existed) {
|
|
473
|
+
try {
|
|
474
|
+
current = parseJsonc(readFileSync(configPath, "utf8"));
|
|
475
|
+
} catch (error) {
|
|
476
|
+
return {
|
|
477
|
+
status: "skipped",
|
|
478
|
+
path: relative(target, configPath),
|
|
479
|
+
reason: `cannot parse ${relative(target, configPath)}: ${error.message}`
|
|
480
|
+
};
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
const merged = mergeOpenCodeConfig(current);
|
|
485
|
+
const next = `${JSON.stringify(merged, null, 2)}\n`;
|
|
486
|
+
if (existed && readFileSync(configPath, "utf8") === next) {
|
|
487
|
+
return { status: "unchanged", path: relative(target, configPath) };
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
const status = existed ? "updated" : "created";
|
|
491
|
+
if (dryRun) return { status: `would-${status}`, path: relative(target, configPath) };
|
|
492
|
+
|
|
493
|
+
if (existed) {
|
|
494
|
+
const backup = join(target, ".companion", "local", `${basename(configPath)}.bak`);
|
|
495
|
+
writeText(backup, readFileSync(configPath, "utf8"));
|
|
496
|
+
}
|
|
497
|
+
writeText(configPath, next);
|
|
498
|
+
return { status, path: relative(target, configPath) };
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
export function installPlugin({ target, force = false, dryRun = false }) {
|
|
502
|
+
const source = join(packageRoot(), "adapters", "opencode", "plugin", "devcomp", "index.ts");
|
|
503
|
+
const destination = join(target, ".opencode", "plugins", "devcomp", "index.ts");
|
|
504
|
+
if (!existsSync(source)) return { plugin: "devcomp", status: "missing" };
|
|
505
|
+
if (existsSync(destination) && !force) return { plugin: "devcomp", status: "kept" };
|
|
506
|
+
if (dryRun) {
|
|
507
|
+
return { plugin: "devcomp", status: existsSync(destination) ? "would-overwrite" : "would-install" };
|
|
508
|
+
}
|
|
509
|
+
writeText(destination, readFileSync(source, "utf8"));
|
|
510
|
+
return { plugin: "devcomp", status: "installed" };
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
export function installGlobalPlugin({ home = process.env.HOME, force = false, dryRun = false } = {}) {
|
|
514
|
+
const source = join(packageRoot(), "adapters", "opencode", "plugin", "devcomp", "index.ts");
|
|
515
|
+
if (!home) return { plugin: "devcomp-global", status: "skipped", reason: "HOME is not set" };
|
|
516
|
+
const destination = join(home, ".config", "opencode", "plugins", "devcomp.ts");
|
|
517
|
+
if (!existsSync(source)) return { plugin: "devcomp-global", status: "missing" };
|
|
518
|
+
if (existsSync(destination) && !force) return { plugin: "devcomp-global", status: "kept", path: destination };
|
|
519
|
+
if (dryRun) {
|
|
520
|
+
return {
|
|
521
|
+
plugin: "devcomp-global",
|
|
522
|
+
status: existsSync(destination) ? "would-overwrite" : "would-install",
|
|
523
|
+
path: destination
|
|
524
|
+
};
|
|
525
|
+
}
|
|
526
|
+
writeText(destination, readFileSync(source, "utf8"));
|
|
527
|
+
return { plugin: "devcomp-global", status: "installed", path: destination };
|
|
260
528
|
}
|
|
261
529
|
|
|
262
530
|
export function writeManifest(target, manifest, { dryRun = false } = {}) {
|
|
@@ -20,9 +20,20 @@ If a file is missing, run `devcomp doctor` and `devcomp update` before coding.
|
|
|
20
20
|
|
|
21
21
|
## How to work
|
|
22
22
|
|
|
23
|
-
The primary agent is the **Coordinator and sole user interlocutor**. It
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
The primary agent is the **Coordinator and sole user interlocutor**. It owns the result, but
|
|
24
|
+
it does not implement it: in OpenCode the `coordinator` agent is the default
|
|
25
|
+
(`default_agent: coordinator`), it cannot edit product code or run shell, and it delegates to
|
|
26
|
+
specialists. The callable `team-lead` remains a read-only advisor. `build` is an explicit
|
|
27
|
+
escape hatch for a routine change the user chooses to run directly. Specialists report
|
|
28
|
+
evidence to the Coordinator, not to the user.
|
|
29
|
+
|
|
30
|
+
A runtime adapter (`.opencode/plugins/devcomp/`) injects the canonical process into every
|
|
31
|
+
session, including child repositories, and forces a user permission prompt before an
|
|
32
|
+
implementation subagent starts. Approval is natural language: the Coordinator presents the
|
|
33
|
+
frame, the user says "apruebo", "dale", "adelante" or "tengo observaciones", and the
|
|
34
|
+
permission prompt is the final confirmation. There is no magic phrase. Questions, permissions
|
|
35
|
+
and errors notify immediately; an idle turn is debounced so a subagent report does not produce
|
|
36
|
+
a toast per subagent.
|
|
26
37
|
|
|
27
38
|
For non-trivial work:
|
|
28
39
|
|
|
@@ -119,10 +130,19 @@ the corresponding evidence.
|
|
|
119
130
|
|
|
120
131
|
## Update and migration contract
|
|
121
132
|
|
|
122
|
-
- `devcomp update` replaces framework-owned files: core process, skills, roles,
|
|
123
|
-
bindings
|
|
124
|
-
|
|
133
|
+
- `devcomp update` replaces framework-owned files: core process, skills, roles, harness
|
|
134
|
+
bindings, the OpenCode runtime plugin, and the managed block in this file. It merges
|
|
135
|
+
`opencode.json` with `default_agent: coordinator`, the five canonical instructions, a
|
|
136
|
+
`git push` denial and a read-only `explore`; unknown keys are preserved and the previous
|
|
137
|
+
file is backed up under `.companion/local/`. Use `--keep` to preserve the config and bindings
|
|
138
|
+
for a manual merge.
|
|
125
139
|
- Before changing this file, the CLI writes `AGENTS.md.bak`. Inspect it if a rule disappears.
|
|
140
|
+
- `devcomp setup opencode --global` installs the runtime plugin in
|
|
141
|
+
`~/.config/opencode/plugins/devcomp.ts` so sessions outside a meta-repo also load it. It is
|
|
142
|
+
idempotent and does nothing for workspaces without `.companion/config.json`.
|
|
143
|
+
- After an update, start a **new session**; an existing session keeps its previous agent. Run
|
|
144
|
+
`devcomp doctor` in the repository. The runtime behavior is verified in a new session, not by
|
|
145
|
+
`doctor` alone.
|
|
126
146
|
- If the previous file was a legacy `AGENTS.md`, the CLI wraps its content under `User guiding`
|
|
127
147
|
and reports a migration. Review the result; the automatic migration preserves the text but
|
|
128
148
|
does not rewrite its tone.
|