geneseed 5.0.0 → 5.0.3
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 +70 -0
- package/README.md +1 -1
- package/SHIPPED.md +1 -1
- package/adapters/claude-code/README.md +6 -4
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
- package/adapters/opencode/plugins/geneseed-context.js +13 -2
- package/adapters/opencode/plugins/geneseed-guard.js +595 -74
- package/adapters/opencode/plugins/geneseed-learn.js +1 -1
- package/bin/geneseed-hook.mjs +21 -7
- package/docs/PRD.md +1 -1
- package/docs/concepts/enforcement-table.md +22 -3
- package/docs/concepts/exclusions.md +48 -2
- package/docs/concepts/foreman-mode.md +19 -4
- package/docs/concepts/hook-gates.md +1 -1
- package/docs/concepts/hooks.md +53 -12
- package/docs/concepts/host-matrix.md +4 -3
- package/docs/concepts/hosts.md +1 -1
- package/docs/concepts/kits.md +18 -0
- package/docs/concepts/shared-tier.md +5 -5
- package/docs/concepts/skills.md +1 -1
- package/docs/extending.md +3 -1
- package/docs/guides/autostart.md +27 -3
- package/docs/guides/choose-your-setup.md +1 -1
- package/docs/guides/migrate.md +5 -3
- package/docs/guides/uninstall.md +1 -1
- package/docs/guides/upgrade-to-5.md +6 -4
- package/docs/reference/plugin-context.md +1 -1
- package/docs/reference/plugin-guard.md +24 -5
- package/docs/reference/troubleshoot-doctor.md +2 -2
- package/docs/understand/a-day.md +9 -5
- package/docs/web-ui.md +78 -20
- package/harness.config.json +1 -1
- package/js/README.md +3 -2
- package/js/build/emit-claude.mjs +9 -1
- package/js/build/emit-opencode.mjs +2 -1
- package/js/build/fold.mjs +7 -7
- package/js/build/rule-decide.mjs +273 -0
- package/js/build/source.mjs +9 -3
- package/js/cli-table.json +122 -2
- package/js/hosts/geneseed-dir.mjs +1 -1
- package/js/hosts/hooks-context.mjs +9 -7
- package/js/hosts/hooks-done.mjs +3 -1
- package/js/hosts/hooks-learn.mjs +1 -1
- package/js/hosts/hooks-prims.mjs +270 -0
- package/js/hosts/hooks.mjs +409 -151
- package/js/hosts/hosts.mjs +22 -0
- package/js/hosts/installs.mjs +13 -9
- package/js/hosts/memory-files.mjs +2 -2
- package/js/hosts/settings.mjs +123 -23
- package/js/hosts/shim.mjs +155 -7
- package/js/hosts/store-watch.mjs +41 -14
- package/js/inspect/diff.mjs +2 -1
- package/js/inspect/inventory.mjs +1 -0
- package/js/inspect/registry.mjs +4 -2
- package/js/inspect/validate.mjs +1 -1
- package/js/lib/paths.mjs +13 -0
- package/js/maintain/migrate.mjs +60 -22
- package/js/maintain/uninstall.mjs +5 -1
- package/js/web/actions.mjs +17 -1
- package/js/web/api.mjs +22 -16
- package/js/web/handler.mjs +2 -0
- package/js/web/routes.mjs +9 -4
- package/js/web/update-check.mjs +2 -2
- package/js/web/user-files.mjs +38 -11
- package/package.json +1 -1
- package/registry.json +21 -0
- package/src/AGENT.md.tmpl +17 -21
- package/src/agents/_self-improvement.md +7 -6
- package/src/agents/developer.md +3 -2
- package/src/agents/docker-expert.md +1 -0
- package/src/agents/memory-curator.md +3 -2
- package/src/doctrines/process.md +24 -19
- package/src/kits/ci-pipelines/rules.md +10 -0
- package/src/kits/ci-pipelines.json +14 -0
- package/src/kits/docker/rules.md +11 -0
- package/src/kits/docker.json +12 -0
- package/src/memory/README.md +5 -4
- package/src/modes/foreman.md +23 -10
- package/src/notebook/README.md +1 -1
- package/src/skills/_self-improvement.md +12 -9
- package/src/skills/compose-ops.md +58 -0
- package/src/skills/gitlab-ci.md +51 -0
- package/src/skills/jenkins-pipeline.md +56 -0
- package/src/skills/pipeline.md +2 -2
- package/src/skills/rule/approve.md +11 -5
- package/src/skills/rule.md +26 -19
- package/src/skills/skill-forge.md +24 -6
- package/themes/_TEMPLATE.json +5 -2
- package/themes/biker.json +5 -2
- package/themes/commentator.json +5 -2
- package/themes/cyberpunk.json +5 -2
- package/themes/gamer.json +5 -2
- package/themes/imperial.json +5 -2
- package/themes/joker.json +5 -2
- package/themes/marvin.json +5 -2
- package/themes/mean.json +5 -2
- package/themes/military.json +5 -2
- package/themes/neutral.json +5 -2
- package/themes/pirate.json +5 -2
- package/themes/sports.json +5 -2
- package/themes/verstappen.json +5 -2
- package/themes/wizard.json +5 -2
- package/web/dist/assets/Activity-Ck_Xffpo.js +1 -0
- package/web/dist/assets/ActivityDetail-CBxVS4mU.js +1 -0
- package/web/dist/assets/{Bonsai-B_y20b3i.js → Bonsai-BlOwsvW6.js} +1 -1
- package/web/dist/assets/{CopyButton-CHQte7Ap.js → CopyButton-DFMOIGbe.js} +1 -1
- package/web/dist/assets/Dashboard-BUdUTjbB.js +2 -0
- package/web/dist/assets/{Docs-Dgv_MWfT.js → Docs-D_2Jt6gU.js} +3 -3
- package/web/dist/assets/{GreenhouseView-CSzTMSl_.js → GreenhouseView-WalcX5bp.js} +1 -1
- package/web/dist/assets/Installs-UGiPDMDt.js +3 -0
- package/web/dist/assets/{JournalView-CvRk1-m5.js → JournalView-CZtXQz-v.js} +1 -1
- package/web/dist/assets/Kits-XQHsazCN.js +1 -0
- package/web/dist/assets/Laws-B6A55S-2.js +4 -0
- package/web/dist/assets/Library-D7L0Wdbh.js +3 -0
- package/web/dist/assets/Loops-C0loS73u.js +2 -0
- package/web/dist/assets/{OperatorHudView-DuGz_sTk.js → OperatorHudView-CeDw5qMB.js} +1 -1
- package/web/dist/assets/Personal-PVmGA2-M.js +2 -0
- package/web/dist/assets/{RailCats-AW92uhsX.js → RailCats-BGZnJ6fa.js} +1 -1
- package/web/dist/assets/Settings-DWuxwh4i.js +1 -0
- package/web/dist/assets/Tabs-d2RIRAKT.js +1 -0
- package/web/dist/assets/api-BMFDSXoB.js +1 -0
- package/web/dist/assets/index-BEI5ugYQ.css +1 -0
- package/web/dist/assets/index-BNttaGQb.js +6 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Activity-D8G4eClY.js +0 -1
- package/web/dist/assets/ActivityDetail-BtOBYk3M.js +0 -1
- package/web/dist/assets/Dashboard-B8uXeJZ_.js +0 -2
- package/web/dist/assets/Installs-BDk9lqBI.js +0 -3
- package/web/dist/assets/Kits-CoITzxWM.js +0 -1
- package/web/dist/assets/Laws-Ctf5r9rE.js +0 -3
- package/web/dist/assets/Library-DNwHYVXt.js +0 -3
- package/web/dist/assets/Loops-S85PMQ8m.js +0 -2
- package/web/dist/assets/Personal-afJNwvRS.js +0 -2
- package/web/dist/assets/Settings-CGDFz-6j.js +0 -1
- package/web/dist/assets/Tabs-1qLrnqmn.js +0 -1
- package/web/dist/assets/api-C46vAuqp.js +0 -1
- package/web/dist/assets/index-COTd4TRZ.js +0 -3
- package/web/dist/assets/index-CtorA7uK.css +0 -1
package/js/web/user-files.mjs
CHANGED
|
@@ -10,10 +10,11 @@
|
|
|
10
10
|
import { createHash } from 'node:crypto';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
|
|
13
|
+
import { RETIRED_RULES_FILE, decideItem, decisionState, draftItems, CHOICE_DECISIONS, RULE_DECISIONS } from '../build/rule-decide.mjs';
|
|
13
14
|
import { PROFILE_STUB } from '../build/stubs.mjs';
|
|
14
15
|
import { readMaybe } from '../hosts/installs.mjs';
|
|
15
16
|
import { splitLines } from '../hosts/hooks-prims.mjs';
|
|
16
|
-
import { frontmatter, isRuleEdge,
|
|
17
|
+
import { frontmatter, isRuleEdge, parseRules, readFoldState } from '../hosts/memory-files.mjs';
|
|
17
18
|
import { writeText, isFile, isDir } from '../lib/fs.mjs';
|
|
18
19
|
import { formatRepr, isTruthy } from '../lib/json.mjs';
|
|
19
20
|
import { WHITESPACE, codePointLength, stripWhitespace } from '../lib/text.mjs';
|
|
@@ -64,22 +65,30 @@ const userDir = (state, tier = tierOf(state)) => tier?.root ?? state.target;
|
|
|
64
65
|
const rulesPath = (state, tier) => path.join(userDir(state, tier), RULES_FILE);
|
|
65
66
|
|
|
66
67
|
/**
|
|
67
|
-
* The blocks the fold left in `<tier>/user-rules.draft.md`,
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
* does not parse, still shows. Empty for a project install and for a missing draft.
|
|
68
|
+
* The blocks the fold left in `<tier>/user-rules.draft.md`, in file order (`draftItems`). A block
|
|
69
|
+
* the ledger already holds as decided is left over from a stopped write, so it is not pending; a
|
|
70
|
+
* block with no row, or a ledger that does not parse, still shows. Empty for a project install and
|
|
71
|
+
* for a missing draft. `apiRulesDecide` below decides one.
|
|
72
72
|
*/
|
|
73
73
|
function ruleDrafts(tier) {
|
|
74
74
|
if (tier === null) return [];
|
|
75
75
|
let ledger = {};
|
|
76
76
|
try { ledger = readFoldState(tier).items; } catch { /* shows all */ }
|
|
77
77
|
const decided = ({ key }) => {
|
|
78
|
-
const row = ledger[key];
|
|
78
|
+
const row = Object.hasOwn(ledger, key ?? '') ? ledger[key] : null;
|
|
79
79
|
return row != null && row.state !== 'pending';
|
|
80
80
|
};
|
|
81
|
-
|
|
82
|
-
|
|
81
|
+
// A bad draft is one row on the page, never a failed page: the rules below it still edit.
|
|
82
|
+
try {
|
|
83
|
+
return draftItems(tier).filter((d) => !decided(d));
|
|
84
|
+
} catch (e) {
|
|
85
|
+
return [{ title: 'The draft could not be read', host: null, body: String(e?.message ?? e), decisions: [] }];
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The fingerprint a decision must send back: `''` where there is no tier, or no draft to read. */
|
|
90
|
+
function draftFingerprint(tier) {
|
|
91
|
+
try { return tier === null ? '' : fingerprint(decisionState(tier)); } catch { return ''; }
|
|
83
92
|
}
|
|
84
93
|
|
|
85
94
|
/**
|
|
@@ -95,7 +104,7 @@ export function apiRules(state) {
|
|
|
95
104
|
const drafts = ruleDrafts(tier);
|
|
96
105
|
if (!isFile(p)) {
|
|
97
106
|
return { exists: false, path: p, rules: [], warnings: [], fingerprint: '', shared, drafts,
|
|
98
|
-
stats: { rules: 0, lines: 0, tokens: 0 } };
|
|
107
|
+
draft_fingerprint: draftFingerprint(tier), stats: { rules: 0, lines: 0, tokens: 0 } };
|
|
99
108
|
}
|
|
100
109
|
const text = readMaybe(p) ?? '';
|
|
101
110
|
const [rules, warnings] = parseRules(text);
|
|
@@ -111,6 +120,7 @@ export function apiRules(state) {
|
|
|
111
120
|
tokens: tokensOf(stripWhitespace(lines.slice(r.start, r.end).join('\n'))),
|
|
112
121
|
}));
|
|
113
122
|
return { exists: true, path: p, rules: out, warnings, fingerprint: fingerprint(text), shared, drafts,
|
|
123
|
+
draft_fingerprint: draftFingerprint(tier),
|
|
114
124
|
// The whole file, so it holds its header too: more than the rules' own tokens added up.
|
|
115
125
|
stats: { rules: rules.length, lines: lines.length, tokens: tokensOf(text) } };
|
|
116
126
|
}
|
|
@@ -186,7 +196,6 @@ function ruleId(v) {
|
|
|
186
196
|
* mistake; it exists so a retire never loses the text. Like user-rules.md it is the user's: no
|
|
187
197
|
* install manifest claims it, so no uninstall deletes it.
|
|
188
198
|
*/
|
|
189
|
-
const RETIRED_RULES_FILE = 'user-rules-retired.md';
|
|
190
199
|
const RETIRED_HEADER = '# Retired rules — not in force, never loaded into any session.\n';
|
|
191
200
|
const isBlank = (line) => !stripWhitespace(line);
|
|
192
201
|
|
|
@@ -254,6 +263,24 @@ export function apiRulesMutate(state, body) {
|
|
|
254
263
|
return { ok: true, op, id: rid, fingerprint: fingerprint(next) };
|
|
255
264
|
}
|
|
256
265
|
|
|
266
|
+
/**
|
|
267
|
+
* One decision on a drafted item (`decideItem`). The fingerprint covers the draft, the shared rules
|
|
268
|
+
* and both files of each `Choose` block, so a click on what the page showed never lands on what an
|
|
269
|
+
* agent session or a fold wrote since: `ok: false`, 409, and the page reloads.
|
|
270
|
+
*/
|
|
271
|
+
export function apiRulesDecide(state, body) {
|
|
272
|
+
const decision = bget(body, 'decision');
|
|
273
|
+
if (![...RULE_DECISIONS, ...CHOICE_DECISIONS].includes(decision)) {
|
|
274
|
+
throw new BadRequest(`unknown decision ${formatRepr(decision)}`);
|
|
275
|
+
}
|
|
276
|
+
const tier = tierOf(state);
|
|
277
|
+
if (tier === null) throw new NotFound('shared tier');
|
|
278
|
+
if (!fpMatches(bget(body, 'fingerprint', ''), draftFingerprint(tier))) {
|
|
279
|
+
return { ok: false, error: 'conflict', detail: 'The draft changed since you loaded it.' };
|
|
280
|
+
}
|
|
281
|
+
return decideItem(tier, strOr(bget(body, 'key')), decision);
|
|
282
|
+
}
|
|
283
|
+
|
|
257
284
|
/**
|
|
258
285
|
* One memory fact promoted into a trial rule. The provenance line and the month of
|
|
259
286
|
* probation are the rule this endpoint owns, and both are DATES read from the real clock —
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin`, `exports` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
|
|
3
3
|
"name": "geneseed",
|
|
4
|
-
"version": "5.0.
|
|
4
|
+
"version": "5.0.3",
|
|
5
5
|
"description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"ai",
|
package/registry.json
CHANGED
|
@@ -574,6 +574,27 @@
|
|
|
574
574
|
"owner": "Guillaume Lemer",
|
|
575
575
|
"added": "2026-09-06",
|
|
576
576
|
"last_verified": "2026-10-13"
|
|
577
|
+
},
|
|
578
|
+
"skills/compose-ops": {
|
|
579
|
+
"status": "experimental",
|
|
580
|
+
"version": "1.0.0",
|
|
581
|
+
"owner": "Guillaume Lemer",
|
|
582
|
+
"added": "2026-11-08",
|
|
583
|
+
"last_verified": ""
|
|
584
|
+
},
|
|
585
|
+
"skills/gitlab-ci": {
|
|
586
|
+
"status": "experimental",
|
|
587
|
+
"version": "1.0.0",
|
|
588
|
+
"owner": "Guillaume Lemer",
|
|
589
|
+
"added": "2026-11-08",
|
|
590
|
+
"last_verified": ""
|
|
591
|
+
},
|
|
592
|
+
"skills/jenkins-pipeline": {
|
|
593
|
+
"status": "experimental",
|
|
594
|
+
"version": "1.0.0",
|
|
595
|
+
"owner": "Guillaume Lemer",
|
|
596
|
+
"added": "2026-11-08",
|
|
597
|
+
"last_verified": ""
|
|
577
598
|
}
|
|
578
599
|
}
|
|
579
600
|
}
|
package/src/AGENT.md.tmpl
CHANGED
|
@@ -189,19 +189,16 @@ contract you do not already know.
|
|
|
189
189
|
<!-- CATALOG:end -->
|
|
190
190
|
|
|
191
191
|
**Rule of delegation:** read-only investigation can be dispatched freely; any
|
|
192
|
-
{{AGENT}} that *writes* must return a summary of exactly what it changed.
|
|
193
|
-
{{AGENT}}
|
|
194
|
-
`spec-feedback:` line, weigh it — record a real flaw (with the user's assent) in
|
|
195
|
-
`{{PATH_NOTES}}/agent-notes/<name>.md` and pass it to later dispatches;
|
|
196
|
-
{{MEMORY}} gets a record only when it clears {{DOCTRINE:persist-insight}}'s bar.
|
|
192
|
+
{{AGENT}} that *writes* must return a summary of exactly what it changed. Weigh any
|
|
193
|
+
`spec-feedback:` line an {{AGENT}}'s report carries, as its spec's self-improvement loop says.
|
|
197
194
|
|
|
198
195
|
<!-- LEAN:begin -->
|
|
199
196
|
**Dispatching a multi-part goal.** When a goal spans several capabilities,
|
|
200
197
|
decompose it into independent subtasks, route each to the single owning {{AGENT}}
|
|
201
198
|
above, and converge the results yourself. Every handoff carries an **envelope** —
|
|
202
199
|
the subtask goal, the inputs the {{AGENT}} needs, and its output contract — and the
|
|
203
|
-
constraints travel with it: dispatched {{AGENTS}} never commit
|
|
204
|
-
stays with you), and an unfulfilled contract returns as a stated gap, never invented
|
|
200
|
+
constraints travel with it: dispatched {{AGENTS}} never push, and commit only in their own
|
|
201
|
+
worktree ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented
|
|
205
202
|
content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
|
|
206
203
|
workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
|
|
207
204
|
the same shape model-driven via the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md).
|
|
@@ -212,8 +209,8 @@ Ten of them — `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`,
|
|
|
212
209
|
dispatched alone; the [council {{SKILL}}]({{DIR_SKILLS}}/council.md) convenes the
|
|
213
210
|
subset that productively clashes on a given motion.
|
|
214
211
|
<!-- LEAN:else -->
|
|
215
|
-
Dispatched {{AGENTS}}
|
|
216
|
-
you), and an unfulfilled contract returns as a stated gap, never invented content. A
|
|
212
|
+
Dispatched {{AGENTS}} commit only in their worktree, never push
|
|
213
|
+
({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented content. A
|
|
217
214
|
multi-part goal goes through the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md)
|
|
218
215
|
(or the [workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md) where the host has a workflow tool);
|
|
219
216
|
the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/council.md).
|
|
@@ -311,8 +308,8 @@ the file, or to {{MEMORY}} ({{DOCTRINE:persist-insight}}).
|
|
|
311
308
|
Persistent facts live in {{LINK_MEMORY}} — one fact per file, indexed by a
|
|
312
309
|
local `MEMORY.md`, a session file (**Session start**, above); write a new memory
|
|
313
310
|
whenever the conversation yields a durable fact, a correction, or a decision worth
|
|
314
|
-
keeping —
|
|
315
|
-
|
|
311
|
+
keeping — on your own; the user sees each memory later in the web console. A standing
|
|
312
|
+
rule goes to the user, through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}
|
|
316
313
|
({{DOCTRINE:persist-insight}}). The `{{PATH_MEMORY}}/` directory is **personal and git-ignored** — it is
|
|
317
314
|
never committed or shared; to share knowledge, put it in code, docs, or the
|
|
318
315
|
project's `user-rules.md` (§1). When the same feedback lesson keeps recurring,
|
|
@@ -325,9 +322,9 @@ the session — memory, notebook, notes, commits, docs — cite a rule by its pr
|
|
|
325
322
|
("Verify Before Asserting"), never its number: numbers are positional. Full convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
|
|
326
323
|
<!-- LEAN:else -->
|
|
327
324
|
Durable facts live in {{LINK_MEMORY}}, one per file, indexed by
|
|
328
|
-
`MEMORY.md`, a session file. Write one
|
|
329
|
-
|
|
330
|
-
|
|
325
|
+
`MEMORY.md`, a session file. Write one on your own; the user sees it in the web
|
|
326
|
+
console. A standing rule goes through the
|
|
327
|
+
[rule]({{DIR_SKILLS}}/rule.md) {{SKILL}} ({{DOCTRINE:persist-insight}}). The directory is
|
|
331
328
|
**personal and git-ignored**; shared knowledge goes in code, docs, or `user-rules.md`
|
|
332
329
|
(§1). In anything that outlives the session, cite a rule by its principle ("Verify Before
|
|
333
330
|
Asserting"), never its number — numbers change. Convention, incl. `force`:
|
|
@@ -355,8 +352,8 @@ own benefit — a scratch script, an analysis dump, a draft, an experiment, a
|
|
|
355
352
|
tool you build for yourself — belongs in `{{DIR_NOTEBOOK}}/`, never in the host
|
|
356
353
|
tree. `NOTEBOOK.md`, a session file, recalls what you keep here; keep the space referable across sessions — the seeded index
|
|
357
354
|
is one way; replace it with whatever scheme serves you better. When a note
|
|
358
|
-
hardens into a durable fact worth recalling verbatim,
|
|
359
|
-
|
|
355
|
+
hardens into a durable fact worth recalling verbatim, write it to {{MEMORY}}
|
|
356
|
+
(§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
|
|
360
357
|
format: {{MEMORY}} holds durable insight for future sessions, the {{NOTEBOOK}}
|
|
361
358
|
holds your working artifacts. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
|
|
362
359
|
git-ignored** — never committed or shared, and the `.gitignore` that guarantees
|
|
@@ -365,8 +362,7 @@ it is not yours to lift.
|
|
|
365
362
|
Your own working space, [`{{DIR_NOTEBOOK}}/`]({{DIR_NOTEBOOK}}/): any file you make
|
|
366
363
|
for your own benefit — scratch code, drafts, datasets, experiments — goes here, never
|
|
367
364
|
in the host tree, in whatever format serves; its index `NOTEBOOK.md` is a session
|
|
368
|
-
file. A note that hardens into a durable fact
|
|
369
|
-
the rule {{SKILL}} (§5).
|
|
365
|
+
file. A note that hardens into a durable fact goes to {{MEMORY}} (§5).
|
|
370
366
|
The charter [`{{DIR_NOTEBOOK}}/README.md`]({{DIR_NOTEBOOK}}/README.md) is yours to
|
|
371
367
|
rewrite; the one fixed law is that the folder is **personal and git-ignored**, and
|
|
372
368
|
that `.gitignore` is not yours to lift.
|
|
@@ -385,8 +381,8 @@ configs, documents, prior work. All of it is context you may use.
|
|
|
385
381
|
|
|
386
382
|
After reading this file, take stock of what surrounds it. That non-harness
|
|
387
383
|
content is knowledge to **read and learn from**, not scaffolding to reorganise.
|
|
388
|
-
When you find a durable fact there worth keeping,
|
|
389
|
-
|
|
384
|
+
When you find a durable fact there worth keeping, write it to {{MEMORY}} (§5) so it
|
|
385
|
+
outlives the session.
|
|
390
386
|
|
|
391
387
|
Because the folder is shared, two cautions hold:
|
|
392
388
|
- **You do not own it.** Files you did not create are not yours to move, rename,
|
|
@@ -400,7 +396,7 @@ scratch scripts, analysis dumps, drafts, experiments — are made in the
|
|
|
400
396
|
<!-- LEAN:else -->
|
|
401
397
|
{{INTRO_WORKSPACE}} Whatever sits beside the harness files — notes, data, configs,
|
|
402
398
|
prior work — is knowledge to read and learn from, not scaffolding to reorganise;
|
|
403
|
-
|
|
399
|
+
write a durable fact from it to {{MEMORY}} (§5). You do not own the folder: files
|
|
404
400
|
you did not create are not yours to move or delete unless the task requires it
|
|
405
401
|
({{LAW:deletion-is-deliberate}}), and a file is verified before it is treated as disposable ({{LAW:verify-before-asserting}}).
|
|
406
402
|
It receives only the task's deliverables; your working files go in the {{NOTEBOOK}}
|
|
@@ -2,10 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
If this spec misled you — an input you needed but were not given, a boundary
|
|
4
4
|
that proved wrong, a step you could not execute — end your report with one line:
|
|
5
|
-
`spec-feedback: [agent|general] <the one-line fix> —
|
|
6
|
-
what this spec led you to expect>`. `general` marks a fix other
|
|
7
|
-
Omit the line when there is no friction. The caller weighs the
|
|
8
|
-
|
|
9
|
-
— never into this rendered file, which a rebuild overwrites —
|
|
10
|
-
to every later dispatch of this {{AGENT}}.
|
|
5
|
+
`spec-feedback: [agent|general] <the one-line fix> [— situation: <when it applies>] — seen:
|
|
6
|
+
<what happened, against what this spec led you to expect>`. `general` marks a fix other
|
|
7
|
+
{{AGENTS}} need too. Omit the line when there is no friction. The caller weighs the
|
|
8
|
+
feedback and writes a real flaw, dated, into `{{PATH_NOTES}}/agent-notes/<name>.md` on
|
|
9
|
+
its own, with no prompt — never into this rendered file, which a rebuild overwrites —
|
|
10
|
+
and hands those notes to every later dispatch of this {{AGENT}}. Folding a note into the
|
|
11
|
+
source is the user's call, after the skill-forge {{SKILL}}'s probe. It records the feedback to {{MEMORY}} only if it clears
|
|
11
12
|
{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
|
package/src/agents/developer.md
CHANGED
|
@@ -25,8 +25,9 @@
|
|
|
25
25
|
- **Read + write to the assigned worktree.** May run the project's own build/lint
|
|
26
26
|
commands to self-check before handing off.
|
|
27
27
|
<!-- bash: allow -->
|
|
28
|
-
- Never
|
|
29
|
-
|
|
28
|
+
- Never pushes ({{DOCTRINE:consent-before-push}}). It commits and merges only inside its own
|
|
29
|
+
worktree branch, from sub-workers it started; the parent re-runs the proof and merges
|
|
30
|
+
beyond it once the user accepts.
|
|
30
31
|
|
|
31
32
|
## Procedure
|
|
32
33
|
0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
|
|
@@ -11,6 +11,7 @@ Builds small, safe container images for Spring Boot 4 applications.
|
|
|
11
11
|
|
|
12
12
|
## When NOT to dispatch
|
|
13
13
|
- Cluster manifests — use [kubernetes-specialist](kubernetes-specialist.md). Pipelines — use [devops-engineer](devops-engineer.md).
|
|
14
|
+
- Operating a Compose stack (updates, rollback, limits, logs, networks) — the docker kit's `compose-ops` skill, when that kit is on.
|
|
14
15
|
|
|
15
16
|
## Inputs
|
|
16
17
|
- The build tool (Maven or Gradle), the Java version and any registry or base-image policy.
|
|
@@ -20,8 +20,9 @@
|
|
|
20
20
|
|
|
21
21
|
## Allowed tools
|
|
22
22
|
- **Read + write to the {{MEMORY}} store only.** May run `geneseed memory` and
|
|
23
|
-
`geneseed learn --consolidate`. A write into the store
|
|
24
|
-
|
|
23
|
+
`geneseed learn --consolidate`. A write into the store meets no prompt at the tool boundary
|
|
24
|
+
(memory is written freely), but bulk curation reworks facts the user already keeps, so it still
|
|
25
|
+
shows each topic's plan and applies it with the user's consent.
|
|
25
26
|
<!-- bash: allow -->
|
|
26
27
|
- Moves a fact out with `geneseed memory rm <name>`, which archives it — never a raw
|
|
27
28
|
`mv` or `rm` past that gate. Deletes only with `--purge`, and only what the user
|
package/src/doctrines/process.md
CHANGED
|
@@ -1,18 +1,20 @@
|
|
|
1
1
|
**{{PACK_PROCESS}}** — how a task is run.
|
|
2
2
|
|
|
3
3
|
### {{DOCTRINE:persist-insight}} Persist Insight
|
|
4
|
-
<!-- note: summary: Durable
|
|
4
|
+
<!-- note: summary: Durable insight is recorded before the session ends — memory on your own, a standing rule only with the user. -->
|
|
5
5
|
<!-- LEAN:begin -->
|
|
6
6
|
When a session yields a durable decision, correction, non-obvious discovery, or
|
|
7
|
-
architectural stance, record it before the session ends
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
architectural stance, record it before the session ends. A durable fact goes into
|
|
8
|
+
{{MEMORY}} on your own, with no prompt: the user sees every memory later in the web
|
|
9
|
+
console. A standing rule binds every later session, so it is the user's call: take it to
|
|
10
|
+
them through the rule {{SKILL}}. A memory phrased as an instruction to later sessions
|
|
11
|
+
("always…", "never…", `force: constraint`) is a standing rule.
|
|
11
12
|
<!-- LEAN:else -->
|
|
12
13
|
When a session yields a durable decision, correction, non-obvious discovery, or
|
|
13
|
-
architectural stance, record it before it ends
|
|
14
|
-
|
|
15
|
-
|
|
14
|
+
architectural stance, record it before it ends: a durable fact into {{MEMORY}} on your
|
|
15
|
+
own (the user sees it in the web console); a standing rule, which includes
|
|
16
|
+
any instruction to later sessions ("always…", "never…", `force: constraint`), only through
|
|
17
|
+
the rule {{SKILL}}, with the user's consent.
|
|
16
18
|
<!-- LEAN:end -->
|
|
17
19
|
|
|
18
20
|
### {{DOCTRINE:plan-before-acting}} Plan Before Acting
|
|
@@ -92,9 +94,10 @@ stands for commits on that branch until the session ends or the scope changes; a
|
|
|
92
94
|
new session, a new branch, or a widened scope re-asks. Push earns no such default
|
|
93
95
|
and stays per-ask unless granted in the same named form. A launched loop's batch
|
|
94
96
|
covers commit and push on its own `loop/*` branch; merging that branch into a
|
|
95
|
-
shared one never is.
|
|
96
|
-
|
|
97
|
-
|
|
97
|
+
shared one never is. A Foreman worker's batch covers commit and merge in its own
|
|
98
|
+
worktree, off any shared branch. Before each, present in order (1) a plain-language
|
|
99
|
+
summary of what changed and why and (2) the exact commit message you intend to use,
|
|
100
|
+
then wait. Never push on your own initiative.
|
|
98
101
|
On a **shared branch** — `main`, `master`, `develop`, `development`, a
|
|
99
102
|
`release`/`hotfix` branch, or anything that is not a dedicated feature branch —
|
|
100
103
|
the same gate applies with extra care; when unsure, treat the branch as shared.
|
|
@@ -104,14 +107,16 @@ through the git-history {{SKILL}} behind a backup. The host gates commit and pus
|
|
|
104
107
|
the tool boundary too, so this consent cannot be lost to a sticky allowlist.
|
|
105
108
|
<!-- LEAN:else -->
|
|
106
109
|
Recording and sharing code is consented, never unilateral: **every** `git commit` and
|
|
107
|
-
`git push` needs **explicit acceptance**, every branch, every time
|
|
108
|
-
not standing consent. A named batch ("commit as
|
|
109
|
-
scope changes; push earns no default.
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
110
|
+
`git push` needs **explicit acceptance**, every branch, every time — a personal feature
|
|
111
|
+
branch included; one-time approval is not standing consent. A named batch ("commit as
|
|
112
|
+
you go") stands until the session ends or scope changes; push earns no default. Never
|
|
113
|
+
push on your own initiative. A launched loop's batch covers commit and push on its own
|
|
114
|
+
`loop/*` branch only; merging it never. A Foreman worker's covers commit and merge in its
|
|
115
|
+
own worktree, off any shared branch. Show the plain summary and the exact commit message
|
|
116
|
+
before each, then wait. Shared branches — `main`, `master`, `develop`, `development`,
|
|
117
|
+
`release`/`hotfix`, any unsure — take the same gate. Never force-push, hard-reset, or
|
|
118
|
+
rebase one: undo with a revert commit (git-history {{SKILL}} for a legitimate rewrite).
|
|
119
|
+
The host gates both at the tool boundary.
|
|
115
120
|
<!-- LEAN:end -->
|
|
116
121
|
|
|
117
122
|
### {{DOCTRINE:bound-the-loop}} Bound the Loop
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
### CI pipelines kit
|
|
2
|
+
|
|
3
|
+
Applies to Jenkins pipelines (declarative `Jenkinsfile`, shared libraries) and GitLab CI (`.gitlab-ci.yml` and its includes). Read the pipeline file and everything it loads before changing it.
|
|
4
|
+
|
|
5
|
+
- One source of truth: the pipeline lives in the repository's pipeline file and the libraries or includes it pins. No job configured by hand in the CI's web UI, no second copy of a step in another file.
|
|
6
|
+
- Secrets come only from the CI's own store (Jenkins credentials, GitLab masked and protected variables). Never in the pipeline file, a commit, a parameter default or the build log.
|
|
7
|
+
- Pin images, tools and shared code: image tags or digests, never `latest`; a fixed tool version; a library or include at a tag, never a moving branch.
|
|
8
|
+
- Fast feedback first: lint and unit tests run early and in parallel; slow stages wait on them.
|
|
9
|
+
- GitLab job conditions use `rules:`; Jenkins logic beyond declarative syntax goes into a tested shared-library step.
|
|
10
|
+
- Lint the pipeline before pushing, then prove the change with a real branch run, read from its log.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "CI pipelines on Jenkins (declarative Jenkinsfile, shared libraries) and GitLab CI (.gitlab-ci.yml): job conditions, stage order, reuse, credentials, caching, testing the pipeline itself.",
|
|
3
|
+
"skills": ["jenkins-pipeline", "gitlab-ci"],
|
|
4
|
+
"agents": [],
|
|
5
|
+
"rules": "kits/ci-pipelines/rules.md",
|
|
6
|
+
"rulesWordBudget": 300,
|
|
7
|
+
"banned": ["only:", "except:"],
|
|
8
|
+
"catalogue": {
|
|
9
|
+
"skills": [
|
|
10
|
+
"| [jenkins-pipeline]({{DIR_SKILLS}}/jenkins-pipeline.md) | writing or fixing a declarative Jenkinsfile or a shared library: stages, when, parallel, credentials, CPS and @NonCPS, sandbox approval, JenkinsPipelineUnit tests |",
|
|
11
|
+
"| [gitlab-ci]({{DIR_SKILLS}}/gitlab-ci.md) | writing or fixing .gitlab-ci.yml: rules, needs, include and extends, cache and artifacts, protected and masked variables, environments, CI lint |"
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
### Docker kit
|
|
2
|
+
|
|
3
|
+
Applies to Docker images and Compose stacks. Run `docker compose config` and read the merged result before changing a stack.
|
|
4
|
+
|
|
5
|
+
- Pin every image to a version tag or a digest. Never `latest`, never an untagged image.
|
|
6
|
+
- Order startup by health: `depends_on` with `condition: service_healthy` on a real readiness check.
|
|
7
|
+
- State lives in named volumes. Never run `docker compose down -v` or prune volumes on a stack with data without a backup and an explicit go-ahead.
|
|
8
|
+
- No secret in an image layer, a build argument, the Compose file or a committed `.env`; use Compose `secrets:` or the runtime environment from a git-ignored file.
|
|
9
|
+
- Images run as a non-root user, built multi-stage, with a `.dockerignore`.
|
|
10
|
+
- Every long-running service has a restart policy, resource limits and capped logs.
|
|
11
|
+
- Before an update, know the rollback target (the previous tag or digest); confirm the new container is healthy before pruning the old image.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "Docker and Compose operations for any stack: health-ordered startup, volumes, pinned images, env and secrets, restart, limits, logging, networks, lean non-root images, safe updates and rollback.",
|
|
3
|
+
"skills": ["compose-ops"],
|
|
4
|
+
"agents": [],
|
|
5
|
+
"rules": "kits/docker/rules.md",
|
|
6
|
+
"rulesWordBudget": 300,
|
|
7
|
+
"catalogue": {
|
|
8
|
+
"skills": [
|
|
9
|
+
"| [compose-ops]({{DIR_SKILLS}}/compose-ops.md) | writing, reviewing or operating a Compose stack or a generic Dockerfile: healthchecks, volumes, image pins, secrets, limits, logs, networks, safe update and rollback |"
|
|
10
|
+
]
|
|
11
|
+
}
|
|
12
|
+
}
|
package/src/memory/README.md
CHANGED
|
@@ -8,10 +8,11 @@
|
|
|
8
8
|
|
|
9
9
|
Durable knowledge that must survive across sessions lives here as **one fact per
|
|
10
10
|
file**. An agent reads `MEMORY.md` (the local index map) at the start of a session,
|
|
11
|
-
and opens the topic file a task needs (see *The index* below).
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
11
|
+
and opens the topic file a task needs (see *The index* below). The agent writes a new fact
|
|
12
|
+
here on its own, with no prompt, following Branch A of the rule {{SKILL}}; the user sees every
|
|
13
|
+
memory afterwards in the web console ({{DOCTRINE:persist-insight}}). A standing rule is different:
|
|
14
|
+
it goes to the user first, through the same {{SKILL}}. The `learn` hook writes here too, where the
|
|
15
|
+
host runs it: a distiller the user opted into at install.
|
|
15
16
|
|
|
16
17
|
This store is for **curated facts**, written for recall. For freeform working space
|
|
17
18
|
the agent shapes for itself — plans, scratch designs, working theories, with no
|
package/src/modes/foreman.md
CHANGED
|
@@ -15,12 +15,24 @@ task that would block it to one background task worker, and keeps answering the
|
|
|
15
15
|
and the brief carries the approved decisions.
|
|
16
16
|
- **One worker per task.** Dispatch one developer {{AGENT}} in the background, in its own
|
|
17
17
|
worktree. The brief carries the task as the user stated it, BASE, the write set, the
|
|
18
|
-
proof commands, and the rule that it never
|
|
19
|
-
explores, implements and tests in its own context, loading {{SKILLS}}
|
|
20
|
-
after two repair rounds on its own red tests it returns red with its
|
|
21
|
-
({{DOCTRINE:bound-the-loop}}).
|
|
22
|
-
when its own context would overflow. Check its write set against every task in flight
|
|
18
|
+
proof commands, and the rule that it never pushes and never merges outside its own
|
|
19
|
+
branch. The worker explores, implements and tests in its own context, loading {{SKILLS}}
|
|
20
|
+
as it needs them; after two repair rounds on its own red tests it returns red with its
|
|
21
|
+
findings ({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
|
|
23
22
|
({{DOCTRINE:one-writer-per-file}}).
|
|
23
|
+
- **A worker may lead, inside its worktree.** It may dispatch read-only helpers (explorer,
|
|
24
|
+
researcher) at any time, and writing sub-workers, each in its own worktree branched from
|
|
25
|
+
its branch. It may commit and merge their branches into its own, locally, and re-runs the
|
|
26
|
+
proof after each merge. Depth stops at main → worker → sub-worker: a sub-worker
|
|
27
|
+
dispatches nothing. Every lead holds every member's result before it ends. The blind
|
|
28
|
+
reviewer stays the parent's.
|
|
29
|
+
- **Status, one line per change.** A worker reports
|
|
30
|
+
`T<n> · <task> · files: <write set> · <state>` at start and on each change: by
|
|
31
|
+
`SendMessage` to the parent on Claude Code (on OpenClaude only in its agent-teams mode);
|
|
32
|
+
elsewhere in its own `{{DIR_NOTEBOOK}}/foreman/<task>.status`, one line it alone writes.
|
|
33
|
+
Read all status files with one command, only before dispatching near the same files and
|
|
34
|
+
when a worker returns, never every turn. On an overlap, one waits or one owns the file;
|
|
35
|
+
record the ruling in the ledger.
|
|
24
36
|
- **Verify non-trivial diffs blind.** When a worker returns green with a diff that touches
|
|
25
37
|
two or more files or changes logic, dispatch a reviewer (a tester for test-heavy work)
|
|
26
38
|
with only the original ask and the diff, never the worker's reasoning. A failing verdict
|
|
@@ -36,11 +48,12 @@ task that would block it to one background task worker, and keeps answering the
|
|
|
36
48
|
worker serves one task and retires when that task is merged or dropped.
|
|
37
49
|
- **Isolate.** Each worker works in its own git worktree/branch; falls back to a single
|
|
38
50
|
tree, one worker at a time, when worktrees are unavailable.
|
|
39
|
-
- **Merge on proof you re-ran.** A worker hands back its
|
|
40
|
-
test + lint output. The parent re-runs those commands itself —
|
|
41
|
-
worker's account, not the state — shows the user the diff
|
|
42
|
-
commits and merges only once the user accepts
|
|
43
|
-
push and merge
|
|
51
|
+
- **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
|
|
52
|
+
uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
|
|
53
|
+
a worker's log is the worker's account, not the state — shows the user the diff from BASE
|
|
54
|
+
and the green output, and commits and merges only once the user accepts
|
|
55
|
+
({{DOCTRINE:consent-before-push}}). Push, and every merge beyond a worker's own branch,
|
|
56
|
+
stay the parent's alone.
|
|
44
57
|
- **Report and watch.** Surface completions, failures, and merges to the user as they
|
|
45
58
|
happen; a worker that returns no proof, or goes silent, is handled as the pipeline
|
|
46
59
|
{{SKILL}}'s step 2 says for a crew.
|
package/src/notebook/README.md
CHANGED
|
@@ -32,7 +32,7 @@ will, in whatever structure serves you.
|
|
|
32
32
|
the host tree. The host tree receives only the
|
|
33
33
|
deliverables of the task.
|
|
34
34
|
- **Promote what hardens.** When something here crystallises into a durable
|
|
35
|
-
fact worth recalling verbatim,
|
|
35
|
+
fact worth recalling verbatim, write it to {{MEMORY}}
|
|
36
36
|
({{DOCTRINE:persist-insight}}).
|
|
37
37
|
- **It is not the repo's.** Do not keep here what the repository already
|
|
38
38
|
records (code, git history, the {{LAWS}}, `user-rules.md`). Keep what is
|
|
@@ -9,12 +9,14 @@ write, and no rebuild touches them.
|
|
|
9
9
|
Close each run with one beat of reflection on the {{SKILL}} itself:
|
|
10
10
|
- A step misled, a needed step was missing, or the trigger fired wrongly — that
|
|
11
11
|
is a flaw in this file. Write the exact correction (trigger, procedure, or
|
|
12
|
-
done-when) into the notes file, with
|
|
13
|
-
`- [skill|general] <correction> — seen: <what happened, against what you expected> (<date>)`.
|
|
14
|
-
`
|
|
15
|
-
that would fix other {{SKILLS}} too. Never
|
|
12
|
+
done-when) into the notes file on your own, with no prompt, as one line:
|
|
13
|
+
`- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what you expected> (<date>)`.
|
|
14
|
+
`situation:` bounds where the correction holds; `seen:` is the evidence it is
|
|
15
|
+
later judged by; `general` marks one that would fix other {{SKILLS}} too. Never
|
|
16
16
|
edit this file: it is a rendered copy, a rebuild overwrites it, and the doctor
|
|
17
|
-
reports the edit as drift. `geneseed diff` carries the notes back to the source
|
|
17
|
+
reports the edit as drift. `geneseed diff` carries the notes back to the source;
|
|
18
|
+
folding a note into the source is the user's call, through the skill-forge
|
|
19
|
+
{{SKILL}} ({{LAW:one-intent-one-act}}).
|
|
18
20
|
- Keep the notes sharp: amend or delete a line before adding one — a line with no
|
|
19
21
|
`seen:`, or whose `seen:` no longer happens, goes first — and prune past about
|
|
20
22
|
twenty lines.
|
|
@@ -26,10 +28,11 @@ Close each run with one beat of reflection on the {{SKILL}} itself:
|
|
|
26
28
|
runs end here.
|
|
27
29
|
<!-- LEAN:else -->
|
|
28
30
|
One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
|
|
29
|
-
wrong trigger is a flaw in this file — write the exact correction, with
|
|
30
|
-
|
|
31
|
-
name) as `- [skill|general] <correction> — seen: <what happened vs expected> (<date>)`,
|
|
32
|
-
never into this rendered file, which a rebuild overwrites.
|
|
31
|
+
wrong trigger is a flaw in this file — write the exact correction on your own, with no
|
|
32
|
+
prompt, into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
|
|
33
|
+
name) as `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened vs expected> (<date>)`,
|
|
34
|
+
never into this rendered file, which a rebuild overwrites. Folding a note into the
|
|
35
|
+
source is the user's call ({{LAW:one-intent-one-act}}). Read that notes
|
|
33
36
|
file before the first step when it exists; it wins where it disagrees. Keep it short.
|
|
34
37
|
A lesson that is not about this file goes to {{MEMORY}} only if it clears
|
|
35
38
|
{{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# {{SKILL}}: compose-ops
|
|
2
|
+
|
|
3
|
+
> {{DESC_COMPOSE_OPS}}
|
|
4
|
+
|
|
5
|
+
{{CREDIT:everything-claude-code:skills/docker-patterns/SKILL.md}}
|
|
6
|
+
|
|
7
|
+
**Trigger:** writing, reviewing or operating a `compose.yaml` (or `docker-compose.yml`) stack, or a generic Dockerfile for it: startup order, health, volumes, image pins, env and secrets, restart, limits, logs, networks, image size and user, or an update that must be safe to roll back. Stack-agnostic. A Spring Boot service's own image (Buildpacks, layered or native jar) belongs to the spring-boot kit's `docker-expert` agent when that kit is on, and so does that service's local-dev Compose file; this skill owns how every other stack is composed and run.
|
|
8
|
+
|
|
9
|
+
## Working loop
|
|
10
|
+
1. Read the Compose file, every `-f` override and `.env` it uses, then the merged result: `docker compose config`. It resolves variables, merges overrides and fails on a bad key.
|
|
11
|
+
2. Check what runs now before changing it: `docker compose ps`, `docker compose images` (the real tags and digests), `docker compose logs --tail=100 <svc>`.
|
|
12
|
+
3. Change, `docker compose config` again, then apply and confirm each changed service is `healthy` (or, for a service with no healthcheck, `running` with clean logs).
|
|
13
|
+
|
|
14
|
+
## Startup order and health
|
|
15
|
+
- `depends_on: { db: { condition: service_healthy } }` waits for the dependency's healthcheck. A bare `depends_on: [db]` waits only for the container to start, not for the database to accept connections.
|
|
16
|
+
- Give every service others depend on a `healthcheck:` that tests readiness: `test: ["CMD", "pg_isready", "-U", "app"]`, with `interval`, `timeout`, `retries` and a `start_period` long enough for a cold start. The command must exist in the image; a missing `curl` makes the check fail forever.
|
|
17
|
+
- `condition: service_completed_successfully` for a one-shot job (a migration) that must finish first.
|
|
18
|
+
|
|
19
|
+
## Volumes
|
|
20
|
+
| Use | Mount |
|
|
21
|
+
|---|---|
|
|
22
|
+
| Data the service owns (database, uploads) | named volume: `pgdata:/var/lib/postgresql/data`, declared under top-level `volumes:` |
|
|
23
|
+
| Config or source you edit on the host | bind mount, read-only where possible: `./nginx.conf:/etc/nginx/nginx.conf:ro` |
|
|
24
|
+
| Scratch that must not persist | `tmpfs:` |
|
|
25
|
+
|
|
26
|
+
- A named volume survives `down` and keeps Docker-managed permissions; a bind mount takes the host path's owner and breaks a non-root container whose UID does not match.
|
|
27
|
+
- `docker compose down -v` deletes named volumes, which is data loss. Never run it on a stack with state unless deleting the data is the intent and a backup exists.
|
|
28
|
+
- An anonymous volume (a container path with no name) carries over when `up` recreates the container, but is orphaned after `down` then `up`, or with `up -V` (`--renew-anon-volumes`), and its data is no longer mounted; name it.
|
|
29
|
+
|
|
30
|
+
## Images
|
|
31
|
+
- Pin every `image:` to a version tag (`postgres:16.4`), and to a digest (`postgres:16.4@sha256:...`) where the stack must reproduce exactly. Never `latest` and never no tag: an update must be a change in the file.
|
|
32
|
+
- Your own images: multi-stage builds, so the final stage carries only the runtime and the built output, not compilers or dev dependencies. Start from a slim or distroless base, and add a `.dockerignore` (`.git`, `node_modules`, build output, `.env`).
|
|
33
|
+
- Run as a non-root user: `USER app` in the Dockerfile, or `user: "1000:1000"` in Compose. Add `read_only: true` with a `tmpfs:` for write paths, `cap_drop: [ALL]` and `security_opt: ["no-new-privileges:true"]` where the service allows.
|
|
34
|
+
|
|
35
|
+
## Env and secrets
|
|
36
|
+
- `.env` holds non-secret settings and the values the file interpolates (`${TAG:?set TAG}` fails loudly when unset). It is git-ignored; commit a `.env.example` with placeholders instead.
|
|
37
|
+
- Secrets go in `secrets:` (a file outside the repository, mounted at `/run/secrets/<name>`), read by images that support `*_FILE` variables (`POSTGRES_PASSWORD_FILE`). An `environment:` secret shows in `docker inspect` and in every child process.
|
|
38
|
+
- Never bake a secret into an image: `ARG`/`ENV` values stay in the layer history. Use `RUN --mount=type=secret,id=...` for a build-time secret.
|
|
39
|
+
|
|
40
|
+
## Running: restart, limits, logs
|
|
41
|
+
- `restart: unless-stopped` for long-running services; `restart: "no"` for one-shot jobs. A service that crash-loops hides its error behind restarts: read `docker compose logs` before raising retries.
|
|
42
|
+
- Set limits so one service cannot starve the host: `deploy: { resources: { limits: { cpus: "1.0", memory: 512M } } }`, or `mem_limit:` on older engines. A JVM or Node process also needs its heap capped below the limit.
|
|
43
|
+
- Cap logs: `logging: { driver: json-file, options: { max-size: "10m", max-file: "3" } }` (or `local`). The default json-file driver grows until the disk is full.
|
|
44
|
+
|
|
45
|
+
## Networks
|
|
46
|
+
- Services reach each other by service name on the stack's default network; never hard-code container IPs.
|
|
47
|
+
- Split networks by trust: a `frontend` network for the proxy and the app, a `backend` network with `internal: true` for the database, which then has no route out and no published port.
|
|
48
|
+
- Publish only the ports users reach, bound to an address where possible: `"127.0.0.1:5432:5432"` for a local-only database. A published port bypasses host firewall rules on most Linux setups.
|
|
49
|
+
|
|
50
|
+
## Safe updates
|
|
51
|
+
1. Record the current state: the running image digests (`docker compose images`) and the committed Compose file. Back up the named volumes of a stateful service before an update that may migrate its data.
|
|
52
|
+
2. Change the pinned tag in the file, then `docker compose pull <svc>`.
|
|
53
|
+
3. `docker compose up -d <svc>` recreates only the services whose image or configuration changed. Add `--wait` (with `--wait-timeout <seconds>`) to block until they are running or healthy; `--wait` only proves health for a service that has a healthcheck, so give one to every service you update.
|
|
54
|
+
4. Check health and logs. Roll back by restoring the previous tag or digest and running `up -d` again; a data migration the new version ran may not roll back, which is why step 1 takes the backup.
|
|
55
|
+
5. Prune old images only after the new version has proved itself: `docker image prune -a` deletes every image no container uses, the rollback target included (plain `docker image prune` removes only dangling images).
|
|
56
|
+
|
|
57
|
+
## Done when
|
|
58
|
+
- `docker compose config` accepts the merged file, every changed service with a healthcheck reports `healthy` and the others are `running` with clean logs, images are pinned, no secret sits in the file, an image or `environment:`, and the rollback target (the previous tag or digest, and a backup for stateful data) is known.
|