typescript-scaffold

Files (74)

• SKILL.md
• ci.yml · assets/
• claude-md-rules.md · assets/
• playwright.config.ts · assets/e2e-front/
• home.spec.ts · assets/e2e-front/tests/
• playwright.config.ts · assets/e2e-fullstack/
• home.spec.ts · assets/e2e-fullstack/tests/
• package.json · assets/e2e/
• tsconfig.json · assets/e2e/
• package.json · assets/interface/
• index.ts · assets/interface/src/
• item.ts · assets/interface/src/
• tsconfig.json · assets/interface/
• package.json · assets/package/
• index.ts · assets/package/src/
• tsconfig.json · assets/package/
• README.md · assets/root-back/
• package.json · assets/root-back/
• README.md · assets/root-front/
• package.json · assets/root-front/
• README.md · assets/root-fullstack/
• package.json · assets/root-fullstack/
• README.md · assets/root-script/
• dot-dependency-cruiser.cjs · assets/root-script/
• package.json · assets/root-script/
• pnpm-workspace.yaml · assets/root-script/
• greeting.test.ts · assets/root-script/src/
• greeting.ts · assets/root-script/src/
• main.ts · assets/root-script/src/
• tsconfig.json · assets/root-script/
• vitest.config.ts · assets/root-script/
• package.json · assets/server/
• app.test.ts · assets/server/src/
• app.ts · assets/server/src/
• main.ts · assets/server/src/
• items.ts · assets/server/src/models/
• items.ts · assets/server/src/routes/
• openapi.ts · assets/server/src/routes/
• items.test.ts · assets/server/src/services/
• items.ts · assets/server/src/services/
• tsconfig.json · assets/server/
• biome.json · assets/shared/
• settings.json · assets/shared/dot-claude/
• dot-env.example · assets/shared/
• dot-gitignore · assets/shared/
• dot-nvmrc · assets/shared/
• settings.json · assets/shared/dot-vscode/
• lefthook.yml · assets/shared/
• tsconfig.base.json · assets/shared/
• package.json · assets/web-front/
• clicks.test.ts · assets/web-front/src/lib/
• clicks.ts · assets/web-front/src/lib/
• main.tsx · assets/web-front/src/
• index.tsx · assets/web-front/src/routes/
• vite.config.ts · assets/web-front/
• package.json · assets/web-fullstack/
• api.ts · assets/web-fullstack/src/lib/
• queries.ts · assets/web-fullstack/src/lib/
• main.tsx · assets/web-fullstack/src/
• index.tsx · assets/web-fullstack/src/routes/
• …and 14 more

SKILL.md (first lines)

# Scaffold a TypeScript project

Produces a project where the architecture is enforced by tooling rather than by
memory, and where a fresh clone passes every check on the first run.

**Greenfield only.** Retrofitting an existing project means merging config
rather than writing it, and merging a `package.json` or a dependency-cruiser
rule set badly is worse than leaving them alone.

Assets live in `assets/` and are *frozen*: `scaffold.sh` copies them
byte-for-byte and substitutes two placeholders. Do not retype them, and do not
improvise variants of them.

Four scopes, one skill:

| Scope | Shape | What it emits |
|---|---|---|
| `fullstack` | pnpm workspace | `apps/server`, `apps/web`, `packages/interface`, `e2e` |
| `back` | pnpm workspace | `apps/server`, `packages/interface` |
| `front` | pnpm workspace | `apps/web`, `e2e` |
| `script` | flat package | `src/` |

The three app scopes share every root config file, so adding the missing half to
a `back` or `front` project later is additive: the import rules for it are
already there.

**No database, in any scope.** Which one is a per-project decision. The server
ships `models/` with mock data wired through a service and a route, so the
place a database goes is already a layer with a rule around it.

---

## Step 0 — Guard

Abort if `package.json`, `pnpm-workspace.yaml`, `apps/`, or `src/` exists in
the target directory. Say what was found and stop. Do not offer to merge.

An existing `.git` is fine — scaffolding into a freshly-cloned empty repo is
normal.

## Step 1 — Interview

**Two `AskUserQuestion` calls: four questions, then four (three for
`script`).** `AskUserQuestion` takes at most four per call, so they cannot all
go out at once. Two calls, not eight turns: a scaffold interview that dribbles one question per turn is what
this is guarding against.

The split is not arbitrary — scope is in the first call because the second
call's first question depends on its answer.

First call:

1. **Scope** — fullstack, back only, front only, or scripting only. One line
   each on what it emits, from the table above.
2. **Project name** — the root `package.json` name and the README title.
   Lowercase, hyphens allowed.
3. **CI** — add `.github/workflows/checks.yml`? Default yes. It runs
   `pnpm check`, the same thing the commit hook runs.
4. **GitHub repo** — is it created and set as `origin`? If not, ask the user to
   create it now (`gh repo create`), or to say the project will not be on GitHub.
   Step 4 reads the answer.

Second call:

5. For `fullstack`, `back`, `front`: **npm scope** — the `acme` in
   `@acme/server`. Lowercase, no `@`. Offer the project name as the default.
   For `script`: **Layers** — see Step 2. Give it room.
6. **Rigor stance** — normal (default) or explicitly experimental. Default emits
   nothing; see the rule bank on why this is never inferred.
7. **Skills** — which shared skills to enable in this project? Multi-select
   (`multiSelect: true`), one option per skill:
   - `module-design` — default yes. The `CLAUDE.md` module rules route to it.
   - `open-pr` — default yes. The `CLAUDE.md` git rule routes to it.
   - `markdown-check` — default no.
8. For `fullstack`, `back`, `front` only: **Extra packages** — anything that
   should be its own package beside the apps, such as a rendering engine or a
   parser? Default none. See Step 2 for what to ask about each.

Do not ask about a Node version, a database, a UI library, or end-to-end tests
in the gate. Those are decided: see the last section.

## Step 2 — Layers

The rule, in every scope:

> A layer may import anything below it, never above.

### fullstack, back, front — fixed, no question

The layers are frozen in `assets/workspace/dot-dependency-cruiser.cjs`, with the
reasoning for each written above the rules:

```
apps/server/src            apps/web/src
  main.ts, app.ts  entry     main.tsx        entry
  routes/          HTTP      routes/         pages
  services/        logic     components/     shared components
  models/          data      components/ui/  shadcn, imports only lib/
  lib/             helpers   lib/            hooks, API client, pure logic
```

Across packages: `packages/interface` imports nothing internal, web imports
server for types only, server never imports web. Below `routes/`, the server
may not import `hono`.

There is no question because the frameworks already fix the directories:
TanStack Router owns `routes/`, shadcn owns `components/ui/`. A rule for a
directory that does not exist yet costs nothing, so the one file covers all
three scopes.

### Extra packages — only if question 8 named any

For each package, get three things:

- its **name** — becomes `packages/<name>/` and `@<npm-scope>/<name>`;
- one line on **what lives in it**;
- **which apps import it**: server, web, or both.

Every package already has a place in the frozen rules: below both apps, above

From heartnetkung/claude-skills, MIT.

More from heartnetkung/claude-skills