Setup

Setup

/setup is the first thing a user runs after npx skills add Background-Craft/hydrant-skills. It collapses three chores into a single guided ritual: getting a Hydrant personal access token, configuring the hosted MCP server in the user's harness, and dropping a workflow pointer into AGENTS.md so future invocations of /create-issue, /refine, /nail, /prep, /go, /preflight, /yeet, and /cleanup know they exist.

/setup writes config files. It is the one skill in this catalogue that mutates anything beyond AGENTS.md. Treat the user's existing files with care.

What this skill produces

Three artifacts, in order:

1. An MCP server entry for hydrant in the active harness's MCP config, pointing at https://hydrant.dev/mcp with Authorization: Bearer hyd_pat_….

2. A fenced lifecycle-workflow section appended to AGENTS.md at the repo root:

   <!-- BEGIN: hydrant lifecycle -->
   ## Hydrant lifecycle
   
   <!-- Generated by /setup. Re-run /setup to update. Manual edits inside this fence are preserved on re-run only when /setup prompts before overwriting. -->
   
   This codebase uses the Hydrant ticket lifecycle. Skills available:
   
   - `/create-issue` — interview the user, draft a well-shaped ticket, write via `mcp__hydrant__create_issue`
   - `/refine` — analyze an existing ticket, surface gaps, update via `mcp__hydrant__update_issue`
   - `/nail` — tighten ambiguity, ground references against the codebase, extract metadata into proper fields
   - `/prep` — assess implementation readiness, surface clarifying questions before starting
   - `/go` — guided implementation: fetch context, create branch, plan, build
   - `/preflight` — pre-PR mechanical checks, adversarial review, quality scoring
   - `/yeet` — ship pipeline: detect commit/push/PR/merge state, pick up from there
   - `/cleanup` — post-merge sync, prune branches
   
   Run `/align` once to record this codebase's conventions (test command, branch naming, PR flow) so the lifecycle skills don't have to ask every time.
   <!-- END: hydrant lifecycle -->
   

3. A mirrored copy of the same fenced section in CLAUDE.md, but only when the active harness is Claude Code (Claude Code reads CLAUDE.md for memory; other harnesses use AGENTS.md).

That is the entire write set. No other file is touched.

Workflow

Run these phases in order. Stop at the first phase that fails and surface a clear error — never silently move on.

Phase 1: Detect the harness

Walk the repo root and the user's home directory looking for harness signals. Stop at the first match in this priority order; do not keep looking once you have one.

1. .claude/ directory at repo root → Claude Code
2. .cursor/ directory at repo root, or ~/.cursor/ → Cursor
3. .codex/ directory at repo root, or ~/.codex/ → Codex CLI
4. .opencode/ directory at repo root, or ~/.opencode/ → OpenCode
5. ~/.gemini/ directory → Gemini CLI
6. None of the above → generic (the skill prints a JSON snippet at the end and lets the user paste it)

Record the detected harness in working memory. Tell the user what you detected and that you'll proceed unless they correct you.

Phase 2: Get a Hydrant PAT

If the user already has a PAT they're ready to paste, skip to the prompt. Otherwise:

1. Tell the user where to generate one: https://hydrant.dev/settings/tokens (or whatever the current settings UI calls it).
2. Tell them what scope to grant — full read/write on the space they want to wire up.
3. Wait for them to paste the token.

Then ask for the space slug they want as the default (e.g. hydrant, acme). The slug is needed because most lifecycle skills accept a spaceId argument and the canonical lookup is mcp__hydrant__get_space(slug: …).

Validate quickly before writing anything:

• Token must start with hyd_pat_. If it doesn't, tell the user it looks wrong and ask them to re-paste.
• Slug must be lowercase letters/digits/hyphens. If it isn't, normalize and confirm with the user.

Do not echo the token back in plaintext after you've stored it. When you reference it in subsequent prompts, mask it (hyd_pat_***…***).

Phase 3: Configure the MCP server

Pick the path for the detected harness. If the user runs Claude Code or Cursor, ask whether they want project scope (lives in the repo, gets committed) or user scope (lives in their home directory, applies to every repo). For the rest, use the harness's documented default scope.

Always check whether a hydrant MCP entry already exists at the target location before writing. If it does:

• If the existing entry's URL matches the hosted endpoint and only the token differs → tell the user "an existing entry was found; replacing it" and proceed.
• If the existing entry points somewhere else (a self-hosted URL, a custom command) → stop and ask the user before overwriting. They may be running their own MCP server intentionally.

