/squid-scaffold

name: squid-scaffold
description: >-
  Bootstrap a new repo or component from the opinionated spec library (mode=create), or audit an
  existing scaffolded repo for drift against the scaffold rules (mode=evaluate, report-only).
disable-model-invocation: true
argument-hint: "[mode=create|evaluate] [project description | target repo path]"

Scaffold

Interactive bootstrap for a new repo (or a new component in an existing one): read only the specs under [`specs/`](specs/) that apply, distil them into a tailored `AGENTS.md`, lay down an empty skeleton, hand back.

Modes

`$ARGUMENTS` may lead with `mode=create` (default) or `mode=evaluate`:

• **`mode=create`** (default) — bootstrap a repo / component. The flow in "## Flow" below.
• **`mode=evaluate`** — audit an *existing* scaffolded repo for drift (report-only). For `mode=evaluate`, read [`evaluate.md`](evaluate.md) and follow E1–E4 instead of the Flow.

Every rule both modes honour lives in [`rules.md`](rules.md) — the single source of truth; `mode=create` follows every `P#` + `I#` while composing, `mode=evaluate` audits the `I#`. Do **not** restate any rule in this file.

When to use

• Bootstrapping a brand-new repo.
• Adding a new runtime component (backend / frontend-web / frontend-tui) to an existing scaffolded repo.
• Re-generating the root `AGENTS.md` after a major stack change (e.g. swapping Vue for React).

When NOT to use

• Authoring application source or business logic (`P1`).
• Adjusting opinions inside an existing project — edit the generated `AGENTS.md` directly.
• Non-polyglot single-package projects where the full machinery is overkill. (You can still use a single spec as reference, but skip the scaffold flow.)

Flow

1. Gather requirements

Use `AskUserQuestion` to collect answers. Consolidate where possible — one or two prompts, not a twelve-step interview. Minimum set:

1. **Project identity** — name, short description, license (MIT / Apache-2.0 / proprietary). Name becomes the repo / root AGENTS.md title; slug is derived. 2. **Layout** — monorepo (`packages/<c>/` tree) or standalone single-package? 3. **Components** (multi-select; at least one required):

• `backend` — Python service / pipeline / library
• `frontend-web` — TypeScript browser SPA
• `frontend-tui` — Go terminal UI

4. **Backend variant** (if backend chosen): `fastapi-service` / `fastmcp-server` / `cli-tool-python` / `library-only`. 5. **Frontend-web framework** (if frontend-web chosen): `react` / `vue` / `svelte` / `vanilla`. 6. **Frontend-tui framework** (if frontend-tui chosen): `bubbletea` (default) / `tview`. 7. **Shared OpenAPI contracts** (only if backend + ≥1 frontend): yes / no. 8. **Infra** (multi-select): `docker`, `github-actions`, `pre-commit-hooks`. 9. **Agent team + tracker?** yes (recommended) / no. Also: file-based tracker or GitHub Issues? 10. **Process & documentation** (multi-select, optional): `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. 11. **External services** (optional, multi-select — skip any category that doesn't apply). Each selection pulls a `specs/<category>-<choice>.md` stub and emits a one-line bullet into the generated AGENTS.md, wrapped per `I9`:

• **Datastore:** `mongodb` / `postgresql` / `redis` / `sqlite` / `other` / `none`
• **Orchestrator:** `prefect` / `dagster` / `temporal` / `other` / `none`
• **Observability & evals:** `opik` / `opentelemetry` / `sentry` / `other` / `none`
• **LLM API:** `anthropic` / `openai` / `gemini` / `other` / `none`
• **Embedding API:** `voyageai` / `openai` / `sentence-transformers` / `other` / `none`
• **Model serving:** `modal` / `replicate` / `other` / `none`
• **Web scraping:** `firecrawl` / `playwright` / `requests-bs4` / `other` / `none`

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

12. **Reference docs (`llms.txt`)** — which tools / frameworks / services publish an `llms.txt`, and each one's index URL (e.g. Pydantic AI → `https://pydantic.dev/docs/ai/llms.txt`)? Governed by `P5`; fully skippable.

Before proceeding to step 2, echo the picked configuration back to the user in a two-line summary and confirm.

2. Select specs

Always include:

• [`monorepo-layout.md`](specs/monorepo-layout.md) — unless the user chose standalone single-package.
• [`makefile-delegator.md`](specs/makefile-delegator.md) — unless standalone.

Conditionally include (from answers):

| Answer | Specs to read | |---|---| | `backend` (any variant) | [`python-backend.md`](specs/python-backend.md) + [`uv-python.md`](specs/uv-python.md) + [`pyproject.md`](specs/pyproject.md) + [`ruff-python.md`](specs/ruff-python.md) | | backend = `fastapi-service` | + [`fastapi-service.md`](specs/fastapi-service.md) | | backend = `fastmcp-server` | + [`fastmcp-server.md`](specs/fastmcp-server.md) | | backend = `cli-tool-python` | + [`cli-tool-python.md`](specs/cli-tool-python.md) | | `frontend-web` | [`typescript-frontend.md`](specs/typescript-frontend.md) + the chosen framework spec ([`react-app.md`](specs/react-app.md) / [`vue-app.md`](specs/vue-app.md) / [`svelte-app.md`](specs/svelte-app.md) / [`vanilla-ts-app.md`](specs/vanilla-ts-app.md)) | | `frontend-tui` | [`go-tui.md`](specs/go-tui.md) (already covers both bubbletea and tview) | | shared OpenAPI contracts | [`openapi-contracts.md`](specs/openapi-contracts.md) | | docker | [`docker.md`](specs/docker.md) | | github-actions | [`github-actions.md`](specs/github-actions.md) | | pre-commit-hooks | [`pre-commit-hooks.md`](specs/pre-commit-hooks.md) | | agent team +