Scaffold New Repo

---
name: scaffold-new-repo
description: >-
  Scaffold a new repository's language-agnostic files: LICENSE, README,
  CHANGELOG, agent config, and plans. Use for "scaffold a new repo".
---

# Scaffold New Repo

Generate the language-agnostic foundation files that every new repository starts with.

## Workflow

### 1. Gather Project Information

If the user provided a project name in their request, use it directly instead of detecting from git remote or README. If they specified a project type (one of `go-cli`, `go-library`, `javascript`, `pascal`, `python`, `ruby`, `rust`, `shell`, `swift`, `zig-cli`, `generic`), use it instead of inferring from `.gitignore`. Any remaining parameters should still be gathered normally.

Derive what you can automatically, then ask for only what's missing:

- **Project name** -- derive from the git remote URL or `README.md` h1 heading, not from the directory or branch name (those are often misleading, e.g. worktree paths). Detection order:
  1. `git remote get-url origin` -- extract the repo name from the URL (strip the trailing `.git` if present, take the last path segment). If the command exits non-zero, returns empty output, or the URL cannot be parsed into a repo name, treat this as "no remote" and continue to step 2.
  1. If there is no usable remote, check for an existing `README.md` and use its h1 heading (converted to kebab-case)
  1. Only if both the remote and README detection fail, ask the user for the project name
- **Short description** -- ask the user for a one-sentence description.
- **Project type** -- check the existing `.gitignore` first (GitHub often generates one when creating the repo). Infer the project type from its contents:
  Check heuristics in the order listed below. The first match wins.
  - `go.work` or `*.test` → Go CLI or Go library
  - `node_modules/` → JavaScript
  - `__pycache__/` or `*.pyc` → Python
  - `*.gem` or `.bundle/` → Ruby
  - `*.ppu` or `*.compiled` → Pascal
  - `xcuserdata/` alone, or both `.build/` and `*.ipa` together → Swift
  - `.zig-cache/` or `zig-out/` → Zig CLI
  - `target/` with no other language markers matched → Rust
  - Minimal or macOS-only entries → Shell or Generic
  - Only ask the user for the project type if the `.gitignore` does not make it clear.
- **Project type options**: Go CLI, Go library, JavaScript, Pascal, Python, Ruby, Rust, Shell, Swift, Zig CLI, Generic

### 2. Detect User Identity

Detect the user's GitHub username and full name for use in templates:

```bash
# GitHub username (for module paths, URLs, clone commands)
gh api user -q .login
```

```bash
# Full name (for LICENSE copyright)
git config user.name
```

If either command fails or returns empty output, ask the user to provide the value. Use the GitHub username wherever templates reference `GITHUB-USERNAME` and the full name wherever they reference `COPYRIGHT-HOLDER`.

### 3. Prepare the Directory

If the current directory is empty or the user specifies a directory name:

```bash
mkdir -p PROJECT-NAME
cd PROJECT-NAME
```

If the current directory already has files, confirm with the user before adding boilerplate alongside existing content.

### 4. Initialize Git

Skip if already inside a git repository.

```bash
git init
```

### 5. Generate LICENSE

Read `./references/license.md` for the MIT license template and create a `LICENSE` file from it.

- Replace `YEAR` with the current year (run `date +%Y` to get it)
- Replace `COPYRIGHT-HOLDER` with the detected full name

### 6. Generate README.md

Read `./references/readme.md` for the README template and create a `README.md` from it.

- Replace the heading with the exact binary or repository name (kebab-case)
- Insert the short description
- Tailor the Installation section placeholder to the project type
- Replace `GITHUB-USERNAME` with the detected GitHub username

### 7. Generate CHANGELOG.md

Read `./references/changelog.md` for the CHANGELOG template and create a `CHANGELOG.md` from it.

No replacements needed. This is a static file ready for the first release.

### 8. Generate .gitignore

