diff --git a/CHANGELOG.md b/CHANGELOG.md index faece80..5d9dd53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,48 +6,43 @@ tagging it. ## [Unreleased] -- A lane's branch pushes to itself. The launcher no longer lets `task/` - track the default branch it starts from, and a won claim sets - `/task/` as the branch's upstream, so a plain `git push` from a - lane worktree is no longer refused or sent to the default branch. -- A sixth skill, `delivery-refine`, runs as a second session in every lane: it - reviews the change `delivery-implement` left, fixes what it finds, simplifies - it without changing its behaviour, re-validates, and adds a Refinement section - to the pull request body. It runs one tier up, or on a tier's new `reviewer` - key in `tiers.conf`; `--no-refine` skips it. The launcher's `LAUNCHED` and - `WOULD-LAUNCH` lines gain the review harness and model after the lane's model - ([ADR-011](docs/decisions/ADR-011-lane-refinement.md)). -- An install whose skills are split between `.claude/skills/` and - `.agents/skills/`, as `npx skills update` leaves after an install naming - only `claude-code`, is reported by `where.sh` as `NEXT repair-install`, and - the lane launcher refuses to start without `delivery-implement`. The README - explains how to install so this cannot happen, and how to repair it. -- Milestones: a large project is cut and run one end-to-end slice at a time, - with a reviewed note closing each before the next is cut. `where.sh` and - `follow.sh` stop at each boundary - ([ADR-010](docs/decisions/ADR-010-milestones.md)). -- Requirement coverage: requirements carry ids, tasks list the ids they cover - in full or in part, and `coverage.sh` reports what is left of each. The - snapshot carries milestones and coverage for connectors. - -## [0.1.0] - Unreleased +## [0.1.0] - 2026-10-23 First public release. -- Five skills that take a project from requirements to draft pull requests: - `delivery-orchestrator`, `delivery-spec`, `delivery-decompose`, `delivery-implement` and - `delivery-status`. +- Six skills that take a project from requirements to draft pull requests: + `delivery-orchestrator`, `delivery-spec`, `delivery-decompose`, + `delivery-implement`, `delivery-refine` and `delivery-status`. - Parallel implementation lanes with claims made by create-only git pushes, so - git is the only state. + git is the only state. A lane's branch pushes to itself: a plain `git push` + from a lane worktree reaches `task/`, never the default branch. +- Every lane is two sessions: `delivery-implement`, then `delivery-refine`, which + reviews the change on the tier above, fixes what it finds, simplifies it + without changing its behaviour, re-validates, and adds a Refinement section to + the pull request body. A tier can name its own `reviewer` in `tiers.conf`; + `--no-refine` skips the second session + ([ADR-011](docs/decisions/ADR-011-lane-refinement.md)). - Tasks name a capability `tier` (`plan`, `build` or `chore`) instead of a vendor's model. A `tiers.conf` maps a tier to a harness and a model; with none, the harness picks its own default. Reasoning effort is left to the harness's own settings. +- Milestones: a large project is cut and run one end-to-end slice at a time, + with a reviewed note closing each before the next is cut. `where.sh` and + `follow.sh` stop at each boundary + ([ADR-010](docs/decisions/ADR-010-milestones.md)). +- Requirement coverage: requirements carry ids, tasks list the ids they cover + in full or in part, and `coverage.sh` reports what is left of each. +- A status snapshot that external tools can project into their own views, + including milestones and coverage. +- An install split between `.claude/skills/` and `.agents/skills/`, as + `npx skills update` can leave, is reported by `where.sh` as + `NEXT repair-install`, and the lane launcher refuses to start without + `delivery-implement` or `delivery-refine`. The README explains how to install + so this cannot happen, and how to repair it. - The helpers are POSIX `sh`: no bash is required, and they run on dash, macOS's own `sh` and BusyBox ([ADR-007](docs/decisions/ADR-007-posix-sh-helpers.md)). - Harness adapters for Claude Code, Copilot CLI, Codex, OpenCode and Pi, and a `DELIVERY_LANE_CMD` template for any other ([ADR-008](docs/decisions/ADR-008-harness-adapters.md)). - Multi-repository projects planned once and landed where each change belongs. -- A status snapshot that external tools can project into their own views. - Licensed under Apache-2.0. diff --git a/README.md b/README.md index 9976368..83edc00 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,9 @@ Agent Skills for AI-native delivery: requirements and design spine, decomposition, parallel implementation lanes, review. Git is the only state: no server, no database, no status file. -> **Status: pre-release.** The kit is used on real projects, but no version is -> tagged yet and conventions may still change between commits. Install from -> `main`, read [CHANGELOG.md](CHANGELOG.md) before updating, and expect breaking +> **Status: early.** The kit is used on real projects, and `v0.1.0` is its first +> release. Conventions may still change between versions. Install from `main`, +> read [CHANGELOG.md](CHANGELOG.md) before updating, and expect breaking > changes to be called out there rather than migrated. **This repository is the kit.** The six Delivery Kit skills are one workflow, @@ -94,7 +94,7 @@ of the route to use: | Path | When | What runs | |---|---|---| -| Direct implement | One well-understood change with obvious acceptance criteria | one task file, then `delivery-implement` in the ordinary checkout; no claim, no worktree, only the merge gate | +| Direct implement | One well-understood change with obvious acceptance criteria | one task file, then `delivery-implement` and `delivery-refine` in the ordinary checkout; no claim, no worktree, only the merge gate | | Full route | Several tasks, contracts to keep parallel work consistent, or a decision worth recording | every phase and every gate, up to three lanes at once | How much of a full route runs in parallel is decomposition's finding, not a @@ -157,7 +157,7 @@ flowchart LR T --> L L -->|create-only push| C L -->|on a won claim| W1 & W2 & W3 - W1 & W2 & W3 -->|draft PR| PR([review]) + W1 & W2 & W3 -->|implement, refine, draft PR| PR([review]) ``` A claim is a create-only push of `task/`: the first push wins, the loser is @@ -167,10 +167,16 @@ from git refs and pull request state on every read. The lane cap is three because three is roughly what one person can review, not what the machine can run. +A lane is two sessions in its worktree: `delivery-implement` writes the change, +then `delivery-refine` reviews and tidies it on a stronger model. The launcher +then commits, pushes and opens the draft pull request. The lane's branch pushes +to itself, so a plain `git push` from the worktree reaches `task/` and never +the default branch. + Each lane's worktree goes in `../lanes//`, beside the checkout the launcher runs from, where `` is that checkout's -directory name. The extra level matters because task ids repeat from one use -case to the next: two repositories cloned side by side would otherwise both put +directory name. The extra level matters because task ids repeat from one +project to the next: two repositories cloned side by side would otherwise both put their `a-001` in `../lanes/a-001`. Nothing under `lanes/` is tracked by git: each directory is a `git worktree` registered with its own clone, holding that clone's task branch. @@ -447,6 +453,10 @@ npx skills add https://github.com/ancelin-code/delivery-kit/tree/main \ The `/tree/main` suffix installs what has been released to `main`. Without it, you get the default branch, `develop`, where unreleased work lands first. +To install a release instead of the tip of `main`, name its tag: +`…/delivery-kit/tree/v0.1.0`. The lock file then records that version, and +`CHANGELOG.md` lists what each one changed. + Add an `-a ` for each other harness your team uses; `npx skills add --help` lists the names it knows. @@ -606,6 +616,10 @@ Lanes run detached, one process per task, with no terminal attached. Each writes everything it does to `.lanes/logs/.log` under the main checkout (`--log-dir` moves it). +A lane's log prints `REFINE` when its second session starts, `PUBLISHED` with +the pull request URL when it ends well, and `REFINE-FAILED` if the review +session failed and the change was published as the first session left it. + ```sh tail -f .lanes/logs/a-001.log # follow one lane tail -n 40 .lanes/logs/*.log # where each lane got to @@ -675,6 +689,10 @@ file and the branch: cd "$lane" && claude "/delivery-implement $home/delivery/tasks/a-001.md" ``` +To redo only the review of a change the first session already left in the +worktree, run `/delivery-refine` on the same task file and `--report +.lane-report.md` instead. + Claude Code can also run lanes as attachable background sessions (`claude --bg`, then `claude attach `), which would remove this asymmetry on the Claude side. The launcher does not use it: Copilot CLI has no equivalent, the @@ -757,6 +775,8 @@ the kit only if removing it measurably degrades results. moved or deleted. - Work done with an agent is labelled `ai-assisted`; see [AGENTS.md](AGENTS.md#pull-requests). +- Each test marks its steps with `# Given`, `# When` and `# Then` comments; see + [AGENTS.md](AGENTS.md#validation). ## Maintenance