Skip to main content
skill CX Codex

deploy-steward — Claude Code skill: what it does, how to install

deploy-steward serializes PR merges into main, tracks CI gates, triggers deploys, and files repair tasks when checks fail.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What deploy-steward does

The skill prevents landing stampedes when multiple agents finish work at once. It processes PRs sequentially using node scripts/deploy-steward.js. Input candidates come from .planning/pr-readiness/*.md reports or explicit URLs supplied via --enqueue-pr. State is saved to .planning/deploy-steward/queue.jsonl.

The steward acquires .planning/deploy-steward/lease.lock to prevent race conditions against main. It inspects PR state via gh pr view, updates branches behind base, waits for checks, and merges via gh pr merge. When checks fail or conflicts appear, it opens a repair task in .planning/intake/ and stops.

An authenticated GitHub CLI is mandatory. Running the steward halts without gh auth status passing, since raw tokens and arbitrary curl calls are rejected by design.

What it helps with

  • serialize multiple pull requests into a safe mainline landing queue
  • update out-of-date branches against main before CI validation
  • execute custom deploy commands after each successful merge
  • generate intake repair tasks when checks fail or conflicts arise

Example prompts for the agent

  • Scan ready PRs and run the steward with the deploy command npm run deploy
  • Enqueue PR https://github.com/OWNER/REPO/pull/123 and execute a dry run
  • Process the landing queue in merge-queue mode

How to install deploy-steward

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill deploy-steward -a claude-code

3Manually: put the files in place

~/.claude/skills/deploy-steward/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/deploy-steward/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about deploy-steward

How to install deploy-steward in Claude Code?

Run /plugin marketplace add SethGammon/Citadel followed by /plugin install citadel@citadel-local. Alternatively, run npx skills add SethGammon/Citadel --skill deploy-steward -a claude-code.

What does deploy-steward do?

It turns parallel agent PRs into a single serial merge stream. It acquires a landing lease, verifies CI checks, updates stale branches, and invokes a deployment script after each safe merge.

What are the prerequisites for running deploy-steward?

You need an active GitHub CLI session (gh auth login) and either .planning/pr-readiness/ reports or specific PR URLs passed via --enqueue-pr.

Source text

SKILL.md · MIT
---
name: deploy-steward
license: MIT
description: >-
  Mainline deploy steward. Consumes ready PRs, owns a lease on mainline landing,
  refreshes PR state, updates stale branches, waits for CI and deploy gates,
  merges or queues one candidate at a time, and opens repair tasks for failures.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - deploy steward
  - deploy queue
  - merge steward
  - mainline steward
  - land prs
  - land PRs
  - deploy prs
  - deploy PRs
  - merge queue
  - release train
effort: high
last-updated: 2026-06-20
---

# /deploy-steward - Mainline Deploy Steward

You are the deploy steward. You serialize mainline landing for parallel agent work.
Your job is to turn many ready PRs into one safe mainline stream: refresh, update,
wait for checks, merge, deploy, and open repair work when something fails.

## When to Use

Use this when the user asks to:

- land multiple ready PRs without a manual merge stampede
- keep agent PRs rebased or branch-updated against latest main
- merge only after required checks pass on current heads
- run a deploy command after each safe serial merge
- open repair tasks for failed checks, conflicts, or closed PRs

Do not use this for code review quality findings; use `/review`. Do not use this
for local worktree conflict analysis only; use `/merge-review`.

## Required Inputs

The steward can start from either source:

- `.planning/pr-readiness/*.md` reports generated by `node scripts/pr-ready.js`
- explicit GitHub PR URLs passed with `--enqueue-pr`

If `.planning/` does not exist yet, run the project setup/init flow first or
create `.planning/pr-readiness/` before scanning. Treat a missing readiness
directory as an empty queue, not as proof that there is nothing to land.

The runtime requires:

- GitHub CLI authenticated for the target repo
- visible PR status checks unless `--allow-no-checks` is explicitly justified
- a deploy command if the repo deploys outside the merge platform

If `gh` is not installed or is not authenticated, stop before `--run` and ask the
operator to run `gh auth status` / `gh auth login`. Do not substitute raw tokens
or ad hoc curl commands inside the steward.

## Invocation Forms

```bash
node scripts/deploy-steward.js --scan
node scripts/deploy-steward.js --scan --run
node scripts/deploy-steward.js --run --deploy-command "npm run deploy"
node scripts/deploy-steward.js --enqueue-pr https://github.com/OWNER/REPO/pull/123 --run
node scripts/deploy-steward.js --run --merge-mode merge-queue
```

Use `--dry-run` before first live use on a repo:

```bash
node scripts/deploy-steward.js --scan --run --dry-run
```

## Protocol

### Phase 1 - Build the Queue

Run:

```bash
node scripts/deploy-steward.js --scan
```

This reads `.planning/pr-readiness`, writes `.planning/deploy-steward/queue.jsonl`,
and records each candidate as `ready`, `blocked`, or already terminal.

For ad hoc PRs:

```bash
node scripts/deploy-steward.js --enqueue-pr <url>
```

### Phase 2 - Acquire the Steward Lease

The run command acquires `.planning/deploy-steward/lease.lock` and mirrors the
lease to `.planning/deploy-steward/lease.json`. If another steward has an active
lease, stop instead of racing main.

Use `--force-lease` only after confirming the old holder is dead.

### Phase 3 - Process One Mainline Candidate at a Time

Run:

```bash
node scripts/deploy-steward.js --run
```

For each processable queue item, the steward:

1. Refreshes live PR state with `gh pr view`.
2. Stops and writes a repair task if the PR is closed, conflicted, or unreadable.
3. Updates the branch against its base when GitHub reports it is behind.
4. Waits when checks are pending.
5. Opens a repair task when checks fail.
6. Merges with `gh pr merge --<method> --match-head-commit <sha>` when checks pass.
7. Runs the optional deploy command after a successful serial merge.

If a branch update, pending check, merge queue wait, or repair task occurs, stop
the run. Rerun after the external state advances.

### Phase 4 - Deploy

For serial landing, pass the project deploy command:

```bash
node scripts/deploy-steward.js --run --deploy-command "npm run deploy"
```

If the repo uses GitHub merge queue, prefer:

```bash
node scripts/deploy-steward.js --run --merge-mode merge-queue
```

In merge-queue mode, the steward queues one PR with GitHub and marks it `landing`.
Rerun after GitHub merges it so the next candidate can be assessed against the
new mainline state.

## State Files

- `.planning/deploy-steward/queue.jsonl` - durable landing queue
- `.planning/deploy-steward/lease.json` - active steward lease mirror
- `.planning/deploy-steward/runs/latest.md` - latest steward report
- `.planning/intake/*deploy-steward*.md` - generated repair tasks

## Safety Rules

- Never let multiple steward runs merge into the same target at once.
- Never merge without a current PR refresh.
- Never merge a PR with failing or pending checks.
- Never merge a conflicted PR; create repair work instead.
- Never force-push a contributor branch from the steward.
- Use `--allow-no-checks` only when the repo truly has no CI.
- Use `--require-fresh-readiness` when local readiness reports must remain the
  source of truth; otherwise live GitHub checks are authoritative after branch
  refreshes.

## Fringe Cases

- **No `.planning/` directory**: stop setup and initialize Citadel state before
  writing queue or repair files.
- **No readiness reports**: report an empty queue; accept explicit `--enqueue-pr`
  URLs if the operator wants to seed the queue manually.
- **`gh` unavailable or unauthenticated**: do not run; surface the authentication
  problem and keep the queue unchanged.
- **PR already merged**: mark the queue item `landed` and continue to the next
  candidate.
- **PR closed without merge**: create a repair intake task and stop.
- **Branch is behind base**: update the PR branch, mark it waiting for checks,
  and stop until CI reruns.
- **Checks fail**: create a repair intake task and stop.
- **Checks pending**: keep the item queued and stop until the external state
  advances.
- **Merge conflict or dirty merge state**: create repair work; never merge or
  force-push from the steward.

## Quality Gates

- `node scripts/test-deploy-steward.js`
- `node scripts/skill-lint.js deploy-steward`
- `node scripts/test-routing-sync.js`
- `node scripts/test-all.js`

## Exit Protocol

Return the steward report and a handoff:

```text
---HANDOFF---
- Queue: <N> candidates in .planning/deploy-steward/queue.jsonl
- Last action: merged | updated-branch | waiting-for-checks | repair-needed | idle
- Report: .planning/deploy-steward/runs/latest.md
- Repair task: <path or none>
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Git and GitHub →

From the same set55

The whole set →
live-preview live-preview takes screenshots of components during construction, not after completion. Catches layout regressions and invisible blocks before they propagate. CX Codex +1 ★ 937repo stars architect architect turns a PRD or task outline into an implementation plan with file trees, data models, and phased build steps. CX Codex +1 ★ 937repo stars cost See token usage and costs for sessions, campaigns, and time periods. Use it to check where spend is going and how quickly it is rising. CX Codex +1 ★ 937repo stars merge-review merge-review scans the fleet worktree merge queue, flags files touched by more than one branch, and suggests a merge order before anything lands in main. CX Codex +1 ★ 937repo stars prd prd turns an app idea into a structured product requirements document, asking about decisions that affect its shape. Use it before handing a project plan to Archon. CX Codex +1 ★ 937repo stars organize organize — a skill that audits and corrects project structure: checks file placement, moves files to match conventions, updates imports. Leaves code inside files untouched. CX Codex +1 ★ 937repo stars create-app create-app — a skill for Claude Code and Codex that builds applications from a single prompt. It routes work across five distinct tiers, passing through PRD, architecture, and verified execution phases. CX Codex +1 ★ 937repo stars postmortem The postmortem skill reviews completed campaigns or incidents using project files, telemetry, and Git history. It shows what failed and which safeguards caught it. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open