Help us improve
Share bugs, ideas, or general feedback.
From squid
Bootstraps a new polyglot monorepo or component from opinionated specs. Asks what to build, generates CLAUDE.md and folder skeleton.
npx claudepluginhub iusztinpaul/squid --plugin squidHow this skill is triggered — by the user, by Claude, or both
Slash command
/squid:scaffoldThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Interactive bootstrap for a new repo (or a new component in an existing one).
specs/adr.mdspecs/cli-tool-python.mdspecs/datastore-mongodb.mdspecs/datastore-postgresql.mdspecs/datastore-redis.mdspecs/datastore-sqlite.mdspecs/docker.mdspecs/embeddings-openai.mdspecs/embeddings-sentence-transformers.mdspecs/embeddings-voyageai.mdspecs/fastapi-service.mdspecs/fastmcp-server.mdspecs/github-actions.mdspecs/go-tui.mdspecs/llm-anthropic.mdspecs/llm-gemini.mdspecs/llm-openai.mdspecs/makefile-delegator.mdspecs/model-serving-modal.mdspecs/model-serving-replicate.mdScaffolds greenfield project architecture and AI agent harness via interview-driven decisions. Outputs markdown spec with code structure exemplar, tests, guardrails, CLAUDE.md setup, and unified plan. Invoke via /scaffold for new projects.
Greenfield project scaffolding: architecture decisions, harness setup, and requirements generation via interview-driven derivation chain. Use for new projects or major restructures.
Initializes SpecKit workflow on new or existing projects: scans codebase for tech stack and project details, supports presets like flask-react/fastapi-next, generates CLAUDE.md, constitution.md, and .specify scaffolding with commands/agents.
Share bugs, ideas, or general feedback.
Interactive bootstrap for a new repo (or a new component in an existing one).
specs/ that apply.CLAUDE.md at the target project root that distils those specs (doesn't copy-paste them)./day next to have the SWE agent write the first code against the generated CLAUDE.md.CLAUDE.md after a major stack change (e.g. swapping Vue for React)./day or /night).CLAUDE.md directly.Use AskUserQuestion to collect answers. Consolidate where possible — one or two prompts, not a twelve-step interview. Minimum set:
packages/<c>/ tree) or standalone single-package?backend — Python service / pipeline / libraryfrontend-web — TypeScript browser SPAfrontend-tui — Go terminal UIfastapi-service / fastmcp-server / cli-tool-python / library-only.react / vue / svelte / vanilla.bubbletea (default) / tview.docker, github-actions, pre-commit-hooks.adr (Architecture Decision Records under docs/adr/), ubiquitous-language (project glossary at docs/glossary.md). Recommend adr for any project expected to live > 6 months; recommend ubiquitous-language for backend services with named domain entities.specs/<category>-<choice>.md stub and emits a one-line bullet into the generated CLAUDE.md, wrapped in <!-- stack:<slug> --> comments so the user can find-and-delete it later:mongodb / postgresql / redis / sqlite / other / noneprefect / dagster / temporal / other / noneopik / opentelemetry / sentry / other / noneanthropic / openai / gemini / other / nonevoyageai / openai / sentence-transformers / other / nonemodal / replicate / other / nonefirecrawl / playwright / requests-bs4 / other / noneAsk this as ONE consolidated question: "Which external services will you use? (deselect anything you don't need)." none skips the category entirely — no stub read, no bullet emitted. other keeps an AGENT: fill in placeholder so the SWE can document the real choice on first use.
Before proceeding to step 2, echo the picked configuration back to the user in a two-line summary and confirm.
Always include:
monorepo-layout.md — unless the user chose standalone single-package.makefile-delegator.md — unless standalone.Conditionally include (from answers):
| Answer | Specs to read |
|---|---|
backend (any variant) | python-backend.md + uv-python.md + pyproject.md + ruff-python.md |
backend = fastapi-service | + fastapi-service.md |
backend = fastmcp-server | + fastmcp-server.md |
backend = cli-tool-python | + cli-tool-python.md |
frontend-web | typescript-frontend.md + the chosen framework spec (react-app.md / vue-app.md / svelte-app.md / vanilla-ts-app.md) |
frontend-tui | go-tui.md (already covers both bubbletea and tview) |
| shared OpenAPI contracts | openapi-contracts.md |
| docker | docker.md |
| github-actions | github-actions.md |
| pre-commit-hooks | pre-commit-hooks.md |
| agent team + tracker | tracker-workflow.md |
process: adr | adr.md |
process: ubiquitous-language | ubiquitous-language.md |
datastore = mongodb / postgresql / redis / sqlite | + datastore-<choice>.md |
orchestrator = prefect / dagster / temporal | + orchestrator-<choice>.md |
observability = opik / opentelemetry / sentry | + observability-<choice>.md |
llm-api = anthropic / openai / gemini | + llm-<choice>.md |
embeddings = voyageai / openai / sentence-transformers | + embeddings-<choice>.md |
model-serving = modal / replicate | + model-serving-<choice>.md |
scraping = firecrawl / playwright / requests-bs4 | + scraping-<choice>.md |
Skip any row where the user picked none / other. other is handled at compose time by leaving an AGENT: fill in placeholder in the generated CLAUDE.md.
Read each selected spec end-to-end. Specs are short markdown — full read is fine. Skip reading specs that don't apply; keep context lean.
CLAUDE.mdWrite a single CLAUDE.md at the target project root (or wherever /scaffold was invoked). Follow the canonical three-section template below — The Why / The What / The How. Every generated CLAUDE.md uses this structure; only the content inside each section changes based on the user's choices. Sections gated on absent components (e.g. "Key TypeScript Design Choices" when frontend-web isn't selected) are omitted entirely, not left empty.
# The Why
{One paragraph, first-person-plural if team-built. What this project does, what it produces, who it's for. Pulled straight from the user's project description during the /scaffold interview.}
# The What
## Key Components
{One bullet per enabled component, linking into its package directory. 1–2 sentences per bullet stating the component's role. Example shape:}
- **Backend:** [`packages/backend/`](packages/backend/) — {chosen Python variant: FastAPI HTTP API / FastMCP MCP server / CLI tool / library-only}. {One-line purpose from user input.}
- **Web frontend:** [`packages/frontend-web/`](packages/frontend-web/) — {chosen framework} SPA. {One-line purpose.}
- **TUI frontend:** [`packages/frontend-tui/`](packages/frontend-tui/) — {chosen framework: bubbletea / tview} terminal UI.
- **Shared contracts:** [`packages/shared/`](packages/shared/) — OpenAPI 3.1 spec + per-language codegen. *Only if shared chosen.*
## Project Structure
{ASCII tree pulled from `monorepo-layout.md`, trimmed to the chosen components. Include tracker/ and docs/PROCESS.md when agent team is chosen.}
## Key Python Design Choices
*Only emit if `backend` ∈ components. Distil 5 headline rules from [`python-backend.md`](skills/scaffold/specs/python-backend.md) — do NOT copy-paste the spec.*
- Python 3.12+ minimum; async for I/O-bound work, sync for CPU.
- Loose clean architecture — `entities/` for shared ODM/Pydantic models and enums; per-module `types.py` for narrow types used only within that module or layers upward.
- Flat structure by actionable concern (`ingestion/`, `serving/`) — not dogmatic clean-arch layers.
- Infrastructure dependencies (DB, orchestrator, observability) are **imported directly, not abstracted**. No premature interfaces.
- Pipelines: idempotent, retryable, checkpointed. Datetimes: timezone-aware, UTC by default. Types: annotate everything including `-> None`.
### Writing Scripts
Every entry-point module in `scripts/` calls `init_logger()` (or the project's logging bootstrap) at module level **before any logic or project import**. Never `print()` in library code — use the project logger.
### Writing Tests
- `tests/` mirrors `src/` 1:1. Files `test_*.py`, functions `test_*`. AAA pattern.
- Shared fixtures in `conftest.py`; no manual setup/teardown.
- Mocking via `pytest-mock` (`mocker`), never hand-rolled.
- `@pytest.mark.parametrize` for table tests.
- **Zero warnings.** `filterwarnings = ["error"]` in pytest config.
- **AVOID** unit-testing infrastructure components (orchestrator adapters, model-serving runtime, observability client) — those belong in integration tests only.
- See the [`testing-python`](skills/testing-python/SKILL.md) skill for depth.
## Key TypeScript Design Choices
*Only emit if `frontend-web` ∈ components. Distil from [`typescript-frontend.md`](skills/scaffold/specs/typescript-frontend.md) + the chosen framework spec (`react-app.md` / `vue-app.md` / `svelte-app.md` / `vanilla-ts-app.md`).*
- Node 20+, `npm` (lockfile `package-lock.json`), Vite bundler, Vitest + jsdom for tests.
- `tsconfig`: `strict: true`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`, `isolatedModules`, `moduleResolution: "bundler"`.
- One exported component per `.tsx` / `.vue` / `.svelte` file. Tests mirror `src/` 1:1.
- Only `VITE_*` env vars reach the browser bundle — **never** put secrets in them. Component-level `.env.example` lists the public surface.
- Generated OpenAPI client (if applicable) lands at `src/api/` — never hand-edit.
## Key Go Design Choices
*Only emit if `frontend-tui` ∈ components. Distil from [`go-tui.md`](skills/scaffold/specs/go-tui.md).*
- Go 1.22+, `gofmt` authoritative, `go vet ./...` for lint, stdlib `testing`.
- `cmd/<slug>/main.go` is thin — wires the framework, calls `run()`. `internal/` holds ~95% of code; `pkg/` only for externally importable API.
- Tests co-located (`foo.go` + `foo_test.go` in the same package); co-location lets tests reach unexported identifiers.
- Pin exact dependency versions in `go.mod` so `go mod tidy` is deterministic.
- TUIs are **not** containerised for dev — they need a real TTY. Use `goreleaser` or a CI build step for reproducible binaries.
## Tech Stack
Multi-language — each component brings its own toolchain:
{- **Python 3.12+** (backend) — `uv`, `ruff`, `pytest`.}
{- **Node.js 20+** (frontend-web) — `npm`, `vite`, `vitest`, `eslint` 9, `prettier` 3.}
{- **Go 1.22+** (frontend-tui) — `go mod`, `gofmt`, `go test`.}
{- **OpenAPI 3.1 + codegen** (shared) — `openapi-spec-validator`, `openapi-python-client`, `@openapitools/openapi-generator-cli`, `oapi-codegen`.}
### External services
*For each external-service slug the user selected in step 1, emit one bullet here wrapped in `<!-- stack:<slug> -->` / `<!-- /stack:<slug> -->` HTML comments. Pull the one-line summary from the spec's frontmatter `description` (distil if too long). Slug = short tool name; disambiguate where the same name appears in multiple categories (`openai-llm`, `openai-embeddings`). Emit nothing for categories the user left as `none`. Use the `other` pattern below when the user picked `other` for a category. Post-scaffold, the user can grep `<!-- stack:` to find any block and delete it.*
Example (MongoDB selected):
mongosh "$MONGODB_URL" for local queries. Spec: datastore-mongodb.
Example (user picked `other` for datastore):
### Access Documentation
Use the `context7` MCP server (when available in the Claude Code session) to look up authoritative usage and best practices for any of the above tech-stack items.
# The How
All core commands live in the [`Makefile`](Makefile). Prefer `make <target>` over ad-hoc shell invocations.
Per-component dependency managers:
{- `uv` for Python (`packages/backend/`).}
{- `npm` for TypeScript (`packages/frontend-web/`).}
{- `go mod` for Go (`packages/frontend-tui/`).}
## Agent Team & Pipeline
*Only emit if agent team + tracker chosen.*
This project ships with an opinionated **agent team workflow** in two modes. The canonical lifecycle and rules live in [`docs/PROCESS.md`](docs/PROCESS.md); read it before invoking either pipeline.
| Role | File | Responsibility |
|---|---|---|
| Product Manager | [`agents/product-manager.md`](agents/product-manager.md) | Grooms tasks; final user-POV acceptance (night mode). |
| Software Engineer | [`agents/software-engineer.md`](agents/software-engineer.md) | Implements code + tests; no commit until Tester PASS. |
| Tester | [`agents/tester.md`](agents/tester.md) | Runs full suite; verifies every AC with evidence. |
| On-Call Engineer | [`agents/oncall-engineer.md`](agents/oncall-engineer.md) | Watches CI after push (night mode). |
**Entry points:**
- **`/night [batch-size]`** — unattended batch pipeline (default 2). Full PM groom → SWE → Tester → PM accept → Commit → On-Call CI.
- **`/day [task]`** — supervised single-task pipeline. SWE → Tester → you commit.
**Tracker:** file-based by default — see [`tracker/README.md`](tracker/README.md). Switch to GitHub Issues via `TRACKER_MODE` at the top of [`docs/PROCESS.md`](docs/PROCESS.md).
**When to use which workflow:**
- **Direct chat** — trivial edits, one-shot questions, typos.
- **`/day`** — a single feature, bug fix, or refactor you want to ship under active supervision with a Tester gate.
- **`/night`** — multi-task batches, unattended runs, anything where you want both PM gates plus On-Call enforced.
## Developing New Features and Bug Fixes Workflow
Direct chat is for trivial edits and one-shot questions. For anything that needs a test gate, use `/day`; for unattended batches, use `/night`.
**Engineering discipline lives in the agent contracts — not here.** TDD-first ordering, branching off the current active branch, running the feature end-to-end before hand-off, regression-test-first for bugs, the PR / review-response loop, and the format/lint/unit-tests/integration-tests cadence are all defined in [`agents/software-engineer.md`](agents/software-engineer.md) and [`agents/tester.md`](agents/tester.md). Read those for the general rules; `/day` and `/night` enforce them automatically.
Project-specific invariants the agents can't fully own:
- **Dependencies:** add to the **component-specific** manifest — {`packages/backend/pyproject.toml`}{, `packages/frontend-web/package.json`}{, `packages/frontend-tui/go.mod`}. Never mix languages' deps.
- **New env vars:** update the **component's** `.env.example` + the component's config module. Cross-cutting secrets go in the **root** `.env.example` and are documented there.
{- **New shared contracts:** edit `packages/shared/openapi/api.yaml` and run `make openapi-gen` to regenerate clients. **Never hand-edit** generated client files (`packages/frontend-web/src/api/`, `packages/frontend-tui/internal/api/client.go`, `packages/backend/src/<pkg>/generated_client/`).}
## Step-by-Step Verification Steps
Standard per-atomic-change verification (format/lint, pre-commit, unit tests, running the feature end-to-end, integration tests pre-PR) is defined in the SWE and Tester agent contracts and runs automatically under `/day` and `/night`.
Project-specific additions:
{- **Editing the OpenAPI spec:** run `make openapi-validate && make openapi-gen` and confirm the generated clients compile.}
{- **Editing the root `Makefile` or adding a component:** run `make help` to confirm the target surface is coherent and every per-component verb is wired.}
{- **Editing `docker-compose.yml`:** run `make docker-up` then `docker compose ps` — every service should be `healthy` within 30s.}
{- **Editing an orchestrator-driven pipeline:** serve the worker in the background (`make serve-workflows &`), then trigger via a wrapped `make run-<pipeline>` so logs stream to the current terminal. Re-serve after code changes — running workers don't auto-reload.}
## Build
make build
Builds every enabled component's deployable artifact. For a single component: `make build-<component>`.
## Running QA and Tests
Every verb runs at repo root. The root Makefile **delegates** to `packages/<c>/Makefile` via `$(MAKE) -C packages/<c> <verb>`; it never reimplements per-component logic. Each component owns its own toolchain (`uv` / `npm` / `go`).
### Aggregate (every enabled component)
| Target | What it does |
|---|---|
| `make install` | Install/refresh every component's deps. |
| `make test` | Run every component's test suite. |
{| `make unit-tests` | Backend unit tests only. |}
{| `make integration-tests` | Backend integration tests only. |}
| `make lint-check` / `make lint-fix` | Static checks / auto-fix. |
| `make format-check` / `make format-fix` | Formatting check / apply. |
| `make pre-commit` | `format-check + lint-check + light tests`. |
| `make build` | Build every deployable artifact. |
| `make ci` | Full pre-PR fan: `install → test → lint-check → format-check → pre-commit → build`. |
| `make help` | Curated target list with descriptions. |
> **Manual QA order:** `format-fix → lint-fix → format-check → lint-check → pre-commit → unit-tests`. Fixers before checkers so auto-fixable issues don't surface as false failures. CI runs the non-fix variants only.
### Per-component (fast inner loop)
Every aggregate verb has a `-<component>` form: `make test-backend`, `make lint-fix-frontend-web`, `make format-check-frontend-tui`, etc. Use these during active work on a single component to skip the fan-out cost.
### Component-specific
{- `make dev-frontend-web` — Vite dev server.}
{- `make run-frontend-tui` — `go run ./cmd/<slug>`.}
{- `make openapi-gen` / `make openapi-validate` — regen clients / validate spec (shared contracts).}
{- `make docker-up` / `make docker-down` — local compose stack.}
Every command uses `$(MAKE) -C` under the hood — **never literal `make`** — so `-j`, variable overrides, and recursion tracking propagate cleanly.
## Running Custom Commands for Project-Level Dependencies
For any command not wrapped by the Makefile:
{- **Python (backend):** `uv run python ...`, `uv run pytest ...`, `uv run ruff ...`, `uvx <one-shot-tool>` (e.g. `uvx openapi-spec-validator`). From the repo root without `cd`: `uv --directory packages/<c> run ...`.}
{- **TypeScript (frontend-web):** `npm run <script>`, `npx <one-shot-tool>`.}
{- **Go (frontend-tui):** `go run ./cmd/<slug>`, `go test ./...`, `go run <module>@<version>` for one-shot tools.}
## Running Custom Commands for Accessing Infrastructure and External Services
External CLIs used during development:
- **Git:** `git` for generic VCS operations.
- **GitHub:** `gh` for PRs, issues, Actions logs.
{- **Docker:** `docker compose up -d`, `docker compose down`, `docker compose logs -f <svc>`.}
External-service CLIs (datastore, orchestrator, observability, LLM, embedding, serving, scraping) are documented per-service in [**Tech Stack › External services**](#external-services) above — each `<!-- stack:<slug> -->` block there includes its invocation. Delete a block to drop the service from the project.
## Documentation Conventions
*Only emit if `adr` and/or `ubiquitous-language` were chosen in step 1.*
{If `adr` chosen, emit:}
- **ADRs.** Architecture Decision Records live at [`docs/adr/`](docs/adr/) as `NNNN-kebab-title.md`. Every non-obvious architectural choice (datastore, async/sync default, auth boundary, dependency lock-in) ships with one. Use the four-section Nygard template — Status / Context / Decision / Consequences. ADR-0001 ([`docs/adr/0001-record-architecture-decisions.md`](docs/adr/0001-record-architecture-decisions.md)) is already in the repo and explains the convention. Spec depth: [`adr.md`](skills/scaffold/specs/adr.md).
{If `ubiquitous-language` chosen, emit:}
- **Glossary.** The canonical domain vocabulary lives at [`docs/glossary.md`](docs/glossary.md). One canonical name per concept; code identifiers, OpenAPI schemas, database columns, and customer-facing UI all use the term as it appears there. Update the glossary in the same PR that introduces or renames a domain concept — never after. PM grooming and [`/grill-me`](skills/grill-me/SKILL.md) read it as the tie-breaker when specs and code disagree. Spec depth: [`ubiquitous-language.md`](skills/scaffold/specs/ubiquitous-language.md).
## Self Improve
If a `self-improve` skill is available in your Claude Code session, run it at the end of a session to analyse corrections and persist lessons learned into `CLAUDE.md` or the memory system.
Size target: ≤ 350 lines (was 300; the extra 50 accommodate the External services block when several stacks are chosen). If CLAUDE.md balloons past that, you're copy-pasting specs verbatim instead of distilling. Cut and link out.
Distil, don't copy. For each Key {Lang} Design Choices section, extract 3–5 headline rules from the relevant spec's "Canonical principles". The rationale and canonical examples stay in the spec files; CLAUDE.md states the rule and points to the spec for depth.
Gate sections on component presence. If backend isn't chosen, drop "Key Python Design Choices", "Writing Scripts", "Writing Tests" (unless another language's tests apply), and every Python bullet under the tables. Same for TypeScript and Go. Drop "Shared contracts" bullets when include_shared_contracts is false. Drop the whole "Agent Team & Pipeline" section if the user opted out of the agent team. Drop the whole "Documentation Conventions" section if neither adr nor ubiquitous-language was chosen; otherwise emit only the bullets matching the chosen options. Do not leave empty sections.
Fill placeholders inline. The {...} braces in the template are instructions to you — replace with concrete content from the user's answers and the specs. The AGENT: fill in markers inside the rendered CLAUDE.md are for the SWE agent to address on the first /day run (datastore CLI specifics, orchestrator CLI specifics, etc.) — leave those literal in the output.
Create these files / directories, empty or with minimal placeholders. Do NOT write application source.
Always:
CLAUDE.md — from step 3.README.md — one-paragraph project-facing intro pointing at CLAUDE.md..gitignore — language-appropriate (.venv/, node_modules/, dist/, bin/, .DS_Store, .env)..env.example — cross-cutting placeholder keys (one commented sample var).If monorepo:
Root Makefile — delegator, generated dynamically from the chosen components per makefile-delegator.md. For every enabled component, emit:
install, test, lint-check, lint-fix, format-check, format-fix, pre-commit, buildbackend in components): unit-tests, integration-tests.frontend-web in components): dev.frontend-tui in components): run.openapi-gen, openapi-validate (shared chosen), docker-up, docker-down (docker chosen), ci (always), help (always)..PHONY list built dynamically from emitted verbs (never hardcoded).help target that echoes the enabled-component summary + the curated target list.HAS_<component> := $(shell test -d packages/<c> && echo yes) and gate targets via $(if $(HAS_<X>), <target>) — so make test on a backend-only render doesn't try to run test-frontend-web.$(MAKE) -C packages/<c> <verb> — never a literal make or a cd chain.Per-component packages/<c>/Makefile — implements the verb set in the chosen language's tooling. Use the canonical sketches from makefile-delegator.md:
uv sync, uv run pytest, uv run ruff check, uv run ruff format, uv build.npm ci, npm run test, npm run lint, npm run format, npm run build.go mod tidy, go test ./..., go vet ./..., gofmt -l/-w, go build.uvx openapi-spec-validator, uvx openapi-python-client, @openapitools/openapi-generator-cli, oapi-codegen.AGENT: fill in stubs) — the verbs are mechanical, the tooling is standard per language, and having make install work out-of-the-box on the fresh scaffold lets the user run make install && make test before any SWE work. Real-code placeholders still apply to src/, not to the Makefile.Each packages/<c>/ also gets:
CLAUDE.md — one-paragraph component brief + "see root CLAUDE.md for conventions"..env.example — component-local placeholder./day run.)If shared OpenAPI chosen: packages/shared/openapi/api.yaml with a minimal /health endpoint seed.
If docker chosen:
docker-compose.yml — one service block per runtime component with AGENT: fill in placeholders for image / ports / healthcheck.Dockerfile stub with AGENT: fill in multi-stage build.If github-actions chosen:
.github/workflows/ci.yml — umbrella workflow with dorny/paths-filter routing..github/workflows/ci-<c>.yml — one reusable workflow stub per component..github/dependabot.yml — one ecosystem per component.If agent team + tracker chosen:
docs/PROCESS.md — copy from the plugin (same file).tracker/README.md + tracker/done/.gitkeep..claude/ — only if the user isn't installing the plugin globally; otherwise skip (the plugin provides it).If adr chosen (Process & documentation):
docs/adr/0001-record-architecture-decisions.md — drop the canonical ADR-0001 boilerplate verbatim from adr.md's Bootstrap section, with {YYYY-MM-DD} replaced by today's date. This is the only ADR scaffold writes — subsequent ADRs are authored by the SWE / PR Reviewer / /architecture-review flow as decisions arise. Do not emit a docs/adr/.gitkeep (ADR-0001 already keeps the directory non-empty).If ubiquitous-language chosen (Process & documentation):
docs/glossary.md — minimal seed: a one-paragraph header declaring the discipline ("The canonical vocabulary for {project}. When code, docs, specs, or conversation use a domain concept, use the term as it appears here.") + an empty 3-column table (| Term | Definition | Notes |) with a single commented-out example row so the format is unambiguous. Do not invent domain terms — the SWE / PM agent populate it as the first feature lands. Recommended seed body:
# Glossary
The canonical vocabulary for {project name}. When code, docs, specs, or conversation use a domain concept, use the term as it appears here. PRs that introduce or rename a domain concept update this file in the same change.
| Term | Definition | Notes |
|---|---|---|
<!-- | **OrderLine** | One line item within an Order, identified by `order_line_id`. | Distinct from "Item" (the catalogue entry). | -->
Summarise for the user:
/day "bootstrap packages/backend with a minimal FastAPI app and a /health endpoint". The SWE agent will read CLAUDE.md and the spec references, and write the first real code.main.py, not App.tsx, not cmd/<slug>/main.go. Only structural / configuration files with AGENT-fill-in placeholders.cli-tool-python and fastapi-service for the same backend, ask which one (they can always run /scaffold again to add the other).CLAUDE.md or a packages/<c>/ for a chosen component, ask before clobbering.specs/ is read-only at scaffold time. Edits happen on the plugin repo, not in a consumer project.datastore-*, orchestrator-*, observability-*, llm-*, embeddings-*, model-serving-*, scraping-* files are all stubs pending real-project use. If a category turns out not to be worth maintaining, delete the stub(s) in plugin-repo edits and drop the matching row in Step 2's decision table — nothing else references them.The spec library lives at specs/. Each file is a standalone reference doc describing opinions, not code. Grouped by role:
Layout & tooling (foundational)
monorepo-layout.md — polyglot monorepo tree + component boundaries.makefile-delegator.md — root Makefile pattern + canonical example.Python
python-backend.md — layout, discipline, testing conventions.uv-python.md — uv usage (add / sync / run / build / publish).pyproject.md — pyproject.toml structure + canonical example.ruff-python.md — ruff configuration opinions.Python project types
fastapi-service.md — FastAPI app factory, lifespan, endpoints.fastmcp-server.md — FastMCP server shape.cli-tool-python.md — typer/click CLI conventions.TypeScript frontend
typescript-frontend.md — package layout + canonical configs.react-app.md — React SPA specifics.vue-app.md — Vue SPA specifics.svelte-app.md — Svelte SPA specifics.vanilla-ts-app.md — no-framework TypeScript SPA.Go TUI
go-tui.md — layout, Bubbletea, and tview in one doc.Infrastructure
docker.md — slim Dockerfile + docker-compose opinions.github-actions.md — monorepo CI patterns.openapi-contracts.md — contract-first OpenAPI 3.1 workflow.pre-commit-hooks.md — project-side hook conventions (pre-commit / lefthook / husky), what runs in pre-commit vs pre-push, escape-hatch policy.Process & documentation
tracker-workflow.md — file-based task tracker format.adr.md — Architecture Decision Records (docs/adr/NNNN-title.md), Nygard template, status lifecycle.ubiquitous-language.md — project glossary at docs/glossary.md; one canonical name per domain concept.External services (all stubs — flesh out as real projects reveal opinions; delete any category or file you decide isn't worth maintaining, and drop the matching row in Step 2's decision table)
datastore-mongodb.md, datastore-postgresql.md, datastore-redis.md, datastore-sqlite.md.orchestrator-prefect.md, orchestrator-dagster.md, orchestrator-temporal.md.observability-opik.md, observability-opentelemetry.md, observability-sentry.md.llm-anthropic.md, llm-openai.md, llm-gemini.md.embeddings-voyageai.md, embeddings-openai.md, embeddings-sentence-transformers.md.model-serving-modal.md, model-serving-replicate.md.scraping-firecrawl.md, scraping-playwright.md, scraping-requests-bs4.md.