docs: add agent-first setup wizard with human-in-the-loop handoffs - #12
Closed
hasansezertasan wants to merge 3 commits into
Closed
docs: add agent-first setup wizard with human-in-the-loop handoffs#12hasansezertasan wants to merge 3 commits into
hasansezertasan wants to merge 3 commits into
Conversation
Add an agent-runnable bootstrap that an AI agent (Claude Code, opencode,
codex, …) executes end-to-end, pausing only for the irreducibly-human
steps: signups, minting credentials, and pasting secrets into HCP.
- docs/wizard.md: narrative entry point — actor model (AGENT/HUMAN),
handoff-block protocol, idempotent resume protocol, 7 phases, and a
"porting to another org" table. Includes a ready-to-run `jq`+`curl`
helper for creating the HCP workspaces.
- docs/setup.steps.yaml: machine-readable manifest the wizard walks;
each step tagged AGENT/HUMAN with a `check` command for resume.
- docs/providers/{cloudflare,github,gcp,migration}.md: per-provider
deep dives. GCP is a marked template (not an active provider —
adopting it is a locked-decision change). migration generalizes the
cf-terraforming runbook across providers.
- Wire the wizard into README.md and docs/README.md.
Orchestrates the existing setup.md / import.md rather than duplicating
them; concrete for perishdev/perish.dev with a documented swap list.
There was a problem hiding this comment.
Pull request overview
Adds an agent-first, human-in-the-loop onboarding “wizard” to make bootstrapping this Terraform infra repo (and forks) more automatable and resumable, while preserving the repo’s security model (humans remain the keyholders; agents don’t see plaintext secrets).
Changes:
- Introduces
docs/wizard.md(narrative) +docs/setup.steps.yaml(machine-readable manifest) with an actor split (AGENT/HUMAN) and resume checks. - Adds provider deep-dives under
docs/providers/(Cloudflare, GitHub, migration pattern, and a clearly marked GCP template). - Wires the new wizard into
README.mdanddocs/README.mdindices.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Links the repo’s primary entry point to the new agent-first onboarding wizard. |
| docs/wizard.md | Adds the narrative wizard with phases, handoff protocol, and resume protocol. |
| docs/setup.steps.yaml | Adds a structured step manifest for agents to execute/resume onboarding. |
| docs/README.md | Updates docs index to include wizard + manifest + provider deep-dives. |
| docs/providers/migration.md | Generalizes the “import, don’t recreate” migration pattern across providers. |
| docs/providers/github.md | Adds an agent-first GitHub App setup deep-dive consistent with existing auth decisions. |
| docs/providers/gcp.md | Adds a template-only GCP provider guide with explicit “not active” constraints. |
| docs/providers/cloudflare.md | Adds an agent-first Cloudflare token + verification deep-dive aligned with secret handling. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Self-review of the setup wizard surfaced correctness and consistency issues, all fixed here: - setup.steps.yaml: checks interpolated $hcp_api as if it were a shell var, but it was only a YAML field — the header now tells the runner to export hcp_api + HCP_TOKEN, and clarifies the org slug is inlined literally. (F1) - providers/cloudflare.md: porting no longer reuses the HCP Edit token to read account/zone IDs; use the throwaway read-only discovery token or the dashboard, keeping the never-see-plaintext rule. (F2) - providers/github.md: describe the App manifest flow accurately (HTML-form POST + 1-hour code exchange that exposes the PEM), and keep that exchange human-run. (F3) - setup.steps.yaml: migrate-import now runs one captured plan instead of two, and documents the mixed import+create caveat. (F4) - setup.steps.yaml: note that hcp-signup's check depends on the token minted by the next step (intentional, not a broken resume order). (F5) - setup.steps.yaml: preflight now actually enforces terraform >= 1.9. (F6) - wizard.md: create_ws guards against an empty oauth-token-id (VCS not connected). (F7)
- setup.steps.yaml: migrate-discovery-token uses real YAML null (~) instead of the literal string "null", matching the header's check-field contract so a consumer won't try to execute "null" as a command. - wizard.md: the cf-verify snippet now uses the full HCP workspace endpoint and derives HCP_TOKEN, so it is copy/paste runnable like the other examples. The other two review comments (double `terraform plan`, and the $hcp_api header contract) were already fixed in 7b48f2e.
Member
Author
|
Superseded by #13, which repackages this agent-first bootstrap as a Claude Code skill ( |
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
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
An agent-first, human-in-the-loop setup wizard for bootstrapping this repo (and forks of it for other orgs). An AI agent runs the whole setup end-to-end and pauses only for the steps a human irreducibly must do — signups, minting credentials, and pasting secrets into HCP.
Inspired by the "let an LLM do it" installation path in
opencode-antigravity-auth, inverted: here the agent drives and hands specific actions to the human.Files
docs/wizard.mdAGENT/HUMANactor model, the handoff-block protocol, an idempotent resume protocol, 7 phases, and a porting-to-another-org table. Includes a ready-to-runjq+curlhelper for HCP workspace creation.docs/setup.steps.yamlAGENT/HUMANwith acheckcommand so an agent can detect state and resume.docs/providers/cloudflare.md,github.md,gcp.md,migration.mdmigration.mdgeneralizes thecf-terraformingrunbook across providers.README.md,docs/README.mdDesign notes
terraform login), then the agent drives HCP over its API.setup.md/import.mdrather than copying them.CLAUDE.md; adopting it is called out as a locked-decision change, and its manifest step stays red until intentionally adopted.perishdev/perish.dev, with a documented swap list for reuse.Validation
setup.steps.yamlparses (12 steps, 4 preflight tools).jq -nworkspace-create payload produces valid JSON:API.Docs-only — no Terraform changes, so no HCP plan expected.