---
paths:
  - "**/*.cs"
  - "**/*.csproj"
  - "**/*.sln"
  - "**/Directory.Build.props"
  - "**/Directory.Build.targets"
  - "**/appsettings*.json"
  - "**/Program.cs"
---

# Torus Core Framework — Bootstrap Rule

> Used by `/tas-plan` and `/tas-dev` when scaffolding a **new .NET backend project** on top of Torus Backend Framework.
> Skip this rule for non-Torus .NET projects, or when modifying an existing solution not started from `torus-bootstrap`.

## When to apply

Apply if **all** of the following hold:
- Tech Stack in `CLAUDE.md` contains `.NET` / `C#` as backend
- Feature / PRD asks for a brand-new backend project (target dir has no `*.sln`)
- User has not opted out of Torus Backend Framework in `tas.yaml` or task description

If a `*.sln` already exists in the target dir → do NOT re-bootstrap. Read the existing layout instead.

## Tooling

CLI: `torus-bootstrap` — generates Onion Architecture solution wired to Torus Backend Framework NuGet packages.

Install globally (once):

```bash
dotnet tool install --global Torus.Bootstrap
```

Or build from source (when working inside the framework monorepo):

```bash
cd Torus.Bootstrap
dotnet pack
dotnet tool install --global --add-source ./bin/Debug Torus.Bootstrap
```

## Bootstrap workflow

### 1. Pick mode

| Mode | Command | Use when |
|---|---|---|
| Interactive | `torus-bootstrap create --name {Name}` | Choices unclear, first-time scaffold |
| Non-interactive | `torus-bootstrap create --name {Name} --interactive false` | Defaults fine: Memory cache, OpenTelemetry, SQL Server |
| Flag-driven | `torus-bootstrap create --name {Name} --cache redis --database postgresql ...` | Choices already decided in PRD / SAD |

`{Name}` follows project naming convention (e.g. `Torus.Org`, `Acme.Billing`).

### 2. Flag reference

| Category | Flag | Values | Default |
|---|---|---|---|
| Cache | `--cache` | `none` / `memory` / `redis` / `both` | `memory` |
| Cache | `--distributed-lock` | flag — requires `--cache redis\|both` | off |
| Messaging | `--messaging` `--kafka` | `--kafka` requires `--messaging` | off |
| Background Jobs | `--background-jobs` `--quartz` | `--quartz` requires `--background-jobs` | off |
| Telemetry | `--telemetry` `--otel` | `--otel` requires `--telemetry` | off |
| Captcha | `--captcha` | `none` / `google` / `turnstile` / `both` | `none` |
| Authorization | `--opa` | flag — Open Policy Agent | off |
| Blob Storage | `--blob-storage` | `none` / `filesystem` / `minio` / `s3` / `both` | `none` |
| Email | `--email` | `none` / `mailkit` / `ses` / `both` | `none` |
| Database | `--database` | `sqlserver` / `postgresql` / `mysql` / `mongodb` | `sqlserver` |
| Multi-Tenancy | `--multi-tenancy` | flag | off |
| Output dir | `--output` | path | current dir |

Flags override interactive prompts when combined.

### 3. Generated structure

```
{Name}/
├── {Name}.Domain.Shared/             # Shared domain primitives
├── {Name}.Domain/                    # Domain layer (entities, value objects)
├── {Name}.Application.Contracts/     # Application contracts (DTOs, interfaces)
├── {Name}.Application/               # Application layer (use cases, services)
├── {Name}.Persistence.EfCore/        # EF Core DbContext + repositories
├── {Name}.Infrastructure/            # Cross-cutting (logging, caching, ...)
├── {Name}.WebApi/                    # ASP.NET Core entry point
└── {Name}.sln
```

Onion dependency direction: `WebApi → Infrastructure / Persistence → Application → Application.Contracts → Domain → Domain.Shared`. Inner layers MUST NOT reference outer layers.

### 4. Post-bootstrap checklist

After `torus-bootstrap create` succeeds:

1. `cd {Name}` && `dotnet restore`
2. Update `appsettings.json` with real config. Secrets go via `dotnet user-secrets` / env vars — never commit.
3. Add EF Core provider package to `{Name}.Persistence.EfCore.csproj`:
   - `sqlserver` → `Microsoft.EntityFrameworkCore.SqlServer`
   - `postgresql` → `Npgsql.EntityFrameworkCore.PostgreSQL`
   - `mysql` → `Pomelo.EntityFrameworkCore.MySql`
   - `mongodb` → `MongoDB.EntityFrameworkCore` (or use the driver directly, skip EF Core)
4. Create initial migration:
   ```bash
   dotnet ef migrations add InitialCreate --project {Name}.Persistence.EfCore
   ```
5. Build + run:
   ```bash
   dotnet build
   dotnet run --project {Name}.WebApi
   ```

## Guardrails

- DO NOT scaffold on top of an existing solution. Verify target dir has no `.sln` first.
- DO NOT add stray top-level projects (e.g. `Common`, `Shared`) outside Onion layers — extend `Domain.Shared` or `Infrastructure` instead.
- DO NOT let `WebApi` reference `Application` directly — go through `Application.Contracts` to keep boundaries clean.
- DO NOT pin to outdated Torus NuGet versions — `torus-bootstrap` resolves current versions; trust its choices unless PRD overrides.
- Multi-tenancy reshapes DbContext + middleware significantly — only enable if PRD / SAD explicitly calls for it.
- Captcha / OPA / Distributed Lock add infra dependencies — only enable when AC requires them.

## Integration with TAS commands

- **`/tas-plan`** — when Feature requires a new .NET backend project, include a `Bootstrap` step in the Execution Plan referencing this rule. Pin the exact `torus-bootstrap create ...` command (with all chosen flags) in the Technical file so `/tas-dev` can replay it deterministically.
- **`/tas-dev`** — before writing application code, if no `*.sln` exists in target dir, run the bootstrap command from the Technical Plan, then continue with regular Tasks.

## Reference

Full bootstrap CLI docs: [`.tas/templates/torus-dotnet-bootstrap.md`](../../templates/torus-dotnet-bootstrap.md).