gh-weld-setup

name	gh-weld-setup
description	Set up a new or existing project end-to-end — scaffold README.md and CLAUDE.md via a guided abstract (tech-agnostic) interview, wire in gh-weld conventions, ensure .gitignore entries, and optionally create a GitHub repo (delegates to gh-weld-repo). Idempotent: re-run to accept, refresh, or refine existing files. Replaces the separate gh-weld-install and gh-weld-init skills. Use when: starting a new repo, onboarding an existing project to gh-weld, scaffolding README/CLAUDE.md, or wiring conventions. Triggers: 'set up this project', 'init this repo', 'scaffold', 'new project setup', 'install gh-weld', 'wire up weld', 'initialize', 'create README', 'new repository'.
compatibility	Requires git and gh CLI. Claude Code with WebFetch.

gh-weld-setup

End-to-end project setup: scaffold files, wire conventions, create GitHub repo.

NEVER

• NEVER ask about technology, language, stack, or frameworks Instead: Ask only abstract questions — goals, audience, tone, scope, seriousness. Why: Tech details produce CLAUDE.md boilerplate the user must clean up; abstract framing produces durable conventions that outlast stack changes.

• NEVER write files before the user accepts the final recap Instead: Complete the full interview and get (a)ccept at the Phase 3 gate first. Why: Writing early locks in unreviewed answers and may overwrite existing files without consent.

• NEVER use the Write tool on an existing .gitignore without reading it first Instead: Read it, check for each entry, then append only missing lines. Why: Write overwrites the entire file, silently destroying existing ignore rules.

• NEVER wire conventions.md before both README.md and CLAUDE.md are written Instead: Write both files first, then fetch and wire conventions.md. Why: conventions.md prepends to CLAUDE.md — running it before generation corrupts the result.

• NEVER append to .gitignore or CLAUDE.md without checking for the exact line first Instead: Search for .weld/tmp/ and @.weld/conventions.md before appending; skip if already present. Why: Duplicate entries signal the skill isn't idempotent and create noisy diffs.

• NEVER overwrite .weld/conventions.md without showing what changed Instead: Compare fetched content to local; if different, note line-count delta before writing. Why: The user may have local edits; silent overwrite destroys them.

• NEVER generate generic boilerplate sections Instead: Write only sections directly implied by the interview recap. Why: A README with five generic headings and placeholder text is worse than a short honest one.

• NEVER chain Bash calls with && or ; Instead: One command per Bash tool call. Why: Claude Code's safety check fires on multi-command calls and interrupts mid-flow.

• NEVER use | (pipe) in Bash tool calls Instead: Redirect output to .weld/tmp/<file> with > and read back with the Read tool. Why: Claude Code stops execution on pipe — no error, no warning. Note: | in markdown table syntax is unaffected.

• NEVER use $() command substitution Instead: Write content to a fixed path under .weld/tmp/ with the Write tool. Why: Claude Code's permission system prompts on $() during execution.

• NEVER use bash heredoc (cat > file << 'EOF') for content with #-prefixed lines Instead: Use the Write tool for all file content. Why: #-prefixed lines (headings) trigger Claude Code's security check on every execution.

• NEVER use echo > or cat to write file content Instead: Use the Write tool. Why: echo-redirect and cat approaches fail silently on #-prefixed content due to Claude Code's security checks.

• NEVER use find, grep, or cat as Bash commands Instead: Use Glob to find files, Grep to search content, and Read to read files. Why: Built-in tools have tighter permissions and avoid Claude Code safety prompts that raw shell commands trigger. Note: this restriction applies only to Bash tool calls — using these words in prose, code examples, or explanations is unaffected.

• NEVER pass multiline content containing #-prefixed lines as an inline gh argument Instead: Write to .weld/tmp/<name>.md with the Write tool and pass via --body-file. Why: Headers in inline gh strings trigger an un-suppressible Claude Code permission prompt on every execution.

