thurbox-extensions

Thurbox extensions

Working reference extracted from CLAUDE.md, which indexes it. The rationale behind these decisions is owned by the docs under docs/; a change that invalidates what this says updates it in the same PR.

Extensions

extensions/ holds opt-in, agent-agnostic add-ons that build on thurbox-cli without touching the core binary. Each ships an extension.toml manifest installed via thurbox-cli extension install <name> (with a thin curl-able install.sh shim over it).

• extensions/flow/ (experimental — new and under active testing) — a focus-protecting triage agent: brain-dumps become thurbox tasks, dispatchable ones spawn worker sessions (on flow/<slug> worktree branches, agents flow-worker/flow-worker-heavy mapped in agents.toml to any CLI), a dedicated flow session monitors them, and every reply ends with the single next thing to focus on. Dispatch is plan-first: scripts/create-task.sh owns the worker prompt and injects a mandatory clarify → plan → build phase (≥3 clarifying questions, then a written plan gated on user approval, then implement; seeded from --accept) so each worker plans before it codes. A dump spanning several repos.md repos becomes one multi-repo task: create-task.sh forwards --add-repo PATH@origin/<base> (own isolated worktree per repo) / --add-dir PATH to task create, and the worker opens a separate PR per repo it changes (its result carries pr_urls). Worker↔flow coordination is event-driven over the inter-session message queue: a worker pushes message send --to flow --kind questions|plan|result (waking flow) with no ids (thurbox stamps sender + task from the injected THURBOX_SESSION/THURBOX_TASK); flow drains its inbox (message inbox --claim), surfaces the questions/plan under "Needs you", and relays the user's answer with message reply <message_id> — routed to that message's sender, so flow never maps a task to a session id (flow-snapshot.sh name-parsing is now human-board only). The worker drains its own inbox on the resulting inbox wake. Flow ships no scheduled automation — a manual tick is the janitor/safety-net (drain missed wakes, reset stale tasks, dispatch). The behavior spec is FLOW.md, surfaced to whichever CLI runs it via context-file symlinks (CLAUDE.md/AGENTS.md/GEMINI.md → FLOW.md). See extensions/flow/README.md.
• extensions/forge/ (experimental) — a workflow analyst that mines your tasks/sessions/automations (and their run history) for recurring patterns and writes ready-to-apply thurbox-cli automation proposals. It proposes, never imposes: a scan (driven by a weekly forge-scan automation on the forge session) only reads state and writes proposals.jsonl (rendered to proposals.md); nothing is created until you apply <slug> — and proposals.sh apply refuses any command not starting with thurbox-cli. Spec: FORGE.md.
• extensions/ci-shepherd/ (experimental) — watches your open change requests (GitHub PRs / GitLab MRs / Bitbucket PRs; repos in repos.md) and dispatches a shepherd-worker fixer for each one with failing CI, a changes-requested review, or a branch that is behind its target (needs rebase — the normalized rebase signal from provider.sh, surfaced as the REBASE action flag by scripts/classify.sh; dispatch-fix.sh --rebase makes the worker rebase onto the base and force-push before fixing). When several PRs in one repo are all REBASE-only, classify.sh serializes them — only the lowest-numbered keeps the live REBASE flag, the rest become REBASE-QUEUED (behind #n) — so the shepherd rebases one at a time (each merge advances the base for the next), clearing the stack in O(n) rebases instead of the O(n²) of force-pushing N mutually-invalidating branches. A shepherd session monitors via a shepherd-tick automation; fixers are thurbox tasks (fix #<n>: …) that self-report with the same ===RESULT=== sentinel as flow. It is forge-agnostic: only git is baked in; how to talk to a repo's host is decided by the shepherd agent each tick — built-in fast paths (github gh/gitlab glab/bitbucket REST via scripts/provider.sh) plus an agent-driven path for any other forge (provider.sh describe hands the agent the remote + installed clients; it lists the repo itself and passes --branch/--checkout-cmd/--feedback-cmd/ --comment-cmd to dispatch-fix.sh). Because thurbox's --worktree always runs git worktree add -b (which fails on an existing branch), dispatch-fix.sh adopts the request branch itself into a shepherd-owned worktree. It is also session-aware: the snapshot joins each request's head branch against the live thurbox-cli session list (scripts/link-sessions.sh, pure + bats-tested). A request whose branch already has a non-fixer thurbox session (someone working it by hand) is not dispatched (two worktrees would force-push the same branch) but is monitored and folded into the merge ordering — that live session counts as the repo's active worker, so the other same-repo requests queue behind it. While such a request stays actionable the shepherd nudges the live session over the message queue (thurbox-cli message send) to do the rebase/merge — once per pending ask (guarded by peeking its unread inbox), not every tick — so the slot actually clears. Spec: SHEPHERD.md.
• extensions/renovate/ (experimental) — keeps local repos on up-to-date dependencies. A renovate session sweeps a repos.md watch list on a weekly renovate-tick automation and dispatches a renovate-worker per eligible repo; the worker runs Renovate's local platform only (scripts/renovate-run.sh hard-codes --platform=local — no hosted bot, no token, no Renovate-opened PR), tests the result, commits to a fresh renovate/updates-<ts> branch, and opens a review PR. Updaters are thurbox tasks (update <repo> deps …) that self-report with the same ===RESULT=== sentinel as flow. Unlike ci-shepherd it starts a new branch, so scripts/dispatch-update.sh uses thurbox's native --worktree (no branch adoption). Version strategy is per-repo (strategy column: patch/minor/ major/all, layered as a RENOVATE_CONFIG overlay) plus a global renovate-config.json. Spec: RENOVATE.md.
• extensions/ui-skill/ (built-in, on by default) — the odd one out: it ships no session, no automation and no agent. It installs a single agent skill, thurbox-ui, into each coding CLI's personal skill directory (~/.claude/skills/, ~/.codex/skills/, ~/.config/opencode/skills/, ~/.copilot/skills/, ~/.agents/skills/ — each guarded by requires_dir, so a CLI the user does not have is skipped), so an agent in any session knows how to change thurbox's own interface. It replaces the workaround of attaching the interface directory to every session as an extra repo: a skill loads only when the request is about the TUI, where an extra repo is in front of the agent always. Like hooks it is embedded + auto-activated (see below) — for the same reason: someone who does not already know the interface is editable will not go looking for the extension that says so. Opt out with thurbox-cli extension deactivate ui-skill. The payload is one SKILL.md — the short form of ui/AGENTS.md + ui/README.md — and it hard-codes no paths, opening with thurbox-cli plugin dir so one file is correct for a release build, a dev build and a THURBOX_UI_DIR override alike. Delivery is the ordinary [[external_files]] machinery, marker-guarded: install/update/uninstall act on thurbox's own copies and leave one the user has taken ownership of alone (drop the Managed by line and it is theirs), while reinstall and install --force overwrite as they do everywhere else.

Removed. Four per-provider task-integration extensions (github-issues, gitlab-issues, linear, jira) lived here and were deleted: four near-identical trees, each carrying a provider's API shape, for a job that is a curl and an upsert. What made them possible is still in the binary and is deliberately provider-neutral (ADR-20 — no provider name in the binary): the task --source/--external-id/--external-url flags, get_task_by_external_id, the idx_tasks_external index, and the Exec automation action. A scheduled Exec running a script of your own does what they did.