setup

Repository Setup

Help the user bring a repository to a solid baseline. Prefer understanding and confirmation over spraying every tool into every repo.

Setup is easy to overdo. A marketing site does not need PyPI publishing; a docs repo may not need a heavy test matrix; a monorepo needs different release config than a single library.

• Infer what you can from the tree, then state your working assumptions.
• If repo type, stack, hosting, or whether a step applies is ambiguous, ask before changing files.
• Apply only baselines that fit this repo. Skip or defer the rest and say why.
• Do not invent boilerplate. Leave the repo so a human or agent can operate from README.md and AGENTS.md.

Phase 1: Understand the repository

First understand if it is a greenfield or a brownfield project. In case of greenfield, ask human what he wants to achieve and the purpose of repo.

Inspect the workspace before proposing a plan. Read package manifests, lockfiles, existing CI, README, and directory layout.

Repo shape (pick the best fit; confirm if unsure)

Shape	Signals
Monorepo	Multiple packages/apps, workspaces, apps/ + packages/, turborepo/pnpm-workspaces
Landing / marketing / blogs	Content-heavy, CMS or MDX, little backend, static or SSG
Backend	API/server entrypoints, OpenAPI, workers, auth, DB migrations
Library	Publishable package metadata, src/ + exports, consumers expected
Documentation	Docs framework, mostly markdown, few runtime deps

Repos can be mixed. Name the mix explicitly.

Tech stack

Use whatever the repo actually uses. Note language(s), package manager, frameworks, test runners, and infrastructure when visible (database, hosting, IaC, container setup).

If detection conflicts (e.g. both package.json and pyproject.toml with no clear primary app), ask which surface this setup pass should target.

Phase 2: Confirm the plan

Present a short plan:

1. What you think the repo is (shape + stack + infra)
2. Baselines you will apply now
3. Optional steps you will skip or ask about (release automation, publishing, branch protection, extra skills)

Wait for confirmation when anything material is unclear or when optional tooling would change release/publish behavior.

Phase 3: Functional baselines

Ensure these exist and match the stack — create or wire them only when missing or broken for this repo type:

• README.md — what the repo is, how to run it, how to test it
• LICENSE — appropriate license file if the user wants one (ask if missing and intent is unclear)
• Tests — a real test runner for the stack (e.g. pytest, vitest) when the repo has executable code worth testing
• Type checking — project-appropriate (e.g. mypy/pyright, tsc)
• Linter / formatter — project-appropriate (e.g. ruff, eslint/biome)

Prefer the repo's existing tools over replacing them. For new Python work prefer uv; for new JS/TS prefer bun unless the repo already standardized on something else.

Phase 4: Agent and repo infrastructure

• AGENTS.md — conventions future agents need (commands, layout, non-obvious rules)
• CONTRIBUTING.md — human/agent contribution norms when useful; keep it short. Point contributors at engineering principles rather than pasting a long essay into every repo
• Conventional Commits — use and document feat:, fix:, chore:, etc. for commits and PR titles
• Branch protection — expect main to require PRs, reviews, and passing CI; create feature branches for work. Configure via GitHub only when the user asks and access is available
• Pre-commit — see references/pre-commit.md
• CI — minimal workflows that match the stack (lint, typecheck, test) when none exist

Phase 5: Optional release and publish tooling

Only when the repo shape warrants it and the user agrees:

• release-please / changelog - libraries, versioned apps, monorepos with releasable packages. See references/release-please.md
• uv trusted publishing - publishable Python packages only. See
• npm trusted publishing - publishable npm packages. See @https://docs.npmjs.com/trusted-publishers

Do not add publishing to apps, marketing sites, or docs-only repos unless the user explicitly wants it.

Phase 6: Relevant agent skills

Equip the repo with skills that match the stack.

• Prefer npx autoskills to detect and install sensible defaults when available
• Use npx skills to search for relevant skills

Install only what clearly helps this repo. Ask before bulk-installing skills.

Phase 7: Agent Engineering workflows

Setup the repo with workflows that improves engineering quality and velocity. Refer to the following most common ones and ask human if he wants to install them:

• Superpowers - Superpowers is a complete software development methodology for coding agents. Refer: @https://github.com/obra/superpowers
• Mattpocock skills - Small, easy to adapt, and composable skills from Matt Pocock. Refer: https://github.com/mattpocock/skills
• Addy Osmani Skills - Production-grade engineering skills for AI coding agents from google team. Refer to: https://github.com/addyosmani/agent-skills

Done criteria

Finish when:

• Assumptions and skips are stated
• Applied baselines match the confirmed plan
• README.md and AGENTS.md are enough to operate the repo
• Optional release/publish steps are either correctly wired or explicitly deferred
• Create a file setup.md and explicitly mention what was done and what was skipped.