development-companion 1.2.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -19
- package/RELEASE.md +7 -7
- package/adapters/README.md +7 -1
- package/adapters/opencode/README.md +7 -2
- package/core/principles.md +21 -0
- package/core/process.md +122 -158
- package/core/quality-gates.md +21 -13
- package/core/roles/team-lead.md +46 -29
- package/core/workflow.md +16 -3
- package/package.json +2 -2
- package/skills/architecture-design/SKILL.md +7 -0
- package/skills/delivery-orchestration/SKILL.md +65 -67
- package/skills/development-workflow/SKILL.md +2 -0
- package/skills/incremental-delivery/SKILL.md +116 -0
- package/skills/project-discovery/SKILL.md +23 -3
- package/skills/test-strategy/SKILL.md +7 -2
- package/skills/ux-design/SKILL.md +7 -2
- package/src/cli.mjs +57 -16
- package/src/content.mjs +1 -0
- package/src/install.mjs +30 -7
- package/src/rules.mjs +3 -1
- package/src/scaffold.mjs +4 -1
- package/templates/artifacts/01-operational-brief.md +17 -3
- package/templates/artifacts/06-delivery-plan.md +26 -5
- package/templates/rules/AGENTS.block.md +34 -18
package/src/cli.mjs
CHANGED
|
@@ -4,9 +4,11 @@ import { homedir } from "node:os";
|
|
|
4
4
|
import { parseArgs, flag, bool, list } from "./args.mjs";
|
|
5
5
|
import { ask, choose, confirm } from "./prompt.mjs";
|
|
6
6
|
import { detectRepo, detectBranching } from "./detect.mjs";
|
|
7
|
-
import { applyRules, ensureGitignore, renderTemplate } from "./rules.mjs";
|
|
7
|
+
import { applyRules, ensureGitignore, hasManagedBlock, renderTemplate } from "./rules.mjs";
|
|
8
8
|
import {
|
|
9
|
+
CANONICAL_FILES,
|
|
9
10
|
ensureDir,
|
|
11
|
+
installCanonical,
|
|
10
12
|
installBindings,
|
|
11
13
|
installRoles,
|
|
12
14
|
installSkills,
|
|
@@ -149,6 +151,7 @@ async function cmdInit(args) {
|
|
|
149
151
|
const skills = resolveSkills(profile, list(args, "skills"));
|
|
150
152
|
const roles = [...ROLES];
|
|
151
153
|
const docs = flag(args, "docs", "local");
|
|
154
|
+
if (!["local", "tracked"].includes(docs)) throw new Error(`invalid docs mode "${docs}". Use local or tracked.`);
|
|
152
155
|
const memory = flag(args, "memory", "none");
|
|
153
156
|
const mode = flag(args, "mode", "copy");
|
|
154
157
|
if (!["copy", "symlink"].includes(mode)) throw new Error(`invalid mode "${mode}". Use copy or symlink.`);
|
|
@@ -215,7 +218,8 @@ async function cmdInit(args) {
|
|
|
215
218
|
const agentsBlock = renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
|
|
216
219
|
projectName,
|
|
217
220
|
profile,
|
|
218
|
-
branching
|
|
221
|
+
branching,
|
|
222
|
+
docsDir: docs === "tracked" ? "docs/companion/" : ".companion/local/"
|
|
219
223
|
});
|
|
220
224
|
const claudeBlock = readTemplate("templates/rules/CLAUDE.block.md").trim();
|
|
221
225
|
|
|
@@ -233,6 +237,7 @@ async function cmdInit(args) {
|
|
|
233
237
|
force
|
|
234
238
|
});
|
|
235
239
|
|
|
240
|
+
const canonicalResults = installCanonical({ target: requested, force });
|
|
236
241
|
const skillResults = installSkills({ target: requested, adapter, skills, mode, force });
|
|
237
242
|
const roleResults = installRoles({ target: requested, roles, force });
|
|
238
243
|
const bindingResults = installBindings({ target: requested, adapter, roles, force });
|
|
@@ -268,6 +273,7 @@ async function cmdInit(args) {
|
|
|
268
273
|
console.log(` ${file}: ${result.mode}${result.reason ? ` (${result.reason})` : ""}`);
|
|
269
274
|
}
|
|
270
275
|
console.log(` Skills: ${skillResults.filter((r) => r.status === "installed").length} installed, ${skillResults.filter((r) => r.status === "kept").length} kept`);
|
|
276
|
+
console.log(` Canonical files: ${canonicalResults.filter((r) => r.status === "installed").length} installed, ${canonicalResults.filter((r) => r.status === "kept").length} kept`);
|
|
271
277
|
console.log(` Roles: ${roleResults.filter((r) => r.status === "installed").length} installed, ${roleResults.filter((r) => r.status === "kept").length} kept`);
|
|
272
278
|
if (bindingResults.length) {
|
|
273
279
|
console.log(` Bindings: ${bindingResults.filter((r) => r.status === "installed").length} installed`);
|
|
@@ -277,7 +283,7 @@ async function cmdInit(args) {
|
|
|
277
283
|
}
|
|
278
284
|
if (ignore.changed) console.log(` .gitignore: added ${ignore.added.join(", ")}`);
|
|
279
285
|
console.log("");
|
|
280
|
-
console.log("Next: run `devcomp doctor
|
|
286
|
+
console.log("Next: run `devcomp doctor`; resolve any FAIL before starting with `project-discovery`.");
|
|
281
287
|
}
|
|
282
288
|
|
|
283
289
|
async function cmdAdd(args) {
|
|
@@ -357,6 +363,20 @@ async function cmdDoctor(args) {
|
|
|
357
363
|
);
|
|
358
364
|
add("roles", missingRoles.length ? "fail" : "pass", missingRoles.length ? `missing: ${missingRoles.join(", ")}` : `${manifest.roles.length} present`);
|
|
359
365
|
|
|
366
|
+
if (adapter?.agentDir && adapter.agentFormat) {
|
|
367
|
+
const extension = adapter.agentFormat === "toml" ? "toml" : "md";
|
|
368
|
+
const missingBindings = (manifest.roles ?? []).filter(
|
|
369
|
+
(role) => !existsSync(join(target, adapter.agentDir, `${role}.${extension}`))
|
|
370
|
+
);
|
|
371
|
+
add("agent bindings", missingBindings.length ? "fail" : "pass", missingBindings.length
|
|
372
|
+
? `missing: ${missingBindings.join(", ")}` : `${manifest.roles.length} present`);
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
const missingCore = CANONICAL_FILES.filter((file) => !existsSync(join(target, ".companion", "core", file)));
|
|
376
|
+
add("canonical process", missingCore.length ? "fail" : "pass", missingCore.length
|
|
377
|
+
? `missing: ${missingCore.join(", ")}; run devcomp update`
|
|
378
|
+
: `${CANONICAL_FILES.length} files present`);
|
|
379
|
+
|
|
360
380
|
if (manifest.harness === "opencode") {
|
|
361
381
|
const teamLeadPath = join(target, ".opencode", "agents", "team-lead.md");
|
|
362
382
|
if (!existsSync(teamLeadPath)) {
|
|
@@ -366,28 +386,40 @@ async function cmdDoctor(args) {
|
|
|
366
386
|
const primary = /^mode:\s*primary\s*$/m.test(content);
|
|
367
387
|
add(
|
|
368
388
|
"orchestrator",
|
|
369
|
-
primary ? "pass" : "
|
|
389
|
+
primary ? "pass" : "fail",
|
|
370
390
|
primary
|
|
371
391
|
? "team-lead is a primary agent"
|
|
372
|
-
: "team-lead is not primary; run
|
|
392
|
+
: "team-lead is not primary; review local edits and run devcomp add role team-lead --force"
|
|
373
393
|
);
|
|
394
|
+
const denies = (action) => new RegExp(`- action: ${action}\\s+resource: "\\*"\\s+effect: deny`).test(content);
|
|
395
|
+
const delegates = /- action: subagent\s+resource: "\*"\s+effect: allow/.test(content);
|
|
396
|
+
add("lead permissions", denies("edit") && denies("shell") && delegates ? "pass" : "fail",
|
|
397
|
+
denies("edit") && denies("shell") && delegates
|
|
398
|
+
? "edits and shell denied; delegation allowed"
|
|
399
|
+
: "outdated team-lead binding; review local edits and run devcomp add role team-lead --force to replace it");
|
|
374
400
|
}
|
|
375
401
|
|
|
376
|
-
const
|
|
402
|
+
const configPaths = ["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc"];
|
|
377
403
|
let defaultAgent = null;
|
|
378
|
-
|
|
404
|
+
for (const file of configPaths) {
|
|
405
|
+
const configPath = join(target, file);
|
|
406
|
+
if (!existsSync(configPath)) continue;
|
|
379
407
|
try {
|
|
380
|
-
|
|
408
|
+
const text = readFileSync(configPath, "utf8");
|
|
409
|
+
// JSONC comments and trailing commas are supported by OpenCode.
|
|
410
|
+
const clean = text.replace(/("(?:\\.|[^"\\])*"|\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g,
|
|
411
|
+
(match) => match.startsWith('"') ? match : "").replace(/,\s*([}\]])/g, "$1");
|
|
412
|
+
defaultAgent = JSON.parse(clean).default_agent ?? defaultAgent;
|
|
381
413
|
} catch {
|
|
382
|
-
|
|
414
|
+
add("OpenCode config", "fail", `cannot parse ${file}; check the config manually`);
|
|
383
415
|
}
|
|
384
416
|
}
|
|
385
417
|
add(
|
|
386
418
|
"default agent",
|
|
387
|
-
defaultAgent === "team-lead" ? "pass" : "
|
|
419
|
+
defaultAgent === "team-lead" ? "pass" : "fail",
|
|
388
420
|
defaultAgent
|
|
389
421
|
? `default_agent=${defaultAgent}`
|
|
390
|
-
: "not set;
|
|
422
|
+
: "not set; set default_agent to team-lead in your existing OpenCode config, then start a new session"
|
|
391
423
|
);
|
|
392
424
|
}
|
|
393
425
|
|
|
@@ -396,17 +428,18 @@ async function cmdDoctor(args) {
|
|
|
396
428
|
add("AGENTS.md", "fail", "missing");
|
|
397
429
|
} else {
|
|
398
430
|
const content = readFileSync(agentsPath, "utf8");
|
|
399
|
-
const managed = content
|
|
400
|
-
const
|
|
401
|
-
add("AGENTS.md",
|
|
431
|
+
const managed = hasManagedBlock(content);
|
|
432
|
+
const current = managed && content.includes(".companion/core/process.md");
|
|
433
|
+
add("AGENTS.md", current ? "pass" : "fail", current ? "canonical process linked" :
|
|
434
|
+
"framework rules missing or outdated; run devcomp init --rules append (preserves existing rules)");
|
|
402
435
|
}
|
|
403
436
|
|
|
404
437
|
const claudePath = join(target, "CLAUDE.md");
|
|
405
438
|
if (!existsSync(claudePath)) {
|
|
406
|
-
add("CLAUDE.md", "warn", "missing; Claude Code will not import AGENTS.md");
|
|
439
|
+
add("CLAUDE.md", manifest.harness === "claude-code" ? "fail" : "warn", "missing; Claude Code will not import AGENTS.md");
|
|
407
440
|
} else {
|
|
408
441
|
const content = readFileSync(claudePath, "utf8");
|
|
409
|
-
add("CLAUDE.md", content.includes("@AGENTS.md") ? "pass" : "warn", content.includes("@AGENTS.md") ? "imports AGENTS.md" : "does not import AGENTS.md");
|
|
442
|
+
add("CLAUDE.md", content.includes("@AGENTS.md") ? "pass" : manifest.harness === "claude-code" ? "fail" : "warn", content.includes("@AGENTS.md") ? "imports AGENTS.md" : "does not import AGENTS.md");
|
|
410
443
|
}
|
|
411
444
|
|
|
412
445
|
const ignorePath = join(target, ".gitignore");
|
|
@@ -457,9 +490,17 @@ async function cmdUpdate(args) {
|
|
|
457
490
|
const skills = manifest.skills ?? [];
|
|
458
491
|
const roles = manifest.roles ?? [];
|
|
459
492
|
const skillResults = installSkills({ target, adapter, skills, force });
|
|
493
|
+
installCanonical({ target, force });
|
|
460
494
|
const roleResults = installRoles({ target, roles, force });
|
|
461
495
|
installBindings({ target, adapter, roles, force });
|
|
462
496
|
const openCodeConfig = adapter.name === "opencode" ? writeOpenCodeConfig(target) : null;
|
|
497
|
+
const rulesPath = join(target, "AGENTS.md");
|
|
498
|
+
if (existsSync(rulesPath) && hasManagedBlock(readFileSync(rulesPath, "utf8"))) {
|
|
499
|
+
applyRules({ filePath: rulesPath, mode: "append", block: renderTemplate(readTemplate("templates/rules/AGENTS.block.md"), {
|
|
500
|
+
projectName: basename(target), profile: manifest.profile, branching: manifest.branching,
|
|
501
|
+
docsDir: manifest.docs === "tracked" ? "docs/companion/" : ".companion/local/"
|
|
502
|
+
}) });
|
|
503
|
+
}
|
|
463
504
|
manifest.packageVersion = VERSION;
|
|
464
505
|
manifest.contentVersion = VERSION;
|
|
465
506
|
writeManifest(target, manifest);
|
package/src/content.mjs
CHANGED
package/src/install.mjs
CHANGED
|
@@ -113,8 +113,29 @@ export function installRoles({ target, roles, force = false }) {
|
|
|
113
113
|
return results;
|
|
114
114
|
}
|
|
115
115
|
|
|
116
|
+
export const CANONICAL_FILES = [
|
|
117
|
+
"principles.md",
|
|
118
|
+
"process.md",
|
|
119
|
+
"workflow.md",
|
|
120
|
+
"quality-gates.md",
|
|
121
|
+
...readdirSync(join(packageRoot(), "core", "guidelines"))
|
|
122
|
+
.filter((file) => file.endsWith(".md"))
|
|
123
|
+
.map((file) => `guidelines/${file}`)
|
|
124
|
+
];
|
|
125
|
+
|
|
126
|
+
export function installCanonical({ target, force = false }) {
|
|
127
|
+
return CANONICAL_FILES.map((file) => {
|
|
128
|
+
const source = join(packageRoot(), "core", file);
|
|
129
|
+
const destination = join(target, ".companion", "core", file);
|
|
130
|
+
if (existsSync(destination) && !force) return { file, status: "kept" };
|
|
131
|
+
ensureDir(dirname(destination));
|
|
132
|
+
copyFileSync(source, destination);
|
|
133
|
+
return { file, status: "installed" };
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
|
|
116
137
|
function bindingBody(role) {
|
|
117
|
-
return `Read \`.companion/roles/${role}.md\` and follow
|
|
138
|
+
return `Read \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/${role}.md\` and follow them. Load the skills it references from \`.agents/skills/\` or \`.claude/skills/\`. Report evidence, not claims.`;
|
|
118
139
|
}
|
|
119
140
|
|
|
120
141
|
function openCodeLeadBody() {
|
|
@@ -149,11 +170,11 @@ function openCodeLeadBody() {
|
|
|
149
170
|
|
|
150
171
|
## Flow
|
|
151
172
|
|
|
152
|
-
1. Read the request and \`.companion/roles/team-lead.md\`.
|
|
173
|
+
1. Read the request, \`.companion/core/process.md\`, \`.companion/core/principles.md\`, \`.companion/core/quality-gates.md\`, and \`.companion/roles/team-lead.md\`.
|
|
153
174
|
2. Decide the route and the bounded deliverable.
|
|
154
175
|
3. Call \`subagent\` with goal, context, deliverable, verification, and do-not.
|
|
155
176
|
4. Review the child's evidence; ask for fixes if needed.
|
|
156
|
-
5. Write only your own plan/closure documents under \`.companion/local
|
|
177
|
+
5. Write only your own plan/closure documents under the configured docs directory in \`AGENTS.md\` (\`.companion/local/\` by default, \`docs/companion/\` when tracked).
|
|
157
178
|
6. Report to the user with evidence.
|
|
158
179
|
|
|
159
180
|
A trivial one-line answer may be answered directly. Anything that changes the repository or produces an artifact must be delegated.`;
|
|
@@ -247,17 +268,19 @@ export function installBindings({ target, adapter, roles, force = false }) {
|
|
|
247
268
|
}
|
|
248
269
|
|
|
249
270
|
/**
|
|
250
|
-
*
|
|
251
|
-
*
|
|
271
|
+
* Create `.opencode/opencode.json` with `default_agent: team-lead` only when the
|
|
272
|
+
* project has no existing OpenCode config at its root or inside `.opencode/`.
|
|
252
273
|
*/
|
|
253
274
|
export function writeOpenCodeConfig(target) {
|
|
254
275
|
const dir = join(target, ".opencode");
|
|
255
276
|
const jsonPath = join(dir, "opencode.json");
|
|
256
277
|
const jsoncPath = join(dir, "opencode.jsonc");
|
|
257
|
-
|
|
278
|
+
const existing = [jsonPath, jsoncPath, join(target, "opencode.json"), join(target, "opencode.jsonc")]
|
|
279
|
+
.find((path) => existsSync(path));
|
|
280
|
+
if (existing) {
|
|
258
281
|
return {
|
|
259
282
|
status: "kept",
|
|
260
|
-
path:
|
|
283
|
+
path: existing,
|
|
261
284
|
};
|
|
262
285
|
}
|
|
263
286
|
ensureDir(dir);
|
package/src/rules.mjs
CHANGED
|
@@ -17,7 +17,8 @@ export function replaceManagedBlock(content, block) {
|
|
|
17
17
|
const start = content.indexOf(START);
|
|
18
18
|
const end = content.indexOf(END);
|
|
19
19
|
if (start === -1 || end === -1 || end < start) return null;
|
|
20
|
-
|
|
20
|
+
const suffix = content.slice(end + END.length);
|
|
21
|
+
return `${content.slice(0, start)}${block}${suffix.trim() ? suffix : "\n"}`;
|
|
21
22
|
}
|
|
22
23
|
|
|
23
24
|
export function appendBlock(content, block) {
|
|
@@ -27,6 +28,7 @@ export function appendBlock(content, block) {
|
|
|
27
28
|
}
|
|
28
29
|
|
|
29
30
|
export function applyRules({ filePath, mode, block, force = false }) {
|
|
31
|
+
block = block.trimEnd();
|
|
30
32
|
const exists = existsSync(filePath);
|
|
31
33
|
if (!exists) {
|
|
32
34
|
writeFileSync(filePath, `${block}\n`, "utf8");
|
package/src/scaffold.mjs
CHANGED
|
@@ -55,7 +55,7 @@ function webPackage() {
|
|
|
55
55
|
"@types/react": "^19.3.0",
|
|
56
56
|
"@types/react-dom": "^19.3.0",
|
|
57
57
|
"@vitejs/plugin-react": "^6.1.2",
|
|
58
|
-
"jsdom": "^
|
|
58
|
+
"jsdom": "^29.1.1",
|
|
59
59
|
"typescript": "^7.0.2",
|
|
60
60
|
"vite": "^8.3.5",
|
|
61
61
|
"vitest": "^5.0.5"
|
|
@@ -125,6 +125,9 @@ import react from "@vitejs/plugin-react";
|
|
|
125
125
|
|
|
126
126
|
export default defineConfig({
|
|
127
127
|
plugins: [react()],
|
|
128
|
+
server: {
|
|
129
|
+
host: "127.0.0.1"
|
|
130
|
+
},
|
|
128
131
|
test: {
|
|
129
132
|
environment: "jsdom"
|
|
130
133
|
}
|
|
@@ -1,19 +1,28 @@
|
|
|
1
1
|
# Operational brief
|
|
2
2
|
|
|
3
|
+
> Maximum one page. This brief unblocks the first slice, not the whole product.
|
|
4
|
+
|
|
3
5
|
## Problem and users
|
|
4
6
|
|
|
5
7
|
## Goals and success metrics
|
|
6
8
|
|
|
9
|
+
## First end-to-end slice
|
|
10
|
+
|
|
11
|
+
- Input:
|
|
12
|
+
- Process:
|
|
13
|
+
- Observable output:
|
|
14
|
+
- Acceptance criteria (one or two sentences):
|
|
15
|
+
|
|
7
16
|
## Scope
|
|
8
17
|
|
|
9
|
-
### In scope
|
|
18
|
+
### In scope for this slice
|
|
10
19
|
|
|
11
20
|
### Out of scope
|
|
12
21
|
|
|
13
|
-
## Existing artifacts
|
|
14
|
-
|
|
15
22
|
## Constraints
|
|
16
23
|
|
|
24
|
+
## Existing artifacts
|
|
25
|
+
|
|
17
26
|
## Hosting and third parties
|
|
18
27
|
|
|
19
28
|
## Data and privacy
|
|
@@ -29,6 +38,11 @@
|
|
|
29
38
|
|
|
30
39
|
## Definition of done
|
|
31
40
|
|
|
41
|
+
## Planning budget
|
|
42
|
+
|
|
43
|
+
- Time spent on this brief:
|
|
44
|
+
- Deferred decisions and the slice that will unblock them:
|
|
45
|
+
|
|
32
46
|
## Open questions
|
|
33
47
|
|
|
34
48
|
## Approval
|
|
@@ -1,13 +1,24 @@
|
|
|
1
1
|
# Delivery plan
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> One page for the first three slices. If it does not fit, the scope is too broad.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## First vertical slice
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Input:
|
|
8
|
+
- Process:
|
|
9
|
+
- Observable output:
|
|
10
|
+
- Acceptance criteria:
|
|
11
|
+
- Verification command:
|
|
12
|
+
|
|
13
|
+
## Slices
|
|
14
|
+
|
|
15
|
+
| Slice | Owner | Observable result | Verification | Depends on |
|
|
8
16
|
|---|---|---|---|---|
|
|
9
17
|
|
|
10
|
-
##
|
|
18
|
+
## WIP limit
|
|
19
|
+
|
|
20
|
+
- One slice per writer.
|
|
21
|
+
- Parallel work only for read-only tasks or disjoint files.
|
|
11
22
|
|
|
12
23
|
## Branch and release flow
|
|
13
24
|
|
|
@@ -15,15 +26,25 @@
|
|
|
15
26
|
|
|
16
27
|
| Gate | Evidence | Accepted by |
|
|
17
28
|
|---|---|---|
|
|
29
|
+
| Frame | One-page brief confirmed | User |
|
|
30
|
+
| Skeleton | End-to-end path + one test + commit | Team Lead |
|
|
31
|
+
| Slice | Acceptance criteria + tests + demo + commit | Team Lead |
|
|
32
|
+
| Release | Security/QA findings closed; install verified | User |
|
|
18
33
|
|
|
19
34
|
## Risks
|
|
20
35
|
|
|
21
36
|
| Risk | Impact | Mitigation | Owner |
|
|
22
37
|
|---|---|---|---|
|
|
23
38
|
|
|
39
|
+
## Delivery log
|
|
40
|
+
|
|
41
|
+
| Date | Slice | Commit | Tests | Next |
|
|
42
|
+
|---|---|---|---|---|
|
|
43
|
+
|
|
24
44
|
## Status
|
|
25
45
|
|
|
46
|
+
- Last commit:
|
|
26
47
|
- Done:
|
|
27
48
|
- In progress:
|
|
28
49
|
- Blocked:
|
|
29
|
-
- Next
|
|
50
|
+
- Next slice:
|
|
@@ -3,7 +3,12 @@
|
|
|
3
3
|
|
|
4
4
|
This project uses the Development Companion process. Read these files before working:
|
|
5
5
|
|
|
6
|
-
- `.companion/
|
|
6
|
+
- `.companion/core/process.md` — delivery loop and gates.
|
|
7
|
+
- `.companion/core/principles.md` — non-negotiable engineering rules.
|
|
8
|
+
- `.companion/core/quality-gates.md` — evidence and completion criteria.
|
|
9
|
+
- `.companion/core/workflow.md` — workflow for individual changes.
|
|
10
|
+
- `.companion/core/guidelines/` — discipline-specific guidance.
|
|
11
|
+
- `.companion/roles/team-lead.md` — delivery owner and orchestration.
|
|
7
12
|
- `.companion/roles/architect.md` — boundaries, patterns, and ADRs.
|
|
8
13
|
- `.companion/roles/cybersecurity-engineer.md` — threat model and security review.
|
|
9
14
|
- `.companion/roles/qa-engineer.md` — test strategy and verification.
|
|
@@ -11,31 +16,42 @@ This project uses the Development Companion process. Read these files before wor
|
|
|
11
16
|
|
|
12
17
|
## Workflow
|
|
13
18
|
|
|
14
|
-
Use the `development-workflow` skill for non-trivial work
|
|
15
|
-
|
|
16
|
-
delivery plan → implementation → security verification → QA → deployment → closure.
|
|
19
|
+
Use the `development-workflow` skill for non-trivial work and the `incremental-delivery` skill
|
|
20
|
+
when the plan starts growing faster than the code. For a new project or a major change:
|
|
17
21
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
+
```text
|
|
23
|
+
frame (one page) → walking skeleton → slice loop → verify → release → close
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
If the harness exposes a team lead, use it as the single accountable owner. In OpenCode,
|
|
27
|
+
`team-lead` is the default primary agent and MUST use the `subagent` tool to delegate; it
|
|
28
|
+
must not implement code or run shell commands itself. Its only writable paths are
|
|
29
|
+
`.companion/local/**` and `docs/companion/**`. In other harnesses, invoke the team lead
|
|
30
|
+
explicitly where supported; Pi has no native subagents, so follow the role workflow without
|
|
31
|
+
claiming delegation that did not occur.
|
|
22
32
|
|
|
23
33
|
Profile: `{{profile}}`. Branching: `{{branching}}`.
|
|
24
34
|
|
|
25
35
|
## Non-negotiables
|
|
26
36
|
|
|
27
|
-
1.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
37
|
+
1. **Working software first.** The first commit lands in the first work block. A session that
|
|
38
|
+
produces only documents, when the user asked for implementation, is a process failure.
|
|
39
|
+
2. **One slice at a time, end-to-end.** No horizontal "finish the domain first" plans. WIP limit:
|
|
40
|
+
one slice per writer.
|
|
41
|
+
3. **Planning budget:** the frame is one page and 30–60 minutes; total planning before the first
|
|
42
|
+
end-to-end slice is ≤ 10–15 % of the effort. A document that does not unblock code is deferred.
|
|
43
|
+
4. Every finding and every completion needs evidence: file and snippet, command and output,
|
|
44
|
+
request, CVE, screenshot, or metric.
|
|
45
|
+
5. Never read `.env` values. You may read key names from `.env.example` and check presence
|
|
31
46
|
without printing values.
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
47
|
+
6. Do not commit secrets, local design documents, or `.companion/local/`.
|
|
48
|
+
7. Keep the domain independent from frameworks and infrastructure. Ports and adapters.
|
|
49
|
+
8. UI work requires screenshots at desktop and mobile widths and a vision-capable review.
|
|
50
|
+
9. If a decision is missing, ask; do not invent requirements.
|
|
36
51
|
|
|
37
52
|
## Local documents
|
|
38
53
|
|
|
39
|
-
Design documents, evidence, and reports live in `.
|
|
40
|
-
|
|
54
|
+
Design documents, evidence, and reports live in `{{docsDir}}`. This configured location
|
|
55
|
+
overrides default paths in skills and role examples. They are living notes, not phase gates.
|
|
56
|
+
The project manifest is `.companion/config.json`.
|
|
41
57
|
<!-- development-companion:end -->
|