Skip to content

lukedj78/dev-flow / monorepo-add-python-service

monorepo-add-python-service

Flagged

Add a Python service (FastAPI, managed by uv) as an app of a turborepo scaffolded by `monorepo-bootstrap`, wired into pnpm workspaces and the turbo task graph, with a generated TypeScript client so `apps/web` never hand-writes a `fetch`. Two variants: `generic` (any HTTP service) and `ml` (vision/OCR models — one model resident at a time, `model_version` on every response, Metal locally and CUDA in production). Requires `stack.framework="monorepo"` and `phase` in {scaffolded, page_generated, module_added}; records `stack.monorepo.services`; never bumps `phase`. Triggers: "aggiungi un servizio python", "aggiungi un microservizio FastAPI", "apps/ml", "servizio di inferenza", "add a fastapi service to the monorepo", "python app in the monorepo", "expose a model to the web app". Not for: scaffolding the monorepo itself (`monorepo-bootstrap`), a shared TS package (`monorepo-add-shared-package`), backend modules inside the Next app (`module-add`), or an eve agent (`eve-agent`).

monorepo-add-python-service — a Python app in a JS monorepo, joined at the task graph

Some work does not belong in Node: a vision model, an OCR pipeline, anything whose ecosystem is Python. The instinct is a second repository, and it costs you the thing a monorepo is for — one install, one task graph, one CI, one version of the contract between the two sides.

This skill puts a FastAPI service in apps/<name>/, managed by uv, joined to the monorepo through two seams and no others:

  1. a minimal package.json whose scripts shell out to uv run — turbo runs scripts and does not care what is behind them;
  2. a generated TypeScript client in packages/api/src/<name>/, so a schema change breaks apps/web's typecheck instead of its users.

Versions re-verified 2026-11-05, Python from PyPI and JS from npm — uv@0.13.7, fastapi@0.162.0, uvicorn@0.54.0, pydantic@2.14.3, pytest@9.2.0, ruff@0.17.3, turbo@2.11.10; openapi-typescript@7.13.0 and openapi-fetch@0.17.0 have not moved at all since 2026-09-11. FastAPI is the one to look at — 0.141.1 → 0.162.0 is 21 minors in eight weeks, so treat its version as a [VERIFY] surface rather than a pin you can carry. Every reference cites its source next to the instruction.

⚠️ Read these from PyPI, not npm. uv and fastapi are also the names of unrelated npm packages (uv@1.4.0, fastapi@0.0.8 on 2026-11-05), so npm view uv version answers confidently with a number that has nothing to do with this file. The command is curl -s https://pypi.org/pypi/<name>/json | python3 -c "…['info']['version']".

Why a package.json bridge and not turbo's native Python support

Turborepo does discover uv workspace members natively — and it is behind a future flag, and its own documentation says: "uv support is experimental and can change at any time. We encourage you to try it out in side projects, proof-of-concepts, and other environments where stability is not essential." (Python (Experimental))

It also requires the repository root to become a uv workspace — a root pyproject.toml, a root uv.lock, [tool.turbo].name — which changes what monorepo-bootstrap writes, for every project, to serve one app.

So this skill takes the stable path: the Python app stays a plain pnpm workspace member with a scripts-only package.json, and everything Python-shaped stays inside apps/<name>/. Revisit when the flag graduates — references/turbo-integration.md carries the migration note.

Contract

