Say the outcome, not the orchestration.
github-delivery turns natural-language requests into evidence-backed GitHub workflows for planning, issue work, implementation, PR publication, review, CI, stacks, backports, verified merges, and release maintenance.
Start here · Capabilities · How it works · Safety · Install & update · Watchdog · Workflow map · Development
Warning
Active development. The complete issue/PR lifecycle and core safety architecture are implemented, but the project is not yet 100% production-ready. I currently consider it roughly 80% of the way there. See Current state.
Important
Natural language is the public API. The Node scripts, policy modules, evaluators, mutation broker, and optional Authority host are internal safety/evidence machinery. You normally do not invoke them yourself.
Requirements:
- Node.js 22, 24, or 26
- Git
- GitHub network access
- an authenticated GitHub CLI (
gh auth login) fornpxinstall/update release verification
Recommended zero-clone setup:
npx github-deliveryThe npm package is a thin bootstrap. It verifies and installs the separately published stable GitHub Release payload; npm is not a second authoritative skill payload source.
Then speak naturally:
what do I have open in this repo?
work on ENG-42 and open a PR
triage the competing PRs in this repo
full review PR #42
full review PR #42 and simplify it safely
fix the review comments on PR #18 and make it merge ready
backport PR #42 to release/1.x and release/2.x
merge PR #32
That is the interface.
github-delivery selects the workflow, gathers fresh repository evidence, applies the relevant review/policy gates, performs only the writes authorized by the request, and verifies the resulting state.
A status question stays read-only. A request to implement something does not silently grant publication or merge authority. A merge happens only from current explicit merge intent; deferred permission such as merge PR #42 only after I confirm again is not current merge authority.
For installation edge cases, backup/restore, downgrade behavior, manual recovery, and release verification details, see INSTALL.md.
| Area | Example request | What GitHub Delivery owns |
|---|---|---|
| Plan & triage | create a PRD for the onboarding flow |
PRDs, issue breakdown, QA intake, triage, agent briefs, refactor planning |
| Open work | what do I have open in this repo? |
Read-only repository-scoped view of your open PRs, work-item references, and bounded next actions |
| Issue research | research issue #90 on the latest development branch |
Evidence-backed research against the current development tip |
| Implement & publish | create a PR for issue #90 |
A bounded research → implementation → pre-open review sequence, minimal complete implementation, exact publication identity, linked PR |
| External work items | work on ENG-42 and open a PR |
Tracker-aware delivery orchestration, covering-PR reuse, evidence-driven milestone reconciliation |
| Review & fix | full review PR #42 |
Bug + Security + Spec + Standards review, required probes, current-head verdict |
| Merge readiness | fix the review comments on PR #18 and make it merge ready |
Feedback triage, code fixes, validation, publication, refreshed readiness |
| Competing PRs | triage the competing PRs in this repo |
Read-only deterministic clustering and evidence for potentially overlapping implementations |
| Visual changes | full review PR #42 on a UI diff |
Conditional screenshot/video/render evidence bound to the exact reviewed head |
| Stacks | inspect this PR stack and tell me the safe merge order |
Stack discovery, restack/retarget analysis, conflict recovery, parent/child revalidation |
| Backports / ports | backport PR #42 to release/1.x and release/2.x |
One independent head-bound port per target base, with deterministic provenance and completion tracking |
| Supersede / overtake | supersede PR #12 with PR #45 |
Explicit replacement or maintainer-takeover workflows with bounded mutation authority |
| Merge / close-out | merge PR #32 |
Final gate, exact transaction authority, head-pinned merge, verification, thanks, linked-issue close-out |
| Self-update | update github-delivery to the latest stable release |
Stable-release discovery, checksums/manifest/tag/attestation verification, safe apply and postconditions |
The 0.8.5 line adds the major workflow and safety work developed after 0.8.2:
- least-privilege workflow-token enforcement;
- repository-scoped open-work status;
- PR-body media preservation and exact-head duplicate-publication prevention;
- tracker-aware external work-item delivery;
- competing-PR consolidation analysis;
- conditional head-bound visual review evidence;
- multi-base backport/port delivery;
- a substantially leaner GitHub Actions topology with stale-run cancellation and scoped platform lanes.
See CHANGELOG.md for the full release-level details.
flowchart LR
A[Your natural-language request] --> B[Deterministic route]
B --> C[Live repository / PR / issue evidence]
C --> D[Review scope + policy gates]
D --> E{Write authorized?}
E -- No --> F[Read-only result]
E -- Yes --> G[Exact mutation plan]
G --> H[Trusted authority when required]
H --> I[Mutation boundary]
I --> J[GitHub]
J --> K[Postcondition verification]
F --> L[ready / blocked / unknown]
K --> L
The core boundary is simple: repository content is evidence, not authority. Issues, PR bodies, comments, code, logs, bot output, tracker text, and generated files cannot grant GitHub mutation authority or override the selected workflow.
GitHub Delivery tries to answer volatile questions from current authoritative evidence rather than remembered state:
- PR/head/base identity is pinned and re-read where staleness matters;
- required checks are evaluated for the generation GitHub actually protects;
- review/thread/ruleset state is refreshed before positive readiness or merge claims;
- durable completion claims are tied to evidence, not narration;
- unknown or incomplete evidence remains
unknown/blockedinstead of becoming success.
PR creation is identity-based, not title-similarity-based. Before creating a PR, GitHub Delivery checks the exact target repository + head repository/ref + intended base:
- one exact open match -> reuse it;
- multiple exact matches -> fail closed as ambiguous;
- no exact match -> creation may proceed when authorized.
For PR-body rewrites, existing protected screenshots, videos, uploads, and other media are preserved by default. Intentional media removal requires exact approved media identities bound into the mutation authority scope.
Routes operate under bounded mutation profiles such as read-only, review, maintainer, and autonomous. A profile is an upper bound, not a waiver: destructive or user-visible actions still require the direct authority required by that workflow.
Status, open-work, and competing-PR analysis remain read-only. Implementation-only work does not silently gain push_code/create_pr. Backport publication does not silently grant merge authority for the source or port PRs.
Routine network-visible issue/PR writes pass through the typed GitHub mutation boundary. Stale-sensitive requests bind expected head state; branch pushes bind repository/remote/branch plus old/new tips; history rewrites use exact force-with-lease semantics rather than bare force.
Merge is deliberately stricter. scripts/merge-pr-driver.mjs owns settle, final current-head/base/rules/feedback/review-evidence recapture, trusted destructive authority, head-pinned merge execution, and post-merge reconciliation. Generic hand-built merge mutation documents are rejected.
Where high assurance is required, trusted grants bind the semantic effect rather than a vague permission flag: repository, action, mode, PR/head, merge method, target identity, idempotency data, and hashes of human-visible text as applicable.
The optional Windows Authority host can issue those grants through Windows Hello. Missing persistent user configuration defaults the effective preference to Sensitive actions (high-assurance); an explicitly stored off or all preference remains supported.
Durable creates/social writes use authenticated exact-effect receipts and read-before-write checks. A hidden marker alone is not proof of ownership or successful prior execution.
Only proven read-only GitHub operations may use bounded rate-limit retry behavior. Ambiguous writes are never blindly retried. An uncertain merge outcome is reconciled through read-only exact-head state instead of issuing a second merge.
Code pushes, base updates, simplification, and other branch mutations require the ownership/maintainer authority declared by the selected workflow. Foreign PRs receive owner instructions unless the user explicitly enters a maintainer-overtake path.
The implementation-level contracts live in:
references/policy-kernel.mdreferences/shared-rules.mdreferences/github-mutation-broker.mdreferences/merge-pr.mdreferences/completion-claims.md
"Green CI" is necessary when required, but it is not the whole review bar.
A full review can combine:
- Bug review;
- Security review;
- Spec review;
- Standards review, including design-quality and typed-code evidence lenses when relevant;
- semantic propagation across related producers/consumers/public forms;
- deterministic required probes derived from the diff;
- proactive contract verification appropriate to the changed behavior;
- conditional visual evidence for rendered/UI surfaces.
Simplification is explicit-only. Its goal is lower cognitive load and safer maintenance. Line count is never the goal; fewer lines are acceptable only when behavior and clarity improve.
A simplification pass may validly conclude that there is nothing worth simplifying. Any proposed mutation still requires explicit approval. After approved candidates are applied and validated, GitHub Delivery automatically runs the complete full review again on the changed head with simplification disabled before publishing the final verdict. See references/simplify-pr.md.
Security-sensitive findings follow SECURITY.md. Undisclosed vulnerabilities belong in private vulnerability reporting, not a public issue or review thread.
Visual evidence is required only when the diff actually carries a visual-surface signal. Accepted evidence is screenshot/video/deterministic render material bound to the exact current head SHA. Stale artifacts and text-only claims do not satisfy that axis; real preview/runtime blockers stay blocked.
The final ship decision is one authoritative ready, blocked, or unknown result from live evidence. Positive readiness/merge claims require a fresh final gate.
- current required-check generation and producer identity;
- active required-status-check rules and strictness;
- review decision, stale approvals, last-push requirements, unresolved threads;
- conflicts, behind state, merge queue / auto-merge state;
- unknown ruleset/state values failing closed;
- exact-head merge execution and read-only reconciliation after ambiguous write results;
- partial success when merge succeeded but non-destructive post-merge ceremony did not.
These are intentionally three different concepts.
A stack is a dependency chain where a child PR targets a parent PR branch. Stack operations discover repository-qualified topology, restack bottom-up, preserve layer ownership, and revalidate every surviving child after an upstream head changes.
Competing-PR analysis is read-only. A shared work-item key establishes related work, not automatic replacement. Supersede-grade planning requires direct substantial implementation overlap between the selected canonical PR and every PR proposed for replacement; transitive A-B-C clustering cannot let A supersede C without direct evidence.
Ports are parallel, not stacked. Each target base gets an independent branch/PR bound to:
- repository;
- source PR;
- exact source head SHA;
- exact target base;
- deterministic provenance marker.
Wrong-base provenance, multiple port markers, duplicate port PRs, invalid refs, or incomplete required targets fail closed. Merge authority remains separate for every port.
npx github-deliveryBare invocation runs environment preflight, detects valid installations, verifies the stable GitHub Release, shows the plan, and asks before skill-target mutation. Confirmation defaults to No.
Useful explicit commands:
npx github-delivery install
npx github-delivery setup
npx github-delivery start
npx github-delivery autostart
npx github-delivery autostart on
npx github-delivery autostart off
npx github-delivery autostart status
npx github-delivery doctor
npx github-delivery doctor --json
npx github-delivery update
npx github-delivery update --applyCheck/verify/plan only:
npx github-delivery updateApply the verified plan:
npx github-delivery update --applySelf-update accepts only the fixed upstream's latest stable vX.Y.Z GitHub Release and replaces nothing until release assets, checksums, distribution manifest, tag/source binding, constrained GitHub artifact attestation, and bounded ZIP extraction verify. Local tracked modifications block replacement even with --force; update does not silently downgrade an ahead install.
npx github-delivery setup
npx github-delivery doctorsetup repairs/finishes activation against an existing managed installation. doctor is read-only and summarizes environment, installed version/integrity, persistent configuration, watchdog activation, stable-update relation, and Windows Authority state. Use doctor --json for machine-readable output.
On supported Windows systems, the stable GitHub Release can include the separately verified self-contained Authority host. Guided setup/update can install or repair it without a local .NET SDK when required or already configured.
npx github-delivery start ensures the host is running and brings the Control Center into view. Login auto-start is opt-in and shared between the CLI and Control Center setting. Normal window close leaves Authority in the tray; tray right-click -> Exit shuts it down completely.
The host is not silently installed for a user whose protection mode is off and who has never installed Authority.
git clone https://github.com/Wibias/github-delivery.git
cd github-delivery
npm run build:dist
node scripts/install-skill.mjs
node scripts/install-skill.mjs --applyTypical skill locations:
~/.agents/skills/github-delivery
~/.cursor/skills/github-delivery
~/.codex/skills/github-delivery
~/.claude/skills/github-delivery
A same-version byte-identical normal reinstall is an unchanged no-op. Same-version payload drift remains fail-closed, including with --force.
Full installation and recovery behavior is documented in INSTALL.md.
GitHub Delivery treats convergence as a runtime + workflow problem rather than a prompt-only rule. The watchdog is defence in depth around execution; it never grants GitHub mutation authority.
| Enforcement level | Purpose |
|---|---|
| Policy | Universal bounded-progress/evidence-economy fallback when the host exposes no trusted interception surface |
| Codex lifecycle hooks | Turn-scoped duplicate/poll/evidence limits and bounded narration recovery at supported tool boundaries |
| Protected Codex stream | Launch-controlled App Server stream that can interrupt in-flight no-progress/tool-emission/protocol stalls |
| Workflow controller | Route/phase locking, checkpointed progress, bounded retries/evidence/actions/tokens/steps/wall time |
Key defaults include:
- evidence warning/block at 8 / 12 consecutive attempts without execution/state progress;
- protected-stream active-work warning/hard bounds of 4k / 8k generated characters and 1,024 / 2,048 generated output tokens since real progress;
- larger completed-plan finalization allowance of 40k / 64k characters and 12k / 16k output tokens;
- bounded lifecycle-hook narration recovery with up to three corrective continuations by default;
- 6,000 serialized characters as the default Codex hook subagent-input budget;
- controller no-progress escalation at 2 / 3 / 4 cycles, with bounded phase/workflow retry, evidence, token, step, and wall-time budgets.
A configured hook is not automatically trusted/active. Codex ties trust to the exact non-managed hook definition; GitHub Delivery reports hook_trust_required instead of claiming protection that has not been verified.
Runtime capability reporting distinguishes:
Full (STREAM)— controlled in-flight stream interruption;Partial (HOOKS)— supported lifecycle/tool-boundary protection;Off (NONE)— no verified interception boundary.
For the complete budgets, trust model, incident replays, false-positive controls, and host integration, see references/agent-progress-watchdog.md.
| Area | Requests | Workflow / method |
|---|---|---|
| Product / issue intake | PRDs, breakdowns, triage, QA intake, refactor plans | references/issue-workflows.md |
| Agent-ready work | Create/update a ready-for-agent contract |
references/agent-brief.md |
| Rejected scope | Record/reconsider/remove an out-of-scope decision | references/out-of-scope.md |
| Issue research | Research an issue on the latest development tip | references/research-issue.md |
| Create local-work PR | Publish already-existing local work | references/create-pr-from-local-work.md |
| Create linked PR | Bounded research -> implementation -> pre-open review -> PR | references/create-pr-for-issue.md |
| Open work | Repository-scoped authored-open-PR overview | references/open-work-status.md |
| External work item | Inspect/deliver ENG-42-style tracker work |
references/work-item-delivery.md |
| Competing PRs | Analyze overlapping/duplicate implementations | references/consolidate-prs.md |
| Status | What is left / why blocked / merge readiness | references/status.md |
| Make merge-ready | Fix humans/bots, own review work, validate | references/fix-pr-bots.md |
| Watch | Poll CI/reviews/gates until merged/closed/blocked | references/watch-pr.md |
| Re-review | Re-evaluate after head/review evidence changes | references/re-review-pr.md |
| Full review | Deep Bug + Security + Spec + Standards review | references/full-review-pr.md |
| Visual evidence | Conditional rendered-surface evidence axis | references/visual-evidence.md |
| Bug review | Evidence-ranked adversarial bug hunt | references/bug-review.md + references/bug-hunt-method.md |
| Security review | Security surfaces, escalation chains, safe reporting | references/security-review.md |
| Spec / standards | Contract, requirements, standards, docs/non-goals | references/spec-standards-review.md |
| Design quality | Advisory design/abstraction/state/seam review | references/design-quality.md |
| Type evidence | Typed-code evidence erosion / anti-slop review | references/type-evidence-review.md |
| Minimal solution | Lowest-complexity complete implementation choice | references/minimal-solution.md |
| Verification boundaries | Stable regression/refactor evidence boundary | references/verification-boundaries.md |
| Change execution | Safe migrations, mechanical sweeps, expand-contract | references/change-execution.md |
| Completion evidence | Prove durable completion/count/coverage claims | references/completion-claims.md |
| Safe simplification | Behavior-preserving cleanup + mandatory re-review | references/simplify-pr.md |
| Prepare + merge | Compound review/fix/simplify request with explicit merge | references/prepare-and-merge-pr.md |
| Merge | Settle, final live gate, exact head-pinned merge | references/merge-pr.md |
| Supersede | Replace an obsolete PR with a canonical PR | references/supersede-pr.md |
| Maintainer overtake | Take over an unresponsive author's PR | references/overtake-pr.md |
| Conflicts | Resolve active conflicts from both sides' intent/evidence | references/resolve-conflicts.md |
| Stacked PRs | Inspect/restack/retarget/recover/review/merge stacks | references/stacked-prs.md |
| Backports / ports | Parallel delivery to one or more target bases | references/multi-base-delivery.md |
| Update installed skill | Verify/check/apply latest stable release | references/update.md |
| Progress watchdog | Runtime generation bounds and workflow convergence | references/agent-progress-watchdog.md |
create a PRD for the onboarding flow
break the roadmap into implementation issues
triage the open issues in this repo
show me what needs triage in this repo
what do I have open in this repo?
research issue #90 on the latest development branch
create a PR for issue #90
research and implement issue #90
work on ENG-42 and open a PR
what's left on ENG-42?
what is left on PR #41?
is PR #42 safe to merge?
full review PR #42
fix the review comments on PR #18 and make it merge ready
watch PR #77 until it merges or needs me
simplify PR #42 without changing behavior
review PR #42, fix it, and merge it when green
merge PR #32
triage the competing PRs in this repo
inspect this PR stack and tell me the safe merge order
backport PR #42 to release/1.x and release/2.x
supersede PR #12 with PR #45
maintainer overtake PR #32 and finish it
update github-delivery to the latest stable release
Supported runtime contract:
Node.js 22 | 24 | 26
Run the canonical repository gate:
npm run checkUseful focused commands:
npm test
npm run security:repo
npm run dist:check
npm run package:check
npm run evals:offline
npm run reliability:gateThe pull-request CI topology is deliberately asymmetric to avoid repeating the full repository suite across every OS/runtime combination:
| Required context | PR behavior |
|---|---|
| Node 24 / ubuntu-latest | Canonical full npm run check; then bounded Node 26 syntax/package/unit compatibility on the same workspace |
| Node 22 / ubuntu-latest | Bounded compatibility lane only when runtime-relevant paths change; forced for main/live-fixture acceptance |
| Node 24 / windows-latest | Windows Authority restore/build/self-test/publish/install smoke only when Authority/platform-relevant paths change; forced for main/live-fixture acceptance |
| Dependency Review | Runs on pull requests |
| CodeQL / Analyze (javascript-typescript) | Runs on pull requests |
| CodeQL / Analyze (csharp) | Scoped to Windows Authority/C#-relevant PRs; still runs on main and schedules |
There are no macOS PR compatibility lanes and no duplicate Architecture Contracts workflow. Superseded CI, CodeQL, and Dependency Review runs are cancelled when a newer commit arrives. Repository-policy verification is daily and orphan-workflow cleanup is weekly.
For ordinary runtime-relevant PRs this reduces full npm run check executions from 9 to 1, full unit-suite runtime executions from 9 to 3, Windows Authority lanes from 2 to 1 when relevant, and macOS PR jobs from 2 to 0 while retaining Node 22/24/26 compatibility coverage.
The unit/eval suite proves deterministic contracts. An explicitly opted-in fixture repository exercises the real GitHub lifecycle with immutable repository-identity binding before the first mutation. Fixture runs force the scoped Node 22 and Windows compatibility lanes even when normal PR path filtering would skip them.
See docs/live-integration.md and docs/live-github-integration.md.
The public interface stays small even though the enforcement surface is not. Key internals:
| Surface | Responsibility |
|---|---|
SKILL.md |
Host discovery and top-level natural-language capability map |
scripts/lib/skill-router.mjs |
Deterministic route and explicit-action selection |
references/policy-kernel.md + references/policy/*.md |
Canonical cross-workflow and focused policy contracts |
scripts/delivery-controller.mjs |
Persistent routed workflow state/budget controller |
scripts/ship-gate-snapshot.mjs |
Current GitHub evidence snapshot |
scripts/ship-gate.mjs |
Authoritative ready / blocked / unknown decision |
scripts/merge-pr-driver.mjs |
Canonical destructive merge boundary |
scripts/github-mutate.mjs |
Typed non-merge GitHub mutation entrypoint |
scripts/lib/authority-scope.mjs |
Exact-effect trusted authority scope |
authority-host/windows/ |
Optional Windows Hello trusted-authority issuer |
scripts/review-scope.mjs |
Evidence-ranked review scope and required probes |
scripts/lib/visual-evidence.mjs |
Conditional head-bound rendered-evidence planning/validation |
scripts/lib/work-item-delivery.mjs |
Tracker milestone/reconciliation planning |
scripts/lib/pr-consolidation.mjs |
Read-only competing-PR clustering/planning evidence |
scripts/lib/multi-base-delivery.mjs |
Parallel port identities/provenance/completion |
scripts/lib/agent-progress-watchdog.mjs |
Shared progress/evidence/tool-emission watchdog logic |
scripts/build-dist.mjs |
Deterministic versioned skill bundle build |
scripts/prepare-release.mjs |
Release identity/checksum/SBOM/provenance preparation |
The architecture uses progressive disclosure: route once, load the selected workflow plus required policy modules, and escalate diagnostics only when needed rather than dumping the full rule set into every agent turn.
Implemented today:
- natural-language routing for the issue/PR lifecycle;
- read-only open-work and competing-PR analysis;
- issue research, implementation, publication, external work-item delivery, and exact-head duplicate prevention;
- deep current-head review with deterministic probe coverage and conditional visual evidence;
- mutation authority, exact-effect receipts, stale-head protection, and head-pinned merge execution;
- stack restacking/merge-order safety and independent multi-base delivery;
- verified stable install/update and optional Windows Authority host;
- progress watchdog/runtime convergence controls;
- deterministic bundles, repository security checks, CodeQL, Dependency Review, live-fixture contracts, and release preparation.
Still active-development territory:
- host/runtime integrations remain constrained by what each agent host exposes;
- the protected Codex App Server streaming boundary depends on an experimental upstream interface;
- broader tracker adapters beyond the normalized work-item contract can be added without weakening GitHub authority boundaries;
- more real-world fixture coverage and adversarial incident replays are still valuable as the system expands.
The project intentionally fails closed rather than claiming unsupported coverage.
Some workflow directions were informed by public/open-source agent skills and GitHub automation patterns, including concepts from OutThisLife/brooklyn-skills. Adapted ideas are rewritten around GitHub Delivery's own evidence, authority, routing, and lifecycle contracts; relevant workflow files include provenance notes where appropriate.
Licensed under the MIT License.