feat: agent-first infra-setup skill (/infra-setup) - #13
Merged
Conversation
Repackage the agent-first bootstrap as a Claude Code skill so an agent can drive the whole setup and adopters only need to read the README and invoke it. - .claude/skills/infra-setup/SKILL.md: router — actor model (AGENT/HUMAN), handoff block, idempotent resume protocol, phase overview, done signal, porting table. - .claude/skills/infra-setup/references/: per-concern deep dives (hcp, cloudflare, github, gcp template, migration) + steps.yaml machine-readable manifest. Progressive disclosure: SKILL.md stays small and routes here on demand. - .claude/commands/infra-setup.md: thin /infra-setup entry point. - AGENTS.md: cross-harness pointer so opencode/Codex/etc. can follow the same skill. - README.md: "Setup — let an agent do it" section + updated file tree. The skill orchestrates the existing docs (setup.md, import.md, secrets.md, state.md, ci.md) rather than duplicating them; those stay canonical for humans. Concrete for perishdev/perish.dev with a documented swap list for other orgs.
- H1 (discoverability): the skill was only linked from the root README. Add it to docs/README.md (Setup & onboarding, as the recommended path) and CONTRIBUTING.md (the bootstrap step), the repo's two designed first-contact entry points. - M1 (name collision): the /infra-setup command and the skill both surfaced as "infra-setup". Reword the command as an explicit shortcut for the skill so both listings converge on the same SKILL.md — no divergent behaviour. - M2 (drift): AGENTS.md restated conventions already in CLAUDE.md; now it defers to CLAUDE.md as the single source of truth. - M3 (drift): mark references/hcp.md as the source of truth for the workspace-create payload; the manifest summary is explicitly just a reminder. - L nits: drop stale "setup wizard" vocabulary; fix stale link text in gcp.md; note the manifest preflight enforces Terraform >= 1.9 (SKILL.md snippet is illustrative); label the GCP WIF block as illustrative-not-runnable; trim WebFetch from the command's allowed-tools; document that manifest `docs:` paths are repo-root-relative.
Deep-pass review found the oauth-token guard in references/hcp.md used a top-level `return 1`. Run as a script (how the agent runs it), `return` outside a function errors AND falls through — so with an empty OAUTH_TOKEN_ID it printed the warning and then still called create_ws, creating a broken (non-VCS) workspace. Replace with an if/else that gates correctly in script, sourced, and interactive contexts. Verified: empty token -> create_ws not called; present token -> both created; the extracted block passes `bash -n`.
1. create_ws is now genuinely idempotent: capture the HTTP status via curl -w and report 201 as "created", a name-taken 422 as "already exists", and any other status as a real error — instead of curl -sf silently swallowing the 422 and crashing jq on empty input. (var named 'code', not 'status', which zsh reserves.) 2. vcs-connect check asserts a GitHub-family service-provider specifically, so a pre-existing GitLab/Bitbucket VCS connection can't false-green the step. 3. migrate-import writes the plan to a private mktemp file (0600, trap-removed) instead of a fixed world-readable /tmp path. Verified: idempotency table (201/422-taken/422-other/401) behaves correctly; vcs check greens on github and reds on gitlab; both blocks pass `bash -n`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Repackages the agent-first bootstrap (previously the doc-based wizard in #12) as a Claude Code skill so an agent drives the whole setup and adopters only read the README and invoke it. Supersedes #12.
Inspired by
cofin/flow's structure: a small SKILL.md router +references/deep-dives, with progressive disclosure.Structure
Design decisions (from the discussion)
/infra-setupis an explicit doorbell..claude/skills/(project-local), not plugin packaging. This repo is forked as groundwork, notplugin installed — the files travel with the fork.AGENTS.mdgives non-Claude harnesses the same entry point.docs/setup.md,import.md,secrets.md,state.md,ci.mdstay canonical (human-first, incident-readable); the skill links into them. Same boundaryflowkeeps betweendocs/andskills/references/.Reuse across orgs
Concrete for
perishdev/perish.dev, with a Porting table in SKILL.md listing every literal to swap (org, domain, CF account/zone IDs, managed repos). Therepo-id-…HCP check ID is explicitly "don't invent — HCP emits it."Validation
references/steps.yamlparses (12 steps; the ephemeral discovery-token step is real YAML null).create_wsoauth guard).Docs/skill only — no Terraform changes, so no HCP plan expected.