geneseed 5.2.0 → 5.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/CHANGELOG.md +27 -0
- package/README.md +2 -2
- package/SHIPPED.md +1 -1
- package/adapters/opencode/plugins/geneseed-context.js +56 -10
- package/adapters/opencode/plugins/geneseed-guard.js +6 -1
- package/bin/geneseed-cli.mjs +61 -16
- package/bin/geneseed-hook.mjs +37 -3
- package/docs/concepts/factories.md +40 -6
- package/docs/concepts/footprint.md +1 -1
- package/docs/concepts/foreman-mode.md +2 -2
- package/docs/concepts/loop-gates.md +1 -1
- package/docs/concepts/loops.md +2 -2
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/design-history.md +140 -0
- package/docs/extending.md +54 -162
- package/docs/guides/run-a-factory.md +15 -2
- package/docs/guides/upgrade.md +2 -2
- package/docs/reference/factory-actions.md +6 -5
- package/docs/reference/troubleshoot-update.md +1 -1
- package/docs/web-ui.md +16 -3
- package/harness.config.json +1 -1
- package/js/README.md +4 -3
- package/js/build/args.mjs +3 -3
- package/js/build/render.mjs +44 -24
- package/js/cli-table.json +135 -59
- package/js/factory/cli.mjs +24 -5
- package/js/factory/graph.mjs +13 -9
- package/js/factory/metrics.mjs +93 -0
- package/js/factory/registry.mjs +37 -12
- package/js/factory/state.mjs +25 -6
- package/js/hosts/hooks-context.mjs +26 -1
- package/js/hosts/hooks-prims.mjs +52 -3
- package/js/hosts/hooks.mjs +50 -29
- package/js/hosts/loss.mjs +6 -1
- package/js/inspect/diff.mjs +16 -1
- package/js/inspect/doctor.mjs +7 -3
- package/js/inspect/excludes.mjs +18 -6
- package/js/inspect/status.mjs +35 -7
- package/js/inspect/validate.mjs +44 -21
- package/js/maintain/uninstall.mjs +28 -1
- package/js/maintain/update.mjs +31 -7
- package/js/ui/cli.mjs +34 -4
- package/js/ui/menu.mjs +1 -1
- package/js/ui/tui.mjs +11 -14
- package/js/web/actions.mjs +2 -0
- package/js/web/api.mjs +28 -10
- package/js/web/daemon.mjs +0 -1
- package/js/web/server.mjs +1 -0
- package/js/web/state.mjs +37 -16
- package/package.json +1 -1
- package/src/AGENT.md.tmpl +23 -17
- package/src/agents/_template.md +1 -1
- package/src/agents/advocate.md +1 -1
- package/src/agents/developer.md +12 -3
- package/src/agents/empiricist.md +1 -1
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/operator.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- package/src/bricks/intake.md +10 -3
- package/src/bricks/retro.md +13 -3
- package/src/doctrines/comms.md +1 -1
- package/src/doctrines/ops.md +1 -1
- package/src/doctrines/process.md +7 -5
- package/src/factories/analysis-to-build.json +1 -0
- package/src/factories/bug-report-to-fix.json +1 -0
- package/src/factories/issue-to-pr.json +1 -0
- package/src/laws/universal.md +2 -2
- package/src/modes/foreman.md +8 -14
- package/src/skills/commit.md +7 -2
- package/src/skills/debug.md +1 -1
- package/src/skills/diagram-design/SKILL.md +1 -1
- package/src/skills/diagram-design/VENDOR.md +3 -1
- package/src/skills/factory-forge.md +5 -3
- package/src/skills/factory.md +22 -1
- package/src/skills/geneseed.md +1 -1
- package/src/skills/handoff.md +1 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/pipeline.md +6 -6
- package/src/skills/plan.md +7 -3
- package/src/skills/spring-testing.md +1 -1
- package/themes/biker.json +78 -78
- package/themes/commentator.json +81 -81
- package/themes/cyberpunk.json +79 -79
- package/themes/gamer.json +77 -77
- package/themes/imperial.json +82 -82
- package/themes/joker.json +79 -79
- package/themes/marvin.json +82 -82
- package/themes/mean.json +82 -82
- package/themes/military.json +78 -78
- package/themes/neutral.json +78 -78
- package/themes/pirate.json +79 -79
- package/themes/sports.json +79 -79
- package/themes/verstappen.json +78 -78
- package/themes/wizard.json +79 -79
- package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
- package/web/dist/assets/Activity-CqJiquEq.js +1 -0
- package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
- package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-Bfpb6W-1.js} +1 -1
- package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-ByIntFtB.js} +1 -1
- package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
- package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
- package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
- package/web/dist/assets/{GreenhouseView-y9WAfcc_.js → GreenhouseView-GpBsYn50.js} +1 -1
- package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
- package/web/dist/assets/{JournalView-DeBLRNGc.js → JournalView-iLuLrOxE.js} +1 -1
- package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
- package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
- package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
- package/web/dist/assets/Library-B4K-1iNF.js +3 -0
- package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
- package/web/dist/assets/{OperatorHudView-2ujVMjq1.js → OperatorHudView-BAXwCEvY.js} +1 -1
- package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
- package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
- package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
- package/web/dist/assets/index-CsAZq0BQ.css +1 -0
- package/web/dist/assets/index-How7SzDZ.js +6 -0
- package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
- package/web/dist/index.html +2 -2
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
- package/web/dist/assets/Activity-DlQ30znB.js +0 -1
- package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
- package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
- package/web/dist/assets/Docs-CisVnYqv.js +0 -5
- package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
- package/web/dist/assets/Installs-m4GElwFW.js +0 -3
- package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
- package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
- package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
- package/web/dist/assets/Library-Dg0ScciC.js +0 -3
- package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
- package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
- package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
- package/web/dist/assets/Tabs-But5R6_r.js +0 -1
- package/web/dist/assets/index-Ck42AbRX.js +0 -6
- package/web/dist/assets/index-PG_ukkh6.css +0 -1
- package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
package/js/web/state.mjs
CHANGED
|
@@ -95,7 +95,7 @@ export function stampMinute(ms) {
|
|
|
95
95
|
* THE CACHING IS BEHAVIOUR, NOT AN OPTIMISATION: `doctorCollect` renders a theme per call
|
|
96
96
|
* and the console GETs `/api/overview` on mount and again after every mutation, so an
|
|
97
97
|
* uncached `doctor` would put a full build on each of those requests. `refresh()` is what a mutation calls to
|
|
98
|
-
* drop both — except where the mutation cannot change anything the doctor reads (the checkout,
|
|
98
|
+
* drop both (a serving daemon then re-runs the doctor on its thread at once, `warmDoctor`) — except where the mutation cannot change anything the doctor reads (the checkout,
|
|
99
99
|
* the hook shim, the hook shell, the OpenCode config dirs, the deployed install): a memory
|
|
100
100
|
* delete passes `{ doctor: false }` and keeps the ~3.6 s verdict. Rule and profile writes do not
|
|
101
101
|
* call `refresh()` at all. Every other caller keeps the default, so a new one is slow, never stale.
|
|
@@ -124,6 +124,8 @@ export function webState(theme = null, target = null) {
|
|
|
124
124
|
_doctorRun: null,
|
|
125
125
|
// The warm-up run still in flight, a promise settled when its thread ends (`warmDoctor`).
|
|
126
126
|
_doctorJob: null,
|
|
127
|
+
// The thread of the latest warm-up, so the next one can stop it once a refresh dropped its job.
|
|
128
|
+
_doctorWorker: null,
|
|
127
129
|
// `diffCollect`'s memo of `expected` renders, made on first use by `api.mjs` (`memoOf`);
|
|
128
130
|
// it re-renders on its own key change, so `refresh()` leaves it alone.
|
|
129
131
|
renderMemo: null,
|
|
@@ -139,6 +141,10 @@ export function webState(theme = null, target = null) {
|
|
|
139
141
|
// The per-install views made off this daemon's state, keyed `[host, root]` — see
|
|
140
142
|
// `installView`. Kept here, not at module level, so each handler (each test's) has its own.
|
|
141
143
|
_views: new Map(),
|
|
144
|
+
// Set by `serve()` once it listens: from then on no request runs the doctor on the event loop.
|
|
145
|
+
// A cold cache starts `warmDoctor` and reads as pending; tests and one-shot reads keep the
|
|
146
|
+
// inline run, which answers at once.
|
|
147
|
+
warm: false,
|
|
142
148
|
};
|
|
143
149
|
// The INSTALL ROOT (== build --out). For globals it IS the data dir; a claude/bob/openclaude
|
|
144
150
|
// PROJECT install keeps its data under <repo>/.claude|.bob|.openclaude while the markers
|
|
@@ -172,7 +178,8 @@ export function webState(theme = null, target = null) {
|
|
|
172
178
|
// NULL WHILE THE WARM-UP RUNS, and only then: a pending verdict, which the console draws as
|
|
173
179
|
// "checking" and asks again for. Blocking here would put the run back on the event loop.
|
|
174
180
|
get() {
|
|
175
|
-
|
|
181
|
+
// A worker that cannot start (`warmDoctor` returns null) falls back to the inline run.
|
|
182
|
+
if (st._doctor === null && st._doctorJob === null && !(st.warm && warmDoctor(st))) st.runDoctor();
|
|
176
183
|
return st._doctor;
|
|
177
184
|
},
|
|
178
185
|
});
|
|
@@ -260,6 +267,9 @@ export function webState(theme = null, target = null) {
|
|
|
260
267
|
st.refresh = (opts = {}) => {
|
|
261
268
|
st.refreshOwn(opts);
|
|
262
269
|
for (const v of st._views.values()) v.refreshOwn(opts);
|
|
270
|
+
// Every job ends here, and the console asks the overview right after: start the new verdict
|
|
271
|
+
// now, on its thread, rather than inside that request (~12 s of a frozen console).
|
|
272
|
+
if (st.warm && opts.doctor !== false) warmDoctor(st);
|
|
263
273
|
};
|
|
264
274
|
return st;
|
|
265
275
|
}
|
|
@@ -268,43 +278,54 @@ export function webState(theme = null, target = null) {
|
|
|
268
278
|
const WARM_DOCTOR_LIMIT_MS = 180_000;
|
|
269
279
|
|
|
270
280
|
/**
|
|
271
|
-
* Run the doctor
|
|
272
|
-
*
|
|
273
|
-
*
|
|
281
|
+
* Run the doctor ON ITS OWN THREAD: right after the server binds, and on a serving daemon
|
|
282
|
+
* (`st.warm`) after every refresh, on a cold cache and for `/api/doctor?fresh=1`. On the event loop
|
|
283
|
+
* this run held every request of a cold daemon for 13-24 s, past `BootSplash`'s stall at 8 s, and
|
|
284
|
+
* froze the console ~12 s after every job. Until it lands `st.doctor` is null and `/api/doctor`
|
|
285
|
+
* waits on the promise this returns. A new run stops the thread of the one it replaces: its
|
|
286
|
+
* verdict would be dropped anyway, and a burst of writes must not stack CPU-bound threads.
|
|
274
287
|
*
|
|
275
288
|
* A verdict is stamped only while its job is still the current one: `refresh`, `selectView` and a
|
|
276
289
|
* newer run all clear `_doctorJob`, and the daemon must not serve what a mutation made stale. A
|
|
277
|
-
*
|
|
278
|
-
*
|
|
279
|
-
*
|
|
290
|
+
* thread that dies (an `error`, or an exit with no verdict) is stamped as a FAILED verdict too:
|
|
291
|
+
* left cold, a serving daemon's getter would start a new thread on every overview poll and read
|
|
292
|
+
* "checking" for good. The `error` listener is not optional, an unheard worker error is uncaught
|
|
293
|
+
* and kills the daemon. `unref`: a stopping daemon does not wait for it. `script` is the worker's
|
|
294
|
+
* module, for a test that needs a thread that dies.
|
|
280
295
|
*
|
|
281
296
|
* A HUNG run would leave `/api/doctor` unanswered and the console polling for good, so past
|
|
282
297
|
* `limitMs` it is stopped and stamped as a FAILED verdict: unknown is never a green. Re-run clears it.
|
|
283
298
|
*/
|
|
284
|
-
export function warmDoctor(st, limitMs = WARM_DOCTOR_LIMIT_MS
|
|
299
|
+
export function warmDoctor(st, limitMs = WARM_DOCTOR_LIMIT_MS,
|
|
300
|
+
script = new URL('./doctor-worker.mjs', import.meta.url)) {
|
|
285
301
|
if (st._doctor !== null || st._doctorJob !== null) return st._doctorJob;
|
|
302
|
+
st._doctorWorker?.terminate();
|
|
303
|
+
st._doctorWorker = null;
|
|
286
304
|
let worker;
|
|
287
305
|
try {
|
|
288
|
-
worker = new Worker(
|
|
289
|
-
{ workerData: { theme: st.theme } });
|
|
306
|
+
worker = new Worker(script, { workerData: { theme: st.theme } });
|
|
290
307
|
} catch { return null; }
|
|
291
308
|
worker.unref();
|
|
309
|
+
st._doctorWorker = worker;
|
|
292
310
|
const job = new Promise((done) => {
|
|
293
|
-
const
|
|
311
|
+
const failed = (said) => {
|
|
294
312
|
if (st._doctorJob === job) {
|
|
295
|
-
const said = `[doctor] the warm-up run did not finish in ${limitMs / 1000} s, so nothing was checked`;
|
|
296
313
|
st.stampDoctor([said], [], [{ check: 'warm_up', label: 'Warm-up run', problems: [said] }]);
|
|
297
314
|
}
|
|
315
|
+
};
|
|
316
|
+
const limit = setTimeout(() => {
|
|
317
|
+
failed(`[doctor] the warm-up run did not finish in ${limitMs / 1000} s, so nothing was checked`);
|
|
298
318
|
worker.terminate();
|
|
299
319
|
}, limitMs);
|
|
300
320
|
limit.unref();
|
|
301
321
|
worker.once('message', (r) => {
|
|
302
322
|
if (st._doctorJob === job) st.stampDoctor(r.problems, r.themes, r.groups);
|
|
303
323
|
});
|
|
304
|
-
worker.once('error', () =>
|
|
305
|
-
worker.once('exit', () => {
|
|
324
|
+
worker.once('error', (e) => failed(`[doctor] the warm-up run failed: ${e?.message ?? e}`));
|
|
325
|
+
worker.once('exit', (code) => {
|
|
306
326
|
clearTimeout(limit);
|
|
307
|
-
|
|
327
|
+
failed(`[doctor] the warm-up run ended (code ${code}) without a verdict, so nothing was checked`);
|
|
328
|
+
if (st._doctorWorker === worker) st._doctorWorker = null;
|
|
308
329
|
done();
|
|
309
330
|
});
|
|
310
331
|
});
|
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.
|
|
4
|
+
"version": "5.3.0",
|
|
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/src/AGENT.md.tmpl
CHANGED
|
@@ -44,14 +44,13 @@ it as your very first tool call — before loading context, reading files, or se
|
|
|
44
44
|
**Session start.** The harness hook injects your session files (any still at its seed is
|
|
45
45
|
skipped) and the `eager` entries of `context.json`. If no `=== SESSION FILES ===` or
|
|
46
46
|
`=== PROJECT CONTEXT ===` block is in your context, read them yourself first:
|
|
47
|
-
`{{PATH_RULES}}`, `{{PATH_PROFILE}}`, `{{PATH_MEMORY}}/MEMORY.md`,
|
|
48
|
-
`{{DIR_NOTEBOOK}}/NOTEBOOK.md`, `{{PATH_WIKI}}`, `{{AT_HARNESS}}context.json`.
|
|
47
|
+
`{{PATH_RULES}}`, `{{PATH_PROFILE}}`, `{{PATH_MEMORY}}/MEMORY.md`, then §6's index, §8's wiki file, `{{AT_HARNESS}}context.json`.
|
|
49
48
|
|
|
50
49
|
**Response voice.** {{VOICE}} This sets *tone and vocabulary* — the section *layout*,
|
|
51
50
|
the law *numbers*, file paths, and folder names stay plain English so tooling and links
|
|
52
51
|
never move.
|
|
53
52
|
|
|
54
|
-
**Precedence.** Stated once, here; nothing below restates it.
|
|
53
|
+
**Precedence.** Stated once, here; nothing below restates it. A {{SKILL}} carries procedure, not rank: it never loosens a {{DOCTRINE}} or the mode.
|
|
55
54
|
|
|
56
55
|
| Rank | Source | Against the rank above it |
|
|
57
56
|
| --- | --- | --- |
|
|
@@ -110,6 +109,7 @@ workers get only approved decisions.{{OWNERSHIP_PROPOSAL}}
|
|
|
110
109
|
|
|
111
110
|
<!-- INCLUDE: laws/universal.md -->
|
|
112
111
|
|
|
112
|
+
<!-- LEAN:begin -->
|
|
113
113
|
**The user's own rules.** `{{PATH_RULES}}` (a session file) holds the
|
|
114
114
|
user's own rules: obey every rule in it with the same force as the {{LAWS}} above
|
|
115
115
|
— always, in every task (its rank is in the precedence table above). That file belongs
|
|
@@ -128,6 +128,15 @@ it only informs. It too belongs to the user: seeded once, never overwritten. Nev
|
|
|
128
128
|
write standing rules into it — those go to `user-rules.md`. When the file is still
|
|
129
129
|
the untouched stub (so it never reaches your session) — or the user asks — the [profile]({{DIR_SKILLS}}/profile.md)
|
|
130
130
|
{{SKILL}} builds or refreshes it through a short interview, with their consent.
|
|
131
|
+
<!-- LEAN:else -->
|
|
132
|
+
**The user's own rules.** `{{PATH_RULES}}` (a session file) binds with the force of the {{LAWS}}
|
|
133
|
+
(rank above). It is the only home of standing rules, written through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}};
|
|
134
|
+
never add, edit or remove a {{LAW}} or a {{DOCTRINE}} rule, both regenerated on update.
|
|
135
|
+
|
|
136
|
+
**The user's profile.** `{{PATH_PROFILE}}` (a session file) is identity, not rules: it informs,
|
|
137
|
+
never binds; never write standing rules into it. The [profile]({{DIR_SKILLS}}/profile.md) {{SKILL}} builds or
|
|
138
|
+
refreshes it, with their consent.
|
|
139
|
+
<!-- LEAN:end -->
|
|
131
140
|
|
|
132
141
|
---
|
|
133
142
|
|
|
@@ -182,9 +191,7 @@ Active packs: {{DOCTRINES_LIST}}{{EXCLUDED_RULES_LINE}}{{GATE_LINES}}
|
|
|
182
191
|
| [operator]({{DIR_AGENTS}}/operator.md) | a council debate needs the production/runtime reality — reliability, on-call — weighed |
|
|
183
192
|
| [historian]({{DIR_AGENTS}}/historian.md) | a council debate needs precedent — what was tried before and how it went |
|
|
184
193
|
<!-- CATALOG:else -->
|
|
185
|
-
Your host lists every {{AGENT}} it can dispatch
|
|
186
|
-
tool inventory — that list is the catalogue and it is authoritative. Read the
|
|
187
|
-
spec in [`{{DIR_AGENTS}}/`]({{DIR_AGENTS}}/) before dispatching one whose output
|
|
194
|
+
Your host's tool inventory lists every {{AGENT}} it can dispatch. Read the spec in [`{{DIR_AGENTS}}/`]({{DIR_AGENTS}}/) before dispatching one whose output
|
|
188
195
|
contract you do not already know.
|
|
189
196
|
<!-- CATALOG:end -->
|
|
190
197
|
|
|
@@ -197,8 +204,8 @@ contract you do not already know.
|
|
|
197
204
|
decompose it into independent subtasks, route each to the single owning {{AGENT}}
|
|
198
205
|
above, and converge the results yourself. Every handoff carries an **envelope** —
|
|
199
206
|
the subtask goal, the inputs the {{AGENT}} needs, and its output contract — and the
|
|
200
|
-
constraints travel with it: dispatched {{AGENTS}}
|
|
201
|
-
|
|
207
|
+
constraints travel with it: dispatched {{AGENTS}} commit only in their own worktree, never
|
|
208
|
+
push, and never merge outside their own branch ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented
|
|
202
209
|
content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
|
|
203
210
|
workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
|
|
204
211
|
the same shape model-driven via the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md).
|
|
@@ -209,8 +216,8 @@ Ten of them — `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`,
|
|
|
209
216
|
dispatched alone; the [council {{SKILL}}]({{DIR_SKILLS}}/council.md) convenes the
|
|
210
217
|
subset that productively clashes on a given motion.
|
|
211
218
|
<!-- LEAN:else -->
|
|
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
|
|
219
|
+
Dispatched {{AGENTS}} commit only in their worktree, never push, never merge outside
|
|
220
|
+
their own branch ({{DOCTRINE:consent-before-push}} stays with you), and an unfulfilled contract returns as a stated gap, never invented content. A
|
|
214
221
|
multi-part goal goes through the [parallel-agents {{SKILL}}]({{DIR_SKILLS}}/parallel-agents.md)
|
|
215
222
|
(or the [workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md) where the host has a workflow tool);
|
|
216
223
|
the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/council.md).
|
|
@@ -288,7 +295,8 @@ its domain comes up:
|
|
|
288
295
|
of a diff: intent, risks, side-by-side git diff.
|
|
289
296
|
<!-- CATALOG:else -->
|
|
290
297
|
Your host lists every {{SKILL}} it can invoke, with its trigger, in your own
|
|
291
|
-
inventory — that list is the catalogue and it is authoritative
|
|
298
|
+
inventory — that list is the catalogue and it is authoritative, as is its
|
|
299
|
+
{{AGENT}} list (§3) where it gives one. Each written
|
|
292
300
|
procedure is in [`{{DIR_SKILLS}}/`]({{DIR_SKILLS}}/) and the host loads it on
|
|
293
301
|
demand.
|
|
294
302
|
<!-- CATALOG:end -->
|
|
@@ -393,12 +401,10 @@ scratch scripts, analysis dumps, drafts, experiments — are made in the
|
|
|
393
401
|
{{NOTEBOOK}} (§6), never here.
|
|
394
402
|
<!-- LEAN:else -->
|
|
395
403
|
{{INTRO_WORKSPACE}} Whatever sits beside the harness files — notes, data, configs,
|
|
396
|
-
prior work — is knowledge to read and learn from, not scaffolding to reorganise
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
It receives only the task's deliverables; your working files go in the {{NOTEBOOK}}
|
|
401
|
-
(§6).
|
|
404
|
+
prior work — is knowledge to read and learn from, not scaffolding to reorganise. You
|
|
405
|
+
do not own the folder: files you did not create are not yours to move or delete unless
|
|
406
|
+
the task requires it ({{LAW:deletion-is-deliberate}}), and a file is verified before it is treated as disposable ({{LAW:verify-before-asserting}}).
|
|
407
|
+
It receives only the task's deliverables.
|
|
402
408
|
<!-- LEAN:end -->
|
|
403
409
|
|
|
404
410
|
---
|
package/src/agents/_template.md
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
## Inputs
|
|
29
29
|
- What the caller must provide (files, diff, scope, acceptance criteria).
|
|
30
30
|
- Dispatches arrive as an envelope: goal, inputs, output contract, inherited
|
|
31
|
-
constraints (never
|
|
31
|
+
constraints (a read-only seat never commits or pushes; a writing one commits only in its own worktree, never pushes, never merges outside its own branch; dispatch no sub-agents — review comes from the caller;
|
|
32
32
|
report gaps instead of inventing). When an
|
|
33
33
|
envelope arrives incomplete, hold the caller to it via `spec-feedback:`.
|
|
34
34
|
|
package/src/agents/advocate.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_ADVOCATE}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs the strongest case for the motion.
|
|
7
7
|
- The user wants the upside of a change, plan, or decision pressed hard rather than hedged.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/developer.md
CHANGED
|
@@ -25,9 +25,10 @@
|
|
|
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
|
-
-
|
|
29
|
-
|
|
30
|
-
beyond it once the user
|
|
28
|
+
- Commits only in its own worktree, never pushes, and never merges outside its own branch
|
|
29
|
+
({{DOCTRINE:consent-before-push}}); into that branch it merges only the branches of
|
|
30
|
+
sub-workers it started. The parent re-runs the proof and merges beyond it once the user
|
|
31
|
+
accepts.
|
|
31
32
|
|
|
32
33
|
## Procedure
|
|
33
34
|
0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
|
|
@@ -53,6 +54,14 @@
|
|
|
53
54
|
- In ownership mode: the diff, for the developer's final review — or
|
|
54
55
|
`blocked: decision needed` with the options, on the line after `STATUS: BLOCKED`.
|
|
55
56
|
|
|
57
|
+
### Task worker (Foreman)
|
|
58
|
+
|
|
59
|
+
Dispatched as Foreman's task worker, there is no tester seat: explore, implement and test
|
|
60
|
+
in your own context, and after two repair rounds on your own red tests return red with the
|
|
61
|
+
findings ({{DOCTRINE:bound-the-loop}}). As a lead, hold every member's result before you end. Report `T<n> · <task> · files: <write set> · <state>`
|
|
62
|
+
at start and on each change, as the mode says. Return the branch, its commit list, any
|
|
63
|
+
uncommitted work, and the raw test + lint output — the parent re-runs it before any merge.
|
|
64
|
+
|
|
56
65
|
## Pipeline role
|
|
57
66
|
|
|
58
67
|
*(Ignored outside pipelines — this section only tells pipeline orchestration who
|
package/src/agents/empiricist.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_EMPIRICIST}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs every claim, for and against, held to evidence.
|
|
7
7
|
- The debate is running on assertion and intuition; the user wants it anchored to data, tests, or precedent.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/framer.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_FRAMER}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs a test of the framing — is this the right problem.
|
|
7
7
|
- The motion may be a solution in search of a problem, or the real need sits upstream of what's proposed.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/historian.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_HISTORIAN}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs precedent and institutional memory.
|
|
7
7
|
- The motion resembles something tried before; the user wants the track record before repeating it.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/operator.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_OPERATOR}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs a voice for running it in production.
|
|
7
7
|
- The motion ships to a live system: its behaviour under load, its observability, and the on-call burden all matter.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/pragmatist.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_PRAGMATIST}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs a judgement of whether the motion is worth its cost.
|
|
7
7
|
- The user wants the real cost, effort, and complexity of a change surfaced against its payoff.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/researcher.md
CHANGED
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
- The question, what a complete answer must contain, and any source the caller
|
|
22
22
|
already trusts or distrusts.
|
|
23
23
|
- Dispatches arrive as an envelope: goal, inputs, output contract, inherited
|
|
24
|
-
constraints (never
|
|
24
|
+
constraints (a read-only seat never commits or pushes; a writing one commits only in its own worktree, never pushes, never merges outside its own branch; dispatch no sub-agents — review comes from the caller;
|
|
25
25
|
report gaps instead of inventing). When an
|
|
26
26
|
envelope arrives incomplete, hold the caller to it via `spec-feedback:`.
|
|
27
27
|
|
package/src/agents/skeptic.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_SKEPTIC}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs a devil's advocate to attack the motion.
|
|
7
7
|
- The user wants a change, plan, or claim stress-tested for how it fails before committing.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/steward.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_STEWARD}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs a defence of the long term against short-term wins.
|
|
7
7
|
- The user wants the architectural and maintenance consequences of a change weighed before committing.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_USER_ADVOCATE}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs a voice for whoever consumes the outcome.
|
|
7
7
|
- The motion touches a user-facing surface: UX, an API's ergonomics, docs, error messages, or a downstream developer's workflow.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/agents/visionary.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> {{DESC_VISIONARY}}
|
|
4
4
|
|
|
5
5
|
## When to dispatch
|
|
6
|
-
-
|
|
6
|
+
- A council debate (the council {{SKILL}}) needs the bold, transformative version argued against incrementalism.
|
|
7
7
|
- The debate risks under-reaching: the user wants the ambitious upside of a change pushed, not just the safe slice.
|
|
8
8
|
|
|
9
9
|
## When NOT to dispatch
|
package/src/bricks/intake.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: intake
|
|
3
|
-
description: Read the work item — a request, a document or an issue — and write it down as one clear item for the run,
|
|
3
|
+
description: Read the work item — a request, a document or an issue — and write it down as one clear item for the run, ask the user what only they can answer, or refuse an item that should not be built.
|
|
4
4
|
effect: read
|
|
5
5
|
agent: explorer
|
|
6
|
-
outcomes: pass, fail, needs-info
|
|
6
|
+
outcomes: pass, fail, needs-info, reject
|
|
7
7
|
gate: human
|
|
8
|
-
gateOn: needs-info
|
|
8
|
+
gateOn: needs-info, reject
|
|
9
9
|
---
|
|
10
10
|
The stage hands you the run's `requirement` and its `input`: free text, a file path, or an issue (a
|
|
11
11
|
GitHub URL or `#<n>`: `gh issue view <n> --json title,body,comments,labels`; a GitLab one:
|
|
@@ -25,3 +25,10 @@ migration; medium between), and `areas:` with any of `security`, `performance`,
|
|
|
25
25
|
Report `pass` with that file's path. Report `needs-info` when a question blocks the work and only
|
|
26
26
|
the user can answer it: write the questions in that file, numbered, each with the assumption you
|
|
27
27
|
would build on without an answer, and report its path. Report `fail` when the input cannot be read.
|
|
28
|
+
|
|
29
|
+
Report `reject` when the item should not be built, and you can show why: it is already done (name
|
|
30
|
+
the commit or the file:line that does it), it duplicates an open issue or pull request (name it),
|
|
31
|
+
or it goes against a rule the project states (quote the rule and its file). Write the reason and
|
|
32
|
+
that evidence in the file and report its path; the user decides. A doubt is not a refusal: with
|
|
33
|
+
no evidence to show, ask (`needs-info`) or go on (`pass`). On a re-run whose `carry` holds the
|
|
34
|
+
user's reason to build it, do not refuse on the same ground again.
|
package/src/bricks/retro.md
CHANGED
|
@@ -10,11 +10,21 @@ A loop's notes leave with its `LOOP.md`, which its close commit removes; read ea
|
|
|
10
10
|
the base (`git merge-base HEAD origin/<default>`), list the commits that removed `LOOP.md`, newest
|
|
11
11
|
first: `git log --format=%H --diff-filter=D <merge-base>..HEAD -- LOOP.md`, and read each loop's
|
|
12
12
|
last `LOOP.md` from its parent: `git show <commit>^:LOOP.md`. A `LOOP.md` that was never
|
|
13
|
-
committed (a loop that made no commit) is gone: say so in the report.
|
|
13
|
+
committed (a loop that made no commit) is gone: say so in the report.
|
|
14
|
+
|
|
15
|
+
Run `geneseed factory report`. It prints the run's numbers as one JSON object and writes nothing:
|
|
16
|
+
`stages` (each stage with its `runs`, `reworks`, `workMs` and `tokens`), then `workMs`, `waitMs`
|
|
17
|
+
(the time the run waited for the user at its gates), `tokens` and `transitions` for the whole run.
|
|
18
|
+
Copy those numbers into the report; never work out a duration or a total yourself. A `null` is a
|
|
19
|
+
number nobody recorded: write `unknown`, never 0.
|
|
20
|
+
|
|
21
|
+
Then write the run report to `.geneseed/factory-runs/<slug>.md` at the worktree root, `<slug>`
|
|
14
22
|
being the branch name after `loop/factory-`. First run `git check-ignore -q <that path>`: when it
|
|
15
23
|
exits non-zero the path is not ignored, so write the report to the OS temp directory instead.
|
|
16
|
-
The report holds the work item, the PR URL,
|
|
17
|
-
|
|
24
|
+
The report holds the work item, the PR URL, a table with one row per stage (stage, runs, reworks,
|
|
25
|
+
work time, tokens), the run's work time and its waiting time, every stage with its outcome, each
|
|
26
|
+
rework and its reason, for each seat of `review-panel` how many rounds it failed (read each failed
|
|
27
|
+
round's finding, the `carry` path of its `history` entry in `FACTORY.md`), each held outcome the user let through with `ok` (above all a locked path `checks`
|
|
18
28
|
reported), and how the run ended (closed, or stopped and why).
|
|
19
29
|
|
|
20
30
|
Change nothing else: no tracked file, no commit. Only a lesson that will hold beyond this run —
|
package/src/doctrines/comms.md
CHANGED
|
@@ -112,5 +112,5 @@ Write every prose reply and report in ASD-STE100 Simplified Technical English; c
|
|
|
112
112
|
commands, paths and quoted output stay as they are. One topic per sentence: 20 words at
|
|
113
113
|
most in an instruction, 25 in a description. Instructions: imperative, one action each,
|
|
114
114
|
condition first. Active voice, no -ing forms, no dropped articles, one word per meaning
|
|
115
|
-
(`use`, not `utilize`). In another language, keep it and these rules.
|
|
115
|
+
(`use`, not `utilize`). In another language, keep it and these rules. The theme keeps its voice.
|
|
116
116
|
<!-- LEAN:end -->
|
package/src/doctrines/ops.md
CHANGED
|
@@ -99,7 +99,7 @@ recreate, down-and-up, reload, or full restart — perform it, then confirm the
|
|
|
99
99
|
value in the *running* system, not the file ({{LAW:verify-before-asserting}}). A correct file above a
|
|
100
100
|
stale process looks like a finished job and is not one.
|
|
101
101
|
<!-- LEAN:else -->
|
|
102
|
-
After a config edit, confirm the new value in the running process, not the file.
|
|
102
|
+
After a config edit, force the re-read, then confirm the new value in the running process, not the file.
|
|
103
103
|
<!-- LEAN:end -->
|
|
104
104
|
|
|
105
105
|
### {{DOCTRINE:serialize-against-a-rationed-resource}} Serialize Against a Rationed Resource
|
package/src/doctrines/process.md
CHANGED
|
@@ -94,8 +94,10 @@ stands for commits on that branch until the session ends or the scope changes; a
|
|
|
94
94
|
new session, a new branch, or a widened scope re-asks. Push earns no such default
|
|
95
95
|
and stays per-ask unless granted in the same named form. A launched loop's batch
|
|
96
96
|
covers commit and push on its own `loop/*` branch; merging that branch into a
|
|
97
|
-
shared one never is. A
|
|
98
|
-
|
|
97
|
+
shared one never is. A dispatched worker, crew or slice (a Foreman worker, a pipeline
|
|
98
|
+
crew, a parallel-agents slice) holds a batch that covers commit, and merge of its own
|
|
99
|
+
sub-workers, in its own worktree, off any shared branch; it never pushes. Outside a
|
|
100
|
+
batch, before each commit, present in order (1) a plain-language
|
|
99
101
|
summary of what changed and why and (2) the exact commit message you intend to use,
|
|
100
102
|
then wait. Never push on your own initiative.
|
|
101
103
|
On a **shared branch** — `main`, `master`, `develop`, `development`, a
|
|
@@ -111,9 +113,9 @@ Recording and sharing code is consented, never unilateral: **every** `git commit
|
|
|
111
113
|
branch included; one-time approval is not standing consent. A named batch ("commit as
|
|
112
114
|
you go") stands until the session ends or scope changes; push earns no default. Never
|
|
113
115
|
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
|
|
115
|
-
own worktree, off any shared branch
|
|
116
|
-
before each, then wait. Shared branches — `main`, `master`, `develop`, `development`,
|
|
116
|
+
`loop/*` branch only; merging it never. A dispatched worker, crew or slice's covers commit
|
|
117
|
+
and merge in its own worktree, off any shared branch, never pushed. Outside a batch, show
|
|
118
|
+
the plain summary and the exact commit message before each, then wait. Shared branches — `main`, `master`, `develop`, `development`,
|
|
117
119
|
`release`/`hotfix`, any unsure — take the same gate. Never force-push, hard-reset, or
|
|
118
120
|
rebase one: undo with a revert commit (git-history {{SKILL}} for a legitimate rewrite).
|
|
119
121
|
The host gates both at the tool boundary.
|
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
{ "from": "intake", "on": "pass", "to": "spec" },
|
|
13
13
|
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
14
14
|
{ "from": "intake", "on": "needs-info", "to": "spec" },
|
|
15
|
+
{ "from": "intake", "on": "reject", "to": "$stop" },
|
|
15
16
|
{ "from": "spec", "on": "pass", "to": "holdout-write" },
|
|
16
17
|
{ "from": "spec", "on": "fail", "to": "$stop" },
|
|
17
18
|
{ "from": "holdout-write", "on": "pass", "to": "loop:feature" },
|
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
{ "from": "intake", "on": "pass", "to": "holdout-write" },
|
|
13
13
|
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
14
14
|
{ "from": "intake", "on": "needs-info", "to": "holdout-write" },
|
|
15
|
+
{ "from": "intake", "on": "reject", "to": "$stop" },
|
|
15
16
|
{ "from": "holdout-write", "on": "pass", "to": "loop:bugfix" },
|
|
16
17
|
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
17
18
|
{ "from": "loop:bugfix", "on": "pass", "to": "checks" },
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
{ "from": "intake", "on": "pass", "to": "holdout-write" },
|
|
17
17
|
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
18
18
|
{ "from": "intake", "on": "needs-info", "to": "holdout-write" },
|
|
19
|
+
{ "from": "intake", "on": "reject", "to": "$stop" },
|
|
19
20
|
{ "from": "holdout-write", "on": "pass", "to": "triage" },
|
|
20
21
|
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
21
22
|
{ "from": "triage", "on": "bug", "to": "loop:bugfix" },
|
package/src/laws/universal.md
CHANGED
|
@@ -86,8 +86,8 @@ force-pushing your own branch, a worktree — runs freely, as does
|
|
|
86
86
|
`reset --hard` over a dirty tree.
|
|
87
87
|
<!-- LEAN:else -->
|
|
88
88
|
Real data loss — deleting untracked, modified, unpushed, unmerged work,
|
|
89
|
-
discarding uncommitted work (except `reset --hard`),
|
|
90
|
-
force-moving main, master or the default branch, pruning reflog/gc — and any
|
|
89
|
+
discarding uncommitted work (except `reset --hard` over a dirty tree),
|
|
90
|
+
rewriting, deleting or force-moving main, master or the default branch, pruning reflog/gc — and any
|
|
91
91
|
irreversible, financial, privilege-changing or outward-facing act need
|
|
92
92
|
explicit confirmation bound to that act, or a durable authorization covering
|
|
93
93
|
it; one yes never stretches to the next. What git restores runs freely:
|
package/src/modes/foreman.md
CHANGED
|
@@ -14,18 +14,17 @@ task that would block it to one background task worker, and keeps answering the
|
|
|
14
14
|
(interfaces, sensitive zones, the granularity's own) are approved inline with the user,
|
|
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
|
-
worktree. The brief carries the task as the user stated it, BASE, the write set, the
|
|
18
|
-
proof commands, and the rule that it
|
|
19
|
-
branch. The worker explores, implements and tests in its own context, loading {{SKILLS}}
|
|
17
|
+
worktree (without worktrees: one tree, one worker at a time). The brief carries the task as the user stated it, BASE, the write set, the
|
|
18
|
+
proof commands, and the rule that it commits only in its own worktree, never pushes, and
|
|
19
|
+
never merges outside its own branch; without a worktree, it never commits. The worker explores, implements and tests in its own context, loading {{SKILLS}}
|
|
20
20
|
as it needs them; after two repair rounds on its own red tests it returns red with its
|
|
21
21
|
findings ({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
|
|
22
22
|
({{DOCTRINE:one-writer-per-file}}).
|
|
23
23
|
- **A worker may lead, inside its worktree.** It may dispatch read-only helpers (explorer,
|
|
24
24
|
researcher) at any time, and writing sub-workers, each in its own worktree branched from
|
|
25
|
-
its branch
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
reviewer stays the parent's.
|
|
25
|
+
its branch, merged into its own with the proof re-run after each merge. Depth stops at
|
|
26
|
+
main → worker → sub-worker: a sub-worker dispatches nothing. Every lead holds every member's result
|
|
27
|
+
before it ends. The blind reviewer stays the parent's.
|
|
29
28
|
- **Status, one line per change.** A worker reports
|
|
30
29
|
`T<n> · <task> · files: <write set> · <state>` at start and on each change: by
|
|
31
30
|
`SendMessage` to the parent on Claude Code (on OpenClaude only in its agent-teams mode);
|
|
@@ -46,17 +45,12 @@ task that would block it to one background task worker, and keeps answering the
|
|
|
46
45
|
only when the old one cannot be resumed — the host has no resume, or its context is
|
|
47
46
|
spent — and hand it a note: the ask, the diff so far, the findings, what was tried. A
|
|
48
47
|
worker serves one task and retires when that task is merged or dropped.
|
|
49
|
-
- **Isolate.** Each worker works in its own git worktree/branch; falls back to a single
|
|
50
|
-
tree, one worker at a time, when worktrees are unavailable.
|
|
51
48
|
- **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
|
|
52
49
|
uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
|
|
53
50
|
a worker's log is the worker's account, not the state — shows the user the diff from BASE
|
|
54
51
|
and the green output, and commits and merges only once the user accepts
|
|
55
|
-
({{DOCTRINE:consent-before-push}}).
|
|
56
|
-
|
|
57
|
-
- **Report and watch.** Surface completions, failures, and merges to the user as they
|
|
58
|
-
happen; a worker that returns no proof, or goes silent, is handled as the pipeline
|
|
59
|
-
{{SKILL}}'s step 2 says for a crew.
|
|
52
|
+
({{DOCTRINE:consent-before-push}}). Surface completions, failures and merges as they
|
|
53
|
+
happen; watch workers as the pipeline {{SKILL}}'s step 2 watches a crew.
|
|
60
54
|
- **Crews are opt-in.** Run the `pipeline` {{SKILL}} only when the user asks for a
|
|
61
55
|
pipeline or a crew, or for a large multi-part task that needs several specialists
|
|
62
56
|
(security, architect, performance). Independent subtasks side by side go to
|
package/src/skills/commit.md
CHANGED
|
@@ -24,7 +24,11 @@
|
|
|
24
24
|
the change *and* the exact commit message, then wait for explicit acceptance before
|
|
25
25
|
committing. For a non-trivial change, offer the `explain-changes` skill's visual
|
|
26
26
|
walkthrough before asking — an offer, never a condition of the commit. A previous
|
|
27
|
-
approval is not standing consent; ask again each commit
|
|
27
|
+
approval is not standing consent; ask again each commit, unless a batch that
|
|
28
|
+
{{DOCTRINE:consent-before-push}} names covers it: a named batch, a launched loop on its
|
|
29
|
+
own `loop/*` branch, or a dispatched worker, crew or slice (a Foreman worker, a
|
|
30
|
+
pipeline crew, a parallel-agents slice) in its own worktree, off any shared branch —
|
|
31
|
+
which commits there without asking, since it cannot reach the user, and never pushes. On a *shared branch*
|
|
28
32
|
(`main`, `master`, `develop`/`development`, a release/hotfix branch, or any branch
|
|
29
33
|
that is not a dedicated feature branch) apply the same gate with extra care.
|
|
30
34
|
6. Push only when the user has explicitly approved *that push* ({{DOCTRINE:consent-before-push}} / {{LAW:deletion-is-deliberate}})
|
|
@@ -33,6 +37,7 @@
|
|
|
33
37
|
|
|
34
38
|
## Done when
|
|
35
39
|
- The commit contains only the intended change and the working tree is clean of it,
|
|
36
|
-
and every commit and push went out only with the user's explicit, per-action consent
|
|
40
|
+
and every commit and push went out only with the user's explicit, per-action consent
|
|
41
|
+
or inside a batch that covers it.
|
|
37
42
|
|
|
38
43
|
<!-- INCLUDE: skills/_self-improvement.md -->
|
package/src/skills/debug.md
CHANGED
|
@@ -21,7 +21,7 @@ faster than thrashing; do not trade it away under pressure.
|
|
|
21
21
|
3. **Rank 3–5 falsifiable hypotheses** ("if X is the cause, changing Y removes the bug") — list them in your reply, then test the top one without waiting. Cite the evidence for each as `file:line` or the exact log line. Proceed only on one that explains ALL the evidence — else gather more evidence, don't guess.
|
|
22
22
|
4. Apply the smallest fix that addresses the root cause, not the symptom; resist fixing things the evidence doesn't implicate ({{LAW:one-intent-one-act}}). One change at a time — no bundled "while I'm here" edits.
|
|
23
23
|
5. Verify: run the project's checks and read the actual output ({{LAW:verify-before-asserting}}) — the step-1 command now passes and nothing nearby broke. Where a test can pin the bug at a seam that reproduces the real call chain, add a regression test that fails before the fix and passes after. If no such seam exists, record that as a finding rather than writing a shallow test. Name the confirmed hypothesis in the commit message. Dispatch the [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for a focused regression check when the blast radius is unclear.
|
|
24
|
-
6. If a fix doesn't work, return to step 1 with what you learned — don't stack a second fix on top. **After
|
|
24
|
+
6. If a fix doesn't work, return to step 1 with what you learned — don't stack a second fix on top. **After two failed fixes, stop fixing** ({{DOCTRINE:bound-the-loop}}): when each attempt only shifts the symptom elsewhere, the architecture, not the line, is likely wrong. Surface that to the user and decide the approach together before trying again ({{LAW:one-intent-one-act}}). If the evidence puts the cause outside the repo, show it; a retry or timeout is then a named workaround, taken with consent ({{LAW:cure-the-cause}}).
|
|
25
25
|
|
|
26
26
|
**Diagnostic logging is scaffolding.** When you add logging to isolate a bug, use the project's real logger at a DEBUG level rather than scattered `print`/`console.log`, and **never log secrets, tokens, or PII** ({{LAW:sealed-secrets}}) — probe a secret's presence, never its value: `[ -n "$TOKEN" ] && echo set || echo unset`. Tag every probe with one unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep, and remove or downgrade each probe, `print`/`console.log`/`debugger` before the change ships ({{LAW:cure-the-cause}}).
|
|
27
27
|
|