scaffold-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.
  2. If there is no usable remote, check for an existing README.md and use its h1 heading (converted to kebab-case)
  3. 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:

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

# 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:

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.

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:

   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.

2. 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.

3. 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)

ln -sfn AGENTS.md CLAUDE.md

.claude/settings.json

Create a minimal team-shared settings scaffold:

{
  "$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:

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