geneseed 5.0.1 → 5.0.4
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 +92 -0
- package/README.md +4 -4
- package/SHIPPED.md +2 -2
- package/adapters/claude-code/README.md +11 -5
- package/adapters/openclaude/README.md +3 -1
- package/adapters/opencode/HOW-OPENCODE-LOADS.md +3 -0
- package/adapters/opencode/plugins/geneseed-context.js +12 -1
- package/adapters/opencode/plugins/geneseed-guard.js +594 -73
- package/adapters/opencode/plugins/geneseed-learn.js +1 -1
- package/adapters/opencode/plugins/geneseed-workflow.js +1 -1
- package/adapters/opencode/workflows/_runtime.js +1 -1
- package/bin/geneseed-cli.mjs +3 -0
- package/bin/geneseed-hook.mjs +31 -9
- package/docs/PRD.md +1 -1
- package/docs/README.md +4 -1
- package/docs/concepts/enforcement-table.md +23 -4
- package/docs/concepts/exclusions.md +48 -2
- package/docs/concepts/factories.md +151 -0
- 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 +5 -3
- package/docs/concepts/hosts.md +1 -1
- package/docs/concepts/kits.md +18 -0
- package/docs/concepts/loop-gates.md +3 -0
- package/docs/concepts/loops.md +1 -0
- package/docs/concepts/rules.md +1 -1
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/concepts/skills.md +1 -1
- package/docs/extending.md +8 -2
- package/docs/guides/autostart.md +29 -3
- package/docs/guides/choose-your-setup.md +1 -1
- package/docs/guides/migrate.md +1 -1
- package/docs/guides/run-a-factory.md +88 -0
- package/docs/guides/set-up-ownership.md +1 -0
- package/docs/guides/uninstall.md +1 -1
- package/docs/reference/factory-actions.md +22 -0
- package/docs/reference/loop-actions.md +1 -1
- package/docs/reference/plugin-activity.md +1 -1
- 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 +101 -17
- package/harness.config.json +1 -1
- package/js/README.md +21 -3
- package/js/build/args.mjs +14 -2
- package/js/build/emit-claude.mjs +9 -1
- package/js/build/emit-opencode.mjs +2 -1
- package/js/build/source.mjs +28 -3
- package/js/cli-table.json +287 -3
- package/js/factory/cli.mjs +153 -0
- package/js/factory/graph.mjs +245 -0
- package/js/factory/registry.mjs +71 -0
- package/js/factory/state.mjs +429 -0
- package/js/hosts/activity.mjs +3 -3
- package/js/hosts/geneseed-dir.mjs +2 -2
- package/js/hosts/gitref.mjs +21 -0
- package/js/hosts/hooks-context.mjs +71 -15
- package/js/hosts/hooks-done.mjs +3 -1
- package/js/hosts/hooks-learn.mjs +1 -1
- package/js/hosts/hooks-prims.mjs +271 -1
- package/js/hosts/hooks.mjs +409 -151
- package/js/hosts/hosts.mjs +22 -0
- package/js/hosts/installs.mjs +9 -5
- package/js/hosts/settings.mjs +128 -27
- package/js/hosts/shim.mjs +155 -7
- package/js/hosts/store-watch.mjs +36 -11
- package/js/inspect/checks-authoring.mjs +11 -1
- package/js/inspect/cost.mjs +91 -5
- package/js/inspect/diff.mjs +2 -1
- package/js/inspect/doctor.mjs +2 -1
- package/js/inspect/inventory.mjs +2 -1
- package/js/inspect/validate.mjs +1 -1
- package/js/loop/catalog.mjs +24 -12
- package/js/loop/cli.mjs +21 -15
- package/js/loop/graph.mjs +13 -4
- package/js/loop/registry.mjs +65 -28
- package/js/loop/state.mjs +18 -8
- package/js/maintain/migrate.mjs +2 -2
- package/js/maintain/uninstall.mjs +5 -1
- package/js/web/actions.mjs +17 -1
- package/js/web/api.mjs +52 -11
- package/js/web/catalog.mjs +38 -2
- package/js/web/daemon.mjs +136 -6
- package/js/web/handler.mjs +14 -5
- package/js/web/routes.mjs +12 -4
- package/js/web/server.mjs +4 -1
- package/package.json +1 -1
- package/registry.json +35 -0
- package/src/AGENT.md.tmpl +18 -24
- 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/bricks/docs-update.md +5 -0
- package/src/bricks/holdout-write.md +23 -0
- package/src/bricks/holdout.md +25 -0
- package/src/bricks/intake.md +18 -0
- package/src/bricks/merge-gate.md +22 -0
- package/src/bricks/pr-open.md +21 -0
- package/src/bricks/retro.md +17 -0
- package/src/bricks/test.md +4 -1
- package/src/bricks/triage.md +19 -0
- package/src/doctrines/comms.md +29 -41
- package/src/doctrines/craft.md +3 -10
- package/src/doctrines/ops.md +4 -15
- package/src/doctrines/process.md +24 -19
- package/src/doctrines/rigor.md +1 -5
- package/src/factories/analysis-to-build.json +34 -0
- package/src/factories/bug-report-to-fix.json +32 -0
- package/src/factories/issue-to-pr.json +49 -0
- 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/_checkpoints.md +1 -0
- package/src/skills/_self-improvement.md +12 -9
- package/src/skills/adhd.md +1 -1
- package/src/skills/compose-ops.md +58 -0
- package/src/skills/factory-forge.md +97 -0
- package/src/skills/factory.md +126 -0
- package/src/skills/gitlab-ci.md +51 -0
- package/src/skills/jenkins-pipeline.md +56 -0
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/pipeline.md +2 -2
- package/src/skills/rule.md +24 -18
- package/src/skills/skill-forge.md +24 -6
- package/src/skills/workflow.md +2 -1
- package/themes/_TEMPLATE.json +9 -4
- package/themes/biker.json +9 -4
- package/themes/commentator.json +9 -4
- package/themes/cyberpunk.json +9 -4
- package/themes/gamer.json +9 -4
- package/themes/imperial.json +9 -4
- package/themes/joker.json +9 -4
- package/themes/marvin.json +9 -4
- package/themes/mean.json +9 -4
- package/themes/military.json +9 -4
- package/themes/neutral.json +9 -4
- package/themes/pirate.json +9 -4
- package/themes/sports.json +9 -4
- package/themes/verstappen.json +9 -4
- package/themes/wizard.json +9 -4
- package/web/dist/assets/ActiveLoops-BTHIaRhn.js +1 -0
- package/web/dist/assets/Activity-BaoxwVFH.js +1 -0
- package/web/dist/assets/ActivityDetail-C_bFD0rW.js +1 -0
- package/web/dist/assets/{Bonsai-C1iBAt4v.js → Bonsai-B01lLf0m.js} +1 -1
- package/web/dist/assets/{CopyButton-DJ3a4N88.js → CopyButton-Bc66KPyA.js} +1 -1
- package/web/dist/assets/Dashboard-X7GZzGJp.js +2 -0
- package/web/dist/assets/{Docs-Kffdg5uV.js → Docs-LRYVnGLG.js} +3 -3
- package/web/dist/assets/Factories-ARenKBiP.js +1 -0
- package/web/dist/assets/{GreenhouseView-k56_cBSF.js → GreenhouseView-CfWR2-sX.js} +1 -1
- package/web/dist/assets/{Installs-DtEKLC9h.js → Installs-nfFHnovH.js} +3 -3
- package/web/dist/assets/{JournalView-RQnk5l7I.js → JournalView-lpOHcHKK.js} +1 -1
- package/web/dist/assets/Kits-Bw5EQl_i.js +1 -0
- package/web/dist/assets/Laws-CnZJ0wjZ.js +4 -0
- package/web/dist/assets/LibRows-Hqvf1beK.js +1 -0
- package/web/dist/assets/Library-JaSsp6Yr.js +3 -0
- package/web/dist/assets/Loops-ZaHC5MVl.js +2 -0
- package/web/dist/assets/{OperatorHudView-CM5jNPwL.js → OperatorHudView-CggG0_sK.js} +1 -1
- package/web/dist/assets/Personal-BObvlb70.js +2 -0
- package/web/dist/assets/Settings-BFfPMPc9.js +1 -0
- package/web/dist/assets/Tabs-B594Pad_.js +1 -0
- package/web/dist/assets/api-DLDVY3K-.js +1 -0
- package/web/dist/assets/index-DsLmKHw0.js +6 -0
- package/web/dist/assets/index-DvPjphz0.css +1 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Activity-Ci4PZco3.js +0 -1
- package/web/dist/assets/ActivityDetail-C8hroCND.js +0 -1
- package/web/dist/assets/Dashboard-C_On4KXw.js +0 -2
- package/web/dist/assets/Kits-CXkEBpnf.js +0 -1
- package/web/dist/assets/Laws-DhhIVqmh.js +0 -3
- package/web/dist/assets/Library-CAUiEoJo.js +0 -3
- package/web/dist/assets/Loops-LKD8mF4E.js +0 -2
- package/web/dist/assets/Personal-B6Uoly3C.js +0 -2
- package/web/dist/assets/RailCats-DQxxYBEP.js +0 -1
- package/web/dist/assets/Settings-BTe6-wda.js +0 -1
- package/web/dist/assets/Tabs-CbdDWTp_.js +0 -1
- package/web/dist/assets/api-D_r0Jtla.js +0 -1
- package/web/dist/assets/index-HfGmYXab.js +0 -3
- package/web/dist/assets/index-ao3M-Fhm.css +0 -1
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "analysis-to-build",
|
|
3
|
+
"description": "Turn an analysis (a document, pasted text or a request) into a spec whose task list you approve, build each task in turn with the feature loop in one worktree, play the holdout scenarios it never saw, then open one pull request and wait for green CI; a failed scenario or red CI sends the work back to the loop as one more task, twice at most each. The merge stays yours.",
|
|
4
|
+
"category": "development",
|
|
5
|
+
"rules": [
|
|
6
|
+
"Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
|
|
7
|
+
"Push only this worktree's own branch."
|
|
8
|
+
],
|
|
9
|
+
"stages": ["intake", "spec", "holdout-write", "loop:feature", "holdout", "pr-open", "merge-gate", "retro"],
|
|
10
|
+
"start": "intake",
|
|
11
|
+
"edges": [
|
|
12
|
+
{ "from": "intake", "on": "pass", "to": "spec" },
|
|
13
|
+
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
14
|
+
{ "from": "spec", "on": "pass", "to": "holdout-write" },
|
|
15
|
+
{ "from": "spec", "on": "fail", "to": "$stop" },
|
|
16
|
+
{ "from": "holdout-write", "on": "pass", "to": "loop:feature" },
|
|
17
|
+
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
18
|
+
{ "from": "loop:feature", "on": "pass", "to": "holdout" },
|
|
19
|
+
{ "from": "loop:feature", "on": "fail", "to": "$stop" },
|
|
20
|
+
{ "from": "holdout", "on": "pass", "to": "pr-open" },
|
|
21
|
+
{ "from": "holdout", "on": "fail", "to": "loop:feature" },
|
|
22
|
+
{ "from": "holdout", "on": "error", "to": "$stop" },
|
|
23
|
+
{ "from": "pr-open", "on": "pass", "to": "merge-gate" },
|
|
24
|
+
{ "from": "pr-open", "on": "fail", "to": "$stop" },
|
|
25
|
+
{ "from": "merge-gate", "on": "pass", "to": "retro" },
|
|
26
|
+
{ "from": "merge-gate", "on": "fail", "to": "loop:feature" },
|
|
27
|
+
{ "from": "merge-gate", "on": "none", "to": "retro" },
|
|
28
|
+
{ "from": "retro", "on": "pass", "to": "$close" }
|
|
29
|
+
],
|
|
30
|
+
"cycles": [
|
|
31
|
+
{ "name": "holdout", "nodes": ["loop:feature", "holdout"], "max": 2 },
|
|
32
|
+
{ "name": "ci", "nodes": ["loop:feature", "holdout", "pr-open", "merge-gate"], "max": 2 }
|
|
33
|
+
]
|
|
34
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "bug-report-to-fix",
|
|
3
|
+
"description": "Take one bug report, fix it with the bugfix loop, play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed scenario or red CI sends the fix back to the loop, twice at most each. The merge stays yours.",
|
|
4
|
+
"category": "development",
|
|
5
|
+
"rules": [
|
|
6
|
+
"Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
|
|
7
|
+
"Push only this worktree's own branch."
|
|
8
|
+
],
|
|
9
|
+
"stages": ["intake", "holdout-write", "loop:bugfix", "holdout", "pr-open", "merge-gate", "retro"],
|
|
10
|
+
"start": "intake",
|
|
11
|
+
"edges": [
|
|
12
|
+
{ "from": "intake", "on": "pass", "to": "holdout-write" },
|
|
13
|
+
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
14
|
+
{ "from": "holdout-write", "on": "pass", "to": "loop:bugfix" },
|
|
15
|
+
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
16
|
+
{ "from": "loop:bugfix", "on": "pass", "to": "holdout" },
|
|
17
|
+
{ "from": "loop:bugfix", "on": "fail", "to": "$stop" },
|
|
18
|
+
{ "from": "holdout", "on": "pass", "to": "pr-open" },
|
|
19
|
+
{ "from": "holdout", "on": "fail", "to": "loop:bugfix" },
|
|
20
|
+
{ "from": "holdout", "on": "error", "to": "$stop" },
|
|
21
|
+
{ "from": "pr-open", "on": "pass", "to": "merge-gate" },
|
|
22
|
+
{ "from": "pr-open", "on": "fail", "to": "$stop" },
|
|
23
|
+
{ "from": "merge-gate", "on": "pass", "to": "retro" },
|
|
24
|
+
{ "from": "merge-gate", "on": "fail", "to": "loop:bugfix" },
|
|
25
|
+
{ "from": "merge-gate", "on": "none", "to": "retro" },
|
|
26
|
+
{ "from": "retro", "on": "pass", "to": "$close" }
|
|
27
|
+
],
|
|
28
|
+
"cycles": [
|
|
29
|
+
{ "name": "holdout", "nodes": ["loop:bugfix", "holdout"], "max": 2 },
|
|
30
|
+
{ "name": "ci", "nodes": ["loop:bugfix", "holdout", "pr-open", "merge-gate"], "max": 2 }
|
|
31
|
+
]
|
|
32
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "issue-to-pr",
|
|
3
|
+
"description": "Take one issue, let triage pick the lane that fits (the bugfix, feature, deps-upgrade or refactor loop, or a docs-only update), play the holdout scenarios it never saw, open the pull request and wait for green CI; a failed scenario or red CI sends the work back to that lane, twice at most each. The merge stays yours.",
|
|
4
|
+
"category": "development",
|
|
5
|
+
"rules": [
|
|
6
|
+
"Never merge, and never enable auto-merge: the run ends at an open PR with green CI.",
|
|
7
|
+
"Push only this worktree's own branch."
|
|
8
|
+
],
|
|
9
|
+
"stages": [
|
|
10
|
+
"intake", "holdout-write", "triage",
|
|
11
|
+
"loop:bugfix", "loop:feature", "loop:deps-upgrade", "loop:refactor", "docs-update",
|
|
12
|
+
"holdout", "pr-open", "merge-gate", "retro"
|
|
13
|
+
],
|
|
14
|
+
"start": "intake",
|
|
15
|
+
"edges": [
|
|
16
|
+
{ "from": "intake", "on": "pass", "to": "holdout-write" },
|
|
17
|
+
{ "from": "intake", "on": "fail", "to": "$stop" },
|
|
18
|
+
{ "from": "holdout-write", "on": "pass", "to": "triage" },
|
|
19
|
+
{ "from": "holdout-write", "on": "fail", "to": "$stop" },
|
|
20
|
+
{ "from": "triage", "on": "bug", "to": "loop:bugfix" },
|
|
21
|
+
{ "from": "triage", "on": "feature", "to": "loop:feature" },
|
|
22
|
+
{ "from": "triage", "on": "deps", "to": "loop:deps-upgrade" },
|
|
23
|
+
{ "from": "triage", "on": "refactor", "to": "loop:refactor" },
|
|
24
|
+
{ "from": "triage", "on": "docs", "to": "docs-update" },
|
|
25
|
+
{ "from": "triage", "on": "fail", "to": "$stop" },
|
|
26
|
+
{ "from": "loop:bugfix", "on": "pass", "to": "holdout" },
|
|
27
|
+
{ "from": "loop:bugfix", "on": "fail", "to": "$stop" },
|
|
28
|
+
{ "from": "loop:feature", "on": "pass", "to": "holdout" },
|
|
29
|
+
{ "from": "loop:feature", "on": "fail", "to": "$stop" },
|
|
30
|
+
{ "from": "loop:deps-upgrade", "on": "pass", "to": "holdout" },
|
|
31
|
+
{ "from": "loop:deps-upgrade", "on": "fail", "to": "$stop" },
|
|
32
|
+
{ "from": "loop:refactor", "on": "pass", "to": "holdout" },
|
|
33
|
+
{ "from": "loop:refactor", "on": "fail", "to": "$stop" },
|
|
34
|
+
{ "from": "docs-update", "on": "pass", "to": "holdout" },
|
|
35
|
+
{ "from": "holdout", "on": "pass", "to": "pr-open" },
|
|
36
|
+
{ "from": "holdout", "on": "fail", "to": "$lane" },
|
|
37
|
+
{ "from": "holdout", "on": "error", "to": "$stop" },
|
|
38
|
+
{ "from": "pr-open", "on": "pass", "to": "merge-gate" },
|
|
39
|
+
{ "from": "pr-open", "on": "fail", "to": "$stop" },
|
|
40
|
+
{ "from": "merge-gate", "on": "pass", "to": "retro" },
|
|
41
|
+
{ "from": "merge-gate", "on": "fail", "to": "$lane" },
|
|
42
|
+
{ "from": "merge-gate", "on": "none", "to": "retro" },
|
|
43
|
+
{ "from": "retro", "on": "pass", "to": "$close" }
|
|
44
|
+
],
|
|
45
|
+
"cycles": [
|
|
46
|
+
{ "name": "holdout", "nodes": ["$lane", "holdout"], "max": 2 },
|
|
47
|
+
{ "name": "ci", "nodes": ["$lane", "holdout", "pr-open", "merge-gate"], "max": 2 }
|
|
48
|
+
]
|
|
49
|
+
}
|
|
@@ -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.
|
package/src/skills/adhd.md
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
**Precedence.** This mode shapes *presentation* only. The harness file itself — the {{LAWS}}, `user-rules.md`, the active doctrines (the comms ones above all) — outranks it; where they collide, the rule wins and the shape stays. The known collisions resolve so:
|
|
14
14
|
- **Readiness sigil.** On a session's first reply the sigil stays the first line; the next action leads right after it.
|
|
15
15
|
- **Cap at five** (step 9) groups and orders what is shown — it never renumbers, merges or drops a {{DOCTRINE:codes-that-persist}} code; an item gets its code when it is first shown, and a code once shown is never dropped.
|
|
16
|
-
- **The closing next action** (step 3) takes the {{DOCTRINE:
|
|
16
|
+
- **The closing next action** (step 3) takes the {{DOCTRINE:codes-that-persist}} form — `👉` for an act to do, `❓` for a question, one ask per block.
|
|
17
17
|
- **No recap** (step 10) never deletes the verification command and its output owed by {{LAW:verify-before-asserting}}, nor the judgment calls owed by {{DOCTRINE:declare-the-judgment-calls}} — those are evidence, not recap.
|
|
18
18
|
- **Harness duties** outrank brevity: announce a tool call when the host requires it, do the work rather than asking "want me to?", and point time estimates at whoever runs the steps.
|
|
19
19
|
|
|
@@ -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.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# {{SKILL}}: factory-forge
|
|
2
|
+
|
|
3
|
+
> {{DESC_FACTORY_FORGE}}
|
|
4
|
+
|
|
5
|
+
**Trigger:** the user wants a new factory, or to change one. For example: "make a factory that
|
|
6
|
+
takes a feature request to a PR", "add a security scan before the PR opens", "send red CI back
|
|
7
|
+
to the loop three times, not two".
|
|
8
|
+
|
|
9
|
+
## Procedure
|
|
10
|
+
|
|
11
|
+
1. **See what exists:** `geneseed factory list` (the factories) and `geneseed loop check` (every
|
|
12
|
+
brick with its outcomes, and every loop template). Adapting a factory starts from its file.
|
|
13
|
+
2. **Interview, one question at a time:**
|
|
14
|
+
- **name** — kebab-case, the file stem. A factory named like an existing one replaces it at
|
|
15
|
+
every level below; say so to the user.
|
|
16
|
+
- **what it does** — one line; it becomes `description`. A short `category` (`development`).
|
|
17
|
+
- **input** — what one run takes: a request, a document, or a GitHub or GitLab issue. The
|
|
18
|
+
first stage reads it, usually `intake`.
|
|
19
|
+
- **stages**, in order — each a brick name or `loop:<template>` (a whole loop: outcomes `pass`
|
|
20
|
+
and `fail`).
|
|
21
|
+
- **forks** — where the work takes one way or another, use a brick with named outcomes (a
|
|
22
|
+
**fork**, such as `triage`: `bug`, `feature`, `deps`, `refactor`, `docs`, `fail`). Give each
|
|
23
|
+
named outcome its own edge to its own **lane**: a loop for work that changes code, or a brick
|
|
24
|
+
where a loop adds nothing (`docs` → `docs-update`). Every lane joins the same path after it
|
|
25
|
+
(`holdout`, then `pr-open` and `merge-gate`). An outcome the factory does not offer goes to
|
|
26
|
+
`$stop`.
|
|
27
|
+
- **where a human gates** — a gate belongs to the brick (`gate: human` in its frontmatter,
|
|
28
|
+
narrowed by `gateOn`), never to the factory. A stage that must hold for a person uses a
|
|
29
|
+
gated brick: an existing one, or one from step 4.
|
|
30
|
+
- **routes** — for every outcome of every stage: the next stage, `$close` or `$stop`.
|
|
31
|
+
- **failures that route back** — each one to an earlier stage, with its `max` from 1 to 5.
|
|
32
|
+
Each becomes a `cycles` entry. After a fork, route back to `$lane`, the lane the run took,
|
|
33
|
+
and start the cycle's `nodes` with `$lane`.
|
|
34
|
+
- **rules** — optional lines every stage receives ("Never merge.").
|
|
35
|
+
- **level** — project `<repo>/.geneseed/factories/` (this repository, shared with the team
|
|
36
|
+
once committed) or global `$XDG_CONFIG_HOME/geneseed/factories/` (default
|
|
37
|
+
`~/.config/geneseed/factories/`, every project on this machine). Shipped `src/factories/`
|
|
38
|
+
only inside the Geneseed repository. At project level, when
|
|
39
|
+
`git check-ignore -q .geneseed/factories/<name>.json` exits 0, the repository's
|
|
40
|
+
`.geneseed/.gitignore` predates `!/factories/`: tell the user the file stays personal until
|
|
41
|
+
they add that line.
|
|
42
|
+
3. **Write `<level>/<name>.json`**, `name` equal to the file stem, in the shape of the shipped
|
|
43
|
+
`bug-report-to-fix`:
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"name": "<name>", "description": "<one line>", "category": "<category>",
|
|
48
|
+
"rules": ["<optional>"],
|
|
49
|
+
"stages": ["intake", "loop:<template>", "pr-open", "merge-gate", "retro"],
|
|
50
|
+
"start": "intake",
|
|
51
|
+
"edges": [{ "from": "<stage>", "on": "<outcome>", "to": "<stage | $lane | $close | $stop>" }],
|
|
52
|
+
"cycles": [{ "name": "<name>", "nodes": ["<first stage of the lap, or $lane>", "..."], "max": 2 }]
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
A cycle's `nodes[0]` is where every lap starts, and every route back targets it. A factory
|
|
57
|
+
with a fork follows the shipped `issue-to-pr`: one edge per named outcome out of `triage`,
|
|
58
|
+
and `$lane` as the target of each route back and as `nodes[0]` of its cycles.
|
|
59
|
+
4. **A brick that does not exist** — never write it here. Offer the `brick-forge` {{SKILL}}, or
|
|
60
|
+
run it when the user says so, then come back to this step. `brick-forge` is the only
|
|
61
|
+
{{SKILL}} that writes bricks.
|
|
62
|
+
5. **Check:** `geneseed factory check --factory <name>` (or the `.json` path). For each problem,
|
|
63
|
+
tell the user which rule it names, then fix the file and re-run until it prints `ok: true`:
|
|
64
|
+
- `no factory named "<name>"` — `--factory <name>` found no loadable file of that name. Run
|
|
65
|
+
a bare `geneseed factory check`: it lists every catalogue problem, among them `not JSON`
|
|
66
|
+
(the file does not parse) and `does not match the file name` (its `name` is not its stem).
|
|
67
|
+
- `must be a non-empty string` / `entry … must have` / `is listed twice` / `rules: must be` —
|
|
68
|
+
the shape: a `name`, well-formed `edges` and `cycles` entries, each stage once, `rules` a
|
|
69
|
+
list of non-empty strings.
|
|
70
|
+
- `is not a stage` — an edge endpoint, `start` or a cycle node names no stage (often a typo).
|
|
71
|
+
- `no brick named` / `no loop template named` / `brick unavailable` — a stage that does not
|
|
72
|
+
exist or cannot run here: fix the name, or step 4.
|
|
73
|
+
- `is not an outcome of` / `no edge for outcome` / `edges for outcome` — every outcome of a
|
|
74
|
+
stage has exactly one edge, and an edge uses only outcomes the stage declares (`error` may
|
|
75
|
+
go without one: it stops the run).
|
|
76
|
+
- `$close is not reachable` — no path from `start` ends the run well.
|
|
77
|
+
- `has no declared cycle around it` — a route back with no `cycles` entry.
|
|
78
|
+
- `max must be an integer` — a cycle's `max` is 1 to 5.
|
|
79
|
+
- `entered at …, not at its first stage` — a way into the cycle lands mid-cycle: reorder its
|
|
80
|
+
`nodes` or move the edge.
|
|
81
|
+
- `laps without spending a declared cycle` — a route back to the middle of a cycle: target
|
|
82
|
+
its first stage.
|
|
83
|
+
- `$lane: no fork chooses a lane` / `before any fork has chosen a lane` — `$lane` needs a
|
|
84
|
+
fork on every path to it. `a fork's edge names its lane` — a fork's edge targets its lane
|
|
85
|
+
stage, never `$lane`.
|
|
86
|
+
- `retired` — the file still uses `loop:$triaged` or `loops`: list each loop as its own stage,
|
|
87
|
+
give the fork one edge per lane, and route back to `$lane`. Rewrite it with the user; never
|
|
88
|
+
silently.
|
|
89
|
+
6. **Hand off:** tell the user the file, then the `factory` {{SKILL}} runs it
|
|
90
|
+
(`geneseed factory init --factory <name> …`). Do not start a run unasked.
|
|
91
|
+
|
|
92
|
+
## Done when
|
|
93
|
+
|
|
94
|
+
- The factory file exists at the chosen level, `geneseed factory check --factory <name>` prints
|
|
95
|
+
`ok: true`, and no brick was written outside `brick-forge`.
|
|
96
|
+
|
|
97
|
+
<!-- INCLUDE: skills/_self-improvement.md -->
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# {{SKILL}}: factory
|
|
2
|
+
|
|
3
|
+
> {{DESC_FACTORY}}
|
|
4
|
+
|
|
5
|
+
**Trigger:** the user asks to run a factory, or to carry one work item (a request, a document,
|
|
6
|
+
a GitHub or GitLab issue) through to an open pull request with green CI; or names a factory
|
|
7
|
+
(`analysis-to-build`, `bug-report-to-fix`, `issue-to-pr`).
|
|
8
|
+
|
|
9
|
+
## What it is
|
|
10
|
+
|
|
11
|
+
`geneseed factory` is a state machine kept in `FACTORY.md` at the worktree's root. A stage is a
|
|
12
|
+
brick or a whole loop; the engine decides every transition, cycle count and stop, and you run the
|
|
13
|
+
stage it hands you and report the outcome. Every action prints one JSON object: act on its keys,
|
|
14
|
+
never on your own reading of the graph. The run ends at an open PR with green CI. **The merge is
|
|
15
|
+
never part of a run.**
|
|
16
|
+
|
|
17
|
+
**Holdout rule.** The `holdout-write` stage writes scenarios the developer never sees, and the
|
|
18
|
+
`holdout` stage plays them before the PR. Both run as the `tester` {{AGENT}}, never as the
|
|
19
|
+
developer and never inline. Never put holdout content (anything under `~/.config/geneseed/holdout/`)
|
|
20
|
+
into any brief, prompt, note or `--carry` you hand on; never name that folder to a developer or a
|
|
21
|
+
loop; never read it on a developer's behalf. Record `holdout-write`'s pass with the `--carry` it
|
|
22
|
+
received, unchanged, and a `holdout` fail with the one-sentence file it reported. No hook refuses a
|
|
23
|
+
read of the folder on any host: the folder is protected only by its place outside the worktree, by `holdout`'s `error`
|
|
24
|
+
when the diff touches it, and by this rule.
|
|
25
|
+
|
|
26
|
+
## Setup
|
|
27
|
+
|
|
28
|
+
1. Pick a short kebab-case `<slug>` from the work item. Create the run's worktree:
|
|
29
|
+
`git worktree add ../<repo>-factory-<slug> -b loop/factory-<slug>`, then make it the session's
|
|
30
|
+
working directory with its own command. Every later command runs there as written below: no
|
|
31
|
+
`cd` prefix, no `git -C`. Several runs may share a repo, each in its own worktree.
|
|
32
|
+
2. Use the factory the user names, else `geneseed factory list` and pick the one whose
|
|
33
|
+
description fits; confirm the pick with the user when two fit. None fits → the `factory-forge` {{SKILL}}.
|
|
34
|
+
3. `geneseed factory init --title "<title>" --requirement "<the user's ask, in their words>" --factory <name> --input "<issue URL, file path or pasted text>"`.
|
|
35
|
+
A refused factory prints `problems`: report them, never edit the graph to get past them.
|
|
36
|
+
|
|
37
|
+
## The cycle
|
|
38
|
+
|
|
39
|
+
Repeat `geneseed factory next` and act on its JSON:
|
|
40
|
+
|
|
41
|
+
- **`{stage, prompt, outcomes}`** — a brick stage. Dispatch its `agent` (or follow its `skill`)
|
|
42
|
+
with the `prompt`, the `requirement`, the `input`, the `carry` and the factory's `rules`. Then:
|
|
43
|
+
`git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome> --carry "<the file path the stage reported>"`.
|
|
44
|
+
The `--carry` is how the next stage gets this one's finding. Always use that porcelain form:
|
|
45
|
+
plain `--porcelain` folds a new directory into one line, which the engine refuses.
|
|
46
|
+
A fork stage (such as `triage`) also gets `lanes`: each outcome it may report, with the stage
|
|
47
|
+
it leads to. Record the outcome it reported (`--outcome docs`): that outcome names the lane,
|
|
48
|
+
and a later route back to `$lane` returns to it.
|
|
49
|
+
A brick stage with `effect: mutate` (a `docs-update` lane) commits what it changed before the
|
|
50
|
+
record: `git add <the files it named>`, then `git commit -m "factory(<slug>): <stage>"`. The
|
|
51
|
+
engine refuses a dirty tree after any stage outside a loop.
|
|
52
|
+
The `spec` stage writes `specs/<slug>/spec.md` (the run's slug; a gate amend reaches it as the
|
|
53
|
+
`carry`, not as a LOOP.md note) and reports with
|
|
54
|
+
`git status --porcelain --untracked-files=all | geneseed factory record --outcome <outcome> --spec specs/<slug>/spec.md --carry <its finding file>`, so the gate shows the user what to review.
|
|
55
|
+
Its gate holds for the user's review of the task list. After `decide --verdict ok`, commit the
|
|
56
|
+
spec before the first loop: `git add specs/<slug>/spec.md`, then
|
|
57
|
+
`git commit -m "factory(<slug>): spec"` (it asks). An uncommitted spec stops the loop's first
|
|
58
|
+
read brick; the engine exempts it only until then.
|
|
59
|
+
- **`{stage, loop, notes}`** — a loop stage: see *Loop stages*.
|
|
60
|
+
- **`{awaiting}`** — a `gate: human` stage holds. Show the user the `stage`, the `outcome` it
|
|
61
|
+
reported and the file its `note` names, then **end the run** and wait. On their answer:
|
|
62
|
+
`geneseed factory decide --verdict ok|no|amend --note "<their words>"` — `ok` follows the
|
|
63
|
+
reported outcome's edge, `no` stops, `amend` re-runs the stage with their note — and continue.
|
|
64
|
+
- **`{terminal: "$close"}`** or **`{terminal: "$stop"}`** — see *The end*.
|
|
65
|
+
- A `record` or `decide` result (`{stage}`, `{awaiting}`, `{stopped}`) — call `next` again.
|
|
66
|
+
- **`{error}`** — read it; it names the step you skipped or the evidence `record` lacks. Do that
|
|
67
|
+
step. Never edit the state block in `FACTORY.md` to get past it.
|
|
68
|
+
|
|
69
|
+
## Loop stages
|
|
70
|
+
|
|
71
|
+
4. Call `next` before every loop, each task of a spec included: it records the launch that
|
|
72
|
+
`record` later checks. When it refuses a `LOOP.md` left by the previous loop, remove it:
|
|
73
|
+
`git rm -f LOOP.md` when git tracks it, else delete the file (a loop that made no commit
|
|
74
|
+
leaves it untracked). Commit only when `git status` then shows the removal:
|
|
75
|
+
`git commit -m "factory(<slug>): clear the previous loop"` (it asks). Then `next` again.
|
|
76
|
+
A loop that ended `done` may instead be recorded `pass` while its `LOOP.md` is still there.
|
|
77
|
+
5. Start the loop in this same worktree:
|
|
78
|
+
`geneseed loop init --title "<title>" --requirement "<requirement, plus the task when next gave one>" --graph <loop> --preset {{TRUST}} --factory <slug> --note-file <notes[0]>`
|
|
79
|
+
where the task is item `task.index` under the spec's Tasks heading, written as
|
|
80
|
+
"task <index>/<count>: <its text>". When `task.extra` is set, the last task has passed and a
|
|
81
|
+
later stage sent the work back: the task is "make CI green" (or, for another stage, make it
|
|
82
|
+
pass), and `notes[0]` says why. Use `--note-file <notes[0]>`
|
|
83
|
+
when `notes[0]` is the path of a stage's finding file (the usual carry), so the loop gets the
|
|
84
|
+
finding, not its path; `--note "<notes[0]>"` when it is plain text; neither when `notes` is
|
|
85
|
+
empty. A loop
|
|
86
|
+
re-entered after a failure is a fresh loop: the reason arrives as its note.
|
|
87
|
+
6. Follow the `loop` {{SKILL}} from *The cycle* through *The end*, skipping its Setup: the
|
|
88
|
+
worktree is this one, and its `loop/<slug>` is `loop/factory-<slug>` here, so every loop push
|
|
89
|
+
is `git push -u origin HEAD:loop/factory-<slug>`. Skip its final report too: the run goes on.
|
|
90
|
+
7. When the loop reaches `$close` and its close commit has removed `LOOP.md`:
|
|
91
|
+
`git status --porcelain --untracked-files=all | geneseed factory record --outcome pass`.
|
|
92
|
+
When it reaches `$stop`, leave its `LOOP.md` in place:
|
|
93
|
+
`git status --porcelain --untracked-files=all | geneseed factory record --outcome fail --carry "<the stop reason>"`.
|
|
94
|
+
|
|
95
|
+
## The end
|
|
96
|
+
|
|
97
|
+
8. On `$close`: the `retro` stage has written the run report. Close the run with
|
|
98
|
+
`git rm -f FACTORY.md`, then `git commit -m "factory(<slug>): close"` and
|
|
99
|
+
`git push -u origin HEAD:loop/factory-<slug>`. The gate asks: that ask is the user's consent.
|
|
100
|
+
The push re-runs CI on the PR, after `merge-gate` saw it green. Read the PR's checks again
|
|
101
|
+
once, with the bounded wait the `merge-gate` brick names (30 minutes at most), and add the
|
|
102
|
+
final state (green, red with the failing checks, or still pending at the bound) to the run
|
|
103
|
+
report. A red result is reported, never reworked: the run has closed.
|
|
104
|
+
9. On `$stop`: the engine hands out no stage after a stop, so have the `docs` {{AGENT}} write the
|
|
105
|
+
run report the `retro` brick would: the stop `reason` first, then the work item, the PR URL if
|
|
106
|
+
any, every stage with its outcome and each rework with its reason, read from `FACTORY.md` and
|
|
107
|
+
the loops' notes. It goes to `.geneseed/factory-runs/<slug>.md`, or to the OS temp directory
|
|
108
|
+
when `git check-ignore -q <that path>` exits non-zero. No tracked file changes, no commit; only
|
|
109
|
+
a lesson that holds beyond this run goes into memory, one entry. Leave the branch and
|
|
110
|
+
`FACTORY.md` as they are.
|
|
111
|
+
10. Report: the PR URL, the final CI state after the close commit, the stages with their outcomes from `summary.history`, every rework and
|
|
112
|
+
its reason, the run report's path, and the branch. **Never merge.**
|
|
113
|
+
|
|
114
|
+
## Resume
|
|
115
|
+
|
|
116
|
+
After a crash or an answered `awaiting`, from the worktree: `geneseed factory next`. When it
|
|
117
|
+
says a loop still runs, resume that loop first with `geneseed loop next` (the `loop`
|
|
118
|
+
{{SKILL}}'s *Resume*). The state is `FACTORY.md`, the child `LOOP.md` and the branch.
|
|
119
|
+
|
|
120
|
+
## Done when
|
|
121
|
+
|
|
122
|
+
- `$close` is reported with the PR open, `FACTORY.md` removed, and the CI state after that
|
|
123
|
+
removal read and reported; or `$stop` is
|
|
124
|
+
reported with its reason and the run report. In both cases nothing was merged.
|
|
125
|
+
|
|
126
|
+
<!-- INCLUDE: skills/_self-improvement.md -->
|