development-companion 1.6.0 → 1.8.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 +82 -0
- package/README.md +133 -57
- package/RELEASE.md +49 -32
- package/adapters/README.md +15 -4
- package/adapters/opencode/README.md +116 -24
- package/adapters/opencode/plugin/devcomp/gates.mjs +688 -0
- package/adapters/opencode/plugin/devcomp/index.ts +603 -0
- package/core/guidelines/coordination.md +138 -4
- package/core/process.md +141 -7
- package/core/quality-gates.md +41 -1
- package/core/roles/README.md +4 -1
- package/core/roles/backend-engineer.md +10 -0
- package/core/roles/coordinator.md +171 -0
- package/core/roles/desktop-linux-engineer.md +10 -0
- package/core/roles/desktop-macos-engineer.md +10 -0
- package/core/roles/desktop-windows-engineer.md +10 -0
- package/core/roles/frontend-engineer.md +10 -0
- package/core/roles/mobile-engineer.md +10 -0
- package/core/roles/multiplatform-engineer.md +10 -0
- package/core/roles/sre-engineer.md +10 -0
- package/core/workflow.md +62 -9
- package/package.json +1 -1
- package/skills/delivery-orchestration/SKILL.md +58 -3
- package/skills/development-workflow/SKILL.md +44 -8
- package/skills/test-strategy/SKILL.md +12 -0
- package/src/cli.mjs +211 -19
- package/src/content.mjs +16 -0
- package/src/install.mjs +397 -44
- package/templates/artifacts/01-operational-brief.md +14 -1
- package/templates/artifacts/11-feature-plan.md +83 -0
- package/templates/artifacts/README.md +8 -5
- package/templates/rules/AGENTS.block.md +117 -8
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,231 @@ 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: classify, frame, approve, delegate, verify, 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
|
+
- An implementation delegation must include \`Plan: <path>\` and \`Scope: <globs>\`. The runtime plan gate rejects a missing plan, a plan outside the workspace, a plan shorter than 200 characters, a missing or non-affirmative \`Aprobado:\`, a plan without a top-level \`Scope:\` or Test/Verification/Evidence content, a development-table plan without a matching \`Step:\`/agent row, and a delegation Scope that exceeds the plan. The scope gate rejects \`edit\`, \`write\`, \`patch\`, \`apply_patch\` or \`multiedit\` outside \`Scope\`; read-only roles may write their own reports under the planning directory (\`.companion/local/**\`, \`plannification/**\`, \`docs/companion/**\`) but cannot rewrite the bound approved plan. \`--auto\` bypasses the session mark, revision guard and \`ask\`; do not use it for destructive or approval-required work.
|
|
161
|
+
- You cannot approve your own plan. Only the user's natural-language approval and the runtime session mark count. Recording \`Aprobado:\` in the plan does not replace the user's session mark and never authorizes a destructive operation.
|
|
162
|
+
- After the plan is approved, the runtime allows approved implementation delegations without a prompt per subagent. The native \`subagent: ask\` remains the fallback.
|
|
163
|
+
- Known destructive patterns always ask the user, even after an "always" approval: file deletion, database drops or truncation, volume or infrastructure destruction. Shell writes remain a residual risk. Plan approval does not authorize any of them.
|
|
164
|
+
- 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.
|
|
165
|
+
|
|
166
|
+
## Working modes
|
|
167
|
+
|
|
168
|
+
Pick the lightest mode that protects the user's data and outcome:
|
|
169
|
+
|
|
170
|
+
| Mode | Agents | Artifact | Authorization |
|
|
171
|
+
|---|---|---|---|
|
|
172
|
+
| Query | You only | None | None |
|
|
173
|
+
| Small change | One writer | Short operational brief: problem, scope, test, evidence, \`Aprobado:\` | Natural language + delegation permission |
|
|
174
|
+
| Feature | Read-only planning + writers | Visible feature plan (development + tests) | User-approved plan |
|
|
175
|
+
| Bug | One writer (+ QA if critical) | Reproduction + failing test + fix + regression | Short brief with Aprobado/Scope |
|
|
176
|
+
| Refactor | One writer | Baseline tests + reversible steps | Short brief with Aprobado/Scope |
|
|
177
|
+
| Incident | You + SRE/security | Stabilize first; postmortem after | Talk to the user |
|
|
178
|
+
|
|
179
|
+
A query is answered directly: do not launch a specialist to read a file or explain code. A small change uses one writer, the short operational brief from \`templates/artifacts/01-operational-brief.md\` with \`Aprobado:\` and \`Scope:\`, and no chain of roles. A feature always gets a visible plan. If it is unclear, treat it as a feature.
|
|
180
|
+
|
|
181
|
+
## Required flow
|
|
182
|
+
|
|
183
|
+
1. **Classify.** Query, small change, feature, bug, refactor or incident.
|
|
184
|
+
2. **Operational conversation.** Agree on the problem, users, first observable slice, scope, exclusions, constraints and acceptance criteria. Ask only what can change the slice.
|
|
185
|
+
3. **Feature intake.** For a feature, cover problem and users, observable outcome, in/out of scope, platforms and limits, requested behavior and what must not change, data/privacy/security/permissions, acceptance criteria and evidence, time and dependencies, golden and dark cases.
|
|
186
|
+
4. **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.
|
|
187
|
+
5. **Visible plan.** Write the plan under the configured planning directory (\`plannification/\` for app work; \`.companion/local/\` by default; \`docs/companion/\` when the install uses tracked docs). For a feature, follow the Development Companion template (\`templates/artifacts/11-feature-plan.md\` in the package) with a top-level \`Scope:\`, Development plan (steps, agents, dependencies, parallelism, step \`Scope\`, evidence), Test plan (golden and dark paths), E2E path, risks and rollback. For a small change, use \`templates/artifacts/01-operational-brief.md\`.
|
|
188
|
+
6. **Approval.** Present the plan 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 an affirmative \`Aprobado:\`, their words and the date in the plan. Recording it does not replace the user's session mark and never authorizes a destructive operation. Editing the plan after approval, or switching plans in the same session, requires a new approval. If they give observations, revise the plan, summarize the changes and ask again. Do not require a magic phrase.
|
|
189
|
+
7. **Delegate.** Launch the applicable specialist with \`Plan: <path>\` and \`Scope: <globs>\` (each on its own line; the scope must be equal to or narrower than the plan), the step, acceptance criteria and required evidence. One writer per slice; parallel writers get disjoint scopes. Do not implement, run tests or run builds yourself.
|
|
190
|
+
8. **Continue to E2E.** Verify each report, integrate it and continue inside the approved plan without asking for routine confirmation. Pause only for a catastrophic or irreversible operation, data loss, critical security, a requirement conflict or an invalidated plan. If a step fails, retry or adjust inside the plan; if scope changes, revise the plan with the user.
|
|
191
|
+
9. **Verify.** Read the specialist's evidence: command and output, tests, screenshots, requests or metrics. Check that the diff stayed inside \`Scope\`; if a critical dark path is untested, record the gap; do not call it a pass.
|
|
192
|
+
10. **Close.** Report what shipped, what was verified, residual risks and the next slice. Do not claim "done", "tests pass" or "verified" without evidence. Do not close a feature until the agreed end-to-end path runs and golden/dark evidence is attached.
|
|
193
|
+
|
|
194
|
+
## Goal continuity
|
|
195
|
+
|
|
196
|
+
After approval, the plan is the execution contract: verify each report and continue to the end-to-end path without asking for routine confirmation. Pause only for the cases in step 8: a catastrophic or irreversible operation, data loss, critical security, a requirement conflict or an invalidated plan.
|
|
197
|
+
|
|
198
|
+
## Scope lock and destructive operations
|
|
199
|
+
|
|
200
|
+
A specialist executes only its step and touches only files inside \`Scope\`. It reports out-of-scope findings (for example an unrequested accessibility change, a broken test or a missing permission) instead of implementing them. Never accept an unrequested change, even if it looks useful; decide whether to extend the plan and ask again.
|
|
201
|
+
|
|
202
|
+
File deletion, database \`DROP\`/\`TRUNCATE\`/\`DELETE\` without \`WHERE\`, volume or infrastructure destruction, and any operation the plan marks destructive require the user's explicit authorization. Stop the specialist, ask the user, and only then continue. The runtime forces the permission prompt for known destructive patterns even after an "always" approval; shell writes remain a residual risk and the message never prints secrets.
|
|
203
|
+
|
|
204
|
+
## Routing
|
|
205
|
+
|
|
206
|
+
| Work | Subagent |
|
|
207
|
+
|---|---|
|
|
208
|
+
| Architecture, boundaries, ADRs | \`architect\` |
|
|
209
|
+
| Threat model, security review | \`cybersecurity-engineer\` |
|
|
210
|
+
| Test strategy, QA, accessibility, load | \`qa-engineer\` |
|
|
211
|
+
| UX, UI, web frontend | \`frontend-engineer\` |
|
|
212
|
+
| API, data, auth, backend | \`backend-engineer\` |
|
|
213
|
+
| Android and Wear OS | \`mobile-engineer\` |
|
|
214
|
+
| Cross-platform core | \`multiplatform-engineer\` |
|
|
215
|
+
| Native desktop | \`desktop-*-engineer\` |
|
|
216
|
+
| Deploy, observability, secrets | \`sre-engineer\` |
|
|
217
|
+
| Second opinion on scope or sequencing | \`team-lead\` |
|
|
218
|
+
|
|
219
|
+
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.
|
|
220
|
+
|
|
221
|
+
## Escape hatch
|
|
222
|
+
|
|
223
|
+
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.`;
|
|
224
|
+
}
|
|
225
|
+
|
|
150
226
|
function bindingBody(role) {
|
|
227
|
+
if (role === "coordinator") return coordinatorBody();
|
|
151
228
|
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
229
|
|
|
153
|
-
${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
|
|
230
|
+
${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.
|
|
231
|
+
|
|
232
|
+
**Scope lock.** Read the approved plan from the delegation's \`Plan:\` path and execute only the assigned step. Touch only files that match the delegation's \`Scope:\` globs. If the step needs another file, stop and report it. Report out-of-scope findings (a missing permission, a broken test, an unrequested feature) with evidence; do not implement them, even when they look useful. Do not perform a destructive operation (file deletion, database drop/truncate, volume or infrastructure destruction) without the user's explicit authorization, requested through the Coordinator; stop and report the operation, its blast radius and the available rollback.`;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
function readOnlyPermissions({ shellTests = false } = {}) {
|
|
236
|
+
const permissions = [
|
|
237
|
+
" - action: subagent",
|
|
238
|
+
' resource: "*"',
|
|
239
|
+
" effect: deny",
|
|
240
|
+
" - action: edit",
|
|
241
|
+
' resource: "*"',
|
|
242
|
+
" effect: deny",
|
|
243
|
+
" - action: edit",
|
|
244
|
+
' resource: ".companion/local/**"',
|
|
245
|
+
" effect: allow",
|
|
246
|
+
" - action: edit",
|
|
247
|
+
' resource: "**/.companion/local/**"',
|
|
248
|
+
" effect: allow",
|
|
249
|
+
" - action: edit",
|
|
250
|
+
' resource: "plannification/**"',
|
|
251
|
+
" effect: allow",
|
|
252
|
+
" - action: edit",
|
|
253
|
+
' resource: "**/plannification/**"',
|
|
254
|
+
" effect: allow",
|
|
255
|
+
" - action: edit",
|
|
256
|
+
' resource: "docs/companion/**"',
|
|
257
|
+
" effect: allow",
|
|
258
|
+
" - action: edit",
|
|
259
|
+
' resource: "**/docs/companion/**"',
|
|
260
|
+
" effect: allow",
|
|
261
|
+
" - action: shell",
|
|
262
|
+
' resource: "*"',
|
|
263
|
+
" effect: deny"
|
|
264
|
+
];
|
|
265
|
+
if (shellTests) {
|
|
266
|
+
permissions.push(
|
|
267
|
+
" - action: shell",
|
|
268
|
+
' resource: "git status *"',
|
|
269
|
+
" effect: allow",
|
|
270
|
+
" - action: shell",
|
|
271
|
+
' resource: "git diff *"',
|
|
272
|
+
" effect: allow",
|
|
273
|
+
" - action: shell",
|
|
274
|
+
' resource: "git log *"',
|
|
275
|
+
" effect: allow",
|
|
276
|
+
" - action: shell",
|
|
277
|
+
' resource: "./gradlew *test*"',
|
|
278
|
+
" effect: allow",
|
|
279
|
+
" - action: shell",
|
|
280
|
+
' resource: "./gradlew *lint*"',
|
|
281
|
+
" effect: allow",
|
|
282
|
+
" - action: shell",
|
|
283
|
+
' resource: "./gradlew *assemble*"',
|
|
284
|
+
" effect: allow",
|
|
285
|
+
" - action: shell",
|
|
286
|
+
' resource: "npm test *"',
|
|
287
|
+
" effect: allow"
|
|
288
|
+
);
|
|
289
|
+
}
|
|
290
|
+
return permissions;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
function coordinatorPermissions() {
|
|
294
|
+
const permissions = [
|
|
295
|
+
"permissions:",
|
|
296
|
+
" - action: edit",
|
|
297
|
+
' resource: "*"',
|
|
298
|
+
" effect: deny",
|
|
299
|
+
" - action: edit",
|
|
300
|
+
' resource: ".companion/local/**"',
|
|
301
|
+
" effect: allow",
|
|
302
|
+
" - action: edit",
|
|
303
|
+
' resource: "**/.companion/local/**"',
|
|
304
|
+
" effect: allow",
|
|
305
|
+
" - action: edit",
|
|
306
|
+
' resource: "plannification/**"',
|
|
307
|
+
" effect: allow",
|
|
308
|
+
" - action: edit",
|
|
309
|
+
' resource: "**/plannification/**"',
|
|
310
|
+
" effect: allow",
|
|
311
|
+
" - action: edit",
|
|
312
|
+
' resource: "docs/companion/**"',
|
|
313
|
+
" effect: allow",
|
|
314
|
+
" - action: edit",
|
|
315
|
+
' resource: "**/docs/companion/**"',
|
|
316
|
+
" effect: allow",
|
|
317
|
+
" - action: shell",
|
|
318
|
+
' resource: "*"',
|
|
319
|
+
" effect: deny",
|
|
320
|
+
" - action: subagent",
|
|
321
|
+
' resource: "*"',
|
|
322
|
+
" effect: deny"
|
|
323
|
+
];
|
|
324
|
+
for (const role of ["architect", "qa-engineer", "cybersecurity-engineer", "team-lead", "explore"]) {
|
|
325
|
+
permissions.push(" - action: subagent", ` resource: "${role}"`, " effect: allow");
|
|
326
|
+
}
|
|
327
|
+
for (const role of IMPLEMENTATION_ROLES) {
|
|
328
|
+
permissions.push(" - action: subagent", ` resource: "${role}"`, " effect: ask");
|
|
329
|
+
}
|
|
330
|
+
permissions.push(" - action: subagent", ' resource: "general"', " effect: ask");
|
|
331
|
+
return permissions;
|
|
154
332
|
}
|
|
155
333
|
|
|
156
334
|
function openCodeBinding(role) {
|
|
335
|
+
const isCoordinator = role === "coordinator";
|
|
157
336
|
const isLead = role === "team-lead";
|
|
158
|
-
const
|
|
337
|
+
const isReadOnly = ["architect", "cybersecurity-engineer", "qa-engineer"].includes(role);
|
|
338
|
+
const mode = isCoordinator ? "primary" : "subagent";
|
|
159
339
|
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
|
-
|
|
340
|
+
const permissions = isCoordinator
|
|
341
|
+
? coordinatorPermissions()
|
|
342
|
+
: isLead
|
|
343
|
+
? [
|
|
344
|
+
"permissions:",
|
|
345
|
+
" - action: edit",
|
|
346
|
+
' resource: "*"',
|
|
347
|
+
" effect: deny",
|
|
348
|
+
" - action: edit",
|
|
349
|
+
' resource: ".companion/local/**"',
|
|
350
|
+
" effect: allow",
|
|
351
|
+
" - action: edit",
|
|
352
|
+
' resource: "**/.companion/local/**"',
|
|
353
|
+
" effect: allow",
|
|
354
|
+
" - action: edit",
|
|
355
|
+
' resource: "docs/companion/**"',
|
|
356
|
+
" effect: allow",
|
|
357
|
+
" - action: edit",
|
|
358
|
+
' resource: "**/docs/companion/**"',
|
|
359
|
+
" effect: allow",
|
|
360
|
+
" - action: shell",
|
|
361
|
+
' resource: "*"',
|
|
362
|
+
" effect: deny",
|
|
363
|
+
" - action: subagent",
|
|
364
|
+
' resource: "*"',
|
|
365
|
+
" effect: deny"
|
|
366
|
+
]
|
|
367
|
+
: isReadOnly
|
|
368
|
+
? ["permissions:", ...readOnlyPermissions({ shellTests: role === "qa-engineer" })]
|
|
369
|
+
: [
|
|
370
|
+
"permissions:",
|
|
371
|
+
" - action: subagent",
|
|
372
|
+
' resource: "*"',
|
|
373
|
+
" effect: deny"
|
|
374
|
+
];
|
|
191
375
|
const frontmatter = [
|
|
192
376
|
"---",
|
|
193
377
|
`description: ${ROLE_DESCRIPTIONS[role] ?? role}`,
|
|
@@ -223,6 +407,7 @@ export function installBindings({ target, adapter, roles, force = false, dryRun
|
|
|
223
407
|
if (!adapter.agentDir || !adapter.agentFormat) return [];
|
|
224
408
|
const results = [];
|
|
225
409
|
for (const role of roles) {
|
|
410
|
+
if (role === "coordinator" && adapter.name !== "opencode") continue;
|
|
226
411
|
const name = adapter.agentFormat === "toml" ? `${role}.toml` : `${role}.md`;
|
|
227
412
|
const destination = join(target, adapter.agentDir, name);
|
|
228
413
|
if (existsSync(destination) && !force) {
|
|
@@ -244,19 +429,187 @@ export function installBindings({ target, adapter, roles, force = false, dryRun
|
|
|
244
429
|
return results;
|
|
245
430
|
}
|
|
246
431
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
432
|
+
export const OPENCODE_INSTRUCTIONS = [
|
|
433
|
+
".companion/core/process.md",
|
|
434
|
+
".companion/core/principles.md",
|
|
435
|
+
".companion/core/quality-gates.md",
|
|
436
|
+
".companion/core/workflow.md",
|
|
437
|
+
".companion/core/guidelines/coordination.md"
|
|
438
|
+
];
|
|
439
|
+
|
|
440
|
+
const OPENCODE_REQUIRED_PERMISSIONS = [
|
|
441
|
+
{ action: "shell", resource: "git push", effect: "deny" },
|
|
442
|
+
{ action: "shell", resource: "git push *", effect: "deny" }
|
|
443
|
+
];
|
|
444
|
+
|
|
445
|
+
const OPENCODE_EXPLORE_PERMISSIONS = [
|
|
446
|
+
{ action: "shell", resource: "*", effect: "deny" }
|
|
447
|
+
];
|
|
448
|
+
|
|
449
|
+
function parseJsonc(text) {
|
|
450
|
+
const clean = text
|
|
451
|
+
.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
|
|
452
|
+
(match) => (match.startsWith('"') ? match : ""))
|
|
453
|
+
.replace(/,\s*([}\]])/g, "$1");
|
|
454
|
+
return JSON.parse(clean);
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
function sameRule(left, right) {
|
|
458
|
+
return left?.action === right.action && left?.resource === right.resource && left?.effect === right.effect;
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
function mergeRules(existing, required) {
|
|
462
|
+
const rules = Array.isArray(existing) ? [...existing] : [];
|
|
463
|
+
for (const rule of required) {
|
|
464
|
+
if (!rules.some((candidate) => sameRule(candidate, rule))) rules.push(rule);
|
|
465
|
+
}
|
|
466
|
+
return rules;
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
function openCodeConfigPath(target) {
|
|
470
|
+
const candidates = [
|
|
253
471
|
join(target, ".opencode", "opencode.json"),
|
|
254
472
|
join(target, ".opencode", "opencode.jsonc"),
|
|
255
473
|
join(target, "opencode.json"),
|
|
256
474
|
join(target, "opencode.jsonc")
|
|
257
|
-
]
|
|
258
|
-
|
|
259
|
-
|
|
475
|
+
];
|
|
476
|
+
return candidates.find((path) => existsSync(path)) ?? join(target, "opencode.json");
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
function mergeOpenCodeConfig(current) {
|
|
480
|
+
const config = current && typeof current === "object" ? current : {};
|
|
481
|
+
config.$schema ??= "https://opencode.ai/config.json";
|
|
482
|
+
config.default_agent = "coordinator";
|
|
483
|
+
config.instructions = [...new Set([...(Array.isArray(config.instructions) ? config.instructions : []), ...OPENCODE_INSTRUCTIONS])];
|
|
484
|
+
config.permissions = mergeRules(config.permissions, OPENCODE_REQUIRED_PERMISSIONS);
|
|
485
|
+
config.agents = config.agents && typeof config.agents === "object" ? config.agents : {};
|
|
486
|
+
config.agents.explore = config.agents.explore && typeof config.agents.explore === "object"
|
|
487
|
+
? config.agents.explore
|
|
488
|
+
: {};
|
|
489
|
+
config.agents.explore.permissions = mergeRules(
|
|
490
|
+
config.agents.explore.permissions,
|
|
491
|
+
OPENCODE_EXPLORE_PERMISSIONS
|
|
492
|
+
);
|
|
493
|
+
return config;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* Install the OpenCode runtime contract:
|
|
498
|
+
* - default_agent=coordinator (the primary cannot edit product code or run shell);
|
|
499
|
+
* - the five canonical instruction files, so root sessions load them even without a plugin;
|
|
500
|
+
* - a global shell deny for git push;
|
|
501
|
+
* - read-only explore.
|
|
502
|
+
*
|
|
503
|
+
* The config is a mixed user file. Preserve unknown keys, merge arrays by adding only what is
|
|
504
|
+
* missing, and write a backup under .companion/local/ before replacing the file.
|
|
505
|
+
*/
|
|
506
|
+
export function writeOpenCodeConfig(target, { dryRun = false } = {}) {
|
|
507
|
+
const configPath = openCodeConfigPath(target);
|
|
508
|
+
const existed = existsSync(configPath);
|
|
509
|
+
let current = null;
|
|
510
|
+
if (existed) {
|
|
511
|
+
try {
|
|
512
|
+
current = parseJsonc(readFileSync(configPath, "utf8"));
|
|
513
|
+
} catch (error) {
|
|
514
|
+
return {
|
|
515
|
+
status: "skipped",
|
|
516
|
+
path: relative(target, configPath),
|
|
517
|
+
reason: `cannot parse ${relative(target, configPath)}: ${error.message}`
|
|
518
|
+
};
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
const merged = mergeOpenCodeConfig(current);
|
|
523
|
+
const next = `${JSON.stringify(merged, null, 2)}\n`;
|
|
524
|
+
if (existed && readFileSync(configPath, "utf8") === next) {
|
|
525
|
+
return { status: "unchanged", path: relative(target, configPath) };
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
const status = existed ? "updated" : "created";
|
|
529
|
+
if (dryRun) return { status: `would-${status}`, path: relative(target, configPath) };
|
|
530
|
+
|
|
531
|
+
if (existed) {
|
|
532
|
+
const backup = join(target, ".companion", "local", `${basename(configPath)}.bak`);
|
|
533
|
+
writeText(backup, readFileSync(configPath, "utf8"));
|
|
534
|
+
}
|
|
535
|
+
writeText(configPath, next);
|
|
536
|
+
return { status, path: relative(target, configPath) };
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
const PLUGIN_FILES = ["index.ts", "gates.mjs"];
|
|
540
|
+
const GLOBAL_PLUGIN_ID = "devcomp-runtime-global";
|
|
541
|
+
|
|
542
|
+
function installPluginFiles(sourceDir, destinationDir, { global = false } = {}) {
|
|
543
|
+
ensureDir(destinationDir);
|
|
544
|
+
const written = [];
|
|
545
|
+
for (const file of PLUGIN_FILES) {
|
|
546
|
+
const source = join(sourceDir, file);
|
|
547
|
+
if (!existsSync(source)) continue;
|
|
548
|
+
let content = readFileSync(source, "utf8");
|
|
549
|
+
if (global && file === "index.ts") {
|
|
550
|
+
// A different id prevents the global copy from shadowing the project-local adapter when
|
|
551
|
+
// both are loaded. The global copy no-ops when a local copy exists.
|
|
552
|
+
content = content.replace('id: "devcomp-runtime"', `id: "${GLOBAL_PLUGIN_ID}"`);
|
|
553
|
+
}
|
|
554
|
+
writeText(join(destinationDir, file), content);
|
|
555
|
+
written.push(file);
|
|
556
|
+
}
|
|
557
|
+
return written;
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
export function installPlugin({ target, force = false, dryRun = false }) {
|
|
561
|
+
const source = join(packageRoot(), "adapters", "opencode", "plugin", "devcomp");
|
|
562
|
+
const destination = join(target, ".opencode", "plugins", "devcomp");
|
|
563
|
+
if (!existsSync(source)) return { plugin: "devcomp", status: "missing" };
|
|
564
|
+
const complete = PLUGIN_FILES.every((file) => existsSync(join(destination, file)));
|
|
565
|
+
if (existsSync(destination) && complete && !force) return { plugin: "devcomp", status: "kept" };
|
|
566
|
+
if (dryRun) {
|
|
567
|
+
return { plugin: "devcomp", status: existsSync(destination) ? "would-overwrite" : "would-install" };
|
|
568
|
+
}
|
|
569
|
+
installPluginFiles(source, destination);
|
|
570
|
+
return { plugin: "devcomp", status: existsSync(destination) ? "installed" : "error" };
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
export function installGlobalPlugin({ home = process.env.HOME, force = false, dryRun = false } = {}) {
|
|
574
|
+
const source = join(packageRoot(), "adapters", "opencode", "plugin", "devcomp");
|
|
575
|
+
if (!home) return { plugin: "devcomp-global", status: "skipped", reason: "HOME is not set" };
|
|
576
|
+
const destination = join(home, ".config", "opencode", "plugins", "devcomp");
|
|
577
|
+
const legacy = join(home, ".config", "opencode", "plugins", "devcomp.ts");
|
|
578
|
+
if (!existsSync(source)) return { plugin: "devcomp-global", status: "missing" };
|
|
579
|
+
|
|
580
|
+
const legacyExists = existsSync(legacy);
|
|
581
|
+
const complete = PLUGIN_FILES.every((file) => existsSync(join(destination, file)));
|
|
582
|
+
if (legacyExists && !force) {
|
|
583
|
+
return {
|
|
584
|
+
plugin: "devcomp-global",
|
|
585
|
+
status: "blocked",
|
|
586
|
+
path: legacy,
|
|
587
|
+
reason: "legacy single-file adapter found; rerun with --force to back it up, remove it and install the gated plugin"
|
|
588
|
+
};
|
|
589
|
+
}
|
|
590
|
+
if (existsSync(destination) && complete && !force) {
|
|
591
|
+
return { plugin: "devcomp-global", status: "kept", path: destination };
|
|
592
|
+
}
|
|
593
|
+
if (dryRun) {
|
|
594
|
+
return {
|
|
595
|
+
plugin: "devcomp-global",
|
|
596
|
+
status: existsSync(destination) ? "would-overwrite" : "would-install",
|
|
597
|
+
path: destination
|
|
598
|
+
};
|
|
599
|
+
}
|
|
600
|
+
installPluginFiles(source, destination, { global: true });
|
|
601
|
+
let migrated = false;
|
|
602
|
+
let backupPath;
|
|
603
|
+
if (legacyExists) {
|
|
604
|
+
// Back up and remove the legacy flat file deterministically: a leftover copy would load
|
|
605
|
+
// alongside this directory and register duplicate hooks.
|
|
606
|
+
backupPath = `${legacy}.bak`;
|
|
607
|
+
if (existsSync(backupPath)) backupPath = `${legacy}.bak-${Date.now()}`;
|
|
608
|
+
writeText(backupPath, readFileSync(legacy, "utf8"));
|
|
609
|
+
rmSync(legacy, { force: true });
|
|
610
|
+
migrated = true;
|
|
611
|
+
}
|
|
612
|
+
return { plugin: "devcomp-global", status: "installed", path: destination, migrated, backupPath };
|
|
260
613
|
}
|
|
261
614
|
|
|
262
615
|
export function writeManifest(target, manifest, { dryRun = false } = {}) {
|
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
# Operational brief
|
|
2
2
|
|
|
3
3
|
> Maximum one page. This brief unblocks the first slice, not the whole product.
|
|
4
|
+
> Use it for a small change as well: one writer, one test, one `Scope:`.
|
|
5
|
+
|
|
6
|
+
**Aprobado:** pendiente
|
|
7
|
+
**Scope:** `path/**`
|
|
8
|
+
|
|
9
|
+
> The runtime reads this first `Aprobado:` line and this top-level `Scope:`. Record `sí`, the
|
|
10
|
+
> user's words and the date only after the user approves; keep `Scope:` inside the paths the
|
|
11
|
+
> writer may touch.
|
|
4
12
|
|
|
5
13
|
## Problem and users
|
|
6
14
|
|
|
@@ -53,7 +61,12 @@
|
|
|
53
61
|
|
|
54
62
|
## Approval
|
|
55
63
|
|
|
56
|
-
-
|
|
64
|
+
- Aprobado (the first line of this file): pending | approved | rejected
|
|
57
65
|
- Approved scope, criteria and technical decisions (or linked ADR):
|
|
58
66
|
- Confirmed by:
|
|
59
67
|
- Date and approval reference:
|
|
68
|
+
|
|
69
|
+
## Verification
|
|
70
|
+
|
|
71
|
+
- Command or test that proves the slice:
|
|
72
|
+
- Evidence to attach:
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Feature plan
|
|
2
|
+
|
|
3
|
+
> User-visible execution contract. The Coordinator iterates it with the user before code.
|
|
4
|
+
> Keep it to the smallest plan that still covers scope, agents, tests and evidence.
|
|
5
|
+
|
|
6
|
+
**Aprobado:** pendiente
|
|
7
|
+
**Scope:** `path/**`
|
|
8
|
+
|
|
9
|
+
> The runtime reads this first `Aprobado:` line and this top-level `Scope:`. Record `sí`, the
|
|
10
|
+
> user's words and the date only after the user approves. Every development-plan step must stay
|
|
11
|
+
> inside this top-level scope; use a narrower `Scope` in the table for each step.
|
|
12
|
+
|
|
13
|
+
## Problem and users
|
|
14
|
+
|
|
15
|
+
## Observable outcome
|
|
16
|
+
|
|
17
|
+
## Scope
|
|
18
|
+
|
|
19
|
+
### In scope
|
|
20
|
+
|
|
21
|
+
### Out of scope (non-goals)
|
|
22
|
+
|
|
23
|
+
## Constraints
|
|
24
|
+
|
|
25
|
+
- Platforms and environments:
|
|
26
|
+
- Data, privacy, security, permissions:
|
|
27
|
+
- Accessibility explicitly requested:
|
|
28
|
+
- Compatibility and contracts:
|
|
29
|
+
- Time and dependencies:
|
|
30
|
+
|
|
31
|
+
## Approach and options
|
|
32
|
+
|
|
33
|
+
| Option | Trade-offs | Recommendation |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
|
|
36
|
+
## Development plan
|
|
37
|
+
|
|
38
|
+
| # | Step | Agent | Depends on | Parallel with | Scope | Evidence |
|
|
39
|
+
|---|---|---|---|---|---|---|
|
|
40
|
+
| 1 | | | — | — | | |
|
|
41
|
+
|
|
42
|
+
- One writer per slice. Parallel steps must have disjoint `Scope` globs.
|
|
43
|
+
- `Scope` globs are relative to the workspace root; in a meta-repo include the child prefix
|
|
44
|
+
(for example `repos/api/src/**`).
|
|
45
|
+
- Every delegation carries `Plan:` (this file), `Scope:`, the step, acceptance and evidence.
|
|
46
|
+
|
|
47
|
+
## Test plan
|
|
48
|
+
|
|
49
|
+
| ID | Type | Case | How it is verified | Evidence |
|
|
50
|
+
|---|---|---|---|---|
|
|
51
|
+
| G1 | Golden | | | |
|
|
52
|
+
| D1 | Dark | | | |
|
|
53
|
+
|
|
54
|
+
Every critical dark path needs evidence or a declared gap; an unexecuted case is not a pass.
|
|
55
|
+
|
|
56
|
+
## Golden paths
|
|
57
|
+
|
|
58
|
+
## Dark paths
|
|
59
|
+
|
|
60
|
+
## Risks and rollback
|
|
61
|
+
|
|
62
|
+
| Risk | Impact | Mitigation |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
|
|
65
|
+
- Rollback:
|
|
66
|
+
|
|
67
|
+
## Destructive operations
|
|
68
|
+
|
|
69
|
+
List any operation that deletes files, drops or truncates data, or destroys volumes or
|
|
70
|
+
infrastructure. Each one requires the user's explicit authorization before execution, separate
|
|
71
|
+
from this plan's approval.
|
|
72
|
+
|
|
73
|
+
## Closure
|
|
74
|
+
|
|
75
|
+
- End-to-end path that must work:
|
|
76
|
+
- Evidence required per acceptance criterion:
|
|
77
|
+
- Residual risks accepted by:
|
|
78
|
+
|
|
79
|
+
## Approval
|
|
80
|
+
|
|
81
|
+
- User's words:
|
|
82
|
+
- Date:
|
|
83
|
+
- Approved scope, criteria and technical approach:
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
# Artifact templates
|
|
2
2
|
|
|
3
|
-
Copy these into `.companion/local/`
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
names in English.
|
|
3
|
+
Copy these into the configured planning directory (`.companion/local/` by default, or
|
|
4
|
+
`docs/companion/` when tracked) when running the process. Rename with the numeric prefix shown
|
|
5
|
+
in `core/process.md` (`01-operational-brief.md`, etc.). They are written in English; translate
|
|
6
|
+
the content to the user's language while keeping identifiers and file names in English.
|
|
7
7
|
|
|
8
|
-
- `01-operational-brief.md`
|
|
8
|
+
- `01-operational-brief.md` — the frame, and the short plan for a small change; it carries
|
|
9
|
+
`Aprobado:` and `Scope:`.
|
|
9
10
|
- `02-architecture.md`
|
|
10
11
|
- `03-threat-model.md`
|
|
11
12
|
- `04-test-plan.md`
|
|
@@ -15,3 +16,5 @@ names in English.
|
|
|
15
16
|
- `08-qa-report.md`
|
|
16
17
|
- `09-runbook.md`
|
|
17
18
|
- `10-closure.md`
|
|
19
|
+
- `11-feature-plan.md` — the user-visible feature plan; it carries `Aprobado:`, a top-level
|
|
20
|
+
`Scope:`, a Development plan and a Test plan.
|