hieuphung97/dely/delivery

Delivery

Dely accepts a request that may still be vague, brings it to an approved design contract, then automates sequential implementation, independent review, and pull-request preparation. It is a thin control protocol, not an orchestrator, SDLC framework, or second source of Git state.

Read AGENTS.md in the repository for this project's gate commands, artifact paths, and default branch. Per-phase harness/model/effort pins come from .dely/, which dely pins resolves. This skill never names them.

Two human gates

1. Approve the design contract before candidate mutation.
2. Merge or publish after Dely has prepared the reviewed pull request.

Dely pauses outside those gates only for a scope or architecture change, a destructive action, new authority, replan, or an unavailable required runtime.

The control session

The current interactive session is Control. It owns the approval invariant, task boundaries, exception handling, dispatch supervision, and release. It does not implement or review the candidate, and does not prescribe question count, order, format, or skill-selection precedence. Native Plan Mode and active design skills govern their own surfaces under the harness's precedence; neither bypasses approval. Before mutation, Control obtains explicit human approval of a design contract. One approval covers that scope; a material change needs a new one. Control surfaces uncertainty that could materially change intent, acceptance, authority, public contract, architecture, or consequential risk. Material assumptions must be explicit.

Shape

Use the smallest contract that safely holds the change. Risk may promote an otherwise small change; diff size never demotes data-loss, security, permission, or public-compatibility risk.

An approved design contract states intent and success criteria; scope and authority; affected public contract or architecture; consequential risks and material assumptions; and a plausible counterexample that distinguishes correct behaviour from a present-but-wrong implementation. If no executable instrument can discriminate, the contract names the manual inspection and its limit.

Architectural work uses templates/decision-record.md (durable) and templates/plan.md (transient, deleted in the release commit, before the release-binding review). Commit both before implementation begins — that commit is the review baseline.

Acceptance

One table: each requirement, the instrument that proves it, the plausible wrong implementation that instrument rejects, and where that rejection was observed.

An acceptance row is invalid until its instrument discriminates. A row that passes both before and after the change proves nothing and will be found at review. Baseline-red is not enough: red only because the feature is absent says nothing about catching an implementation that is present, runs, returns a pass, and is wrong. Each row names such a wrong implementation. "The feature is absent" does not satisfy Counterexample. Where none exists, the row says so and a human reads the diff.

Record what the instruments cannot observe. Prefer the simplest instrument that proves the contract. Any claim about extent — a scope, a count, a set of call sites — names the command that produced it, reports its output, and enumerates rather than samples. Naming the command is not the measurement; the command must have been run.

Execution envelope

Before mutation, Control resolves deployment preferences against the live harness surface, starts Orca and verifies its required capabilities, records the dirty baseline and exact-path ownership, and creates a feature branch when starting on the default branch. The envelope freezes owned scope and paths; protected pre-existing dirty paths; acceptance criteria, counterexample, and focused instruments; branch, base, remote, and pull-request target; resolved harness, model, and effort for dispatched roles, from dely pins --repo <path> with each phase's source (local, team or control); and authority to branch, commit owned paths, run gates, push, and open or update a pull request. It never authorises merge, force-push, stash, reset, cleanup, or an edit outside owned scope. Dely stages and commits only contract-owned paths. It never stashes, resets, cleans, or silently absorbs the user's existing changes. If a path carries protected baseline changes and Dely must also modify it, Control pauses rather than combining ownership.

Orca and the helper

Orca is the required execution plane. It launches and supervises fresh native harness TUIs with the resolved harness, model, and effort. Orchestration is a required Orca capability. dely:delivery starts Orca, then Control loads orca skills get orchestration and follows its supervised loop. It stops only when the CLI is missing, the runtime cannot start, or a required capability is absent — there is no direct dispatch and no headless fallback of any kind. The launcher is scripts/dely relative to this skill. Control learns the helper's interface by running scripts/dely with no arguments, which prints its identity and usage, and does not read scripts/dely.js. Control's wake mode is that harness's controlWake in ../../harnesses.json. The preflight step runs in setup and again after a NO_ACK; a delivery does not preflight before its first dispatch. Run dely preflight and dely dispatch with no tool timeout, or one of at least 300 s.

Write the prompt to a file in the Run's folder, <repo>/.dely/local/runs/<run>/, where <run> is the Orca Run id; dely dispatch refuses a --spec-file anywhere else. It writes .dely/local/.gitignore containing * when that file is absent and leaves an existing one as it is, so the Run's files stay out of git status only while that file ignores them. Never inline it in a shell argument: prompts carry backticks, quotes and newlines, and a shell argument mangles them. A path outside the workspace can trigger a second permission surface some harnesses still prompt for even when tool approval is skipped. The handoff is a file in the same folder; its path travels as payload.reportPath and the message body stays short. Routing, review and remediation read earlier prompts and handoffs, so nothing in the folder is deleted when a worker returns; it is kept until the run closes. A Spike that dispatches workers opens its own Run, dispatches through dely dispatch the same way, and closes when it reports its recommendation. --spec and --body are shell arguments, which this skill already forbids for prompts.

The dispatch prompt carries the task, its scope, and the evidence required. It does not define role dispositions or the conditions for reaching one — those belong to this skill, and a prompt that restates them narrows or contradicts them. Where the design contract states an acceptance row, the prompt carries that row as written. Every dispatch goes through dely dispatch. Control does not compose a worker launch or call worker-start by hand. The helper resolves the pins from .dely/ as dely:setup describes and appends the acknowledgement instruction and a sentence that the Orca preamble and the spec file are everything the worker needs and that it should read no other skill. The worker-start receipt records launch.requested and launch.effective; it does not establish that the worker can serve the request or that it cannot. Orca applies the execution plane's configured permission default and does not add a sandbox the project did not pin.

Name the model and effort on every dispatch. The helper passes --model/--effort when ../../harnesses.json says that harness takes them, and omits a flag whose value is default. A harness whose entry has effortInModel and modelFlag receives a pinned Effort joined to the Model by that string in --model (selector:level), never --effort; Effort default passes the Model alone, and a pinned Effort with Model default is refused. A harness whose entry names modelPin: spec-unchecked receives its pin as a spec line instead of flags, and the helper never verifies the reported model; a pin such a harness cannot resolve stops the worker before its first request and surfaces as NO_ACK. A spec line must not start dely-pin:. On a harness that takes neither flags nor a spec pin, a Model written there is silently not applied: write default and set the model in Orca's agent default arguments. A worker left on a harness default is an unpinned environment: it lives in the harness's own config, it changes without announcing itself, and the dispatch that relies on it looks identical to one that pinned the same value deliberately.

Never act on an Orca nudge. After DISPATCHED, wait by the wake mode of this Control's own harness — not the harness of the worker being waited on. --control is this session's harness id, the same id whatever worker is in flight. background runs dely wait --run <run> --control <self> as a background command and ends the turn; waker runs dely wait-bg --run <run> --control <self> as its last command, then ends the turn (a waker Control never runs dely wait); unsupported cannot be Control. The helper reads the harness of the Orca terminal it runs in and refuses a waker even when --control names another one, so REFUSED … (called with --control …) means use wait-bg.