• NEVER use the -i flag in git commands Instead: Use non-interactive equivalents (e.g. git rebase --onto instead of git rebase -i). Why: Claude Code runs in a non-interactive shell — -i hangs waiting for input that never comes.

• NEVER skip git hooks with --no-verify unless the user explicitly requests it. Instead: Investigate and fix the hook failure before committing. Why: Hooks exist to catch real problems; bypassing them silently hides errors that break CI or deployments.

---

Phase 1 — Idempotency Check

Verify the current directory is a git repo:

git rev-parse --is-inside-work-tree

If it fails or returns anything other than true: run git init as a separate Bash call, then continue.

If the repo check passed (not freshly initialised): run git rev-parse --show-toplevel as a separate Bash call and write the result to .weld/tmp/toplevel.txt. Read it back. If the path does not match the current working directory, ask (single keypress):

You're inside a git repo subdirectory, not the root.
Running setup here will scaffold files in this subdirectory.
(c)ontinue here / (Q)uit

If (Q): stop. If (c): proceed. Then run rm .weld/tmp/toplevel.txt.

Use Glob to check for existing files:

• Glob README.md in the current directory
• Glob CLAUDE.md in the current directory

If both exist: Read both files. Show a recap of what they currently say — purpose, audience, tone, scope. Then ask (single keypress):

README.md and CLAUDE.md already exist.
(a)ccept current state / (u)pdate with fresh interview / (r)efine existing content

• (a): Skip Phases 2–4 (interview, recap gate, and file generation) and jump directly to Phase 5 (wire conventions), then continue to Phase 6 (offer GitHub repo creation).
• (u): Proceed to Phase 2 (full interview from scratch; both files will be overwritten on accept).
• (r): Proceed to Phase 2 pre-filled from existing content; user amends rather than restarts.

If one file exists: Warn which file exists. Ask <filename> already exists — overwrite it? (y/n). If no: skip generating that file only; continue with the other.

If neither exists: Proceed directly to Phase 2.

---

Phase 2 — Interview

If entering from Phase 1 (r)efine: Open by showing the user what is already known from the existing files before asking any questions:

Based on your existing README.md and CLAUDE.md, here's what I have:

  Purpose:  [extracted value or "unclear"]
  Audience: [extracted value or "unclear"]
  Scope:    [extracted value or "unclear"]
  Tone:     [extracted value or "unclear"]
  Type:     [extracted value or "unclear"]

What would you like to change or add?

Ask only about gaps or changes the user raises — do not re-ask for values already present.

Generate abstract questions one at a time. Let the project context (directory name, any existing files, prior answers) inform which questions to ask — do not follow a fixed list. Good question domains: project purpose and goals, intended audience, scope and explicit out-of-scope boundaries, tone (serious vs. playful, strict vs. forgiving), whether this is a hobby or professional project.

All answers are long-form free text. Do not offer multiple-choice options during the interview.

After each answer, display an updated recap:

## Project Recap

