---
name: bootstrap-uv-python-workspace
description: Bootstrap new Python projects and multi-package workspaces with uv on macOS using deterministic scripts and consistent defaults. Use when creating a new uv Python project, scaffolding a uv monorepo/workspace, setting up package or service profiles, customizing scaffold defaults through layered YAML profiles, initializing dev tooling (pytest, ruff, mypy), creating README scaffolds, or initializing git with an optional first commit.
license: Apache-2.0
compatibility: Designed for Codex and compatible Agent Skills clients on macOS with uv, git, Python project scaffolding workflows, and shell access for the bundled scripts.
metadata:
  owner: gaelic-ghost
  repo: python-skills
  category: python-bootstrap
allowed-tools: Bash(uv:*) Bash(git:*) Read
---

# Bootstrap UV Python Workspace

## Purpose

Create repeatable `uv`-based scaffolds for both single projects and workspaces.
Use this skill as the shared scaffolding basis for other Python bootstrap skills that need consistent `uv` project and workspace defaults.

## When To Use

- Use this skill for generic `uv` project or workspace creation.
- Use this skill when the user needs package or service scaffolding without the higher-level FastAPI or FastMCP overlays.
- Expect downstream higher-level Python bootstrap skills to delegate here rather than duplicate its defaults.

## Primary Workflow

1. Choose the canonical entrypoint:
   - single project: `scripts/init_uv_python_project.sh`
   - workspace: `scripts/init_uv_python_workspace.sh`
2. Select the profile or profile map:
   - `package`
   - `service`
3. Run the selected script with explicit `--name` and optional `--path`, `--python`, `--force`, `--initial-commit`, and `--no-git-init`.
4. Accept the built-in validation path:
   - `uv run pytest`
   - `uv run ruff check .`
   - `uv run mypy .`
5. Confirm the generated output includes:
   - a committed `.env` for safe defaults
   - an ignored `.env.local` for machine-local or secret overrides
   - typed configuration via `pydantic-settings`
6. Return the generated path plus the exact next-step commands emitted by the script.

## Commands

```bash
# Package project
scripts/init_uv_python_project.sh --name my-lib --profile package

# Service project
scripts/init_uv_python_project.sh --name my-service --profile service --python 3.13

# Workspace with defaults (core-lib package + api-service service)
scripts/init_uv_python_workspace.sh --name my-workspace

# Workspace with explicit members and profile mapping
scripts/init_uv_python_workspace.sh \
  --name platform \
  --members "core-lib,billing-service,orders-service" \
  --profile-map "core-lib=package,billing-service=service,orders-service=service"

# Allow non-empty target directory
scripts/init_uv_python_project.sh --name my-lib --force

# Skip git initialization
scripts/init_uv_python_workspace.sh --name platform --no-git-init

# Create initial commit after successful scaffold
scripts/init_uv_python_project.sh --name my-service --profile service --initial-commit
```

## Defaults

- Python version: `3.13` (override with `--python`).
- Quality tooling: `pytest`, `ruff`, `mypy`.
- Config baseline: committed `.env`, ignored `.env.local`, and `pydantic-settings`.
- Git initialization: enabled by default (disable via `--no-git-init`).
- Workspace defaults:
- Members: `core-lib,api-service`
- Profiles: first member `package`, remaining members `service`
- Local linking: services depend on the first package member using uv workspace sources.

## Outputs

- `status`
  - `success`: scaffold and built-in validation completed
  - `blocked`: prerequisites or target-directory constraints prevented the run
  - `failed`: the script started but validation or generation failed
- `path_type`
  - `primary`: one of the two canonical shell entrypoints completed
- `output`
  - resolved project or workspace path
  - emitted validation commands
  - generated run examples

## Guardrails

- Refuse non-empty target directories unless `--force` is set.
- Refuse to overwrite an existing `pyproject.toml`.
- Require `uv` and `git` when git initialization is enabled.
- Exit non-zero with actionable error text for invalid arguments or missing prerequisites.

## Fallbacks and Handoffs

- Preferred paths are `scripts/init_uv_python_project.sh` and `scripts/init_uv_python_workspace.sh`.
- Recommend `bootstrap-python-service` when the user wants FastAPI-first scaffolding.
- Recommend `bootstrap-python-mcp-service` when the user wants FastMCP-first scaffolding.
- Recommend `integrate-fastapi-fastmcp` when the user already has one surface and needs integration guidance for the other inside the same `uv` project or workspace.

