deploy-steward

Files (1)

• SKILL.md

SKILL.md (first lines)

# /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`.

From mayankjain1815-commits/CITADEL, MIT.

More from mayankjain1815-commits/CITADEL