Hydrant setup

The pack's lifecycle skills (capture, refine and the rest) contain no facts about any repository. This skill gathers those facts once, writes them to a profile the user owns, and installs the pack's skills without touching skills the user already has.

Three layers, three owners:

Setup writes only the profile, the skills the user approved and backups of anything the user agreed to replace. It never edits AGENTS.md, CLAUDE.md or any other file, never creates keys or connects clients, and never calls a Hydrant write tool.

Phase 1: Scan

Everything in this phase is read-only. Work from the repository root.

The scan reads files and runs only inspection commands: read-only git (rev-parse, status, symbolic-ref, log, ls-tree, show, remote, branch), read-only gh (api GET calls and repo view), ls, cat, readlink, test -f/-d, text filters such as grep, head and tail on what those print, and npx skills add <source> --list (or its isolated form, below, which only creates an empty temporary folder outside the repository for npx to put the skills CLI in). It never runs package scripts, tests, builds, installs, make/just/task targets or anything else the repository defines: in a repository someone has just cloned, that runs its code before they have approved anything.

git rev-parse --show-toplevel
git status --short

If this is not a Git repository, say so and stop. If the profile .agents/hydrant-workflow.md already exists, this is a rerun: follow the rerun rules in Phase 3.

Skills already here

ls -la .agents/skills .claude/skills 2>/dev/null
cat skills-lock.json 2>/dev/null

For every entry record its name, path and kind: a directory, or a symlink with its target (readlink). A .claude/skills/<name> symlink into .agents/skills/<name> is one skill in two places, not two skills. So is every skill when .claude or .claude/skills is itself a symlink into .agents (check with readlink .claude .claude/skills). From skills-lock.json, note each skill's source and sourceType. A skill whose lockfile source is Background-Craft/hydrant-skills but whose name the pack's list (below) no longer shows is a stale earlier install, such as the April 2026 align, nail or yeet; report it as such. A same-named skill the pack does list (for example an April 2026 refine) is reported as a clash in Phase 2 like any other.

Older Hydrant guidance

Instructions or skills written for an earlier Hydrant give agents conflicting directions once the pack is installed. Read the text files (such as Markdown, YAML, JSON, shell or Python scripts and plain text) of:

