Define Workflow Bundle authoring and packaging ergonomics

[Sandstorm831]

Question

What source layout, scaffolding, validation diagnostics, build/watch/export commands, and future YAML-to-packaged-JSON path should make self-contained Workflow Bundles practical to author without changing the .wfb runtime contract?

[Sandstorm831]

Starting context

Superseding inputs (2026-09-05): Read the Review checkpoint amendment and Bundle-contract amendment after the original linked resolutions. Authoring must emit the required Repeat-group review cadence/message; there is no launch-time interval or trust-revocation action, External Bundle uninstall removes its grant, and built-in Bundle removal remains undecided.

Input	Why it matters	Authority
Workflow Bundle contract resolution	Fixes the runtime boundary authoring must target: strict packaged JSON, deterministic .wfb build, build-and-install default, optional export, derived engine/platform fields, exact asset kinds, validation, and YAML explicitly deferred to an authoring compiler	Canonical decision
Minimum generic Workflow capabilities	Defines the Step kinds, Routing, artifact declarations, prompt slots, sessions, retries, and Composition check that authoring tools must help users express and diagnose	Canonical decision
Docker build overview and exporters	A mature comparison for separating source context, build, local installation/load, and optional exported artifacts without importing Docker's image model wholesale	Research

Required methods

• /grilling
• /domain-modeling
• /codebase-design

Reading rule

Read the Bundle resolution first and treat its packaged manifest.json, archive, identity, validation, and trust rules as fixed. This ticket designs the human/AI authoring experience that produces that contract; it may add future YAML authoring or source-only conveniences, but it must not add a second runtime manifest language or make an installed Bundle depend on its source folder.

[Sandstorm831]

Starting context addendum (2026-09-07)

Input	Why it matters	Authority
Define built-in Workflow Bundle shipping, installation, and upgrade and ADR 0029	bundle build now has --no-install (requires --output); built-in versions are authored, locked with their digest in bundles/builtin.lock.json, and maintainers iterate under prerelease versions. Authoring ergonomics must not weaken these.	Canonical decision

Read after the existing Starting context. The existing context is otherwise unchanged and the ticket stays context-ready.

[Sandstorm831]

Not required for v1

This ticket is not a v1 prerequisite. The resolved sequencing decision, Sequence vertical slices, refactoring gates, and legacy deletion, states that M1 needs only the minimal build-from-folder path the Bundle contract already implies, and that this ticket refines authoring beyond that. The handoff approval, Approve Crucible's architecture and migration handoff, confirmed it is not a prerequisite for M0 to M6.

It stays open and context-ready for a later effort; nothing in v1 blocks on it.