diff --git a/README.md b/README.md index a0340bb..e1cc9f9 100644 --- a/README.md +++ b/README.md @@ -1,152 +1,70 @@ # dely + + + dely + + [![contracts](https://github.com/hieuphung97/dely/actions/workflows/contracts.yml/badge.svg)](https://github.com/hieuphung97/dely/actions/workflows/contracts.yml) -An automation-first delivery protocol for coding agents, packaged for Claude -Code, Codex CLI, Grok Build, Antigravity CLI, Kiro CLI, Cursor Agent CLI, and -GitHub Copilot CLI: it takes a request that may still be vague, brings it to -an approved design contract, then automates sequential implementation, -independent review, and pull-request preparation. +Ask for a change; Dely takes it through design approval, implementation, +independent review, and a pull request you merge. -## Quickstart +[![Dely demo](https://img.youtube.com/vi/6pRWkhlQSAc/maxresdefault.jpg)](https://www.youtube.com/watch?v=6pRWkhlQSAc) -Four steps, and nothing more: +## Contents -1. Install `dely` in the harness. -2. Open a session in the project. -3. Invoke `dely:setup` (optional). -4. Ask for a change normally. +- [Quickstart](#quickstart) +- [Project setup](#project-setup) +- [Install](#install) +- [How Dely works](#how-dely-works) +- [Troubleshooting](#troubleshooting) -You need one of Claude Code, Codex CLI, Grok Build, Antigravity CLI, Cursor -Agent CLI, or GitHub Copilot CLI, each with plugin support, or Kiro CLI with -the `npx skills` installer; [Orca](https://www.onorca.dev/docs/install) as the -required, -constant execution plane that launches and supervises the per-phase worker -TUIs; and Git plus a GitHub remote for the project you run Dely against. -`dely:delivery` preflights Orca and stops when the CLI is missing, the runtime -cannot start, or a required capability is absent. +## Quickstart -Preflight Orca before installing a harness plugin. Orca's orchestration -feature must be enabled: +Install Orca, then Dely. + +1. Install the [desktop app](https://www.onorca.dev/docs/install). +2. Register the CLI (it ships with the app): Settings → General → Orca CLI. + See the [CLI overview](https://www.onorca.dev/docs/cli/overview). +3. Enable orchestration: Settings → Experimental. See + [orchestration](https://www.onorca.dev/docs/cli/orchestration). +4. Preflight: ```bash -orca open # launches Orca and waits for the runtime to be reachable -orca status --json # confirms the runtime is reachable -orca orchestration run-list --json # confirms orchestration is enabled +orca open +orca status --json +orca orchestration run-list --json ``` -Per-harness install commands live under [Install](#install). Project pins live -under [Project setup](#project-setup). +`dely:delivery` stops if this preflight fails. On Linux the binary is +`orca-ide` (see the [install docs](https://www.onorca.dev/docs/install)). -## How Dely works +Optional agent skills `orca-cli` and `orchestration`: +https://www.onorca.dev/docs/cli/skills -Dely is a thin control protocol, not an orchestrator, an SDLC framework, or a -second source of Git state. The current interactive session is Control. Control -owns the approval boundary, task boundaries, exception handling, dispatch -supervision, and release. It never implements or reviews the candidate itself: -those roles run in fresh worker sessions that Control launches and watches. - -There are two human gates and only two. The first is to approve the design -contract before any candidate mutation. The second is to merge or publish after -Dely has prepared the reviewed pull request. Between those gates Dely pauses -only for a scope or architecture change, a destructive action, new authority, a -replan, or an unavailable required runtime. - -Work takes one of three shapes, and you pick 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. - -A Spike is investigation only. It produces an approved probe and a -recommendation. No candidate is delivered and no delivery run starts, so it -gets no review. - -A Bounded change is small, with clear behaviour and ownership. Its artifact is -an approved in-chat design plus a short execution envelope, and it gets one -independent whole-change review. - -An Architectural change covers multiple behaviours, a public-contract change, -an architecture decision, or promoted risk. Its artifacts are an approved -decision record, a task plan, and an execution envelope. Each task gets its own -review, then a different fresh reviewer performs one integration review. Only -that final review is release-binding. - -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 or failure mode that -distinguishes correct behaviour from a present-but-wrong implementation. If no -executable instrument can discriminate the requirement, the contract names the -manual inspection and its limit. - -Acceptance is one table: each requirement, the instrument that proves it, the -plausible wrong implementation that instrument rejects, and where that -rejection was observed. A row is invalid until its instrument discriminates. An -instrument that passes both before and after the change proves nothing. Baseline -red is not enough on its own: an instrument that is red only because the -feature is absent says nothing about whether it can catch an implementation that -is present, runs, returns a pass, and is wrong. "The feature is absent" is not -a counterexample. - -Before mutation, Control records the execution envelope: owned scope and paths, -protected pre-existing dirty paths, acceptance criteria, the feature branch, -and the resolved harness, model, and effort. The envelope never authorises -merge, force-push, stash, reset, cleanup, or an edit outside owned scope. - -The run itself is sequential. After the design contract is approved and the -envelope is frozen, Control dispatches `implement`, then an independent -`review`, then performs `release` on exact HEAD — native Git and forge tools, -no LLM worker, no post-review candidate edit. Release pushes the feature -branch, opens or updates a draft pull request, requires the applicable review's -`ACCEPT` plus required checks green, then marks the pull request ready and -reports it for the human to merge. Dely never merges or force-pushes. - -Each worker returns a structured handoff. `END OF HANDOFF` is the last line and -load-bearing: it is the only thing that distinguishes a complete handoff from -one cut off mid-write. The block names status, harness, session, baseline, -changed paths, contract coverage, verification, deviations, residue, -and git state. - -If review returns in-contract `CHANGES_REQUESTED`, there is one remediation -pass per finding by the original implementer: verify the finding, fix the -root cause, rerun the affected instruments and closure gates, and write a -separate remediation commit. The reviewer that raised the finding checks -reproduction and the fix-only diff. If that scoped re-review does not accept, -Control routes to replan rather than starting another repair loop. - -`BLOCKED` and `NEEDS_REPLAN` are distinct stop statuses, not synonyms for a -crash. `BLOCKED` preserves the candidate and escalates an unresolved -dependency or authority question to Control; it is not remediated by the -original implementer. `NEEDS_REPLAN` means the task no longer fits the -approved contract — the record contradicts the code, the contract is -ambiguous, work outside the task became necessary, or an existing test -disproves an assumption. A worker that *failed* — a non-zero exit with no -result, an exhausted quota, an authentication error — is not the same as one -that returned `BLOCKED`, and must not be treated as one. - -Ownership is split and Dely duplicates none of it. Orca owns dispatch: it -launches and supervises the worker TUIs, and evidence is a property of a -dispatch, not a skill-owned journal. Git owns the candidate. CI and the forge -own release state. Durable facts come from those stores; Dely does not keep a -second copy. - -The full workflow contract is -[`skills/delivery/SKILL.md`](skills/delivery/SKILL.md). Per-harness launch -mechanics — Orca agent id, permission defaults, forbidden headless forms, and -launch notes — live in -[`skills/delivery/references/harnesses.md`](skills/delivery/references/harnesses.md). -Rationale for the current design is in -[`docs/decisions.md`](docs/decisions.md). +Then: + +1. Install `dely` in the harness ([Install](#install)). +2. Open a session in the project. +3. Invoke `dely:setup` (optional). +4. Ask for a change. + +## Project setup + +In the project, invoke `dely:setup`. + +It asks Quick (this harness for both phases) or Customize (pick harness, +model, and effort for `implement` and `review`), then writes one managed +block into `AGENTS.md`. Skip it and `dely:delivery` uses the current +harness and that harness's defaults. ## Install -The plugin is `dely`, served from the `dely` marketplace at -`https://github.com/hieuphung97/dely.git`. Install it in each of the six -plugin harnesses — Claude Code, Codex CLI, Grok Build, Antigravity CLI, -Cursor Agent CLI, and GitHub Copilot CLI — from that remote. The skill keeps -the name `delivery`; the intended namespaced name is `dely:delivery`. The -marketplace entry keeps `"source": "./"`, which is what makes the plugin -resolve inside its own repository whether the marketplace is added by path -or by git URL. Kiro CLI -has no plugin verb; see `### Kiro CLI` below for its `npx skills` install. +The plugin is `dely`, from the `dely` marketplace at +`https://github.com/hieuphung97/dely.git`. The skill name is `delivery`; +invoke it as `dely:delivery`. Kiro CLI has no plugin verb; use +`### Kiro CLI` below. ### Claude Code @@ -159,10 +77,6 @@ claude plugin update dely # update (restart required to apply) claude plugin uninstall dely # uninstall ``` -`claude plugin marketplace add` and `claude plugin install` track whatever -the marketplace source currently points at; the checked command surface has -no ref option for Claude, so this README does not claim one. - ### Codex CLI ```bash @@ -174,20 +88,10 @@ codex plugin marketplace upgrade # update: see below codex plugin remove dely@dely # uninstall ``` -`codex plugin marketplace add --ref ` targets the marketplace at an -explicit Git ref instead of the default branch — use a tag such as -`v0.17.0` or an exact full commit SHA for an -immutable pin; `main` is a mutable branch, not a pin. There is no -`codex plugin update`: `codex plugin marketplace upgrade` is the actual -update command. On the checked CLI, when the marketplace's Git root has -advanced, that command refreshes both the marketplace snapshot and the -already-installed plugin's cache, so a following `codex plugin add` is not -required to pick up the change. This is a separate concern from the -[self-update boundary](#cache-refresh-boundary): a delivery already running -keeps the plugin version that was frozen at its start regardless of any -refresh, and a refreshed cache is only picked up by the next session. `codex plugin -install` does not exist on the checked CLI (`codex plugin install --help` -exits non-zero with "unrecognized subcommand 'install'"); do not use it. +`codex plugin marketplace add --ref ` pins the marketplace to a tag +such as `v0.17.0` or an exact full commit SHA. There is no +`codex plugin update`: use `codex plugin marketplace upgrade`. Do not use +`codex plugin install`. ### Grok Build @@ -199,15 +103,9 @@ grok plugin update dely # update grok plugin uninstall dely # uninstall ``` -`grok plugin install` takes a source (git URL, GitHub shorthand, or local -path), not a marketplace selector, and tracks the default branch unless you -append `@ref`. For an immutable pin, use a tag such as -`hieuphung97/dely@v0.17.0` or an exact full -commit SHA — a branch name such as `@main` is still mutable, not a pin. - -`grok plugin install` refuses a local directory without `--trust`. Whether a -git-remote install prompts the same way is untested; if the prompt appears, -it is the install asking for trust, not a failure. +`grok plugin install` takes a git URL, GitHub shorthand, or local path. +Pin with `@tag`, for example `hieuphung97/dely@v0.17.0`. A local directory +needs `--trust`. ### Antigravity CLI @@ -219,8 +117,7 @@ agy plugin install https://github.com/hieuphung97/dely.git # refresh: no `plugi agy plugin uninstall dely # uninstall ``` -`agy plugin install` takes a git URL or a local path. This README documents -the command, not a plugin cache directory. +`agy plugin install` takes a git URL or a local path. ### Cursor Agent CLI @@ -241,29 +138,19 @@ cursor-agent plugin marketplace add https://github.com/hieuphung97/dely.git The snapshot is addressed by commit, so `marketplace update` only re-indexes and does not fetch. Remove and re-add the marketplace to pick up new commits, then choose `Uninstall` from the `Installed` tab and install again from the -`Marketplace` tab of the `/plugin` panel — both panel halves are still -required after that refresh. +`Marketplace` tab of the `/plugin` panel. Add the marketplace first with `cursor-agent plugin marketplace add`, then in -a Cursor Agent session type `/plugin` and press Enter. A panel opens headed -`Plugins`, with two selectable tabs, `Installed` and `Marketplace`, cycled -with the left and right arrows or Tab. Go to the `Marketplace` tab, type -`dely` in the search box, and press Enter on the `dely (dely)` result, then choose -`Install for you (user scope)` (the other offered action is `Install for all -collaborators on this repository (project scope)`). - -To uninstall, go to the `Installed` tab instead, select `dely`, and choose -`Uninstall`. There is no non-interactive uninstall command; -`cursor-agent plugin marketplace remove` only removes the marketplace entry -and leaves the plugin installed. That `Uninstall` action only appears for a -`dely` installed through Cursor's own marketplace; a `dely` installed through -Claude Code shows as `dely (Claude Code)` in the same `Installed` tab with -only `Try in chat`, and is not uninstallable from Cursor. - -Cursor does not namespace plugin skills the way Claude Code does with -`dely:setup`; with another plugin also installed, the palette can show more -than one bare `/setup` entry. Type `/dely` to filter the palette down to -exactly Dely's `/delivery` and `/setup`, then pick from that filtered list. +a Cursor Agent session type `/plugin` and press Enter. Open the `Marketplace` +tab, type `dely` in the search box, press Enter on `dely (dely)`, and choose +`Install for you (user scope)` (or `Install for all collaborators on this +repository (project scope)`). + +To uninstall, open the `Installed` tab, select `dely`, and choose +`Uninstall`. `cursor-agent plugin marketplace remove` removes the marketplace +entry and leaves the plugin installed. + +Type `/dely` to filter the palette to Dely's `/delivery` and `/setup`. ### GitHub Copilot CLI @@ -287,12 +174,7 @@ npx skills update --global # update npx skills remove --agent kiro-cli --global --skill delivery --skill setup # uninstall ``` -`npx skills add` installs the existing `delivery` and `setup` skills — no -Kiro Power, no duplicated skill tree — through the open `npx skills` -installer, targeting the `kiro-cli` agent (`--agent`) at global scope -(`--global`). Kiro's default agent discovers global skills from -`~/.kiro/skills/` automatically. Invoke them natively in a Kiro CLI session -as `/delivery` and `/setup`. +Invoke the skills in a Kiro CLI session as `/delivery` and `/setup`. ### Checked versions @@ -310,88 +192,27 @@ against — observations, not a promised minimum: | GitHub Copilot CLI | 1.0.82 | | Orca | 1.4.196 | -## Project setup - -A consuming project supplies its own facts through `AGENTS.md`: closure gate -commands, artifact paths, the default branch. `dely:setup` writes the -per-phase harness, model, and effort for `implement` and `review` into one -managed block between `` and ``, -discovered live from the installed harnesses rather than a stored catalogue. -A project with no managed block still works: `delivery` runs on the current -harness with harness defaults. - -Orca is a required, constant execution plane, so the managed block has no -coordinator field, no `control` row, and no `release` row — release is -performed by the current interactive session with native Git and forge tools -and dispatches no worker. - -**Claude Code does not read `AGENTS.md`.** Codex, Grok, Antigravity CLI, -Kiro CLI, Cursor Agent CLI, and GitHub Copilot CLI do. A consuming project -whose sessions run on Claude Code needs a `CLAUDE.md` containing `@AGENTS.md` -— one line — or the managed block never reaches it. Grok does not expand that -import. GitHub Copilot CLI loads both `AGENTS.md` and `CLAUDE.md`. - -## Operating notes - -### Cache refresh boundary - -The six plugin harnesses — Claude Code, Codex CLI, Grok Build, Antigravity -CLI, Cursor Agent CLI, and GitHub Copilot CLI — each run a **copy** of this -package taken at install time, so editing the source changes nothing until -each cache is refreshed. Bump the -version and refresh every copy whenever a rule changes, or the harnesses -disagree about what the workflow says. - -Kiro CLI instead reads from a shared store, usually a symlink into this -checkout. `npx skills update --global` refreshes it by comparing a folder -hash, not the `0.17.0` version string. `update` takes no `--agent`/`--skill` -because the store is shared. - -A self-update's release phase runs through the frozen installed plugin -version already in use for that plan; candidate changes take effect starting -with the next delivery. - -### Opt-in logging - -Maintenance logging is machine-local and off by default. Dely never creates -`~/.dely/log`; a missing path is skipped silently, and deleting the file opts -back out. Opt in by creating it yourself with owner-only permissions: - -```bash -mkdir -p ~/.dely -touch ~/.dely/log -chmod 600 ~/.dely/log -``` - -Once the file exists, Control appends exactly one line only after a delivery -is accepted and all required checks are green; aborted or incomplete -deliveries are not recorded. Dely never reads this file for routing, -recovery, or runtime decisions. +## How Dely works -### Compatibility limitation +Ask for a change. Approve the design when asked. Dely implements, a +different session reviews, then opens a PR. You merge. A Spike investigates +only — no delivery run. -This README's install/verify/update/uninstall commands were checked against -the harness's normal, already-configured profile, not an isolated -clean-profile install: no supported harness offers a safe disposable -configuration boundary that avoids touching live caches, so no such -clean-install mutation was performed. Validation here is limited to public -remote access, manifest validation, and the verified command surface. +The workflow contract is [`skills/delivery/SKILL.md`](skills/delivery/SKILL.md). ## Troubleshooting - **`dely:delivery` stops immediately.** Orca is not running or a required - capability is absent, including orchestration. Run `orca open` and - `orca status --json`, then retry. + capability is absent, including orchestration. Run the Quickstart + preflight, then retry. - **A harness still runs the old workflow after you edited this checkout.** - You edited the source, not an installed copy. Bump the version and - reinstall/update in the harness (see Cache refresh boundary above). + You edited the source, not an installed copy. Reinstall or update the + plugin in the harness. - **Codex still behaves the same after `codex plugin marketplace upgrade`.** - That command only refreshes the installed cache when the marketplace's Git - root has actually advanced — confirm the remote has new commits. A - delivery already running mid-session keeps the plugin version frozen at - its start regardless; only a new session picks up a refreshed cache. -- **`AGENTS.md` pins don't seem to apply in Claude Code.** Confirm - `CLAUDE.md` contains `@AGENTS.md`; Claude Code does not read `AGENTS.md` + Confirm the remote has new commits. A delivery already running keeps the + plugin version from its start; open a new session after the upgrade. +- **`AGENTS.md` pins don't seem to apply in Claude Code.** Put + `@AGENTS.md` in `CLAUDE.md`; Claude Code does not read `AGENTS.md` directly. ## Contributing, security, and license diff --git a/tests/contracts.sh b/tests/contracts.sh index 7389fe0..cdd28b2 100755 --- a/tests/contracts.sh +++ b/tests/contracts.sh @@ -168,6 +168,20 @@ for needle in 'plugin marketplace add' 'plugin install dely@dely' 'plugin list' quickstart="$(awk '/^## Quickstart[[:space:]]*$/{p=1;next} p && /^## /{exit} p' "$root/README.md")" [ -n "$quickstart" ] || fail_with "README.md is missing a ## Quickstart section" printf '%s\n' "$quickstart" | grep -Fq 'orca orchestration run-list --json' || fail_with "README.md Quickstart does not give orca orchestration run-list --json as the confirmation command" +awk '/6pRWkhlQSAc/{v=NR} /^## Quickstart[[:space:]]*$/{q=NR} END{exit (v&&q&&v