**Purpose:** [what you've learned, or "unknown"]
**Audience:** [what you've learned, or "unknown"]
**Scope:**    [what you've learned, or "unknown"]
**Tone:**     [what you've learned, or "unknown"]
**Type:**     [hobby / professional / unknown]

Continue until Purpose, Audience, and Tone have no "unknown" — those three are required before moving to Phase 3. Scope and Type may be inferred if the user hasn't addressed them. Typically 4–6 questions suffice; stop when you can write the first sentence of the README without a placeholder.

When evaluating whether an answer is strong enough to accept, load references/interview-guide.md.

---

Phase 3 — Recap Gate

Show the complete final recap. Ask (single keypress):

(a)ccept and generate files / (r)evise

• (a): Proceed to Phase 4.
• (r): Ask "What would you like to change?" Collect the answer, update the recap, and loop back to this gate.

Do not proceed to Phase 4 until the user explicitly accepts.

---

Phase 4 — Generate Files

README.md — write via Write tool.

Before writing, verify the recap gives a specific enough scope that a stranger can understand what this project does and doesn't do in one sentence. If not, prompt for one clarifying answer before generating.

Shape every decision from the recap: framing, tone, what's included and omitted. Consider these sections (not all required — include only what the recap warrants): project name and one-line purpose, who it's for, what it does and doesn't do, a tone-appropriate closing. A three-section README that matches the project's character is better than eight generic sections.

CLAUDE.md — write via Write tool.

Derive all conventions from the recap. Load references/interview-guide.md for the tone-to-voice translation table.

Include: 1–2 sentences of project purpose, coding philosophy derived from tone and seriousness, and any scope boundaries the agent should respect. Do not include technology-specific guidance.

.gitignore — ensure two entries are present: settings.local.json and .weld/tmp/.

Use Glob to check if .gitignore exists. If missing: create via Write tool with both entries on separate lines. If exists: read it, then append any missing entries on separate lines.

---

Phase 5 — Wire gh-weld

Fetch conventions.md from upstream:

WebFetch: https://raw.githubusercontent.com/WrathZA/github-weld/main/.weld/conventions.md

Prompt: "Return the full raw file content verbatim, no summarization."

If fetch fails: output "Could not reach github-weld repo — check your connection. Run /gh-weld-setup again or wire manually." and skip to Phase 6.

Evaluate each target. Record a status: add, update, skip.

.weld/conventions.md:

• If file is missing → status: add (create from upstream)
• If file exists and content matches fetched content exactly → status: skip
• If file exists and content differs → status: update (note line counts: upstream N lines vs local M lines)

CLAUDE.md (@.weld/conventions.md line):

• Read the freshly-written CLAUDE.md
• If @.weld/conventions.md appears on any line → status: skip
• Otherwise → status: add (prepend as first line)

Display:

gh-weld wiring — planned changes:

  .weld/conventions.md  <status>
  CLAUDE.md             <status>

Proceed? (y/n)

If both are skip: output "gh-weld already wired." and skip to Phase 6.

If user answers n: skip to Phase 6.

Apply only add and update targets:

• .weld/conventions.md (add or update): if update, note "Updating conventions.md — upstream has N lines, local had M lines." Write fetched content via Write tool.
• CLAUDE.md (add): read current content, prepend @.weld/conventions.md followed by a blank line, write back via Write tool.

---

Phase 6 — GitHub Repo (optional)

Check for an existing remote:

git remote -v > .weld/tmp/remotes.txt

Read .weld/tmp/remotes.txt with the Read tool. If the content contains origin, a remote already exists — run rm .weld/tmp/remotes.txt and skip silently.

If no origin remote exists, ask (single keypress):

No GitHub remote found — create one now? (y/n)

If yes: invoke /gh-weld-repo to create and push the repo. If /gh-weld-repo is not installed or fails, tell the user: "Install gh-weld and run /gh-weld-repo manually to create the GitHub repo." If no: skip.

---

Phase 7 — Done

Output a summary reflecting what was actually done in this run. Use the following labels:

• written — file was generated by Phase 4
• (existing) — file already existed; Phase 4 was skipped (Phase 1a path)
• (skipped) — file was skipped by user choice (one-file case)
• wired — conventions applied by Phase 5
• (already wired) — Phase 5 found both targets already up to date

Setup complete.

  README.md            <label>
  CLAUDE.md            <label>
  .weld/conventions.md <label>

If /gh-weld-repo was run, include the repo URL in the output.

Then ask (single keypress):

Close the loop? (y) run /gh-weld-adopt → /gh-weld-ship → /gh-weld-export  (n) skip

• (y): invoke /gh-weld-adopt. When it completes, invoke /gh-weld-ship. When it completes, invoke /gh-weld-export. If any skill invocation fails or is not installed, output which step failed and stop — do not attempt subsequent steps.
• (n): exit cleanly — no further output, no partial state.