See references/contracts.md (vendored from dev-flow). Key facts:

  • Reads <project-root>/.workflow/meta.json#stack.framework — must be "monorepo".
  • Requires phase in {scaffolded, page_generated, module_added}.
  • Records the service in stack.monorepo.services (array; see the contract's stack section).
  • Appends history. Does not modify phase — same policy as monorepo-add-shared-package: this skill adds a capability, it does not advance the build. Never regress phase.
  • Golden rule 1 (code in English) applies to everything generated here.
  • Golden rule 2 (i18n) does not apply: the service has no UI. It returns JSON. Nothing here is user-facing text, so there are no locales to add — state this rather than leaving a reader to wonder, the way eve-agent does for the agent app.

The ownership pact

apps/<name>/ belongs to this skill, the way apps/agent/ belongs to eve-agent. Concretely:

  • design-md-to-app, screenshot-to-page, forms, transitions, shadscan, coss-ui and the other web skills must never be proposed for this app. They target a Next.js app with a UI; this app has neither. dev-flow's routing table says so — if something proposes them here, that is the bug.
  • module-add operates in apps/web/. It does not reach into apps/<name>/.
  • The two sides meet at exactly two places: the generated client in packages/api/src/<name>/ and the <NAME>_SERVICE_URL environment variable. Nothing else crosses.

When this skill applies

  • "aggiungi un servizio python" / "add a fastapi service to the monorepo" / "apps/ml".
  • A PRD needs work the JS ecosystem does not do well: vision, OCR, classical ML, scientific computing, a library that only exists in Python.
  • dev-flow may route here from scaffolded / page_generated / module_added when stack.monorepo.services is empty and the PRD names such work. It is proposed, never imposed — a Python service is a stack decision and a second runtime to deploy.

Knowledge dependencies

  • monorepo-bootstrap/references/structure.md — the canonical apps/ + packages/ layout.
  • dev-flow/references/stack-monorepo.md — the stack.monorepo.* sub-keys.
  • references/service-layout.md — what lands in apps/<name>/ and why each file is there.
  • references/turbo-integration.md — the task graph, and the caching trap that eats a day.
  • references/openapi-client.md — FastAPI → packages/api → a typecheck that fails on drift.
  • references/deploy-container.md — the Dockerfile, the registry, the runtime, both env sides.
  • references/variant-ml.md — the model variant: memory, model_version, Metal vs CUDA, the narrowest interface that makes a model swappable, the differential bench that decides whether to swap it, and why a token limit is a wall the pipeline walks through rather than hits.

Workflow

Step 1 — Verify preconditions

Refuse, with the reason and the fix, if any of these is false:

CheckMessage when it fails
.workflow/meta.json exists"No dev-flow project here. Run dev-flow first."
stack.framework == "monorepo""This skill is monorepo-only. A single Next app has no apps/ to add to — put the service in its own repo, or run monorepo-bootstrap first."
phase ∈ {scaffolded, page_generated, module_added}"Need a scaffolded monorepo. Current phase: <phase>."
pnpm-workspace.yaml exists and its globs cover apps/*"apps/* is not a workspace glob — the service would be invisible to pnpm."
turbo.json exists"No turbo.json at the root: this is not a turborepo."
uv on PATH"uv is required. Install it: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) — see https://docs.astral.sh/uv/getting-started/installation/."

Read meta.json#project_slug for the package namespace.

Step 2 — Collect the inputs

One round-trip, with defaults, and say the variant out loud because it changes the dependency tree and the deploy target:

  • name — default ml. kebab-case. Rejected: web, mobile, agent, root, and any existing entry in apps/.
  • port — default 8000. Must not collide with apps/web (3000) or an existing service.
  • variant — generic (default for anything else) or ml. The ml variant adds an optional dependency group, a model registry with explicit unloading, and a different production image. It does not add any inference code.

Step 3 — Scaffold

bash <skill>/scripts/scaffold_python_service.sh <project-root> --name <name> --port <port> --variant <generic|ml>

Idempotent by construction: every file is written only if absent, and the script reports created / exists per path. Re-running it is a no-op that prints what it found. See references/service-layout.md for what each file is and why.

Step 4 — Register the tasks

Patch the root turbo.json — references/turbo-integration.md has the exact JSON and the reason for every key. The one that is not obvious and costs a day if missed:

inputs opts you out of turbo's .gitignore awareness. A Python package without $TURBO_DEFAULT$ in its inputs hashes __pycache__/, .venv/ and .pytest_cache/, and the cache never hits again. (Configuring turbo.json → inputs)

Step 5 — Generate the client

pnpm --filter @<slug>/<name> run openapi     # FastAPI → apps/<name>/openapi.json
pnpm --filter @<slug>/api run build          # openapi.json → packages/api/src/<name>/

apps/web imports the client and reads <NAME>_SERVICE_URL from the environment. A hand-written fetch to the service is the anti-pattern this whole seam exists to prevent — see references/openapi-client.md, which also shows how to make the typecheck the gate.

Step 6 — Verify, and say what actually ran

python3 <skill>/scripts/check_python_service.py <project-root> --name <name>

It reports signals, never a verdict: uv present and its version, the Python version the service pins, whether the turbo tasks are registered, whether the client exists and is newer than the schema. Read them and decide; do not paste them as a pass.

Then the real thing, because a signal is not a run:

pnpm turbo dev --filter @<slug>/<name>     # then: curl -s localhost:<port>/health
pnpm turbo test lint --filter @<slug>/<name>

Step 7 — Record it

meta.json#stack.monorepo.services gains one entry, and history gains one line:

python3 <dev-flow>/scripts/update_meta.py <project-root> append-history \
  --skill 'monorepo-add-python-service' \
  --inputs '{"name":"<name>","port":<port>,"variant":"<variant>"}' \
  --outputs '{"app":"apps/<name>","client":"packages/api/src/<name>"}'

phase is untouched, before and after.

Common anti-patterns (NEVER do)

  • ❌ fetch("http://localhost:8000/…") in apps/web. The generated client exists so that a schema change is a compile error, not a runtime 422 nobody sees until production.
  • ❌ A hardcoded service URL. <NAME>_SERVICE_URL, both locally and on Vercel.
  • ❌ inputs without $TURBO_DEFAULT$ — see Step 4.
  • ❌ Giving the service the database. It is stateless: input in, JSON out. The exception and its cost are in references/service-layout.md; taking it without reading that is how two services end up owning one schema.
  • ❌ Model dependencies in the base dependency set. torch in the base install means every uv sync on every laptop and every CI job pulls gigabytes. references/variant-ml.md.
  • ❌ Running the ml variant in Docker on macOS expecting the GPU. Docker Desktop does not expose Metal. Native locally, CUDA container in production.
  • ❌ Committing model weights, or caching them inside the repo.

What this skill does NOT do

  • No inference code. It scaffolds the contract and the extension points. Which model, how it is called, what it returns — product work.
  • No second scaffold. One service per run. Run it again for another.
  • No deploy. It writes the Dockerfile and documents the target; pushing the image and creating the runtime is the user's move, with credentials this skill never handles.
  • No UI. Golden rule 2 does not apply here; see Contract.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall