kit ↔ engine boundary
claude-kit (the dev-workflow tooling) and @tedos/engine (the product's last-mile execution
engine) must never carry two implementations of the same operation. Every workflow op has
exactly one canonical home, and both surfaces — interactive Claude Code and the engine — consume
that one home. Consistent by construction, not by discipline.
Two families, one owner each
| Family | What | Canonical home |
|---|---|---|
| 1. Repo git-mechanics | worktree create / recover / prune, branch, commit, the kit-task flow on our repo | the scripts/lib/ bash bundle — kit skills are thin wrappers; the engine shells out to the same bundle |
| 2. Plan / task graph | the plan-node tree, links (issue / PR / deploy), status, "create issue / start / link PR" | the Plan Engine Postgres graph — see Plan Engine |
Hard rules
- No second implementation. Before writing a git/GitHub/task op in either surface, check whether its family already has a canonical home; if so, call it — never re-author. A repeated op → extract to the family's home.
- Family 1 is bash, kit-owned. Git-mechanics of our repo live in
scripts/lib/. The engine invokes them via a child process; it does not reimplement them in TypeScript. - Family 2's source of truth is the graph (the daily driver); GitHub issues are kept synced with it (a mirror, not eliminated — elimination is deferred). Never reintroduce a second ticket store.
Tenant connectors are product, never workflow
The engine's tenant connectors (GitHub, Google, HubSpot, …) are tenant-aware, OAuth-scoped, and operate on the client's systems. They have nothing to do with our dev-workflow git-mechanics. Family-1/2 ops are never routed through a tenant connector, and a tenant connector is never routed through the dev-workflow tooling. This is the product / workflow boundary — see Engine.
kit ⇄ project — stay in sync
claude-kit and a project's .claude/ + scripts/lib/ are one body in two checkouts; they must
never drift. An update brings new kit versions into a project; when an effort improves a
kit-managed file, that improvement belongs upstream in the kit — otherwise the next update
reverts it.
The kit CLI
A bash dispatcher (scripts/kit) fronts both families without adding a third implementation: it
dispatches to the Family-1 bash and proxies Family-2 to the engine through a pluggable
adapter. The adapter is off by default, so the kit stays portable as a product (engine-less =
GitHub-backed behavior); a project opts in by configuring the engine seam.
Where claude-kit fits
claude-kit is documented in full in its own section — see claude-kit. This page is the boundary between that dev tooling and the product engine: two families, one owner each, no duplication.