Add an agent-led onboarding skill for first-time setup

[pa911-eric]

Summary

DeployBot already provides the pieces needed to install and operate an agent-managed delivery pipeline:

• deploybot init creates a starter policy.
• deploybot doctor --json / MCP diagnose report setup and policy problems.
• examples/github-workflow.yml provides the pinned coordinator workflow.
• skills/deploybot and skills/manage-merge-queue guide agents after setup.
• Codex, Claude Code, Cursor, and generic MCP clients are supported.

What is missing is the first-run bridge instructions between those pieces.

I would expect to be able to give a coding agent this repository URL and prompt something like "Use DeployBot in this project".

My agent should then adopt a temporary DeployBot Onboarding Assistant role, inspect the target repository, ask the human only for policy decisions it cannot safely infer, prepare the required files and GitHub setup, verify the result, and hand off to the existing operational DeployBot skill.

This seems aligned with DeployBot’s provider-neutral agent model: it adds an agent-readable setup workflow without changing the durable human deploy authorization gate.

Problem

The current surfaces begin on opposite sides of setup:

• The README lists installation steps for a human.
• deploybot init writes a generic starter .mergequeue.toml.
• doctor --json diagnoses a configured or partially configured repository.
• The existing skills teach an already-configured agent how to inspect and operate the delivery pipeline.
• Client adapters must be selected and installed separately.

There is no canonical, agent-executable path that composes these pieces into a safe first-run conversation. An agent must independently discover:

1. which repository and default branch it is configuring;
2. the exact CI workflow/check display names;
3. trusted deploy actors and coordinator actors;
4. whether human or bot review is required;
5. the desired integration and post-merge delivery policy;
6. which client adapter or MCP configuration to install;
7. which repository and GitHub changes require human confirmation; and
8. how to prove the resulting setup is ready.

That makes “use DeployBot” dependent on each agent improvising the installation and security model.

Proposed MVP

Add a canonical onboarding skill, for example:

skills/onboard-deploybot/SKILL.md

Link it prominently from the README with an agent-oriented entry point such as:

For coding agents: when the user asks to install DeployBot in a project, read and follow skills/onboard-deploybot/SKILL.md.

Package or mirror the skill in the supported client adapters using the same release-pinning process as the existing operational skills.

The onboarding skill should define five phases.

1. Discover

Read-only inspection before proposing changes:

• identify the target repository, remote, and default branch;
• detect the active coding client;
• check for gh, GitHub authentication, DeployBot, .mergequeue.toml, a DeployBot workflow, and an installed adapter/MCP entry;
• inspect existing GitHub Actions workflows and observed check names;
• inspect current branch protection/ruleset state where permissions allow;
• run deploybot doctor --json when the CLI and config are available;
• preserve existing configuration and report partial installations rather than overwriting them.

2. Explain and decide

Show the inferred setup, then ask only for decisions that cannot be safely derived:

• exact GitHub logins allowed to say deploy;
• required CI checks;
• optional human, check-based, or bot review providers;
• merge method;
• integration mode (manual, overlap, or all);
• deploy workflows and optional health verifications;
• whether the agent should prepare GitHub-side changes such as labels.

The assistant should explain the security consequence of each decision, especially:

• trusted actors must be explicit;
• github-actions[bot] is a coordinator, not a trusted deploy actor;
• branch protection/rulesets remain the authoritative merge guard;
• the privileged workflow must remain pinned and must not execute PR-head code;
• setup does not authorize any pull request for deployment.

3. Prepare

After the human confirms the proposed configuration:

• install the documented pinned DeployBot release if needed;
• run deploybot init only when no config exists;
• update .mergequeue.toml from the confirmed answers;
• install the pinned coordinator workflow from examples/github-workflow.yml;
• install or describe the appropriate Codex, Claude Code, Cursor, or generic MCP adapter;
• show the exact diff before any commit or push;
• request explicit confirmation before repository-external writes such as deploybot ensure-labels.

The onboarding contract should be idempotent: rerunning it on a partially configured repository should reconcile or report differences, not replace files blindly.

4. Verify

