define-steward

What this skill does

# Define Steward

Use this skill when the user wants a new steward or wants to revise an existing steward. The goal is not to fill out a form. The goal is to define a narrow judgment lens that feels native to this repository and this user's work.

The Steward MCP server must be connected. If `prepare_steward_onboarding` or `configure_steward` is not available, ask the user to run `/mcp`, confirm the `steward` server is connected, and authenticate if Claude Code requests it.

A steward is an AI agent with one zone of concern. Every other artifact - its mission, review lens, backlog, metrics, notes, and first actions - starts from a small structured steward spec: an ownership zone, a rubric of 4-7 dimensions, and a thin layer of inventory, metric, and evidence anchors. The `configure_steward` MCP tool is the only path that writes a steward, and the coding agent owns the post-create activation work.

## Start Here

When this skill starts, first identify the current repository from the local git remote and call `prepare_steward_onboarding` with the concrete `owner/repo` slug.

Handle the response before doing any steward drafting:

- If `next_action` is `authenticate_mcp`, tell the user to complete the Claude Code MCP authentication browser handoff, then call `prepare_steward_onboarding` again.
- If `next_action` is `install_github_app`, give the user the returned install URL. Before sending them off, tell them: "These are two different things — first we connect your account to Steward, then we install a GitHub App so Steward can review PRs." After the browser handoff, return to Claude Code and call `prepare_steward_onboarding` again.
- If `next_action` is `choose_workspace`, call `prepare_steward_onboarding` again with the workspace selector requested by the response.
- If `next_action` is `fix_repository_access`, explain the reported access problem and stop until the user fixes it.
- If `next_action` is `define_steward`, continue in Claude Code. Do not send the user back through web onboarding.

After setup is ready, determine whether this is the user's first steward in this repository. Call `list_stewards` for the resolved workspace and filter to stewards scoped to the current `owner/repo` (matching `repositories` exactly, or workspace-wide stewards that would apply here). If `list_stewards` is unavailable or errors, treat the run as first-steward-in-repo by default rather than skipping orientation. A user can have other stewards in the workspace and still be a first-time user in this repo; do not gate on the workspace-wide count.

When this is the first steward in this repo, the orientation pause below is a required step. Do not propose, inspect, or suggest a zone — and do not ask the opening question — until you have delivered the 3-5 sentence explanation and the user has acknowledged or moved past it. The orientation must cover all three of:

- **Reach**: what a steward owns, and why a steward is useful because it is narrow. Tie this to Ryan's framing — "what is the reach of a steward" — and make it explicit that a steward's reach is one zone of concern, not a department or framework heading.
- **Rubric**: the 4-7 judgment dimensions that make this a good — "optimal" — steward rather than a generic label. The rubric is the steward's point of view, not decorative metadata, and it is what shows up in PR reviews, heartbeats, and consult responses.
- **Vigilance**: what the steward will actually do after creation — review every relevant PR or commit through this rubric, maintain its inventory, and surface concerns when the zone is at risk.

Keep it to 3-5 sentences total, written for this user and this repository (not boilerplate). A concrete opener you can adapt: "A steward is a focused AI agent that owns one narrow domain of your repository — it reviews PRs through its rubric, maintains an inventory of its zone, and gives advice when you work there." Mention that the coding agent will inspect the repo and configure inventory, metrics, notes, and first actions with the user rather than making them fill out a form. Then — and only then — ask the opening question.

When this is not the first steward in the repo, skip the orientation and go directly to the opening question; existing stewards in the same repo mean the user already understands the model.

When the user has not provided an explicit steward zone, ask one short question before inspecting or suggesting zones. Offer three ways in:

```text
How would you like to find this steward's zone?

A. You have a zone in mind — tell me what to watch.
B. Browse battle-tested steward prototypes — narrow lenses that work well across most codebases — and see which fit best here.
C. Inspect the repository and suggest zones grounded in your recent work.
```

All three modes end at the same place: one narrow zone grounded in this repository. They differ only in where the starting lens comes from — the user's intent (A), the prototype library (B), or recent repository activity (C). Every mode is still customized to this repo.

- A: the user names a zone. Inspect the repository to ground it before drafting.
- B: see "Battle-Tested Steward Prototypes" below. Give the short orientation, inspect the repository, then surface the three or four prototypes that fit best, each with one-line evidence. The user picks one; specialize it to this repo.
- C: inspect first, then offer three narrow options grounded in recent work, with one-line evidence for each.

Four options is the hard maximum for any choice menu. Never present five or more options in one question or structured choice menu; Claude Code rejects question menus with too many options. If you find more than four plausible zones or prototypes, show the best three or four and say you can inspect more if none fit. Default to asking the A/B/C question; do not jump straight to a mode C zone-suggestions menu unless the user asked for suggestions or already provided enough context to imply that they want them.

## Battle-Tested Steward Prototypes

Option B starts from a prototype: a narrow steward lens that has proven useful across many codebases. Prototypes are not canned stewards and not templates to paste. They are starting lenses — the narrow-decomposition work already done — that you still ground and specialize against this repository. A prototype tells you where to look; the rubric, inventory, and evidence still come from this repo's real artifacts.

When the user chooses B, give a short orientation (what a prototype is, and that you will fit one to their repo), inspect the repository, then surface the three or four prototypes that best fit, each with one-line evidence from this codebase. Do not list all of them; show the ones that fit. Once the user picks one, the workflow is identical to every other mode.

Current prototypes:

- **Auth & access boundary** — where identity is checked and enforced: route guards, session and token handling, permission checks.
- **Subscription / billing integrity** — plan state, entitlement gating, and webhook-driven billing transitions stay correct.
- **Data retention & PII** — what personal data is stored, where it flows, and whether deletion and retention paths exist.
- **Product analytics contracts** — event names, typed properties, emit sites, and dashboard alignment.
- **Product copy / brand voice** — user-facing strings: tone, terminology, and consistency across surfaces.
- **SEO** — crawlability, metadata, structured data, canonical URLs, sitemap and robots.
- **Dead code** — unreferenced exports, unreachable branches, orphaned files, and stale flags.
- **Perf budget** — latency, bundle size, and render cost measured against a budget.
- **External API surface** — public routes, webhooks, and versioning of backward-compatible contracts.
- **Background jobs & async correctness** — idempotency, retries, ordering, and failure handling in queues and cron.

Each prototype still has to pass the narrowness test for this specific rep