setup-repo

Files (1)

• SKILL.md

SKILL.md (first lines)

# Setup Repo

## Overview

Gets a project ready to work in. It looks first, because the situations need different things: a
new project has to be created, an existing one has to be understood, and a project with no code in
it needs far less than one with code.

**Every project gets** a repo, a slim `CLAUDE.md`, the `needs-info`/`ready-for-agent` issue labels, and somewhere for
tickets to live.

**Projects with code also get** a stack, a dev environment, a commit gate and CI.

A documentation, training or planning repo has no stack and no tests, so a commit gate on it is
friction with nothing behind it. That is the whole difference. It is not a lesser setup - tickets
matter there as much as anywhere, because `wayfinder` puts decision tickets on the tracker and a
decision is not code.

## Step 0: look before you act

Establish which situation you are in before changing anything:

- `git rev-parse --is-inside-work-tree` - is this a repo at all?
- Manifests: `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`,
  `*.csproj`, `pom.xml`, `Gemfile`.
- Existing tooling: a lockfile, `.pre-commit-config.yaml`, `.husky/`, workflows under
  `.github/workflows/`, a configured formatter or linter.

No manifest and no repo means **new project**. Anything already there means **existing
project**, and the job changes from building to understanding.

**Then settle whether it has code**, because that decides how much of this runs. On an existing
repo, read it off the manifests above - one present means code, and asking about something visible
on disk wastes the user's attention. On a new, empty project there is nothing to read, so ask - in
the same breath as the name and the owner, never as a separate interview.

## New project

### 1. Name it

**Ask the user what the repo should be called and which owner (account or org) it belongs
under.** Do not guess and do not derive it from a convention - naming schemes are the owner's
business, and renaming a repo later breaks every clone and remote. This is the cheapest possible
moment to be sure.

### 2. Create it

Create the repository under the correct owner, with an empty first commit so the default
branch exists. Seed only:

| Seeded | Why |
|---|---|
| Issue labels: `needs-info` `ready-for-agent` | `to-issues` stamps one on every slice: is every decision made? `ready-for-agent` when an agent can build it with no questions, `needs-info` where a decision is still open. `orchestrate` grills on `needs-info` work, and `implement` may merge `ready-for-agent` work on green. Type and severity are deliberately absent - GitHub gives you those and nothing here read them |
| A license | One file, and awkward to remember later |
| The default branch | Nothing else works without it |

Not seeded: a starter `.github/` directory (an empty template folder is clutter the agent
reads past every session - add it the day a real PR template exists), and not branch
protection (those rules need per-project thought, and a rule set too tight silently blocks the
agent's own pull requests).

### 3. Take the stack from the plan

**Code projects only.** A project with no code skips to `CLAUDE.md` and the tracker.

By the time this runs the stack is usually already settled - `grill-me` or `wayfinder` decided it,
or the user named it in the same breath as the repo. Read it off what you have and confirm in one
line rather than re-asking.

Ask only about what is genuinely still open, and only where the answer changes what you build. The
two that are rarely inferable are the **package manager** (`bun` vs `npm`) and
**what kind of thing this is** - CLI, library, web service - because that shapes the layout.
Everything else: take the ecosystem standard and say which one you took.

**Match the question to the person** - someone who names a stack gets answered in those terms;
someone who does not know gets a recommendation they can take without bluffing.

### 4. Scaffold

**Code projects only.**

1. `git init` if needed; a language-appropriate `.gitignore`, plus `.claude/reports/` so generated reports never get committed.
2. The minimal layout and manifest for the chosen stack.
3. Install dependencies with the project's package manager.
4. A formatter, a linter or type-checker, and a test runner - plus **one trivial passing
   test**, so the suite is green from the first commit and the gate has something to run.
5. The commit gate (below).
6. An initial commit.

## Existing project

### 1. Identify the stack

Read the manifests and lockfiles. Do not assume - a repo with a `package.json` may still be
driven by a Makefile.

### 2. Install the dependencies

With the project's own package manager, read off the lockfile. Note anything else the repo
says it needs to run: required runtime versions, env vars (`.env.example`), services
(`docker-compose.yml`, a README "Getting started"). Nothing in step 3 can run until this has.

### 3. Find the real commands, then run them

Look for what the project actually uses for format, lint, type-check, test and build:
`package.json` scripts, a `Makefile` or `Taskfile`, `pyproject.toml`, `tox.ini`, the CI
workflows.

**Then run each one and confirm it works.** This is the step that matters. Config rots: a repo
can claim `npm test` works when it has not for a year, and a command taken on trust puts
everything built on top of it on a broken foundation. A documented command is a claim, not
evidence.

### 4. Fill the gaps

If a formatter, linter or test gate is missing, propose adding it - but **match what is already
there** rather than imposing a different stack on someone else's codebase.

**A missing test runner and missing tests are two different findings.** Installing a runner is

From solution8-com/s8-agentic-playbook, MIT.

More from solution8-com/s8-agentic-playbook