Deliver

This path is for delivering a new version, of the whole project or of a single module, and then publishing it on the public channel. You come here when a version is ready and you want the agent to run the delivery for you.

What you ask the agent

💬 You ask your agent

« Prepare the delivery of the site module as a patch and show me the plan. »

→ The agent callseffortless_release_plan

• bump = patch
• stack = site

💬 You ask your agent

« What would the tag be if we delivered the whole project as a minor? »

→ The agent callseffortless_release_plan

• bump = minor

💬 You ask your agent

« Set up delivery of the site module: build with pnpm build, artifacts in dist/*.zip. »

→ The agent callseffortless_release_delivery_set

• stack = site
• build_command = pnpm build
• artifacts = dist/*.zip

💬 You ask your agent

« Turn on the tag and the documentation update in the release configuration. »

→ The agent callseffortless_release_config_set

• tag = true
• update_docs = true

💬 You ask your agent

« Declare acme/site-dev as the internal repository and acme/site as the public one for the site module. »

→ The agent callseffortless_release_channels_set

• stack = site
• internal = acme/site-dev
• public = acme/site

💬 You ask your agent

« Deliver the site module: bump the version, commit and push, tag, build and artifacts. »

→ The agent callseffortless_release_apply

• steps = bump_version,git_flow,tag_release,delivery
• stack = site

(the agent asks for your agreement first)

💬 You ask your agent

« Publish the site-v1.4.1 version, already delivered internally, to the public channel. »

→ The agent callseffortless_release_promote

• stack = site
• tag = site-v1.4.1
• confirm = site-v1.4.1

(the agent asks for your agreement first)

💬 You ask your agent

« Show me the delivery history. »

→ The agent callseffortless_deliveries

What the agent does

Plan a delivery

1. effortless_release_plan computes the plan without writing anything: current and target version, tag, repository, branch, version files. bump is patch (default), minor or major. stack targets a module; without stack, the plan covers the whole project.
2. The tag depends on the target: vX.Y.Z for the whole project or for a module with its own repository, <module>-vX.Y.Z for a module that lives in the project's repository.

Configure the delivery

1. effortless_release_config_show reads the effective release configuration.
2. effortless_release_config_set sets three options: git_flow (commit and push step), tag (tag creation) and update_docs (documentation update). At least one is required.
3. effortless_release_delivery_set records, for a module (or default), the build command (build_command) and the artifacts to upload (artifacts, comma-separated globs). Without artifacts, the ones already recorded are kept. An undeclared module is refused.

Run the delivery

This step acts for real: version files are written, then commit, push, tag, GitHub release, build. The agent runs it only after your explicit agreement.

1. effortless_release_apply takes steps (among bump_version, git_flow, tag_release, update_docs, delivery), bump and, for a module, stack.
2. Steps always run in that order. A failing step stops the chain: the following ones are reported as "not run". A step the engine cannot do (for example without gh) is reported as "to do by hand", with what remains to be done.
3. Bump the version checks every version file before writing any. Commit and push only merges onto the main branch by fast-forward. Tag and GitHub release refuses to place a tag on uncommitted files: the tag would point at the previous commit, without the new version.
4. The agent reads the result step by step and summarizes it for you.

Declare the internal and public channels

1. effortless_release_channels_set sets the two release repositories of a target (stack, or default for the whole project): internal (empty = the origin repository) and public (empty = no public channel). An omitted parameter is left unchanged. A repository is written owner/name.

Publish publicly

Public publication promotes a version already delivered internally, as it is: same tag, same artifacts, no new bump. It cannot be undone. The agent starts it only after your explicit agreement.

1. effortless_release_promote takes tag (the tag already delivered internally), stack for a module, and confirm, which must repeat exactly the same tag.
2. The engine downloads the internal release, republishes it on the public repository and records the publication in the journal.

Read the history

1. effortless_deliveries returns the delivery journal, most recent first: date, channel, module, tag, version, repository, outcome. It also returns the channels of each target. It needs no network.

What you get

• Version files at the new value, a commit, an annotated tag and, if the repository is on GitHub and gh is available, a release with its artifacts.
• Every delivery, successful or stopped, and every publication, is recorded in .effortless/deliveries.json, versioned with the project.
• In the app, the Delivery screen shows the same plan, configuration, channels and the Delivery history.

When the agent is refused

Situation	What the refusal says	What to do
The project is in semi-auto mode	release_apply returns an "execution tool disabled" message (flagged gated); release_promote is refused with release:gated	Switch the project to full mode, then ask for the delivery again.
The module does not exist	release:unknownModule (plan, execution, channels); deploiement:stackUnknown for the delivery configuration	Pass the id of a declared module, or default / no stack for the whole project.
No step selected	deploiement:noStepSelected	Pick at least one valid step in steps (unknown ids are ignored).
A step fails during execution	deploiement:applyStopped, with the failing step's detail	Fix the cause named in the detail, then run again. Steps already done are not undone.
Tag requested while files are uncommitted	tag_release step fails: "Tag … not placed"	Replay with the git_flow step, or commit first.
release_config_set with no option	deploiement:configNoField	Pass at least git_flow, tag or update_docs.
Delivery configuration without a module	deploiement:stackRequired	Pass stack; effortless_stack_list names the declared ones.
Badly written repository	release:repoInvalid	Write the repository as owner/name, or an empty value to remove the channel.
No public repository declared	release:noPublicChannel	Declare it with effortless_release_channels_set.
confirm differs from the tag	release:confirmMismatch	Give back exactly the tag, after your explicit agreement.
The version was not delivered internally	release:notInternal	Deliver the version internally first ("Tag and GitHub release" step).
The version is already public	release:alreadyPublic	Nothing to do. For a new version, deliver it internally first.
gh missing or failing during a publication	release:ghMissing or release:ghFailed	Install gh and sign in, then run again.