• run deploybot doctor --json;
• verify the workflow’s workflow_run.workflows list agrees with pipeline.ci_workflows;
• verify configured checks were observed or clearly flag that a first CI run is required;
• report unresolved warnings, especially branch-protection/ruleset checks;
• stop short of claiming success if any hard doctor failure remains.

5. Handoff

End with a concise readiness report:

• files prepared or changed;
• GitHub-side state changed;
• warnings or manual owner actions still required;
• example operational prompts such as “show the delivery pipeline” and “why is PR 42 blocked?”;
• an explicit reminder that only the user’s exact deploy instruction authorizes the current thread’s pull request.

Then hand control to the existing deploybot / manage-merge-queue operational skills.

Example conversation contract

User: Use DeployBot in this project.

Agent: I’ll inspect the repository and existing GitHub setup first.

Agent: I found:
- repository: owner/project
- default branch: main
- CI workflow/check: CI
- no .mergequeue.toml
- no DeployBot coordinator workflow
- GitHub CLI authenticated as owner

Before I prepare the setup:
1. Who may authorize deployment by saying `deploy`?
2. Should DeployBot require only the CI check, or also a review provider?
3. Which integration mode do you want: manual, overlap, or all?

Agent: Here is the proposed config and workflow diff. Shall I apply it and
create the required GitHub labels?

Agent: Setup verified. `deploybot doctor --json` has no hard failures.
DeployBot is ready; no pull request has been authorized for deployment.

Acceptance criteria

• A repository-level link clearly tells coding agents where first-run onboarding begins.
• A canonical onboarding skill covers discover → decide → prepare → verify → handoff.
• The flow works for Codex, Claude Code, Cursor, and generic MCP/CLI clients without making one client the canonical model.
• Read-only discovery occurs before any file or GitHub mutation.
• Existing .mergequeue.toml, workflow, and adapter configuration are preserved and reconciled rather than overwritten.
• The assistant asks for explicit trusted actors and never places github-actions[bot] in queue.trusted_actors.
• The generated workflow is pinned to the reviewed release commit and does not execute pull-request-head code.
• The workflow trigger list and pipeline.ci_workflows are checked for agreement.
• GitHub-side writes and commit/push actions are separately disclosed and confirmed.
• Verification uses doctor --json, and hard failures prevent a “ready” result.
• The final handoff loads or points to the existing operational DeployBot skills.
• The onboarding flow never treats setup, CI success, or review completion as deploy authorization.
• Tests or fixtures cover a fresh repository, a partial installation, an existing valid installation, and a failing doctor report.

Backward compatibility

This can be documentation/skill-only for the MVP. It does not require changes to:

• .mergequeue.toml schema;
• GitHub marker schemas;
• existing command behavior;
• the manual deploy authorization model; or
• commit-pinned existing installations.

Possible follow-on: structured bootstrap report

If the documentation/skill flow proves useful, a later issue could add a read-only command such as:

deploybot bootstrap --json

It could combine client-agnostic discovery with doctor output and report:

{
  "repository": "owner/project",
  "installation": "partial",
  "config": {"present": false},
  "workflow": {"present": false},
  "observed_checks": ["CI"],
  "adapter": {"client": "codex", "installed": false},
  "next_actions": []
}

I would keep that out of the MVP unless maintainers prefer a CLI-owned discovery contract. The existing init and doctor --json commands already provide most of the execution and verification primitives; the immediate gap is the canonical agent-led orchestration and conversation.

Out of scope

• Automatically weakening or bypassing repository rulesets.
• Inferring deploy authority from repository roles.
• Automatically committing or pushing without confirmation.
• Authorizing or merging a pull request during onboarding.
• A hosted onboarding service or client-specific UI.

Why this appears aligned

DeployBot describes itself as a provider-neutral merge queue for coding agents, ships agent skills and client adapters, exposes structured MCP/JSON diagnostics, and deliberately keeps the human’s exact deploy instruction as the authority boundary. A provider-neutral onboarding skill extends those same design choices to first-run setup.

The narrow MVP also matches the repository’s existing preference for additive features that reuse structured CLI/MCP primitives and preserve the security model.