Repository navigation
feat(git): add the ship skill - #346
Conversation
The records and the two delivery terms settle what git:ship is before the skill is written: one manual-only skill with two end points, whose invocation authorizes the whole delivery while every stop of a chained skill stays a blocker.
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ddd8170a35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
🟡 Changes recommended
Two critical workflow defects remain: the merge-ready endpoint can incorrectly continue into the merge workflow, and history-rewriting parent merges can leave child requests containing stale parent commits or conflicts.
2 open issues
What changed in this PR
Adds the manual-only git:ship workflow, which carries work from its current stage through implementation, review, publication, CI, and merge—or stops at merge-ready when requested. It extends Git plugin documentation and records the delivery-plan and authorization decisions.
Changes:
- Adds
git:shipwith stage detection, delivery planning, blocker handling, review requirements, stack sequencing, and reporting rules. - Adds Codex metadata, documentation, plugin terminology, and bumps the Git plugin version to
4.5.0. - Adds ADRs documenting the skill’s two endpoints and authorization model.
| File | Description |
|---|---|
| README.md | Documents the new git:ship skill and its engineering-plugin requirement. |
| plugins/git/skills/ship/SKILL.md | Defines the manual-only delivery orchestration workflow, endpoints, stage detection, blocker handling, and stack sequencing. |
| plugins/git/skills/ship/agents/openai.yaml | Adds Codex display metadata and disables implicit invocation for the skill. |
| plugins/git/README.md | Documents the skill, dependency, invocation, authorization, and workflow behavior. |
| plugins/git/plugin.json | Bumps the portable Git plugin version to 4.5.0. |
| plugins/git/.claude-plugin/plugin.json | Aligns the Claude plugin extension version at 4.5.0. |
| plugins/AGENTS.md | Adds the Delivery plan and Stack terminology and their relationship. |
| docs/adr/README.md | Indexes ADRs 0006 and 0007. |
| docs/adr/0007-a-ship-invocation-authorizes-the-whole-delivery.md | Records the authorization, blocker, and exception model for ship. |
| docs/adr/0006-ship-is-one-git-skill-with-two-end-points.md | Records the decision to provide one skill with merged and merge-ready endpoints. |
Review effort: Lite
There was a problem hiding this comment.
🟡 Changes recommended
The starting-stage matrix cannot resume an already merged change request that still requires verification or cleanup, instead attempting to create a duplicate request or reporting nothing to ship.
1 open issue
2 resolved since last review
Review effort: Lite
There was a problem hiding this comment.
🟡 Changes recommended
Approval is blocked by a critical endpoint-safety issue that can merge or delete artifacts after a request was already merged, plus a moderate cleanup gap that can leave the merged parent branch orphaned.
2 open issues
1 resolved since last review
Review effort: Lite
There was a problem hiding this comment.
🟡 Changes recommended
Approval is blocked by two critical correctness gaps and two moderate cleanup issues that can allow stale or unreviewed heads, incorrect dependent branches, or orphaned remote branches while reporting success.
4 open issues
2 resolved since last review
Review effort: Lite
The delivery skills already continue into each other when the request asks for a later outcome, but the request had to be restated in prose each time, and nothing said what a session does when one of them stops. git:ship is a manual-only skill that takes the work from its current stage to a merged change request, or to a merge-ready one on request. An invocation authorizes the whole delivery, and every stop a chained skill defines stays a blocker that ship reports and waits on.


The delivery skills already continue into each other when the request asks for a later outcome:
engineering:tddends inengineering:review-changes,create-prcontinues intobabysit-prormerge-pr, andbabysit-prcontinues intomerge-pr. Using that chain meant restating the requestin prose every time, and nothing said what a session does when one of the skills stops partway.
This change adds
git:ship, a manual-only skill that takes the work from its current stage to amerged change request, or to a merge-ready one when the invocation asks to stop there.
How it behaves
commits, change requests, the review loop, a normal merge, and its cleanup. It adds nothing a
chained skill excludes, such as an administrative bypass or an unapproved reply to a person.
shipreports it and waits, the answer resolves that blocker only, and the run continues to theend point or the next blocker. A stop that only recommends another skill of the chain is a hand
off that
shipfollows.shipmerges aresolved-with-exceptionschange request only whenbabysit-prrecommends that merge, and it lists each exception. It also stops before a merge that no review
covered.
shipreads the stage from the checkout and the forge, so it can start fromsettled decisions, unpublished changes, or an open change request, and it continues after a
context compaction.
shipdecides the split, states it, and proceeds. Dependent change requests run in sequence whenthe end point is merged.
shipbuilds a stack only for a merge-ready end point or a recordedplan.
shiphas a hard requirement on theengineeringplugin, in the form the requirement policy inplugins/AGENTS.mddefines.Decisions
Two decision records carry the reasons: 0006 for one skill with two end points in the
gitplugin,and 0007 for the authority an invocation carries.
plugins/AGENTS.mdgains the terms Deliveryplan and Stack.
The first version builds a stack from plain base branches and does not use a forge's stack feature.
A review fix to a parent branch after its child exists is a blocker, because
tidy-historyrefusesa branch that an open change request targets.
Refs: #344
Validation
Three pressure-test runs in isolated agents passed without a wording change:
merge, and reported the blocker.
resolved-with-exceptionsresults: the agent merged the onebabysit-prrecommended, held the one with a deferred finding, and filed no issue.merge-ready end point.
The pressure tests did not cover stacks or GitLab. The skill is manual-only, so it has no trigger
fixtures.