Claude Code

• Project scope → .mcp.json at the repo root. Create the file if it doesn't exist.
• User scope → run claude mcp add if the CLI is available; otherwise edit ~/.claude.json.

Snippet (HTTP transport, native — Claude Code supports HTTP MCP servers directly):

{
  "mcpServers": {
    "hydrant": {
      "type": "http",
      "url": "https://hydrant.dev/mcp",
      "headers": {
        "Authorization": "Bearer hyd_pat_…"
      }
    }
  }
}

CLI form for user scope (preferred over hand-editing ~/.claude.json):

claude mcp add --scope user --transport http hydrant https://hydrant.dev/mcp \
  --header "Authorization: Bearer hyd_pat_…"

Note: .claude/settings.json holds permissions, hooks, and env — not MCP server definitions. The canonical home for MCP entries in Claude Code is .mcp.json (project) or ~/.claude.json (user, written by claude mcp add).

Cursor

• Project scope → .cursor/mcp.json at the repo root. Create the directory and file if missing.
• User scope → ~/.cursor/mcp.json.

Snippet (Cursor supports HTTP MCP servers natively):

{
  "mcpServers": {
    "hydrant": {
      "url": "https://hydrant.dev/mcp",
      "headers": {
        "Authorization": "Bearer hyd_pat_…"
      }
    }
  }
}

Codex CLI

Codex's TOML config does not always support HTTP transport directly. Use the mcp-remote stdio bridge to be safe. Append to ~/.codex/config.toml:

[mcp_servers.hydrant]
command = "npx"
args = ["-y", "mcp-remote", "https://hydrant.dev/mcp", "--header", "Authorization: Bearer hyd_pat_…"]

If the user is on a recent Codex build that has native HTTP MCP support, they can swap this for the URL form documented in their Codex release notes.

OpenCode

OpenCode reads MCP config from opencode.json at the project root or the user's config directory. Use the mcp-remote stdio bridge:

{
  "mcp": {
    "hydrant": {
      "type": "local",
      "command": ["npx", "-y", "mcp-remote", "https://hydrant.dev/mcp", "--header", "Authorization: Bearer hyd_pat_…"]
    }
  }
}

If the user's OpenCode build supports the type: "remote" HTTP form, use that instead — check their docs for the current key name (url vs endpoint).

Gemini CLI

Gemini CLI's user config lives at ~/.gemini/settings.json. Most builds expect a stdio-launched MCP server, so use the mcp-remote bridge:

{
  "mcpServers": {
    "hydrant": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hydrant.dev/mcp", "--header", "Authorization: Bearer hyd_pat_…"]
    }
  }
}

Generic / unknown harness

Print the JSON snippet below and tell the user to consult their harness's MCP server documentation for the right file location and key name. Do not write any files in the generic path — the user opted into manual install by running an unrecognized harness.

{
  "mcpServers": {
    "hydrant": {
      "url": "https://hydrant.dev/mcp",
      "headers": {
        "Authorization": "Bearer hyd_pat_…"
      }
    }
  }
}

If their harness only supports stdio, point them at npx -y mcp-remote https://hydrant.dev/mcp --header "Authorization: Bearer hyd_pat_…" as the bridge.

Phase 4: Write the lifecycle section to AGENTS.md (and CLAUDE.md if Claude Code)

Now write to AGENTS.md at the repo root.

1. If AGENTS.md doesn't exist: create it with a top-level # Agents heading and the lifecycle block as the first section. Do not pull in any other content.
2. If AGENTS.md exists and contains a <!-- BEGIN: hydrant lifecycle --> fence: replace only the fenced region (inclusive of both sentinels) after prompting the user. Never silently overwrite. Do not touch any line outside the fence. Do not reorder or reflow surrounding content.
3. If AGENTS.md exists but has no fence: append the fenced block at the end of the file, separated from prior content by a single blank line.
4. Coexist with /align: the <!-- BEGIN: hydrant alignment --> fence (written by /align) is a separate region with separate sentinels. Do not touch it. Both blocks live in the same AGENTS.md peacefully.

When the active harness is Claude Code, also mirror the same fenced block into CLAUDE.md at the repo root using the same rules. Skip this mirror for any other harness — CLAUDE.md is Claude-specific memory and other harnesses ignore or actively conflict with it.

