repo-setup

Files (6)

• SKILL.md
• openai.yml · agents/
• glossary.md
• issue-labels.md
• issue-tracker-github.md
• issue-tracker-local.md

SKILL.md (first lines)

# Repository Setup Skill

One-time interactive setup to configure a repository for autonomous development. Scaffolds the per-repository configuration that our engineering skills assume:

- **Glossary**: The project's domain terms, and the synonyms to avoid
- **Issue Tracker**: Where issues live; (GitHub by default; then local Markdown)
- **Issue Labels**: The string labels used for canonical issue triage roles

This is a prompt-driven skill, not a deterministic script. It will inspect the code, ask questions, and make decisions based on your answers. It will not overwrite existing configuration files without explicit confirmation.

## Purpose

Create or modify `AGENTS.md` or `CLAUDE.md`. Create all Farseer configuration files in `.farseer/` through an interactive process with auto-detection.

## Asking the User

**Every question this skill puts to the user goes through the `AskUserQuestion` tool**. When presenting options, provide genuine alternatives, the recommended one should always be first and labeled "(Recommended)". An open-ended question still must go through the tool, whose built-in free-text path carries the user's own words. If a question is worth stopping for, it is worth making answerable in one click. A prose paragraph the user must answer by essay is the failure this rule ends.

**All multi-sentence output for user presentation** should trigger the Skill using `/farseer:humanize` to give a more human voice to the text.

## Execution Steps

### Step 1: Check for Existing Configuration

First, inspect the current repository and understand its starting state. Read what exists and DO NOT assume:

Is this a GitHub repository? Which one? -- `git remote -v` and check `.git/config`

Do we already have configuration files in place?

```bash
ls AGENTS.md CLAUDE.md .farseer/architecture.md .farseer/code-standards.md .farseer/glossary.md .farseer/issue-labels.md .farseer/issue-tracker.md .farseer/testing.md 2>/dev/null
```

Are there any existing plans or ADRs?

```bash
ls .farseer/plans/ .farseer/adr/ .farseer/*/adr/ 2>/dev/null
```

Check for signs if a local-Markdown issue tracker is in place:

```bash
ls .farseer/scratch/ 2>/dev/null
```

If `AGENTS.md` or `CLAUDE.md` and all config files (`architecture.md`, `code-standards.md`, `glossary.md`, `issue-labels.md`, `issue-tracker.md`, `testing.md`) exist, inform the user:

> Repository already configured. Config files exist in `.farseer/`.

Then ask which config files, if any, the user wants regenerated, and continue setup for only those. Never tell the user to delete `.farseer/`: it also holds plans, ADRs, and the out-of-scope records.

Otherwise, continue with setup.

### Step 2: Auto-Detect Project Type

Scan the repository root for configuration files to detect the technology stack:

**Check for these kinds of files (in parallel):**

- `composer.json` → PHP/Magento/Laravel/Symfony
- `package.json` → Node.js/React/Vue/Next.js
- `Cargo.toml` → Rust
- `go.mod` → Go
- `pyproject.toml` or `requirements.txt` → Python
- `Gemfile` → Ruby/Rails
- `pom.xml` or `build.gradle` → Java
- `*.csproj` or `*.sln` → .NET

**For each detected file, extract:**

- Framework and version
- Linting/formatting tools
- Testing framework (from devDependencies or test config)

**Example auto-detection output:**

```markdown
Detected configuration:

- PHP Version: 8.4
- Framework: Laravel 11 (from composer.json)
- Linting: Laravel Pint (from composer.json require-dev)
- Testing: Pest PHP (from composer.json require-dev)
```

### Step 3: Confirm Detection

Ask user to confirm detected configuration:

> I detected the following. Is this correct? (y/n)
> [Show detected config]

If incorrect, ask clarifying questions about each incorrect item.

### Step 4: Gather Additional Information

Ask these questions in order using the `AskUserQuestion` tool. One question, one answer, then the next.

Lead each question with the recommended answer so the user can accept it easily. Give a one-line explainer only when the choice genuinely branches; skip the question entirely when exploration already detected it.

**Q1: Test Command**

> What command runs your tests?
> Detected: `./vendor/bin/pest` [Enter to confirm or type custom]

**Q1b: Parallel Test Command**

> Does your test runner support parallel execution? If so, what's the command?
> (e.g., `./vendor/bin/pest --parallel`, `npm test -- --parallel`, `pytest -n auto`, `go test ./... -parallel 4`)
> [Enter detected parallel command, type custom, or 'none' if not supported]

Auto-detect hints:

- `composer.json` has `brianium/paratest` or `pestphp/pest` → suggest `{test command} --parallel`
- `package.json` has `jest` → suggest `{test command} --runInBand` is serial, default is already parallel
- `package.json` has `vitest` → already parallel by default
- `pytest` with `pytest-xdist` → suggest `pytest -n auto`
- `go test` → suggest `go test ./... -parallel {num}`

From petemcw/farseer, MIT.

More from petemcw/farseer