Scaffolding Reference

Guidance for generating and updating projects with the Vibetuner Copier template.

Package name convention

In all examples, app refers to your project's Python package (the directory under src/). The actual name depends on your project slug (e.g., src/myproject/ for a project named "myproject").

Overview

vibetuner scaffold wraps Copier to generate a fully configured project from the files in vibetuner-template/. Answers to the prompts below are stored in .copier-answers.yml inside the generated project, so subsequent updates can reuse them.

Self-Sufficient Framework

Vibetuner is designed to work immediately after uv add vibetuner. The scaffolding provides project configuration and infrastructure, while the framework handles all the boilerplate:

What the framework provides (no scaffolding needed):

• Working FastAPI app with authentication
• Default templates and styles
• Hot reload in development
• CLI tools (vibetuner run dev, vibetuner run prod)
• Auto-discovery of routes, models, tasks

What scaffolding adds:

• Project metadata (name, slug, description)
• Docker configuration (dev and prod)
• CI/CD workflows
• Justfile commands
• Localization setup
• Environment file templates

Flexible Project Structures

The auto-discovery system supports multiple project layouts:

Structure	Example	When to use
src/app/	src/app/models/post.py	Scaffolded projects (default)
src/{package}/	src/myapp/models/post.py	Custom package name
Flat	models.py	Simple projects, scripts

The framework tries these in order: app.X → {package_name}.X → X

Scaffolded projects use src/app/ by convention, configured in pyproject.toml.

Template Prompts

• company_name – default Acme Corp. Displayed in generated metadata, email templates, and documentation.
• author_name – default Developer. Used for attribution in project metadata.
• author_email – default [email protected]. Included in scaffolded docs and config.
• project_name – default _folder_name. Human-friendly name used throughout the README and docs.
• project_slug – default _folder_name. Must match ^[a-z][a-z0-9\-]*[a-z0-9]$ (used for Python package name, Docker image, compose project name).
• project_description – default A project that does something useful.

Populates package metadata.

• fqdn – default empty. When set, enables production deployment extras (Caddy,

Watchtower, etc.).

• python_version – default 3.14. Controls .python-version, Docker images, and uv settings.
• supported_languages – default []. JSON/YAML list of language codes (for example ["es", "fr"]), adds translation skeletons.
• enable_watchtower – default false. Only prompted when fqdn is set; adds Watchtower service to production Docker Compose.

Database URLs (MONGODB_URL, DATABASE_URL, REDIS_URL) are configured via environment variables in .env, not scaffolding prompts.

Supplying Values Non-Interactively

• --defaults answers all prompts with defaults.
• --data key=value overrides individual answers (repeat the flag for multiple overrides).
• --template lets you point at a different Copier template source (local path, git URL, or github:user/repo).

Post-Generation Tasks

After vibetuner scaffold new, Copier executes the commands listed in copier.yml:

• just git-init {{ project_slug }} – initializes a git repository and tags v0.0.1.
• uv sync – installs Python dependencies defined by the scaffold.
• uv run prek install – installs the repository's pre-commit (prek) hooks.

Updating Existing Projects

There are two supported update flows:

1. vibetuner scaffold update (works everywhere)

2. Reads .copier-answers.yml and reapplies the latest template files.

3. Respects previous answers by default; pass --no-skip-answered to revisit prompts.

4. Runs the same post-generation tasks after updating files.

5. just update-scaffolding (inside generated projects)

6. Shells out to copier update -A --trust, then re-syncs dependencies (bun install, uv sync --all-extras).

7. Useful when you already have the project checked out with the scaffolded justfile.

Both commands update tracked files. Always commit or stash local changes before running them, review the results, and resolve any merge prompts Copier surfaces.

Automated Update with Claude Code

Scaffolded projects ship with an /update-scaffolding Claude Code skill that automates the entire update-and-PR workflow. It:

1. Checks upstream for a newer template version (stops early if already up to date).
2. Creates an isolated git worktree so your working tree is untouched.
3. Updates dependencies (just update-and-commit-repo-deps).
4. Applies the latest scaffolding (just update-scaffolding).
5. Detects and resolves merge conflicts intelligently.
6. Creates a PR with a summary of changes and any unresolved conflicts.

Using the Skill Interactively

Open Claude Code in your project and run:

/update-scaffolding

Running from the Command Line (Headless)

You can invoke the skill directly from your terminal without entering the Claude Code TUI:

claude -p "run the /update-scaffolding skill"

This is useful for cron jobs, CI pipelines, or quick one-liners.

Conflict Resolution

The skill resolves most conflicts automatically:

File type	Strategy
pyproject.toml, package.json	Keep newer upstream deps, preserve project additions
Justfiles, CI workflows, Dockerfiles	Prefer upstream (infrastructure stays current)
Templates (.html.jinja)	Prefer upstream structure, keep project content
Source code (src/app/)	Prefer project version (user code wins)

If a conflict cannot be resolved with confidence, the skill leaves the conflict markers in place, flags the file in the PR description, and does not auto-merge. You resolve those files manually and push to the PR branch.

Recommended Workflow

Manual

1. Commit your working tree.
2. Run either vibetuner scaffold update or just update-scaffolding.
3. Re-run tests (just test-build-prod, just dev) to confirm nothing broke.
4. Commit the changes produced by the update.

With Claude Code

1. Run /update-scaffolding (or claude -p "run the /update-scaffolding skill").
2. Review the PR it creates.
3. Resolve any flagged conflicts if needed.
4. Merge the PR.

Refer back to this document whenever you need to adjust template answers, automate non-interactive scaffolding, or keep existing projects in sync with the latest Vibetuner release.