Repo Setup

Bring a GitHub repository to the baseline every project starts from, or audit one against it. The script decides every item; the session reads the report, does the one thing the API cannot (installing the Greptile app), and commits the files.

Announce at start: "I'm using the repo-setup skill to bring <owner/repo> to the hygiene baseline."

The baseline

| stack-doc | docs/stack.md, written from ~/.claude/prompts/stack-template.md when absent, never overwritten | R-608: every application repository lists its stack by layer from its first commit, each entry with version, a plain explanation, the official docs link, its role, why it was chosen, and where it is configured, so each task that changes a dependency has an entry to update. SKIPPED when .enforce.json sets stackDoc to false |
| observability-doc | docs/observability.md, written from ~/.claude/prompts/observability-template.md when absent, never overwritten | R-608: the catalog of every analytics event, log event, error code, tracker rule, request-ID hop, health endpoint, and metric exists from the first commit. SKIPPED when .enforce.json sets observabilityDoc to false |

--no-product-docs opts a library or tooling repository out of product-docs by recording "productDocs": false in .enforce.json, which the harness push gate also reads; ask the user before passing it, since an application repository that opts out loses R-607's check entirely. --no-stack-doc and --no-observability-doc do the same for the two R-608 documents, each recording its own key (stackDoc, observabilityDoc); the three flags are independent, so a library that passes only --no-product-docs still gets both R-608 documents. Ask before passing any of them.

--required-reviews N adds N required approvals to protect-merge; the default is 0 because a solo maintainer cannot approve their own PR and would be locked out. Pass 1 or more for a team. A repository that already runs CI under another workflow file satisfies the ci item as it is; pass --ci-context <job name> so protect-merge requires the check that workflow actually reports (this repository's enforce.yml reports fixtures).

Procedure

1. From the repository's checkout, run the audit first so the user sees what will change:

   bash ~/.claude/skills/repo-setup/scripts/setup.sh <owner/repo> --check

   Every item prints OK or MISSING with the reason. Exit 1 means at least one item is missing.

2. Apply, which is idempotent (each item is checked before it is written, and an existing file is never overwritten):

   bash ~/.claude/skills/repo-setup/scripts/setup.sh <owner/repo> [--stack node|python|go|ruby] [--required-reviews N]

   The stack is detected from package.json, pyproject.toml or requirements.txt, go.mod, or Gemfile; pass --stack to override. The rulesets, the merge policy, the alerts, and secret scanning need an admin token (gh auth status); a MISSING with "admin token needed" or "not admin" means the user runs that line, not that the item is optional.

3. Do the one manual item when the report says so: open https://github.com/apps/greptile/installations/new, grant the repository, re-run --check to confirm greptile OK.

4. Commit the written files together, .claude/settings.json, .claude/hooks/harness-bootstrap.sh, and the product docs included (chore(repo): CI, Dependabot, PR template, gitignore, harness, product docs baseline), open the first PR, and confirm the ci check appears on it; a ruleset that requires a context no workflow reports blocks every merge until the workflow runs once.

5. Report the final --check table to the user. Every row OK is the definition of done.

Existing repositories

Run --check on any repository before its first PR of a session that touches process; MISSING rows are the hygiene debt. Applying to a repository with history is safe: files are written only when absent, the rulesets are added beside whatever protection exists (a classic branch protection rule stays until the user removes it), and the merge policy change affects future merges only.

Common mistakes

• Applying before --check: the user should see the delta first, since the rulesets change who can push where.
• Leaving greptile MISSING because "the script did not do it": the script cannot; the install link is the action.
• Requiring 1 review on a solo repository: the owner cannot approve their own PR and every merge needs the admin bypass.
• Renaming the CI job: the ruleset requires the context ci; rename both or neither.