onboarding

name	onboarding
description	Interview the user, inspect this template repo, run the interactive onboarding CLI, and prune unused systems so a new Python project gets running quickly.

Onboarding

Use this skill when the user wants to turn this template into a real project, especially when they invoke /onboarding, ask to run onboarding, or want to remove unused template systems.

onboard.py is the source of truth for the guided setup. Read it before changing anything: STEPS (the ordered step list), the per-step @app.command functions (rename, deps, env, hooks, media, jules), and what each one actually mutates. The CLI is a Typer app; make onboard runs the full orchestrator, and each step is also runnable on its own as a subcommand (uv run python onboard.py <step>).

Workflow

1. Inspect the repo before changing anything:

   • CLAUDE.md / AGENTS.md, README.md (note the main vs saas feature table), pyproject.toml, Makefile
   • onboard.py - the six steps and exactly what each writes:
     • rename - rewrites pyproject.toml name/description and the README.md heading/tagline (only runs while the name is still python-template)
     • deps - uv venv + uv sync
     • env - interactively fills .env from .env.example, preserving group comments and any custom vars
     • hooks - prek install (lists the hooks from prek.toml first)
     • media - generates banner/logo assets via init/generate_banner.py and init/generate_logo.py (needs GEMINI_API_KEY; safe to skip)
     • jules - enables/disables the Jules maintenance workflows under .github/workflows/ by toggling the .disabled suffix
   • The systems themselves so you know what can be pruned: common/ (config), utils/llm/ (DSPY + LangFuse), src/, tests/, docs/ (the Fumadocs site), and the .github/workflows/ (release + Jules automation)

2. Interview the user briefly before running anything. Establish:

   • Project name (kebab-case) and one-line description - drives the rename step
   • Which subsystems they actually want to keep. Common prune candidates:
     • LLM stack (utils/llm/, DSPY/LangFuse deps, related .env keys) if the project does no LLM inference
     • Docs site (docs/) and the media/banner generators (init/, media step) if they don't need branded assets or a docs site
     • Jules automation workflows if they don't want scheduled maintenance PRs
   • Which secrets they have on hand (so the env step is productive)

3. Run onboarding interactively; it is the source of truth for setup:

   • make onboard runs the full guided flow (rename → deps → env → hooks → media → jules), letting the user Skip any step.
   • To run or re-run a single step, use the subcommand, e.g. uv run python onboard.py env or uv run python onboard.py jules.
   • The flow is interactive (questionary prompts); it needs a TTY. If you can't drive prompts, walk the user through running make onboard themselves and help interpret each step.

4. Prune unused systems only after the user confirms. Unlike a headless init, this template has no automatic prune command - remove systems deliberately:

   • Delete the unused directory/module and drop its dependency from pyproject.toml, then uv sync to refresh the lockfile.
   • Remove now-dead .env.example keys and the matching Makefile targets.
   • For Jules automation, prefer the jules onboarding step (toggles .disabled) over deleting the workflow files outright.
   • Do not hand-translate docs; per CLAUDE.md, docs/content/ locales are regenerated by the Jules Translation Sync workflow from the English source.

5. Verify the resulting project:

   • make fmt then make ci (ruff, vulture, ty, import lint, docs lint, dep check, link check, file-length check).
   • make test (or make test_fast for a quick pass).
   • make all to sync deps and run main.py.

Guardrails

• Do not delete the LLM stack, docs site, or CI/release workflows without explicit user confirmation.
• Do not push to main, force-push, or run destructive git commands. Onboarding edits files locally - it never commits or pushes.
• Confirm the prune plan with the user before removing any subsystem, and run uv sync after touching pyproject.toml so the lockfile stays consistent.
• Run make ci before committing; fix everything it flags first.