• AGENTS.md and CLAUDE.md
• each skill folder found above, except skills whose skills-lock.json source is Background-Craft/hydrant-skills (any case, with or without https://github.com/) or, after resolving a relative path, the pack source found below

Look for these signals:

A file with no signal is not reported, even when it mentions Hydrant. Record each hit's path, the signals and, for AGENTS.md and CLAUDE.md, their line numbers. Name the signal, never quote a token. Treat a skill's .agents/skills folder and its .claude/skills copy as one entry with both paths, as for clashes. This is read-only: never edit, move or back up a flagged file.

Agents to install for

Without -a, the skills CLI links a skill into every agent folder it can find (.windsurf/skills, .kiro/skills, a top-level skills/ and more) and deletes any same-named folder there first. So every install in this skill names its agents, and the scan covers exactly their folders:

.agents/skills is also the CLI's shared copy: an install for more than one agent writes .agents/skills/<name> and links the other folders to it. So check .agents/skills for clashes, and back it up on replace, even when codex is not chosen.

Another agent is added only when the user asks, and only after listing its project skills folder for clashes the same way.

The pack's skills

Find the source this skill was installed from, so a trial from a local clone lists the same clone:

• The hydrant-setup entry in skills-lock.json. A local source is a path relative to the repository root; resolve it and check that it exists.
• Otherwise Background-Craft/hydrant-skills.

npx skills add <source> --list

The installable set is every listed skill except hydrant-setup. Do not use a list from memory; the pack grows.

--list needs the network for a GitHub source, and some clients run commands without it (Codex does by default, in read-only and workspace-write). If --list fails, use the shipped pack list below instead and keep going: clash and stale-install checks use whichever list you used. The plan then says, in one line, where the list came from and why, quoting the error. Name the network as the reason only when the error is a DNS or connection failure (ENOTFOUND, EAI_AGAIN, ECONNREFUSED, ECONNRESET, ETIMEDOUT and similar); for any other error, quote it without blaming the network. For example:

Pack list  shipped with hydrant-setup (lockfile hash f32100d3); may be older than the latest pack (--list failed: getaddrinfo ENOTFOUND registry.npmjs.org, no network)

Before falling back for an npm config error, try the isolated form once per command (next section).

The lockfile hash is the first 8 characters of the hydrant-setup entry's computedHash in skills-lock.json (unknown when there is none). A plan built from the shipped list is complete: present it for approval as usual, never as unverified or pending. Installs without the network fail too; Phase 3's on-disk check already marks them failed and prints the commands for the user's own terminal.

When npx trips over package.json

npx reads the repository root's package.json before the skills CLI starts. An overrides entry that conflicts with a direct dependency makes every npx skills command fail with npm error code EOVERRIDE, and other npm config errors such as ERESOLVE do the same. When an npx skills command fails with EOVERRIDE, ERESOLVE or a similar npm config error about the project's dependencies, rerun it once from an empty prefix. Not for a DNS or connection failure, not for EACCES, EPERM or a registry auth error (401 or 403), and not when your client denied the command:

npx --yes --prefix "$(mktemp -d)" skills add <source> --list

The prefix only changes where npx puts the skills CLI. The command still runs from the repository root and installs there. Once the plain form has failed with an npm config error, the isolated form is the installer for the rest of this run, even when its rerun fails for another reason (no network, for example): use it for every later npx skills command, including installs and every command you print for the user. When the rerun fails, go on with its error as if the plain command had failed (for --list, the shipped list below). Rerun once per command, and never switch package managers on your own.

The plan's Installer line names the form in use. For the isolated one it gives the plain form's error, and the rerun's error too when that failed:

Installer  npx --yes --prefix "$(mktemp -d)" skills (plain npx failed: npm error code EOVERRIDE)
Installer  npx --yes --prefix "$(mktemp -d)" skills (plain npx failed: npm error code EOVERRIDE; isolated rerun failed: getaddrinfo ENOTFOUND registry.npmjs.org)

Shipped pack list

Every skill in the pack except hydrant-setup, as of this copy. The pack's CI fails when this list and the pack's skills/ folders disagree.

• capture
• go
• hydrant
• prep
• refine
• review-triage
• ship

Repository facts

gh api "repos/{owner}/{repo}/pulls/comments?per_page=100" \
  --jq '[.[].user | select(.type=="Bot") | .login] | unique'

Record where each fact came from. A command that is not in a file is not detected: never invent npm test because the repository uses Node. A command found in a file is recorded with its source, never run: setup does not prove a command works by running it.

Phase 2: Plan and confirm

Classify each installable skill:

Show one plan before writing anything:

Agents     claude-code, codex
Installer  npx skills
Skill      Status   Existing                                    Action
hydrant    new      -                                           install
refine     clash    .agents/skills/refine (dir, not from pack)  keep yours (default) / replace with backup
           clash    .claude/skills/refine (dir, separate copy)
Profile    .agents/hydrant-workflow.md                          create

May conflict: older Hydrant guidance, left as is, your call
CLAUDE.md      lines 12, 15: tools this Hydrant server does not list (set_dependencies, replace_issue_description)
sauce-hydrant  .agents/skills/sauce-hydrant (dir), .claude/skills/sauce-hydrant (separate copy): hyd-NNN IDs, "work item"

When the tool signal was skipped and a scanned file names a Hydrant tool, the block gets one line: Tool names not checked: no Hydrant tools in this session, followed by the files and lines that name them. Show the "May conflict" block when Phase 1 flagged something or that line applies, and not otherwise. The user decides what to do with flagged files; setup asks nothing about them.

Then ask, in one message, for: approval of the plan, a keep-or-replace answer for each clash (keep is the default), the facts Phase 1 could not detect (see the profile's "When unknown" column), and Install whenever lockfiles from more than one manager exist. Wait for the answer. Replace only a skill the user named for replacement. If the user cannot answer a fact now, record unknown.

Phase 3: Apply

Install new skills

One skill per command, never the whole source:

npx skills add <source> -s <name> -a claude-code -a codex -y

With the isolated installer in the plan, run npx --yes --prefix "$(mktemp -d)" skills add <source> -s <name> -a claude-code -a codex -y instead. If a plain install fails with EOVERRIDE, ERESOLVE or a similar npm config error, rerun that command once in the isolated form (once per command, as above) and keep that form for the rest of the run. Use the -a values from the plan. Never drop -s (the CLI would overwrite every same-named skill) or -a (it would reach agent folders the scan never looked at).

Check each install on disk

The CLI can exit 0 when it wrote nothing: a sandboxed run prints Failed to install … and then Done!. Don't trust the exit code or the last line. After each install, check the files:

test -f .agents/skills/<name>/SKILL.md && echo ok || echo missing   # when codex or more than one agent is chosen
test -f .claude/skills/<name>/SKILL.md && echo ok || echo missing   # when claude-code is chosen

A single-agent install copies the skill straight into that agent's folder, so a Claude Code-only install has no .agents/skills/<name>. Check each other agent the user added in its own skills folder the same way.

A skill is installed only when every check prints ok. If your client denied the command, the output shows EPERM, Operation not permitted or Failed to install, or any check prints missing:

• Mark that skill failed, with the reason (the denial, the error line, or "exit 0 but no files").
• Stop. Don't run the remaining installs, replaces or backups.
• Print what is left for the user to run from their own terminal, with <source> resolved:
  • For each new skill that isn't installed yet, the same npx skills add <source> -s <name> -a … -y line, in the plan's installer form. When the failure was EOVERRIDE, ERESOLVE or a similar npm config error, print the isolated form, npx --yes --prefix "$(mktemp -d)" skills add <source> -s <name> -a … -y, even if its rerun failed here.
  • For each replace not done yet, the backup and diff block below, then the rm -rf and that install line.
  • Nothing for a kept clash. An install there would overwrite the user's skill.
• Go on to write the profile, then report.

A sandboxed client usually fails this way. Codex's workspace-write sandbox protects .agents/. Ask for the escalation your client offers before you give up, and report a refused escalation as a denial.

Clashes the user kept

Leave both locations untouched. Print this section for the user to paste into their own skill if they want it to work with Hydrant:

## Hydrant

When the work is tracked in Hydrant, read the issue, all of its activity and its relationships over the Hydrant MCP server before acting. Use the server's own status keys, IDs and revisions; send one request UUID per write and the same one on an uncertain retry; read back after every write; record evidence on the issue. Repository facts (commands, CI gate, review bots, release steps) are in `.agents/hydrant-workflow.md`.

Skip the paste-in for a kept earlier install from this pack; npx skills update -p <name> (project only) or a replace brings it current.

Clashes the user chose to replace

Back up every real directory first, into a folder no agent scans for skills:

b=.agents/hydrant-setup-backup/<name>
test -e "$b" && echo "backup exists: stop and ask"   # stop here if it prints
mkdir -p "$b"
cp -Rp .agents/skills/<name> "$b/agents"      # if it is a directory
cp -Rp .claude/skills/<name> "$b/claude"      # if it is a directory, not a symlink into .agents
diff -r .agents/skills/<name> "$b/agents"     # must print nothing
diff -r .claude/skills/<name> "$b/claude"

Only after every diff is clean, remove the originals (rm -rf on exactly those paths) and install ours with the same -s <name> -a … -y command as above. A symlink needs no backup; note its old target. If a backup already exists, stop and ask rather than overwrite it.

If a removal fails or your client denies it, stop for that skill: put back anything already removed (the numbered restore steps below), keep the backup, do not install over the original (the CLI would overwrite it), and report the path with the commands that finish the replace once the user has removed it (rm -rf <path>, then the same npx skills add <source> -s <name> -a … -y, in the plan's installer form). A rerun does not replace skills, so do not tell the user to rerun setup for this.

If the install after the removal fails the on-disk check above, restore before you stop, so the user's skill is never left missing:

1. Remove whatever the failed install left at those paths (rm -rf).
2. cp -Rp each backup back.
3. Recreate a symlink from its noted target (ln -s).
4. Run diff -r again.

If the restore is denied too, keep the backup and print these restore commands for the user.

Write the profile

.agents/hydrant-workflow.md, exactly these H2 sections in this order, so lifecycle skills can find each fact:

Template:

# Hydrant workflow profile

Repository facts for the Hydrant workflow skills. Written by `hydrant-setup`; edit freely. Rerunning `hydrant-setup` proposes additions and never rewrites your lines. Workspace policy (statuses, acceptance, ship grants) lives in Hydrant, not here.

## Repository

- Base branch: `main` (origin/HEAD)
- Branch protection: none (protection 404 "Branch not protected", no rules)

## Commands

- Install: `pnpm install` (pnpm-lock.yaml; package-lock.json also present)
- Lint: `pnpm lint` (package.json)
- Typecheck: unknown
- Test: `pnpm test` (package.json)
- Browser/e2e: none
- Other: `build`, `dev` (package.json)

## CI gate

- `CI / test` on pull_request (.github/workflows/ci.yml)

## Pull requests

- Branches: no convention
- Merge method: squash

## Review bots

- None detected (optional)

## Release and deploy

- None detected (optional)

## Done

- Merged to `main` and accepted in Hydrant.

## Installed skills

- `hydrant`: installed
- `refine`: kept yours (.agents/skills/refine)

Record a failed skill as failed (<reason>) in "Installed skills", never as installed.

If the write is denied or the file isn't there afterwards (test -f .agents/hydrant-workflow.md), print the complete profile text in one fenced block. Ask the user to save it as .agents/hydrant-workflow.md themselves, and report the profile as not written.

Rules:

• Only the "Ask" rows become questions. CI gate, review bots and release are detected or "None detected", never unknown.
• Repository facts only. No workspace IDs, statuses, people's authority, keys, tokens or secrets.
• No timestamps, run counters or anything else that changes on every run.
• Keep each line short and give its source in parentheses when it was detected.

Rerun

When the profile exists:

• Rescan (Phase 1) and compare each detected item (every script or target, workflow job, bot, deploy file) with the profile. An item the profile does not mention anywhere is new.
• Never change or remove an existing line. Treat every line as the user's. Two exceptions: new names may be appended to the Other commands line, and an "Installed skills" line that says failed or not attempted becomes installed once that skill passes the on-disk check and its skills-lock.json entry names the pack's source. A restored skill of the user's keeps its failed line.
• Propose, as a diff, only additions for newly detected facts, and questions for lines whose detected source has gone (for example a script that is no longer in package.json).
• Do not reinstall, update or replace installed skills. That is npx skills update -p, which overwrites local edits. A pack skill that is not here at all is new and may be offered through Phase 2.
• Show the "May conflict" block as in Phase 2 on every rerun. It is never a profile change: do not write it into the profile.
• If nothing changed, say so and write nothing.
• Write only after the user confirms the diff.

Phase 4: Report

End with:

Offer this line for the user to add to AGENTS.md or CLAUDE.md themselves:

Hydrant workflow facts for this repository are in `.agents/hydrant-workflow.md`.

Checklist

• Scanned skills, lockfile, instructions, commands, CI, deploy, PR conventions and review bots before writing.
• The scan ran only inspection commands (read-only git and gh, ls, cat, readlink, test -f, text filters, skills add --list); no package script, test, build, install or repository task.
• Pack skills listed from the source with --list, or, when that failed, from the shipped pack list with the plan saying so and why; never from memory.
• One plan shown and confirmed before any write, with its Installer line.
• An npx skills command that failed with EOVERRIDE, ERESOLVE or a similar npm config error was rerun once per command from an isolated prefix, and the isolated form was the installer for every later and every printed command.
• Every install used -s <name> and the plan's -a agents.
• Every "installed" skill was checked on disk; the first failure stopped the installs and printed the user's commands.
• No existing skill overwritten without a named yes and a verified backup.
• Profile has every section; nothing invented; no secrets or timestamps.
• Rerun changed no existing line beyond its two exceptions, and wrote nothing when nothing moved.
• AGENTS.md, CLAUDE.md and non-pack skills checked for older Hydrant guidance; hits listed as may conflict, none edited.
• No AGENTS.md/CLAUDE.md edit, no key, no Hydrant write.