Manual-edit safety. If you detect that the existing fence has a comment line like # manually edited or the body has been reflowed into prose, pause and ask the user before overwriting:

"The existing lifecycle block has been hand-edited. Overwriting would lose those edits. Do you want to overwrite, keep the existing version, or abort?"

Only proceed once the user picks one.

Phase 5: Verify the connection

Call mcp__hydrant__list_spaces to confirm the hosted MCP is reachable with the supplied token.

Two cases:

• Harness hot-reloaded the MCP config (some do, some don't): the call succeeds and returns the user's spaces. Confirm that the slug they gave in Phase 2 appears in the result. If it doesn't, surface "I configured the token but the slug <slug> isn't on the list — typo, or different workspace?"

• Harness needs a restart: mcp__hydrant__list_spaces is not available in the current session because the harness loads MCP config at startup. Tell the user:

  "Configuration written. Restart your harness, then run mcp__hydrant__list_spaces (or just invoke /setup verify) to confirm the connection."

  Do not pretend the connection is verified when it isn't.

If the call fails with a 401 or 403, the token is wrong. Tell the user, ask whether they want to retry Phase 2 with a fresh token, and if yes, loop back. Never leave a known-bad token in place.

If the call fails with any other error (5xx, network), surface the raw error and stop — don't guess.

Phase 6: Confirm

Print a short summary back to the user:

• Detected harness.

• Where the MCP config was written (path + scope).

• Whether AGENTS.md was created or appended; whether CLAUDE.md was mirrored.

• Verification result (success, deferred-pending-restart, or failure).

• Next-step pointer:

  "Run /align next so the lifecycle skills know your codebase's conventions (test command, branch naming, PR flow). Then /create-issue is the entry point for the lifecycle."

Edge cases

• User runs /setup with no internet — Phase 5 fails with a network error. The config is still written; tell the user verification will happen on next launch.
• User's harness doesn't support MCP at all — print the REST endpoint URL (https://hydrant.dev/mcp) and the bearer-token header format, and tell them they can drive Hydrant manually via the documented HTTP API. Skip Phases 3–5 for that harness.
• User has multiple harnesses installed simultaneously (rare but possible: .claude/ and .cursor/ both present) — ask which one they want to wire up; do not configure both silently.
• AGENTS.md is huge or owned by a different convention — only the fenced region belongs to /setup. If there's no fence, append; never insert mid-document.
• AGENTS.md is a symlink, read-only, or owned by another user — stop, tell the user, do not silently fail.
• Re-running /setup after a successful first run — Phase 1 detects the harness again, Phase 2 asks if the user wants to rotate the token (default: no), Phase 3 detects the existing entry and prompts before replacing, Phase 4 prompts before replacing the AGENTS.md fence, Phase 5 verifies. Idempotent end-to-end.
• npx skills update ran later and bumped this skill — the user's AGENTS.md lifecycle section is theirs and is never overwritten by an update. Only /setup itself touches it, only when the user runs /setup themselves.
• User pastes a token with leading/trailing whitespace — trim before validation. Do not store untrimmed tokens.
• Repo has no .git directory (raw working tree) — fine for AGENTS.md write, but warn the user that lifecycle skills like /yeet will misbehave without a git repo.

What this skill never does

• Write any file outside .mcp.json / .cursor/mcp.json / ~/.codex/config.toml / opencode.json / ~/.gemini/settings.json / ~/.claude.json (or what the active harness requires), AGENTS.md, and CLAUDE.md (Claude Code only).
• Modify content outside the <!-- BEGIN: hydrant lifecycle --> … <!-- END: hydrant lifecycle --> fences.
• Touch the <!-- BEGIN: hydrant alignment --> fence written by /align.
• Echo the user's PAT in plaintext after capture.
• Generate a PAT on the user's behalf — the user gets the token themselves from the Hydrant settings page.
• Rotate, revoke, or delete tokens — only writes new entries with prompted overwrites.
• Configure any non-Hydrant MCP server.

Why this matters

Without /setup, the user finishes npx skills add with a directory full of skill files that don't know how to reach Hydrant. The agent has the skill prompts but no mcp__hydrant__* tools wired up. Skills fail at the first MCP call and the user gets an unhelpful "tool not found" error — the worst possible first impression.

/setup makes the install end-to-end functional in one ritual, with one user-visible prompt for the token, on whichever harness the user happens to be running. The fenced AGENTS.md section makes the rest of the catalogue discoverable so the user knows what skills they just installed and when to reach for each.