## Automation Suitability

- Codex App automation: Medium. Best for scheduled scaffold health checks, not day-to-day product delivery.
- Codex CLI automation: High. Strong fit for CI or scheduled scaffold validation.

## Codex App Automation Prompt Template

```markdown
Use $bootstrap-uv-python-workspace.

Scope boundaries:
- Work only inside <REPO_PATH>.
- Create temporary scaffolds only under <SCRATCH_ROOT>/<NAME>-<STAMP>.
- Do not modify unrelated files outside the temporary scaffold path.

Task:
1. If <MODE:PROJECT|WORKSPACE> is PROJECT, run:
   `scripts/init_uv_python_project.sh --name <NAME> --profile <PROFILE:PACKAGE|SERVICE> --python <PYTHON_VERSION> --path <SCRATCH_ROOT>/<NAME>-<STAMP> <FORCE_FLAG> <GIT_INIT_MODE>`
2. If <MODE:PROJECT|WORKSPACE> is WORKSPACE, run:
   `scripts/init_uv_python_workspace.sh --name <NAME> --python <PYTHON_VERSION> --path <SCRATCH_ROOT>/<NAME>-<STAMP> --members "<MEMBERS_CSV>" --profile-map "<PROFILE_MAP>" <FORCE_FLAG> <GIT_INIT_MODE>`
3. Run validation checks in the scaffold root:
   - `uv run pytest`
   - `uv run ruff check .`
   - `uv run mypy .`
4. If <KEEP_OR_CLEANUP_ARTIFACTS:KEEP|CLEANUP> is CLEANUP, remove the scaffold directory after reporting results.

Output contract:
1. STATUS: PASS or FAIL
2. COMMANDS: exact commands executed, in order
3. RESULTS: concise check outcomes
4. If FAIL: include a short stderr summary and minimal fix recommendation
5. If PASS with no findings: include "safe to archive"
```

## Codex CLI Automation Prompt Template

```bash
codex exec --full-auto --sandbox workspace-write --cd "<REPO_PATH>" "<PROMPT_BODY>"
```

`<PROMPT_BODY>` template:

```markdown
Use $bootstrap-uv-python-workspace.
Stay strictly within <REPO_PATH>. Create temporary artifacts only under <SCRATCH_ROOT>/<NAME>-<STAMP>.
Run scaffold generation for <MODE:PROJECT|WORKSPACE>, then run:
- `uv run pytest`
- `uv run ruff check .`
- `uv run mypy .`
Return STATUS, exact commands, and concise results only. If failures occur, provide only the minimal remediation needed.
```

## Customization Placeholders

- `<REPO_PATH>`
- `<SCRATCH_ROOT>`
- `<NAME>`
- `<STAMP>`
- `<MODE:PROJECT|WORKSPACE>`
- `<PROFILE:PACKAGE|SERVICE>`
- `<MEMBERS_CSV>`
- `<PROFILE_MAP>`
- `<PYTHON_VERSION>`
- `<FORCE_FLAG>`
- `<GIT_INIT_MODE>`
- `<KEEP_OR_CLEANUP_ARTIFACTS:KEEP|CLEANUP>`

## Interactive Customization Workflow

1. Ask whether users want project or workspace script execution.
2. Gather name, path, Python version, and git/force flags.
3. If project script, gather profile (`package` or `service`).
4. If workspace script, gather members and optional profile map.
5. Return both:
- A YAML profile for durable reuse.
- The exact scaffold command to run.
6. Use this precedence order:
- CLI flags
- `--config` profile file
- `.codex/profiles/bootstrap-uv-python-workspace/customization.yaml`
- `~/.config/gaelic-ghost/python-skills/bootstrap-uv-python-workspace/customization.yaml`
- Script defaults
7. If users want temporary reset behavior:
- `--bypassing-all-profiles`
- `--bypassing-repo-profile`
- `--deleting-repo-profile`
8. If users provide no customization or profile files, keep existing script defaults unchanged.
9. See [`references/interactive-customization.md`](references/interactive-customization.md) for schema and examples.

## References

- `references/uv-command-recipes.md`
- `references/customization.md`

## Script Inventory

- `scripts/init_uv_python_project.sh`
- `scripts/init_uv_python_workspace.sh`

## Assets

- `assets/README.md.tmpl`