bootstrap-monorepo — Claude Code skill: what it does, how to install
bootstrap-monorepo scaffolds a polyglot monorepo using moon, proto, and Bun with a TypeScript control plane and strict boundary rules.
MIT 126 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a claude-codeWhat bootstrap-monorepo does
The skill structures a multi-language monorepo where TypeScript serves as the control plane while Python, Rust, or Go act as bounded engines. Proto pins toolchain versions inside .prototools, moon handles the project graph and task caching, and Bun runs scripts alongside root workspaces.
Cross-language communication follows a ladder: CLI processes on stdio come first, stepping up to protobuf or Arrow IPC when throughput demands it. It generates a canonical tsconfig.base.json under TypeScript 7 conventions, leaving the root types array omitted so packages declare their own dependencies.
The workspace relies directly on moon tasks, which fail if proto runtimes are not pre-installed.
What it helps with
- Scaffold a multi-language repository using moon and Bun
- Configure strict cross-language boundaries between Python and TypeScript
- Establish a centralized
tsconfig.base.jsonfor TypeScript packages - Set up task orchestration and affected-project pipelines with
moon ci
Example prompts for the agent
- Bootstrap a new monorepo using the moon and proto stack
- Set up a typed boundary between our Rust kernel and TypeScript
- Generate the root tsconfig for an Nx-convergent Bun monorepo
How to install bootstrap-monorepo
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a claude-code2Manually: put the files in place
~/.claude/skills/bootstrap-monorepo/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bootstrap-monorepo/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a codex2Manually: put the files in place
.agents/skills/bootstrap-monorepo/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a cursor2Manually: put the files in place
.cursor/skills/bootstrap-monorepo/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/itp/skills/bootstrap-monorepo2Manually: put the files in place
.github/skills/bootstrap-monorepo/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/itp/skills/bootstrap-monorepoManually: put the files in place
.devin/skills/bootstrap-monorepo/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about bootstrap-monorepo
How to install bootstrap-monorepo in Claude Code?
Run npx skills add terrylica/cc-skills --skill bootstrap-monorepo -a claude-code in your terminal.
What does bootstrap-monorepo do?
It scaffolds a polyglot monorepo structure orchestrated by moon, pinned with proto, and controlled through TypeScript.
Which tools manage the language toolchains?
Proto manages versions pinned in .prototools, while native engines like Python and Rust run through uv and cargo via moon tasks.
Source text
SKILL.md · MIT
---
name: bootstrap-monorepo
description: Autonomous polyglot monorepo bootstrap meta-prompt on the moon + proto + Bun stack (Nx-convergent). TRIGGERS - new monorepo, new repository, polyglot setup, scaffold repo, moon proto bootstrap, monorepo from scratch.
allowed-tools: Read
disable-model-invocation: false
---
# Bootstrap Polyglot Monorepo (moon + proto + Bun, Nx-convergent)
Canonical reference lives in THIS skill:
→ **See**: [references/bootstrap-monorepo.md](references/bootstrap-monorepo.md) → **Cross-language boundaries**: [references/cross-language-interop.md](references/cross-language-interop.md) — boundary decision ladder + verified tool status (research-verified 2026-06)
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## When to Use This Skill
Use this skill when:
- Starting ANY new repository — single-language or polyglot (the structure scales down)
- Setting up a moon-orchestrated, proto-pinned, Bun/TypeScript-wired monorepo
- Wiring engines (Rust/Python/Go) behind contracts under a TS control plane
- You want the repo Nx-convergent from day one (later `nx init` is mechanical, not a restructure)
## Stack
| Tool | Responsibility |
| -------------- | ---------------------------------------------------------------------------------- |
| **proto** | Toolchain versions (bun, python, rust, node, …) pinned in repo-local `.prototools` |
| **moon** | Project graph + task orchestration + caching + affected detection (`moon ci`) |
| **Bun** | TS runtime for every script, CLI, glue tool, and test; root workspaces |
| **uv / cargo** | Python / Rust engines invoked natively from moon `script:` tasks |
| **TypeScript** | Type-safe control plane (7.0.2+); see **TypeScript Configuration** below |
TypeScript is the control plane; other languages are engines behind language-neutral contracts (JSON Schema 2020-12 / proto) with drift gates and parity tests.
## TypeScript Configuration
This skill scaffolds **`tsconfig.base.json`** as the canonical reference implementation for all new repositories. Boilerplate path: `[templates/tsconfig.base.json](templates/tsconfig.base.json)` — the single source of truth for TS7 config shape.
Each new monorepo receives a root `tsconfig.base.json` with:
- `moduleResolution: bundler`, `target: ESNext`, `strict: true`, `noEmit`, `skipLibCheck`
- `allowImportingTsExtensions`, `lib: ["ESNext"]`, `verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `noImplicitOverride`, `exactOptionalPropertyTypes`
- **`types` is deliberately omitted from the base** — TS7 defaults it to `[]` (stopping resolution of `@types/*`, `process`, JSX globals). Every package declares its own via `"types": ["bun"]` or `["node"]` etc. — bare name only, never `@types/bun` or `bun-types`.
Package-level `tsconfig.json` files extend the base and add their own `types` array + any legitimate package-specific overrides.
**Reference**: `~/.claude/typescript-latest-CLAUDE.md` (applies estate-wide). Package.json declares `"typescript": "latest"` (TS7.0.2+).
For TS 7 migration details and per-repo adoption: consult the bootstrapped skill docstrings and the upstream reference.
## Language-Selection Default (greenfield tiebreaker)
Choose _which language owns the code_ before choosing how to cross between them. This is a **tiebreaker, not a mandate** — a SOTA-native ecosystem and existing repo convention override it.
- **TypeScript by default** for the control plane: app logic, orchestration, CLIs, APIs, config, validation, agent/workflow automation, and anything future agents must refactor. (TS is structurally typed by default — the most agent-navigable surface.)
- **An engine language only where its ecosystem is SOTA-native**: Python for ML/data/science/quant or Python-only libraries; Rust/Go for hot kernels and systems work (Go > Rust as the tiebreaker).
- **Never let an engine language leak across the repo.** A Python-only library does NOT make the project Python — wrap it behind ONE typed boundary (ladder below) and keep TS as the public interface. Validate at the boundary: TS types are compile-time only and Python hints are not runtime-enforced.
## Crossing a Language Boundary (decision ladder)
When work must cross languages, climb from cheapest to most coupled — **stop at the first rung that satisfies the need** (full doctrine + verified tool status: [references/cross-language-interop.md](references/cross-language-interop.md)):
1. **Process boundary** — CLI + JSON/NDJSON on stdio (moon `script:` task). Default.
2. **Schema-typed RPC** — protobuf + buf / ConnectRPC, when a long-lived service or stream exists.
3. **Data-plane** — Apache Arrow IPC/Flight/ADBC, the moment two languages exchange _tables_.
4. **In-process FFI** — PyO3/maturin, napi-rs, Bun FFI, when call frequency makes 1–3 too slow.
5. **One WASM component core** — WIT + Component Model, ONLY if the kernel needs no threads (WASI threading still unshipped as of mid-2026).
Pattern B gate amendment: after the 8-float-op test selects Pattern B, ask "does the kernel need threads?" → if yes, native core (cdylib/PyO3), not WASM.
**TypeScript ↔ Python** (the most common pair) verified picks, June 2026: rung 1 = `Bun.spawn`/`child_process` running Python via `uv run`, with the version from `.python-version` (NOT `bun:ffi` — C-ABI only); rung 2 = FastAPI + `@hey-api/openapi-ts` (HTTP) or `buf`-generated `protobuf-es` + `protocolbuffers/python` stubs (RPC); schema SSoT = Pydantic v2 → JSON Schema 2020-12 → TS, with a CI drift gate. Full table in the reference.
## Quick Commands
```bash
# After bootstrap:
moon ci # affected quality pipeline
moon run <project>:check # one project's full gate (lint+test+drift)
moon query projects # machine-readable project graph (agents read this)
moon query tasks # machine-readable task surface
proto use # install all .prototools pins on a fresh machine
```
## Legacy Path
Pre-2026-06 repos on **Pants + mise** (mise is retired; no mise-era reference remains): migrate them onto this stack per-repo (parity-first, cut tasks over one at a time), never big-bang. The old→new mapping is the Migration Map in [references/bootstrap-monorepo.md](references/bootstrap-monorepo.md).
## Releases (local-first)
Two cases (full recipes in [references/bootstrap-monorepo.md](references/bootstrap-monorepo.md) Phase 9):
- **One releasable unit** → stock `semantic-release`, one `.releaserc.yml`, tag `v${version}`.
- **Multiple independently-versioned projects** (the monorepo standard) → per-project **namespaced tags** (`<project>/v${version}`) via **`@rimac-technology/semantic-release-monorepo`** (stock semantic-release ignores `commitPaths` — upstream #1279/#1212), selected by a `RELEASE_PROFILE`-keyed `.releaserc.cjs` dispatcher that derives each stream's `processCommits` from its `commitPaths`, plus a repo-wide umbrella on stock semantic-release. Install the fork with `npm i -D --ignore-scripts`. Reference impl: `example-org/monorepo`.
## Related Skills
- `itp:semantic-release` - Release automation (local-first; Actions only for release/CodeQL/Dependabot/deploy)
---
## Troubleshooting
| Issue | Cause | Solution |
| ---------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
| `proto::detect::failed` for moon | tool installed but no version pinned | `proto pin --to global moon <version>` (or add to `.prototools`) |
| `moon` not found over ssh | shims not on non-interactive PATH | export `PROTO_HOME` + shims PATH in `~/.zshenv` (NOT only `.zshrc`) |
| Python tests "No module named pytest" | `uv run` prunes dev extras | `uv run --extra dev pytest <path>` from repo root |
| PyO3 crate `cargo test` link errors (`_PyBool_Type`) | tests reference `#[pyfunction]` under extension-module | keep logic in pure-Rust core fns; tests call the core, wrapper stays thin |
| Task runs in wrong cwd | script assumes repo root | `options: { runFromWorkspaceRoot: true }` in the task |
| Guard task wrongly cached | moon caches by default | `options: { cache: false }` on guards/parity/network tasks |
| Commit "passed" but didn't land | a hook auto-fixed files and aborted | re-stage and retry; ALWAYS verify `git log --oneline -1` after commit |
## Post-Execution Reflection
After this skill completes, check before closing:
1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills