geneseed 5.6.0 → 6.0.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 +20 -0
- package/README.md +2 -2
- package/SHIPPED.md +2 -2
- package/adapters/opencode/README.md +7 -4
- package/docs/concepts/agents.md +8 -0
- package/docs/concepts/exclusions.md +1 -1
- package/docs/concepts/foreman-mode.md +4 -2
- package/docs/concepts/kits.md +20 -2
- package/docs/concepts/loops.md +5 -0
- package/docs/concepts/skills.md +1 -1
- package/docs/concepts/superpowers-kit.md +79 -0
- package/docs/extending.md +11 -4
- package/docs/guides/install-scripted.md +1 -1
- package/docs/reference/cli.md +2 -0
- package/docs/reference/profiles.md +10 -5
- package/harness.config.json +1 -1
- package/js/README.md +2 -0
- package/js/build/args.mjs +4 -2
- package/js/build/driver.mjs +8 -8
- package/js/build/emit-claude.mjs +5 -3
- package/js/build/emit-opencode.mjs +2 -2
- package/js/build/generate.mjs +1 -1
- package/js/build/profile.mjs +15 -7
- package/js/build/render.mjs +81 -10
- package/js/build/source.mjs +75 -1
- package/js/cli-table.json +17 -2
- package/js/hosts/installs.mjs +50 -4
- package/js/hosts/native.mjs +104 -3
- package/js/hosts/opencode.mjs +13 -15
- package/js/inspect/checks-authoring.mjs +24 -1
- package/js/inspect/checks-build.mjs +43 -2
- package/js/inspect/checks-counts.mjs +72 -1
- package/js/inspect/diff.mjs +17 -3
- package/js/inspect/doctor.mjs +23 -2
- package/js/inspect/status.mjs +5 -1
- package/js/inspect/validate.mjs +1 -1
- package/js/loop/catalog.mjs +10 -0
- package/js/maintain/kit-migration.mjs +109 -0
- package/js/maintain/plugin-detect.mjs +150 -0
- package/js/maintain/profiles.mjs +46 -5
- package/js/maintain/setup.mjs +45 -11
- package/js/maintain/update.mjs +1 -1
- package/js/web/actions.mjs +28 -7
- package/js/web/api.mjs +3 -1
- package/js/web/profiles-api.mjs +11 -7
- package/package.json +1 -1
- package/profiles/autonomous.json +1 -0
- package/profiles/corporate.json +1 -1
- package/profiles/mentor.json +1 -0
- package/profiles/minimal.json +2 -1
- package/profiles/starter.json +1 -1
- package/src/AGENT.md.tmpl +1 -6
- package/src/agents/_template.md +4 -0
- package/src/agents/advocate.md +1 -0
- package/src/agents/architect.md +1 -0
- package/src/agents/developer.md +12 -4
- package/src/agents/empiricist.md +1 -0
- package/src/agents/explorer.md +1 -0
- package/src/agents/framer.md +1 -0
- package/src/agents/historian.md +1 -0
- package/src/agents/operator.md +1 -0
- package/src/agents/performance.md +2 -1
- package/src/agents/pragmatist.md +1 -0
- package/src/agents/react-reviewer.md +1 -0
- package/src/agents/researcher.md +1 -0
- package/src/agents/reviewer.md +1 -0
- package/src/agents/security.md +1 -0
- package/src/agents/skeptic.md +1 -0
- package/src/agents/spring-reviewer.md +1 -0
- package/src/agents/spring-security.md +1 -0
- package/src/agents/steward.md +1 -0
- package/src/agents/user-advocate.md +1 -0
- package/src/agents/visionary.md +1 -0
- package/src/bricks/ci-fix.md +12 -2
- package/src/kits/superpowers/missing.md +3 -0
- package/src/kits/superpowers/provider.md +7 -0
- package/src/kits/superpowers/rules.md +6 -0
- package/src/kits/superpowers.json +45 -0
- package/src/modes/foreman.md +18 -12
- package/src/skills/parallel-agents.md +2 -2
- package/src/skills/spring-boot/cloud.md +8 -2
- package/src/skills/spring-boot.md +3 -1
- package/src/skills/spring-testing.md +3 -3
- package/src/upstreams.json +1 -1
package/js/web/profiles-api.mjs
CHANGED
|
@@ -15,10 +15,10 @@ import path from 'node:path';
|
|
|
15
15
|
import { ROOT } from '../build/source.mjs';
|
|
16
16
|
import { installProfile } from '../build/profile.mjs';
|
|
17
17
|
import { HOSTS, expanduser } from '../hosts/hosts.mjs';
|
|
18
|
-
import { installState, installTargets } from '../hosts/installs.mjs';
|
|
18
|
+
import { installState, installTargets, tiersOfDir } from '../hosts/installs.mjs';
|
|
19
19
|
import {
|
|
20
20
|
BASE_PROFILE, isGitClone, listProfiles, loadProfile, profileBuildArgs, profileDiff, profileDirs,
|
|
21
|
-
profileFromInstall, profileHosts,
|
|
21
|
+
profileFromInstall, profileHosts, profileKits,
|
|
22
22
|
} from '../maintain/profiles.mjs';
|
|
23
23
|
import { checkProjectFolder, globalLayering, markerCollision } from '../maintain/profile-scope.mjs';
|
|
24
24
|
import { hostTools, profileChanges } from '../maintain/setup.mjs';
|
|
@@ -50,9 +50,13 @@ function activeTargets() {
|
|
|
50
50
|
* `starter`, which lists four hosts, could match no install). `sharedTier` counts only on a
|
|
51
51
|
* project install: a global apply ignores it (D37), so a global install cannot differ on it.
|
|
52
52
|
*/
|
|
53
|
-
export function followsProfile(installP, scope, p) {
|
|
53
|
+
export function followsProfile(installP, scope, p, root = null) {
|
|
54
54
|
const skip = new Set(['hosts', 'login', ...(scope === 'global' ? ['sharedTier'] : [])]);
|
|
55
|
-
|
|
55
|
+
// A kit chosen by detection is the kit an apply would have built for the install's own host: an
|
|
56
|
+
// install has the kits it has, never a kit "by detection", so compare the resolved list.
|
|
57
|
+
const resolved = p.kitsByDetection?.length
|
|
58
|
+
? { ...p, kits: profileKits(p, installP.hosts?.[0] ?? '', scope === 'project' ? root : null), kitsByDetection: [] } : p;
|
|
59
|
+
return profileDiff(installP, resolved).every((d) => skip.has(d.key));
|
|
56
60
|
}
|
|
57
61
|
|
|
58
62
|
/** The hosts row of the tab: `{ host, label, present }` in HOSTS order. */
|
|
@@ -79,7 +83,7 @@ function previewRows(p, project, hosts) {
|
|
|
79
83
|
// (`markerCollision`): the row says so and the panel does not offer it.
|
|
80
84
|
const refused = project ? markerCollision(project, h.host) : null;
|
|
81
85
|
const changes = h.present && !refused && state === 'active'
|
|
82
|
-
? profileChanges(profileBuildArgs(p, h.host, project)) : [];
|
|
86
|
+
? profileChanges(profileBuildArgs(p, h.host, project, root ? tiersOfDir(root, h.host) : null)) : [];
|
|
83
87
|
return {
|
|
84
88
|
host: h.host, label: h.label, present: h.present, state, root: root ? String(root) : null,
|
|
85
89
|
changes, layering: project && !refused ? globalLayering(h.host) : null, refused,
|
|
@@ -114,14 +118,14 @@ export function apiProfiles(state, url, { src = {}, tools = hostTools } = {}) {
|
|
|
114
118
|
...head, description: p.description ?? '', profile: p,
|
|
115
119
|
gatesOff: Object.keys(p.gates ?? {}),
|
|
116
120
|
diff: base.ok ? profileDiff(p, base.profile) : [],
|
|
117
|
-
matches: readBacks.filter((rb) => followsProfile(rb.profile, rb.scope, p))
|
|
121
|
+
matches: readBacks.filter((rb) => followsProfile(rb.profile, rb.scope, p, rb.path))
|
|
118
122
|
.map(({ host, scope, path: at }) => ({ host, scope, path: at })),
|
|
119
123
|
};
|
|
120
124
|
});
|
|
121
125
|
const loaded = profiles.filter((x) => x.profile);
|
|
122
126
|
const installs = readBacks.map((rb) => ({
|
|
123
127
|
host: rb.host, scope: rb.scope, path: rb.path,
|
|
124
|
-
matches: loaded.filter((x) => followsProfile(rb.profile, rb.scope, x.profile)).map((x) => x.name),
|
|
128
|
+
matches: loaded.filter((x) => followsProfile(rb.profile, rb.scope, x.profile, rb.path)).map((x) => x.name),
|
|
125
129
|
diff: base.ok ? profileDiff(rb.profile, base.profile) : [],
|
|
126
130
|
}));
|
|
127
131
|
const hosts = hostRows(tools);
|
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": "
|
|
4
|
+
"version": "6.0.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/profiles/autonomous.json
CHANGED
package/profiles/corporate.json
CHANGED
package/profiles/mentor.json
CHANGED
package/profiles/minimal.json
CHANGED
|
@@ -7,8 +7,9 @@
|
|
|
7
7
|
"mode": "direct",
|
|
8
8
|
"trust": "balanced",
|
|
9
9
|
"doctrines": ["craft", "rigor"],
|
|
10
|
-
"excludeSkills": ["brick-forge", "bruno", "daydream", "factory", "factory-forge", "forge-mcp", "
|
|
10
|
+
"excludeSkills": ["brick-forge", "bruno", "daydream", "factory", "factory-forge", "forge-mcp", "react-view-transitions"],
|
|
11
11
|
"kits": [],
|
|
12
|
+
"kitsByDetection": ["superpowers"],
|
|
12
13
|
"contextWindow": "200k",
|
|
13
14
|
"gates": { "ownershipGate": false },
|
|
14
15
|
"login": true
|
package/profiles/starter.json
CHANGED
package/src/AGENT.md.tmpl
CHANGED
|
@@ -232,14 +232,11 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
|
|
|
232
232
|
<!-- CATALOG:begin skills -->
|
|
233
233
|
| {{SKILL}} | Trigger |
|
|
234
234
|
| --- | --- |
|
|
235
|
-
| [brainstorm]({{DIR_SKILLS}}/brainstorm.md) | a new feature or project with no design yet, or whose goal, scope, or success criteria need pinning down first |
|
|
236
|
-
| [plan]({{DIR_SKILLS}}/plan.md) | a task has more than a couple of steps |
|
|
237
235
|
| [codebase-design]({{DIR_SKILLS}}/codebase-design.md) | designing a module's interface, placing a seam, or needing the deep-module vocabulary; pinning domain terms in GLOSSARY.md or recording a hard-to-reverse decision as an ADR |
|
|
238
236
|
| [wayfinder]({{DIR_SKILLS}}/wayfinder.md) | a chunk of work too big for one session, still in the fog — chart decision tickets before building |
|
|
239
237
|
| [parallel-agents]({{DIR_SKILLS}}/parallel-agents.md) | several independent subtasks and a tool that runs subagents |
|
|
240
238
|
| [develop]({{DIR_SKILLS}}/develop.md) | implementing a feature, fixing a bug, or changing behaviour — failing test first, affected suite green, one committed slice at a time |
|
|
241
239
|
| [worktree]({{DIR_SKILLS}}/worktree.md) | work must not share a tree with what is in flight — a crew, a second task, another session in this checkout |
|
|
242
|
-
| [debug]({{DIR_SKILLS}}/debug.md) | a bug or failure to diagnose before fixing — a red CI run or pre-merge check included, reproduced under CI's conditions |
|
|
243
240
|
| [prototype]({{DIR_SKILLS}}/prototype.md) | a design question needs a runnable answer before real implementation |
|
|
244
241
|
| [document-project]({{DIR_SKILLS}}/document-project.md) | missing/drifted docs, or a PRD, design system, architecture doc or AGENTS.md; orienting to the repo, or refreshing its map after the structure changed |
|
|
245
242
|
| [ingest]({{DIR_SKILLS}}/ingest.md) | a task needs content from a PDF, Office doc, or URL |
|
|
@@ -248,8 +245,6 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
|
|
|
248
245
|
| [learn-mode]({{DIR_SKILLS}}/learn-mode.md) | the user wants to learn while building — they design, you code what they approve |
|
|
249
246
|
| [ownership]({{DIR_SKILLS}}/ownership.md) | the developer must own production code — they decide each part at a granularity the team sets, from the root AGENTS.md |
|
|
250
247
|
| [commit]({{DIR_SKILLS}}/commit.md) | staging and writing a commit |
|
|
251
|
-
| [geneseed-code-review]({{DIR_SKILLS}}/geneseed-code-review.md) | reviewing a diff or PR |
|
|
252
|
-
| [review-response]({{DIR_SKILLS}}/review-response.md) | acting on review feedback you have received |
|
|
253
248
|
| [fresh-eyes]({{DIR_SKILLS}}/fresh-eyes.md) | a finished artifact needs an independent verdict on whether it meets the original spec, from an agent with none of the solving session's context |
|
|
254
249
|
| [security-audit]({{DIR_SKILLS}}/security-audit.md) | a change touches the security surface — auth, untrusted input, secrets, shell or file access, a new dependency — or "is this safe" |
|
|
255
250
|
| [dependencies]({{DIR_SKILLS}}/dependencies.md) | auditing dependencies — outdated, vulnerable, abandoned, unused — or upgrading a dependency, framework, or language version one change at a time |
|
|
@@ -298,7 +293,7 @@ inventory — that list is the catalogue and it is authoritative, as is its
|
|
|
298
293
|
procedure is in [`{{DIR_SKILLS}}/`]({{DIR_SKILLS}}/) and the host loads it on
|
|
299
294
|
demand.
|
|
300
295
|
<!-- CATALOG:end -->
|
|
301
|
-
{{EXCLUDED_SKILLS_LINE}}{{KITS_LINE}}{{SHARED_TIER_LINE}}{{CONTEXT_WINDOW_LINE}}
|
|
296
|
+
{{EXCLUDED_SKILLS_LINE}}{{KITS_LINE}}{{SHARED_TIER_LINE}}{{CONTEXT_WINDOW_LINE}}{{TIERS_LINE}}
|
|
302
297
|
When a task repeats and no {{SKILL}} covers it, forge one through the
|
|
303
298
|
[skill-forge]({{DIR_SKILLS}}/skill-forge.md) {{SKILL}}: copy
|
|
304
299
|
[`{{DIR_SKILLS}}/_template.md`]({{DIR_SKILLS}}/_template.md), keep it to one coherent
|
package/src/agents/_template.md
CHANGED
|
@@ -38,6 +38,10 @@
|
|
|
38
38
|
edit, webfetch, and bash. If it must run read-only commands (tests, linters,
|
|
39
39
|
scanners), add the marker `<!-- bash: allow -->` in this section to gate bash to
|
|
40
40
|
"ask" instead of denying it outright.
|
|
41
|
+
- Model tier: an unmarked agent is `standard`. For `light` (read-only, read-and-summarise
|
|
42
|
+
seats) or `strong` (judgement seats that must run on the session model), put the marker
|
|
43
|
+
`<!-- tier: light -->` on a line of its own directly above `## When to dispatch`; the build
|
|
44
|
+
strips it from every output. A seat that writes code is never `light`.
|
|
41
45
|
- Caution: the build detects the phrase "Read-only" anywhere in the file — a
|
|
42
46
|
write-capable {{AGENT}}'s spec must not contain it, or its emit is locked down.
|
|
43
47
|
|
package/src/agents/advocate.md
CHANGED
package/src/agents/architect.md
CHANGED
package/src/agents/developer.md
CHANGED
|
@@ -48,9 +48,10 @@
|
|
|
48
48
|
actually close — report the blocker instead ({{ONTOLOGY}}: {{ONT_EVIDENCE}}).
|
|
49
49
|
|
|
50
50
|
## Output contract
|
|
51
|
-
- The report starts with one line, `STATUS: OK|BLOCKED|OUT_OF_SCOPE|ERROR`: `OK` the contract is met;
|
|
51
|
+
- The report starts with one line, `STATUS: OK|BLOCKED|OUT_OF_SCOPE|ERROR|RELAY`: `OK` the contract is met;
|
|
52
52
|
`BLOCKED` an input or a decision is missing; `OUT_OF_SCOPE` not this task; `ERROR` a step failed,
|
|
53
|
-
red tests included
|
|
53
|
+
red tests included; `RELAY` a task worker hands off at its ceiling: work in progress committed,
|
|
54
|
+
handoff note follows.
|
|
54
55
|
- The files changed in the worktree and a one-line summary of what changed and
|
|
55
56
|
why, ready for the tester's pass.
|
|
56
57
|
- If the scoped task cannot be implemented as given (missing input, contradictory
|
|
@@ -61,8 +62,15 @@
|
|
|
61
62
|
### Task worker (Foreman)
|
|
62
63
|
|
|
63
64
|
Dispatched as Foreman's task worker, there is no tester seat: explore, implement and test
|
|
64
|
-
in your own context
|
|
65
|
-
|
|
65
|
+
in your own context. While you iterate, run the targeted test file, not the full suite.
|
|
66
|
+
Send its output to a file, and read only the count line and the failing test names. Wait
|
|
67
|
+
for a background run's completion notice; never poll it with a monitor or a sleep loop.
|
|
68
|
+
Count your proof runs (one run of a check command); these bounds are starting values
|
|
69
|
+
({{DOCTRINE:bound-the-loop}}). After the 3rd run in a row that leaves the same test red,
|
|
70
|
+
return `STATUS: ERROR` with the findings. At about 150k tokens of context, or after about
|
|
71
|
+
20 proof runs, hand off: commit your work in progress, and return `STATUS: RELAY` with a
|
|
72
|
+
handoff note (the failing tests, what you tried, the next step). A hand-off is no failure.
|
|
73
|
+
As a lead, hold every member's result before you end. Report `T<n> · <task> · files: <write set> · <state>`
|
|
66
74
|
at start and on each change, as the mode says. Return the branch, its commit list, any
|
|
67
75
|
uncommitted work, and the raw test + lint output — the parent re-runs it before any merge.
|
|
68
76
|
That output is a full run to completion, with the runner's own count line, never a
|
package/src/agents/empiricist.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_EMPIRICIST}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs every claim, for and against, held to evidence.
|
|
7
8
|
- The debate is running on assertion and intuition; the user wants it anchored to data, tests, or precedent.
|
package/src/agents/explorer.md
CHANGED
package/src/agents/framer.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_FRAMER}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs a test of the framing — is this the right problem.
|
|
7
8
|
- The motion may be a solution in search of a problem, or the real need sits upstream of what's proposed.
|
package/src/agents/historian.md
CHANGED
package/src/agents/operator.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_OPERATOR}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs a voice for running it in production.
|
|
7
8
|
- The motion ships to a live system: its behaviour under load, its observability, and the on-call burden all matter.
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_PERFORMANCE}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: strong -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- The user reports something slow, heavy or timing out — a latency, throughput,
|
|
7
8
|
memory or startup complaint, or a regression against an earlier version.
|
|
@@ -13,7 +14,7 @@
|
|
|
13
14
|
## When NOT to dispatch
|
|
14
15
|
- No one has measured anything and nothing is slow — speculative tuning is the
|
|
15
16
|
waste this {{AGENT}} exists to refuse.
|
|
16
|
-
- The code is wrong, not slow — that is the debug {{SKILL}}.
|
|
17
|
+
- The code is wrong, not slow — that is the [debug {{SKILL}}](../{{DIR_SKILLS}}/debug.md).
|
|
17
18
|
|
|
18
19
|
## Inputs
|
|
19
20
|
- The symptom or the diff, the workload it runs under (data size, call rate,
|
package/src/agents/pragmatist.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_PRAGMATIST}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs a judgement of whether the motion is worth its cost.
|
|
7
8
|
- The user wants the real cost, effort, and complexity of a change surfaced against its payoff.
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
React-specific review only. Generic correctness, naming and structure belong to [reviewer](reviewer.md); defer to it and do not repeat its checks.
|
|
8
8
|
|
|
9
|
+
<!-- tier: strong -->
|
|
9
10
|
## When to dispatch
|
|
10
11
|
- A change touches `.tsx` / `.jsx` files, hooks or React tests and needs a framework-aware pass.
|
|
11
12
|
|
package/src/agents/researcher.md
CHANGED
package/src/agents/reviewer.md
CHANGED
package/src/agents/security.md
CHANGED
package/src/agents/skeptic.md
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
Spring-specific review only. Generic correctness, naming and structure belong to [reviewer](reviewer.md); defer to it and do not repeat its checks.
|
|
8
8
|
|
|
9
|
+
<!-- tier: strong -->
|
|
9
10
|
## When to dispatch
|
|
10
11
|
- A change touches Spring Boot code (controllers, services, repositories, configuration, tests) and needs a framework-aware pass.
|
|
11
12
|
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
Spring Security 7 audit only. The generic audit (injection, secrets, dependencies beyond Spring) belongs to [security](security.md); defer to it.
|
|
8
8
|
|
|
9
|
+
<!-- tier: strong -->
|
|
9
10
|
## When to dispatch
|
|
10
11
|
- A Spring change touches authentication, authorization, CORS, CSRF, headers, TLS or secrets handling.
|
|
11
12
|
|
package/src/agents/steward.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_STEWARD}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs a defence of the long term against short-term wins.
|
|
7
8
|
- The user wants the architectural and maintenance consequences of a change weighed before committing.
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_USER_ADVOCATE}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs a voice for whoever consumes the outcome.
|
|
7
8
|
- The motion touches a user-facing surface: UX, an API's ergonomics, docs, error messages, or a downstream developer's workflow.
|
package/src/agents/visionary.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> {{DESC_VISIONARY}}
|
|
4
4
|
|
|
5
|
+
<!-- tier: light -->
|
|
5
6
|
## When to dispatch
|
|
6
7
|
- A council debate (the council {{SKILL}}) needs the bold, transformative version argued against incrementalism.
|
|
7
8
|
- The debate risks under-reaching: the user wants the ambitious upside of a change pushed, not just the safe slice.
|
package/src/bricks/ci-fix.md
CHANGED
|
@@ -5,8 +5,18 @@ effect: mutate
|
|
|
5
5
|
skill: debug
|
|
6
6
|
outcomes: pass, fail
|
|
7
7
|
---
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
The steps below stand alone. If a debug skill is installed, or the superpowers plugin's
|
|
9
|
+
systematic-debugging skill, load it for the general procedure; if neither is, carry on without.
|
|
10
|
+
Work against the failing check the card names:
|
|
11
|
+
|
|
12
|
+
1. Read its actual log, not a guess from the check's title, before changing anything. Find the
|
|
13
|
+
first failing job and step, and the command that produced the error.
|
|
14
|
+
2. Classify before touching anything: a real failure, an environment difference (version, path,
|
|
15
|
+
line endings, a binary missing in CI), an infra flake, or a gate on the report itself.
|
|
16
|
+
3. Reproduce under CI's own conditions (its script, flags and toolchain). Green locally and red in
|
|
17
|
+
CI has not reproduced yet. Never retry a run blindly.
|
|
18
|
+
4. Fix at the cause. Make the repo deterministic rather than CI more permissive; fix a flake at
|
|
19
|
+
its source or quarantine it with an issue and an owner, never skip it silently.
|
|
10
20
|
|
|
11
21
|
Touch only what that failure requires; this is a repair, not a chance to improve the pipeline
|
|
12
22
|
along the way.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
{{PROVIDER_HEADING}}
|
|
2
|
+
|
|
3
|
+
The `superpowers` kit is off, and this host has no superpowers plugin to stand in for it, so the brainstorm, debug, plan, code-review and review-response {{SKILLS}} are not installed. Work such a task from the general method. If no superpowers skill is in your inventory, tell the user once: turn on the `superpowers` kit.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
{{PROVIDER_HEADING}}
|
|
2
|
+
|
|
3
|
+
The `superpowers` kit is off, so the official superpowers plugin is this install's provider of the brainstorm, debug, plan, code-review and review-response {{SKILLS}}.
|
|
4
|
+
|
|
5
|
+
1. **Rank.** The plugin's {{SKILLS}} are procedure, never rank. "Invoke it at a 1% chance" never outranks a {{LAW}}, a user rule or a {{DOCTRINE}}.
|
|
6
|
+
2. **Routing.** `{{PLUGIN_PREFIX}}dispatching-parallel-agents`, `{{PLUGIN_PREFIX}}subagent-driven-development` and `{{PLUGIN_PREFIX}}executing-plans` are allowed, but the parent writes every worker's brief by the parallel-agents {{SKILL}}'s Brief checklist (BASE, write set, proof commands, commit only in its own worktree). `{{PLUGIN_PREFIX}}finishing-a-development-branch` yields to the ship {{SKILL}}: main changes only through a pull request with green checks. `{{PLUGIN_PREFIX}}test-driven-development` yields to the develop {{SKILL}}, `{{PLUGIN_PREFIX}}using-git-worktrees` to worktree, and `{{PLUGIN_PREFIX}}writing-skills` to skill-forge.
|
|
7
|
+
3. **Missing provider.** If no superpowers skill is in your inventory, tell the user once: turn on the `superpowers` kit or install the superpowers plugin.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
### Superpowers kit
|
|
2
|
+
|
|
3
|
+
The brainstorm, debug, plan, geneseed-code-review and review-response {{SKILLS}} come from this kit. They are Geneseed's vendored, modified copies of obra/superpowers (Jesse Vincent, MIT). The official superpowers plugin offers the same {{SKILLS}} under other names: brainstorming, systematic-debugging, writing-plans, requesting-code-review and receiving-code-review.
|
|
4
|
+
|
|
5
|
+
- Keep one provider, never both. If your skill list also holds a `superpowers:` skill (or a bare superpowers name on OpenCode), the two duplicate each other and the plugin injects about 800 tokens a session. Tell the user once to turn off one of them: this kit, or the plugin.
|
|
6
|
+
- These {{SKILLS}} are procedure, never rank. A Dictate, a user rule or a Doctrina always wins over what they say.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "Geneseed's vendored, modified versions of the obra/superpowers skills (Jesse Vincent, MIT): brainstorm, debug, plan, code review and review response. Turn it off when the official superpowers plugin is installed; keep one of the two.",
|
|
3
|
+
"skills": [
|
|
4
|
+
"brainstorm",
|
|
5
|
+
"debug",
|
|
6
|
+
"plan",
|
|
7
|
+
"geneseed-code-review",
|
|
8
|
+
"review-response"
|
|
9
|
+
],
|
|
10
|
+
"agents": [],
|
|
11
|
+
"rules": "kits/superpowers/rules.md",
|
|
12
|
+
"rulesWordBudget": 300,
|
|
13
|
+
"replacedBy": {
|
|
14
|
+
"upstream": "superpowers",
|
|
15
|
+
"provider": "kits/superpowers/provider.md",
|
|
16
|
+
"missing": "kits/superpowers/missing.md",
|
|
17
|
+
"plain": {
|
|
18
|
+
"brainstorm": "brainstorming pass",
|
|
19
|
+
"debug": "debugging pass",
|
|
20
|
+
"plan": "written plan",
|
|
21
|
+
"geneseed-code-review": "code review",
|
|
22
|
+
"review-response": "review-feedback pass"
|
|
23
|
+
},
|
|
24
|
+
"hosts": {
|
|
25
|
+
"claude": "superpowers:{name}",
|
|
26
|
+
"opencode": "{name}"
|
|
27
|
+
},
|
|
28
|
+
"skills": {
|
|
29
|
+
"brainstorm": "brainstorming",
|
|
30
|
+
"debug": "systematic-debugging",
|
|
31
|
+
"plan": "writing-plans",
|
|
32
|
+
"geneseed-code-review": "requesting-code-review",
|
|
33
|
+
"review-response": "receiving-code-review"
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
"catalogue": {
|
|
37
|
+
"skills": [
|
|
38
|
+
"| [brainstorm]({{DIR_SKILLS}}/brainstorm.md) | a new feature or project with no design yet, or whose goal, scope, or success criteria need pinning down first |",
|
|
39
|
+
"| [debug]({{DIR_SKILLS}}/debug.md) | a bug or failure to diagnose before fixing — a red CI run or pre-merge check included, reproduced under CI's conditions |",
|
|
40
|
+
"| [plan]({{DIR_SKILLS}}/plan.md) | a task has more than a couple of steps |",
|
|
41
|
+
"| [geneseed-code-review]({{DIR_SKILLS}}/geneseed-code-review.md) | reviewing a diff or PR |",
|
|
42
|
+
"| [review-response]({{DIR_SKILLS}}/review-response.md) | acting on review feedback you have received |"
|
|
43
|
+
]
|
|
44
|
+
}
|
|
45
|
+
}
|
package/src/modes/foreman.md
CHANGED
|
@@ -23,8 +23,9 @@ task that would block it to one background task worker, and keeps answering the
|
|
|
23
23
|
proof commands, and the rule that it commits only in its own worktree, never pushes, and
|
|
24
24
|
never merges outside its own branch; without a worktree, it never commits. It also covers
|
|
25
25
|
the **Brief checklist** in the parallel-agents {{SKILL}}: read it before you write the brief. The worker explores, implements and tests in its own context, loading {{SKILLS}}
|
|
26
|
-
as it needs them
|
|
27
|
-
|
|
26
|
+
as it needs them. It returns `STATUS: ERROR` when stuck and `STATUS: RELAY` when long.
|
|
27
|
+
The task-worker section of the developer spec sets both bounds
|
|
28
|
+
({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
|
|
28
29
|
({{DOCTRINE:one-writer-per-file}}).
|
|
29
30
|
- **A worker may lead, inside its worktree.** It may dispatch read-only helpers (explorer,
|
|
30
31
|
researcher) at any time, and writing sub-workers, each in its own worktree branched from
|
|
@@ -45,22 +46,27 @@ task that would block it to one background task worker, and keeps answering the
|
|
|
45
46
|
goes back to the same worker.
|
|
46
47
|
- **Keep a ledger; route follow-ups to the same worker.** Keep
|
|
47
48
|
`{{DIR_NOTEBOOK}}/foreman-ledger.md`, one line per live task:
|
|
48
|
-
`T3 · <task> · agent <id> · worktree <path> · <state>` (running, green, red,
|
|
49
|
-
merged, dropped). Update it on every dispatch and return; re-read it after a compaction.
|
|
49
|
+
`T3 · <task> · agent <id> · worktree <path> · <state>` (running, green, red, relay,
|
|
50
|
+
verifying, merged, dropped). Update it on every dispatch and return; re-read it after a compaction.
|
|
50
51
|
A correction, follow-up or verifier finding on a task goes to that task's worker, which
|
|
51
52
|
resumes with its full context: by `SendMessage` on Claude Code (on OpenClaude only in its
|
|
52
53
|
agent-teams mode); on OpenCode by the `subagent` tool with that worker's `sessionID` (V1:
|
|
53
54
|
`task` with `task_id`); the same call without `sessionID` (V1: `task_id`) starts a fresh
|
|
54
55
|
worker. Bob has no resume. Start a new worker only when the old one cannot be resumed —
|
|
55
56
|
the host has no resume, or its context is spent — and hand it a note: the ask, the diff
|
|
56
|
-
so far, the findings, what was tried.
|
|
57
|
-
to
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
57
|
+
so far, the findings, what was tried. On `STATUS: RELAY` (ledger `relay`), hand the task
|
|
58
|
+
off to a fresh worker on the same worktree and branch, with the handoff note. A hand-off
|
|
59
|
+
is no failure and no retry of yours. On `STATUS: ERROR` (ledger `red`) from the first
|
|
60
|
+
worker, hand off once with the findings. A task gets at most 2 hand-offs, counted in the
|
|
61
|
+
ledger line (`relay 2 of <id>`). When it needs a 3rd, or a worker that took a hand-off
|
|
62
|
+
returns `STATUS: ERROR`, take the task to the user. A new task gets a new
|
|
63
|
+
worker by default. It may go to an idle worker whose own task is settled (merged or
|
|
64
|
+
dropped) when it works in the same files and that worker's context is still under about
|
|
65
|
+
100k tokens: the worker starts it on a new branch from the current BASE, with the full
|
|
66
|
+
brief of *One worker per task* (BASE, write set, proof commands, the Brief checklist) and
|
|
67
|
+
its write set checked against every task in flight. Write the reason (same files, context size) in the task's new ledger
|
|
68
|
+
line. Otherwise start a new worker. A worker never holds two live tasks; one past that
|
|
69
|
+
size, or whose last task touched other code, retires.
|
|
64
70
|
- **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
|
|
65
71
|
uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
|
|
66
72
|
a worker's log is the worker's account, not the state — merges the branch into its own,
|
|
@@ -17,8 +17,8 @@
|
|
|
17
17
|
- **Git state:** the ref to measure (`HEAD` or `origin/main`, after a fetch) and whether the diff is staged, on disk or committed; after a restart, `git log` before redoing "uncommitted" work — a stale ref redoes every finding.
|
|
18
18
|
- **The whole write set:** every other call or literal site of a touched symbol, and its twin or generated copies, found by search before dispatch — a new field breaks the sites nobody listed.
|
|
19
19
|
- **Scratch and load:** one scratch path per unit, at most cores/2 full suites at once, and default test concurrency where spawning is CPU-bound (Windows) — shared scratch clobbers, an oversubscribed suite fails as time-outs.
|
|
20
|
-
- **Model tier:** you pick each unit's tier per task and name it in the brief. The strongest tier is your own current model (no override = inherit); step down, never up — intermediate for well-scoped writing, light for read-only search, counting and digests, your own for judgement (review, security, design) and for a retry after a failed attempt. Host with no lower tier, or model names unknown (OpenCode: set per machine): inherit. (Claude: opus > sonnet > haiku.)
|
|
21
|
-
- **Long runs and the done gate:** a suite over about two minutes runs through the host's background mechanism and is waited on to completion before the unit ends — a foreground run dies at the tool's time-out. Where the project has a done gate (`.geneseed/done-checks.txt`), its checks run unpiped
|
|
20
|
+
- **Model tier:** you pick each unit's tier per task and name it in the brief. The strongest tier is your own current model (no override = inherit); step down, never up — intermediate for well-scoped writing, light for read-only search, counting and digests, your own for judgement (review, security, design) and for a retry after a failed attempt. The one exception: a model the user asked for (in chat, or as a pin in `agent-overrides.json`) may step up. On Claude Code, an install whose carrier says `Model tiers: auto` already runs each named seat at its tier (the judgement seats — reviewer, security, architect, performance and the kit reviewers — on your model; explorer, researcher and the council on a light model; the rest on an intermediate one), so pass no model for a named seat. Host with no lower tier, or model names unknown (OpenCode: set per machine): inherit. (Claude: opus > sonnet > haiku.)
|
|
21
|
+
- **Long runs and the done gate:** a suite over about two minutes runs through the host's background mechanism and is waited on to completion before the unit ends — a foreground run dies at the tool's time-out. Wait for the completion notice; never poll with a monitor or a sleep loop. While a task worker iterates, it runs the targeted test file with output to a file, and reads only the count line and the failing test names; the full suite runs once, at the end. A crew tester's logs stay raw. Where the project has a done gate (`.geneseed/done-checks.txt`), its checks run unpiped: a redirect to a file keeps the exit code, output piped through `tail` or `grep` does not count.
|
|
22
22
|
- **Dependency installs:** whether a dependency install (`npm ci` or the stack's own) is allowed in a fresh worktree — a new worktree has none.
|
|
23
23
|
- **Host shell limits:** one plain command per call, from the worktree as working directory or with absolute paths (`git -C`, `npm --prefix`), never opening with `cd <worktree> &&`; the isolated host may refuse or ask approval for heredocs, shell variables and compound commands, so prefer plain single commands unless the brief's proof commands need one; a multi-line commit message goes through `git commit -F <file>`, the file written with the edit tools. Paths outside the worktree (a scratch path) may be refused too: scratch files go through the file tools.
|
|
24
24
|
- **One judge per copy:** when a global and a project install both run, a stand-down that lets one copy record for several is safe only for records every copy sees the same way (counts, child runs) — never for a verdict each copy reaches from its own config.
|
|
@@ -56,7 +56,13 @@ public Quote fetch(String id) { ... }
|
|
|
56
56
|
public void sendNotification() { ... }
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
Retry only idempotent calls.
|
|
59
|
+
Retry only idempotent calls.
|
|
60
|
+
- `maxRetries` counts the retries after the first call: total attempts are 1 + `maxRetries`. The default is 3 retries, 1 second apart.
|
|
61
|
+
- Every exception is retried unless `includes` or `excludes` narrow the set; both also match nested causes.
|
|
62
|
+
- `@ConcurrencyLimit` caps simultaneous calls, like a pool size. It is not a rate limiter over time.
|
|
63
|
+
- Boot 4 no longer manages a Spring Retry version (`org.springframework.retry`): use the Framework annotations above, or declare the version yourself.
|
|
64
|
+
|
|
65
|
+
Framework 7 has no circuit breaker. At the edge, use the Gateway `CircuitBreaker` filter. In-service, Resilience4j publishes a Boot 4 module (`resilience4j-spring-boot4`), but its annotation and property names were not re-verified for Boot 4 here, so check its current docs before copying old config.
|
|
60
66
|
|
|
61
67
|
## Gateway
|
|
62
68
|
Spring Cloud Gateway's reactive server uses the `spring.cloud.gateway.server.webflux.*` prefix in current releases (older guides show `spring.cloud.gateway.*`). Prefer YAML routes over the Java DSL for simple cases.
|
|
@@ -75,7 +81,7 @@ spring:
|
|
|
75
81
|
- CircuitBreaker=usersBreaker
|
|
76
82
|
```
|
|
77
83
|
|
|
78
|
-
The `CircuitBreaker` filter needs a Spring Cloud CircuitBreaker starter (for example the reactor-Resilience4j one) on the classpath.
|
|
84
|
+
The `CircuitBreaker` filter needs a Spring Cloud CircuitBreaker starter (for example the reactor-Resilience4j one) on the classpath. Pick the starter for the server stack: `spring-cloud-starter-gateway-server-webflux` (reactive, the YAML above) or `spring-cloud-starter-gateway-server-webmvc` (Servlet, its properties under `spring.cloud.gateway.server.webmvc.*`). The WebFlux server cannot share a module with a Spring MVC service.
|
|
79
85
|
|
|
80
86
|
## Observability
|
|
81
87
|
- Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those, and permit `/actuator/health/**` in the security chain. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest. `management.endpoint.health.show-components: always` with `show-details: when-authorized` tells an anonymous caller which component is down without leaking hosts or versions.
|
|
@@ -40,11 +40,13 @@ Removed or renamed in Boot 4 (do not write them): `@MockBean` and `@SpyBean`, `C
|
|
|
40
40
|
| Security configuration | Spring Security 7: lambda DSL, `authorizeHttpRequests` |
|
|
41
41
|
| `org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest` | `org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest`: slices moved to per-technology modules; import from the new packages |
|
|
42
42
|
| Jackson 2 (`com.fasterxml.jackson`) | Jackson 3 is the default (`tools.jackson`); Jackson 2 support is deprecated, `spring.jackson.use-jackson2-defaults` eases migration |
|
|
43
|
+
| Inject `ObjectMapper`, `@JsonComponent`, `@JsonMixin` | Inject the auto-configured `JsonMapper`; use `@JacksonComponent`, `@JacksonMixin`. Only the annotations keep their package (`com.fasterxml.jackson.annotation`) |
|
|
43
44
|
| `@DynamicPropertySource` for container URLs | `@ServiceConnection` on the container |
|
|
44
45
|
| MockMvc status assertions via Hamcrest | `MockMvcTester` (AssertJ) or `RestTestClient` with `@AutoConfigureRestTestClient` |
|
|
45
46
|
| OpenFeign for declarative clients | `@HttpExchange` interfaces, registered with `@ImportHttpServices` |
|
|
46
47
|
| Zipkin-only tracing setup | `spring-boot-starter-opentelemetry`, `management.opentelemetry.tracing.export.otlp.*` |
|
|
47
|
-
| Starters assumed to pull everything | Boot 4 starters are modular; add the matching starter or test starter for each technology, and read the migration guide when a class vanishes |
|
|
48
|
+
| Starters assumed to pull everything | Boot 4 starters are modular; add the matching starter or test starter (`spring-boot-starter-<technology>-test`) for each technology, and read the migration guide when a class vanishes |
|
|
49
|
+
| `spring-boot-starter-web`, `-aop`, `-oauth2-*`; `flyway-core` or `liquibase-core` alone | `spring-boot-starter-webmvc`, `-aspectj`, `-security-oauth2-*`; `spring-boot-starter-flyway`, `-liquibase`. The old web and OAuth2 names are deprecated |
|
|
48
50
|
|
|
49
51
|
## Side files
|
|
50
52
|
- **Web/REST** -> read [spring-boot/web.md](spring-boot/web.md) and follow it.
|
|
@@ -18,9 +18,9 @@ Target stack: Spring Boot 4, JUnit 5, Mockito, AssertJ.
|
|
|
18
18
|
| Controller mapping, validation, serialization | `@WebMvcTest(X.class)` + `MockMvcTester` + `@MockitoBean` |
|
|
19
19
|
| Repository queries, mappings | `@DataJpaTest` against the real database engine |
|
|
20
20
|
| Whole app over HTTP | `@SpringBootTest(webEnvironment = RANDOM_PORT)` + `@AutoConfigureRestTestClient` |
|
|
21
|
-
| Whole app, no server | `@SpringBootTest` + `@AutoConfigureMockMvc` |
|
|
21
|
+
| Whole app, no server | `@SpringBootTest` + `@AutoConfigureMockMvc` (`@SpringBootTest` alone no longer gives MockMvc) |
|
|
22
22
|
|
|
23
|
-
Boot 4 split the test support into modules: slice annotations live in `org.springframework.boot.<module>.test.autoconfigure` (e.g. `org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest`); `@AutoConfigureTestDatabase` is in `org.springframework.boot.jdbc.test.autoconfigure`. Let the IDE import them. Use the matching test starter (`spring-boot-starter-data-jpa-test`, and so on) so each slice is on the classpath.
|
|
23
|
+
Boot 4 split the test support into modules: slice annotations live in `org.springframework.boot.<module>.test.autoconfigure` (e.g. `org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest`); `@AutoConfigureTestDatabase` is in `org.springframework.boot.jdbc.test.autoconfigure`. Let the IDE import them. Use the matching test starter (`spring-boot-starter-data-jpa-test`, and so on) so each slice is on the classpath. `@AutoConfigureRestTestClient` is in the `spring-boot-resttestclient` module, which `spring-boot-starter-webmvc-test` brings in; without that starter, add the module in test scope.
|
|
24
24
|
|
|
25
25
|
## Mocking beans
|
|
26
26
|
|
|
@@ -80,7 +80,7 @@ class ContainersConfig {
|
|
|
80
80
|
class AuthorRepositoryTests { /* ... */ }
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
-
- Testcontainers 2 containers are non-generic and live in per-module packages (`org.testcontainers.postgresql.PostgreSQLContainer`, artifact `testcontainers-postgresql`).
|
|
83
|
+
- Testcontainers 2 containers are non-generic and live in per-module packages (`org.testcontainers.postgresql.PostgreSQLContainer`, artifact `testcontainers-postgresql`). With them, add `spring-boot-testcontainers` and, for `@Testcontainers`/`@Container`, `org.testcontainers:testcontainers-junit-jupiter`, all in test scope.
|
|
84
84
|
- The default `replace = NON_TEST` already keeps a `@ServiceConnection` data source; `replace = NONE` is only needed for a non-test `DataSource` you defined yourself.
|
|
85
85
|
- Where `@ServiceConnection` has no support for the container, use `@Testcontainers` + `@Container static` + `@DynamicPropertySource` to register the properties.
|
|
86
86
|
- Share one container configuration across tests so the context cache is reused.
|