The UX release: the design system that shipped in Ticketwright v2.0, applied to jobwright —
10 skills → 7, one front door, a ≤5-question setup wizard, graceful degradation, and plain
language on every user surface. Engine changes are additive (the init wizard and doctor's
interdependent-key checks); every existing config, vendored hook, and generated catalog keeps
working unchanged.
Changed — the rename map (v1 → v2)
| v1 | v2 |
|---|---|
onboard + configure-workspace |
setup (one skill, backed by the interactive jobwright init wizard; adopt mode for repos that already have jobs) |
start-job + scaffold-job |
start-job (the front door — chains recall → scaffold → document → validate and routes to /safe-deploy) |
validate-job (skill) |
folded into start-job (Phase 4) and safe-deploy (step 1); the jobwright validate-job CLI is unchanged |
document-job |
same name, new default: inspection mode — drafts the fields from the code instead of asking the user to fill TODOs |
safe-deploy / triage-failure / architecture-audit / build-jobs-index |
unchanged names |
All 4 removed v1 names (onboard, configure-workspace, scaffold-job, validate-job) still
work as deprecated alias stubs (commands/); they will be removed in 1.0.
Added
jobwright initis now an interactive wizard — detects the platform (project files, CLI
configs, CLIs on PATH), the jobs directory, ticket prefixes, and definition dirs; asks at most
5 questions with every answer pre-filled; writes a config where everything not asked is a
commented default. The composed config is validated before it is written. Non-interactive
callers (--yes, CI, piped stdin) take the detected proposal — degrade, don't die.
--forcereplaces an existing config; without it, an existing config is respected.- Interdependent-key validation (
jobwright.config.cross_validate) —job_def_dirsvs
dags_dirmust matchdeploy_model, with errors that say exactly what to change. Enforced by
jobwright doctorand theinitwizard;load_configstays lenient so existing configs
keep loading and every file-based command keeps working. /safe-deployruns the validation gate first — step 1 isjobwright validate-job, closing
the v1 gap where a user could deploy a job that had never been validated.- The deploy-safety guard announces itself — the SessionStart banner now states the guard is
active and what it will pause on, instead of protecting silently. - Adopt mode (
skills/setup/adopt.md) —/setupon a repo that already has jobs maps onto
the observed layout (never renames/overwrites), respects an existing config andAGENTS.md
(gen-agentsdefaults toAGENTS.jobwright.md), and leaves vendored hooks alone. - Docs:
docs/architecture.md— the two-seam model, deploy models, and adapter contract moved
out of the README (which is now a 5-minute quickstart). Contributor jargon lives there. - Self-test v2-surface check — asserts the 7-skill surface, no stray v1 folders, all 4 alias
stubs, the safe-deploy validation step, and the guard announcement.
Changed (language)
- User-facing jargon retired from skills and README: "platform seam" and the deploy-model tokens
(api-reset/git-sync/sql-ddl) now appear only in contributor docs, the config file
(where they are values, each with a plain-language comment), and CLI validation messages.
Skills say "platforms that deploy definitions from repo files" / "platforms that deploy straight
from git" instead. - Long skills split into a short SKILL.md plus reference files (
start-job/lifecycle.md,
document-job/inspection.md,setup/adopt.md); every description leads with the trigger
use-case.
Upgrade path for existing consumer repos
For a repo already running jobwright v0.0.x (config committed, deploy_safety.py vendored under
.claude/hooks/, JOBS.md checked in):
jobwright.config.yaml— no changes required. The format is unchanged
(schema_version: 1).jobwright doctornow also cross-checksjob_def_dirs/dags_dir
againstdeploy_model: a cross-consistent config passes as-is, but a config carrying the
key its deploy model never reads (e.g. a leftoverdags_diron anapi-resetconfig, or
job_def_dirsongit-sync) now failsdoctorwith a message naming the fix. Loading and
every file-based command still work either way — onlydoctor's exit code is stricter, so
check CI gates that calldoctorafter upgrading.- Vendored hooks keep working.
deploy_safety.py's import surface
(jobwright.platforms.destructive_patterns_for) and its embedded fallbacks are unchanged —
no need to re-vendor, though re-vendoring is safe. JOBS.md/OBJECTS.mdare byte-identical — no regeneration needed, no CI churn.- Old skill names keep working as deprecated aliases; switch habits to
/start-job(front
door) and/setup. ThejobwrightCLI surface is unchanged exceptinit, which upgraded
from a static template to the wizard.