Read `./references/gitignore-templates.md` for the curated language templates.

If a `.gitignore` already exists (e.g., generated by GitHub), merge the appropriate template entries into it, avoiding duplicates.

If no `.gitignore` exists, create one using the appropriate template based on the project type.

#### GitHub Fallback for Unlisted Types

When the user explicitly specifies a project type that is NOT in the curated list above:

1. Attempt to fetch the template from GitHub's gitignore repository using WebFetch:

   ```text
   https://raw.githubusercontent.com/github/gitignore/main/{TemplateName}.gitignore
   ```

   Derive `{TemplateName}` from the user-specified language using these candidates, tried in order until one succeeds:
   - Title-cased with spaces removed (e.g., `visual studio` → `VisualStudio`)
   - Title-cased with spaces replaced by `-` (e.g., `objective c` → `Objective-C`)
   - The user's input as-is (e.g., `C++`)
     URL-encode special characters in the URL (e.g., `C++` → `C%2B%2B`). Stop at the first successful (non-404) response.

1. **If any fetch succeeds**: merge the fetched entries with the common entries (`.DS_Store`, `.env`, `.claude/settings.local.json`), avoiding duplicates. Use the combined result as the `.gitignore`.

1. **If all candidate fetches fail** (404 or network error): fall back to the Generic template and inform the user that no template was found for that language.

This fallback is ONLY used when the user explicitly specifies a type not in the curated list. It is never used during auto-detection from an existing `.gitignore`.

### 9. Bootstrap Agent Config Files

Set up the hub-and-spoke agent configuration pattern (see the clean-up-agent-config skill for the full rationale). Create these files:

#### AGENTS.md

Read `./references/agents-md.md` for the AGENTS.md template and create the canonical instruction file from it.

- Replace the heading with the exact binary or repository name (kebab-case)
- Insert the short description in the Overview section

#### CLAUDE.md (symlink)

```bash
ln -sfn AGENTS.md CLAUDE.md
```

#### .claude/settings.json

Create a minimal team-shared settings scaffold:

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [],
    "deny": []
  }
}
```

#### .github/copilot-instructions.md

Read `./references/copilot-instructions.md` for the Copilot instructions template and create a `.github/copilot-instructions.md` file from it.

- Replace the heading with the exact binary or repository name (kebab-case)
- The file cross-references AGENTS.md for full project conventions

### 10. Create docs/plans/

Use the Write tool to create empty `.gitkeep` files in both subdirectories:

- `docs/plans/todo/.gitkeep`
- `docs/plans/done/.gitkeep`

The Write tool creates parent directories automatically. The `todo/` subdirectory holds active plans; `done/` holds completed plans preserved for reference.

### 11. Create Initial Commit

Stage all generated files and create the initial commit:

```bash
git add -A
git commit -S -m "feat: scaffold new repository"
```

### 12. Summary

Print a summary of what was created:

- List every file generated
- Note the project type used for `.gitignore`
- Note the agent config files and symlink
- Suggest running the add-community-files skill to add CONTRIBUTING.md, CODE_OF_CONDUCT.md, .github/SECURITY.md, and .github/PULL_REQUEST_TEMPLATE.md

## Error Handling

- If the target directory already contains a `LICENSE` or `README.md`, ask the user before overwriting
- If a `.gitignore` already exists, merge new entries rather than overwriting
- If `git init` fails, continue generating files but warn the user
- If the user provides an unrecognized project type, attempt the GitHub fallback (see Step 8). If that also fails, fall back to Generic and mention it

## Reference Templates

- `./references/license.md` -- MIT license template
- `./references/readme.md` -- README template
- `./references/changelog.md` -- CHANGELOG template (Keep a Changelog format)
- `./references/gitignore-templates.md` -- Per-language `.gitignore` templates
- `./references/agents-md.md` -- AGENTS.md template
- `./references/copilot-instructions.md` -- `.github/copilot-instructions.md` template