bootstrap-uv-python-workspace

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

# 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

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

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

<PROMPT_BODY> template:

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