Skip to content

feat: control-plane template for thurbox orchestration#1

Merged
LeTuR merged 1 commit into
mainfrom
feat/control-plane-template
Jul 9, 2026
Merged

feat: control-plane template for thurbox orchestration#1
LeTuR merged 1 commit into
mainfrom
feat/control-plane-template

Conversation

@LeTuR

@LeTuR LeTuR commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Fills in the empty template repo. Someone clicks Use this template and gets a
working control plane: a repo holding the map of their projects and the
orchestration of thurbox agent sessions run against them.

The defining idea, carried over from the private repo this pattern was learned
in: the control plane holds the plan and the log; it never holds the workers'
branches.
Real work happens in thurbox worker sessions, each in its own git
worktree in a real repo. What accumulates here is playbooks and run logs.

Layout

README.md                                    the pattern, quickstart, run loop, mailbox
CLAUDE.md                                    operating guide for an agent in a clone
FLEET.md                                     standing context for the long-lived session
LICENSE                                      MIT
.gitignore                                   ignores the rendered /extension.toml
extension.toml.in                            manifest template (see below)
.claude/settings.json                        SessionStart hook -> scripts/sync-checkout.sh
.claude/skills/thurbox-session/SKILL.md      how to drive a worker session
.github/workflows/ci.yml                     shellcheck + YAML validity + registry shape
registry/owners.txt                          placeholder owners, one per line
registry/repos.generated.yaml                GENERATED; shipped empty but valid
registry/context/_TEMPLATE.md                copy-this-to-add-a-project
orchestration/playbooks/_TEMPLATE.md         anatomy of a playbook
orchestration/playbooks/cross-repo-sweep.md  worked example
orchestration/playbooks/ship-feature.md      worked example
orchestration/runs/_TEMPLATE.md              copy-this-per-run
scripts/install-extension.sh                 render extension.toml, then install
scripts/sync-registry.sh                     regenerate repos.generated.yaml from `gh`
scripts/sync-checkout.sh                     fast-forward main when clean
scripts/trust-thurbox-dir.sh                 seed Claude workspace trust for a worktree

__REPO_PATH__ and why it exists

The manifest ships as extension.toml.in with a __REPO_PATH__ placeholder;
scripts/install-extension.sh renders it to a gitignored extension.toml
carrying the clone's real absolute path, then installs.

This is not a style choice. [[sessions]] repo_path must be an absolute
path: thurbox does not expand ~ there. ExtensionDef::resolved_for_home()
substitutes the {home} token but never calls expand_tilde, so a leading
tilde is taken literally and the session lands in a directory literally named
~. And {home} itself resolves to the extension home
(~/.config/thurbox/extensions/fleet), not the checkout — while the session
must open the checkout, because it needs registry/ and orchestration/ in
hand.

A template obviously cannot hardcode a path that exists on one machine. Hence
the placeholder. The installer sets -euo pipefail, verifies thurbox-cli
exists, verifies it is inside a git repo, and refuses to install if the
placeholder survives substitution — a half-rendered manifest would otherwise
register a session pointing at a directory named __REPO_PATH__. Both
extension.toml.in and the README explain the tilde behavior, so nobody
"simplifies" it back to ~.

Owner-parameterized registry

scripts/sync-registry.sh reads its owners from registry/owners.txt (one per
line, # comments and blank lines ignored) instead of hardcoding them. With no
active entries it exits non-zero telling the user to edit the file, rather than
silently emitting an empty map. registry/repos.generated.yaml ships as
valid-but-empty YAML so a fresh clone parses before its first sync, and the CI
registry-shape check passes on it.

Deliberate omissions

  • No [[automations]]. The only scheduled candidate is the registry sync,
    which commits and pushes to main — so a human runs it and reads the diff.
    Noted in a comment in the manifest.
  • No apply-protection.sh. It encoded one account's branch-protection and
    plan constraints; that is noise in a template.
  • No real run logs or registry/context/<repo>.md files. Only the
    _TEMPLATE.mds — real ones would leak the source repo's history.

Verification

  • shellcheck scripts/*.sh — clean.
  • Every YAML file parses; the CI registry-shape check passes on the shipped
    empty registry.
  • sed-rendered extension.toml.in parses as TOML with repo_path
    substituted.
  • sync-registry.sh exercised end-to-end: refuses the placeholder-only
    owners.txt with a non-zero exit, and with a real owner produced a
    shape-valid 23-repo registry (reverted before commit).
  • The genericization grep from the brief returns nothing — no usernames, no
    private repo names, no machine paths.

SKILL.md keeps the source's hard-won lessons (fast-forward the base branch
before creating a worktree or you get correct work in a conflicting PR; remote
hosts need their own GitHub credentials; session send types and presses Enter,
so long prompts go in a BRIEF.md) with the machine-specific host names,
cross-references, and dated PR anecdotes stripped.

Fill in the empty template repo: a control plane that holds the map of a
user's projects and the orchestration of thurbox agent sessions run against
them. The control plane holds the plan and the log; workers hold the branches.

- registry/ — owner-parameterized map. sync-registry.sh reads the owners from
  registry/owners.txt rather than hardcoding them, and refuses to run when the
  file has no active entries instead of emitting an empty map.
- orchestration/ — playbook and run-log templates, plus two worked playbooks.
- extension.toml.in — rendered to a gitignored extension.toml at install time,
  because [[sessions]] repo_path cannot be a `~` (see below).
- scripts/ — install, registry sync, checkout sync, worktree trust seeding.
- .github/workflows/ci.yml — shellcheck, YAML validity, registry shape, all
  feeding a single "All Checks" gate.
@LeTuR
LeTuR merged commit d768c3d into main Jul 9, 2026
4 checks passed
@LeTuR
LeTuR deleted the feat/control-plane-template branch July 9, 2026 18:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant