create-justscale 0.1.0

package/dist/scaffold.js

@@ -0,0 +1,324 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Skills shipped with the installer live under packages/misc/install/templates/skills/
+// (single source of truth - repo root .claude/skills/ symlinks here). At runtime
+// this resolves to <package>/templates/skills/ in the published install.
+const SKILLS_TEMPLATE_DIR = join(__dirname, '..', 'templates', 'skills');
+export function scaffoldProject(options) {
+    const { projectDir, projectName, system, coreVersion = '^0.1.0' } = options;
+    const generated = [];
+    mkdirSync(projectDir, { recursive: true });
+    mkdirSync(join(projectDir, 'src'), { recursive: true });
+    // package.json
+    writeFile(projectDir, 'package.json', JSON.stringify({
+        name: projectName,
+        version: '0.1.0',
+        type: 'module',
+        scripts: {
+            build: 'just build',
+            test: 'just test',
+            dev: 'just dev',
+        },
+        dependencies: {
+            '@justscale/core': coreVersion,
+        },
+        devDependencies: {
+            '@justscale/typescript': coreVersion,
+            'tsx': '^4.0.0',
+        },
+    }, null, 2) + '\n', generated);
+    // tsconfig.json
+    writeFile(projectDir, 'tsconfig.json', JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            outDir: 'dist',
+            rootDir: 'src',
+            declaration: true,
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ['src'],
+    }, null, 2) + '\n', generated);
+    // justscale.config.ts
+    writeFile(projectDir, 'justscale.config.ts', `import { defineProject } from '@justscale/core'
+
+export default defineProject({
+  modes: {
+    serve: () => import('./src/serve.js'),
+    cli: () => import('./src/cli.js'),
+  },
+  build: {
+    outDir: './dist',
+  },
+})
+`, generated);
+    // src/app.ts
+    writeFile(projectDir, 'src/app.ts', `import JustScale from '@justscale/core'
+
+export const app = JustScale()
+  // Add services, features, and adapters here
+  // .add(PostgresClient)
+  // .add(AuthFeature)
+`, generated);
+    // src/serve.ts
+    writeFile(projectDir, 'src/serve.ts', `import { app } from './app.js'
+
+// HTTP mode - add controllers and start listening
+export default app
+  // .add(AuthEndpointsFeature)
+  // .add(ApiController)
+  .build()
+`, generated);
+    // src/cli.ts
+    writeFile(projectDir, 'src/cli.ts', `import { app } from './app.js'
+
+// CLI mode - add custom CLI controllers
+// Package CLI commands (user add, pg migrate, etc.) are auto-discovered
+export default app
+  .build()
+`, generated);
+    // .gitignore
+    writeFile(projectDir, '.gitignore', `node_modules/
+dist/
+.justscale/
+*.tsbuildinfo
+`, generated);
+    // IDE config
+    if (system.ides.includes('jetbrains')) {
+        generateJetBrainsConfig(projectDir, generated);
+    }
+    if (system.ides.includes('vscode') || system.ides.includes('cursor')) {
+        generateVSCodeConfig(projectDir, generated);
+    }
+    // AI config
+    if (system.aiTools.includes('claude')) {
+        generateClaudeConfig(projectDir, projectName, generated);
+    }
+    // CI/CD
+    if (system.gitHosting === 'github') {
+        generateGitHubActions(projectDir, system.packageManager, generated);
+    }
+    else if (system.gitHosting === 'gitlab') {
+        generateGitLabCI(projectDir, system.packageManager, generated);
+    }
+    return generated;
+}
+function writeFile(dir, relativePath, content, generated) {
+    const fullPath = join(dir, relativePath);
+    const parentDir = join(fullPath, '..');
+    if (parentDir !== dir)
+        mkdirSync(parentDir, { recursive: true });
+    // Refuse to follow symlinks. Without this check, an attacker (or a
+    // hostile pre-existing target dir) could plant a symlink at e.g.
+    // `package.json -> ~/.ssh/authorized_keys`, and the scaffold would
+    // happily clobber the link target with our generated content.
+    // lstatSync resolves the link itself (not the target).
+    if (existsSync(fullPath)) {
+        const st = lstatSync(fullPath);
+        if (st.isSymbolicLink()) {
+            throw new Error(`Refusing to overwrite symlink at ${relativePath} (would write to the link target outside the project directory).`);
+        }
+    }
+    writeFileSync(fullPath, content);
+    generated.push(relativePath);
+}
+function generateJetBrainsConfig(projectDir, generated) {
+    const ideaDir = join(projectDir, '.idea');
+    mkdirSync(ideaDir, { recursive: true });
+    writeFile(projectDir, '.idea/typescript.xml', `<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="TypeScriptCompilerConfiguration">
+    <option name="useService" value="true" />
+    <option name="typeScriptServiceDirectory" value="$PROJECT_DIR$/node_modules/@justscale/typescript" />
+    <option name="versionType" value="SERVICE_DIRECTORY" />
+  </component>
+</project>
+`, generated);
+    const runConfigDir = join(ideaDir, 'runConfigurations');
+    mkdirSync(runConfigDir, { recursive: true });
+    for (const [name, cmd] of [['just_dev', 'dev'], ['just_build', 'build'], ['just_test', 'test']]) {
+        writeFile(projectDir, `.idea/runConfigurations/${name}.xml`, `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="just ${cmd}" type="js.build_tools.npm">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="${cmd}" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+`, generated);
+    }
+}
+function generateVSCodeConfig(projectDir, generated) {
+    writeFile(projectDir, '.vscode/settings.json', JSON.stringify({
+        'typescript.tsdk': './node_modules/@justscale/typescript/lib',
+        'typescript.enablePromptUseWorkspaceTsdk': true,
+    }, null, 2) + '\n', generated);
+    writeFile(projectDir, '.vscode/launch.json', JSON.stringify({
+        version: '0.2.0',
+        configurations: [{
+                type: 'node',
+                request: 'launch',
+                name: 'just dev',
+                runtimeExecutable: 'npx',
+                runtimeArgs: ['just', 'dev'],
+                cwd: '${workspaceFolder}',
+                console: 'integratedTerminal',
+            }],
+    }, null, 2) + '\n', generated);
+}
+function generateClaudeConfig(projectDir, projectName, generated) {
+    writeFile(projectDir, '.claude/settings.json', JSON.stringify({
+        mcpServers: {
+            justscale: {
+                command: './node_modules/.bin/just',
+                args: ['mcp', 'serve'],
+            },
+        },
+    }, null, 2) + '\n', generated);
+    writeFile(projectDir, 'CLAUDE.md', `# ${projectName}
+
+## Commands
+
+\`\`\`bash
+just build              # Build the project
+just test               # Run tests
+just dev                # Development mode with hot reload
+just init               # Re-run project setup
+just install <package>  # Install a JustScale plugin
+\`\`\`
+
+## Architecture
+
+This project uses JustScale — a TypeScript framework with:
+- Custom TypeScript compiler (\`ptsc\`) for durable process compilation
+- Dependency injection with compile-time validation
+- CLI commands discoverable from installed packages
+- Mode-based entry points defined in \`justscale.config.ts\`
+
+## Conventions
+
+- ESM everywhere (\`"type": "module"\`)
+- 2-space indent, single quotes, semicolons
+- Tests: \`node:test\` runner via \`tsx --test\`
+
+## Claude Code skills
+
+The installer scaffolded a set of JustScale-aware Claude Code skills under
+\`.claude/skills/\`. Each one encodes a recurring framework rule as an
+executable workflow or a load-on-demand reference. Invoke them from inside
+Claude Code:
+
+- \`/justscale-concepts\` — orientation: the four core principles
+  (durable processes, ID-free domain, type-states, distributed-first)
+  and the canonical project layout. Auto-loads when starting work on
+  this codebase.
+- \`/new-process\` — scaffold a durable process (signals + handler) with
+  the framework's distributed-safety rules baked in.
+- \`/audit-domain-purity\` — static check for ID leaks, infra imports
+  from domain, hand-edited migrations, missing \`Locked<T>\`.
+- \`/multi-instance-test\` — scaffold a two-instance e2e test that
+  proves a behavior holds across nodes (the canonical JustScale test
+  shape for distributed primitives).
+
+Edit them in place — they're yours now.
+`, generated);
+    // JustScale-aware Claude Code skills, scaffolded into the user's
+    // project so every dev gets the framework's rules as one-shot tools.
+    // Templates live alongside the install package; symlinked from the repo
+    // root .claude/skills/ for our own dev workflow.
+    copyJustScaleSkills(projectDir, generated);
+}
+/**
+ * Defense-in-depth against a compromised template package: returns false
+ * for any entry whose name contains path separators, parent traversal, or
+ * is a hidden-dot reference. readdirSync should never return such names on
+ * a real filesystem, but if a malicious npm package or symlink injects one,
+ * a naive `join(dir, name, ...)` would escape the intended destination.
+ *
+ * Exported for unit-testing.
+ */
+export function isSafePathSegment(name) {
+    if (name === '' || name === '.' || name === '..')
+        return false;
+    if (name.includes('/') || name.includes('\\'))
+        return false;
+    // Reject NUL just to be paranoid — fs APIs would throw anyway, but better
+    // explicit refusal than implementation-dependent behavior.
+    if (name.includes('\0'))
+        return false;
+    return true;
+}
+function copyJustScaleSkills(projectDir, generated) {
+    if (!existsSync(SKILLS_TEMPLATE_DIR)) {
+        // Skills directory is optional - older installs ship without it.
+        return;
+    }
+    for (const name of readdirSync(SKILLS_TEMPLATE_DIR)) {
+        if (!isSafePathSegment(name))
+            continue;
+        const src = join(SKILLS_TEMPLATE_DIR, name, 'SKILL.md');
+        if (!existsSync(src))
+            continue;
+        const body = readFileSync(src, 'utf8');
+        writeFile(projectDir, `.claude/skills/${name}/SKILL.md`, body, generated);
+    }
+}
+function generateGitHubActions(projectDir, pm, generated) {
+    const setupStep = pm === 'pnpm'
+        ? '      - uses: pnpm/action-setup@v4\n'
+        : '';
+    const cache = pm === 'pnpm' ? 'pnpm' : pm === 'yarn' ? 'yarn' : 'npm';
+    writeFile(projectDir, '.github/workflows/ci.yml', `name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setupStep}      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: ${cache}
+      - run: ${pm} install
+      - run: ${pm} run build
+      - run: ${pm} run test
+`, generated);
+}
+function generateGitLabCI(projectDir, pm, generated) {
+    const enablePm = pm === 'pnpm' ? '    - corepack enable\n' : '';
+    writeFile(projectDir, '.gitlab-ci.yml', `image: node:22
+
+stages:
+  - build
+  - test
+
+build:
+  stage: build
+  script:
+${enablePm}    - ${pm} install
+    - ${pm} run build
+
+test:
+  stage: test
+  script:
+${enablePm}    - ${pm} install
+    - ${pm} run build
+    - ${pm} run test
+`, generated);
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-justscale",
+  "version": "0.1.0",
+  "description": "Create a new JustScale project",
+  "author": "JustScale",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justscale/justscale.git",
+    "directory": "packages/misc/install"
+  },
+  "homepage": "https://justscale.sh",
+  "bugs": {
+    "url": "https://github.com/justscale/justscale/issues"
+  },
+  "type": "module",
+  "bin": {
+    "create-justscale": "./bin/create-justscale.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.20.6",
+    "@justscale/typescript": "6.0.0"
+  },
+  "scripts": {
+    "build": "ptsc -b tsconfig.build.json",
+    "test": "node --import @justscale/typescript/register --import tsx --test --test-timeout=10000 --test-force-exit 'test/**/*.test.ts'",
+    "typecheck": "ptsc --noEmit"
+  }
+}

package/templates/skills/audit-domain-purity/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: audit-domain-purity
+description: Static audit for JustScale domain-purity violations — `id`/`createdAt`/`updatedAt` fields in `defineModel`, infra package imports from `domain/`, `findById('...')` patterns, repository mutators called without `Locked<T>`, and hand-painted span-coloured code in docs. Run before commits or during code review. Reports violations with file:line; does NOT auto-fix.
+allowed-tools: Bash, Read, Grep
+---
+
+# Skill: audit-domain-purity
+
+Run a static audit against `$ARGUMENTS` (default: `.`) for JustScale's
+domain-purity rules. This is the rule book made executable.
+
+The script-style checks below are intentionally crude — `grep` and `git
+log` over a real AST. Crude is fine: this is a triage tool. False
+positives are easier than missed violations. Run before a commit, in CI,
+or during review.
+
+## What to check
+
+### 1. Infrastructure fields in domain models
+
+Domain `defineModel` blocks must NOT define `id`, `createdAt`, or
+`updatedAt`. The adapter owns those concerns and stores them via
+non-enumerable symbols. Putting them in domain fields breaks the
+ID-free principle and leaks adapter details upward.
+
+```bash
+!grep -rEn "(^|[[:space:]])(id|createdAt|updatedAt):[[:space:]]*field\." "$ARGUMENTS" --include="*.ts" 2>/dev/null \
+  | grep -v "/dist/" \
+  | grep -v "/migration"
+```
+
+### 2. Infra imports from domain
+
+Files under any `domain/` folder must NOT import from
+`@justscale/postgres`, `@justscale/redis`, or sibling `infra/` paths.
+Domain is storage-agnostic; if it knows about Postgres, the abstraction
+is broken.
+
+```bash
+!for d in $(find "$ARGUMENTS" -type d -name "domain*" 2>/dev/null); do
+  grep -rEn "from ['\"]@justscale/(postgres|redis)['\"]|from ['\"](\.\./)*infra/" "$d" --include="*.ts" 2>/dev/null
+done
+```
+
+### 3. String IDs leaking into domain code
+
+`findById('...')` reveals that callers are passing loose strings instead
+of typed refs. Domain methods take `Ref<T>` / `Persistent<T>` /
+`Locked<T>`. If a service does `findById`, the boundary above it should
+have already converted the string via `Model.ref\`${id}\``.
+
+```bash
+!grep -rEn "\.findById\(['\"]" "$ARGUMENTS" --include="*.ts" 2>/dev/null \
+  | grep -v "/test/" \
+  | grep -v "/dist/"
+```
+
+### 4. Repository mutators without `Locked<T>`
+
+`repo.update` / `repo.save` / `repo.delete` requires `Locked<T>` at
+compile time, but it's easy to miss in review. Best-effort grep —
+inspect each match by hand:
+
+```bash
+!grep -rEn "\.(update|save|delete)\([a-zA-Z_][a-zA-Z0-9_]*," "$ARGUMENTS" --include="*.ts" 2>/dev/null \
+  | grep -v "/test/" \
+  | grep -v "/dist/"
+```
+
+For each match: was the variable declared with `using x = await
+repo.lock(...)`? If not, flag it. The compiler catches this, but a grep
+sweep before commit catches drift faster than a build.
+
+### 5. Hand-painted span-coloured code in docs
+
+Doc-page code samples should use `FileTreeServer` / `FileTreeClient` /
+`Code`. Hand-rolled `<span className="text-purple-400">` colouring drifts
+from real syntax over time — and it doesn't get type-hinting. If you
+find any, replace with a real Monaco panel.
+
+```bash
+!grep -rEn '<span className="text-(purple|blue|green|orange|zinc)-[0-9]+">' "$ARGUMENTS" --include="*.tsx" 2>/dev/null \
+  | grep -v "/dist/" \
+  | head -30
+```
+
+### 6. (Optional) Hand-edited migrations
+
+Migrations are generated artifacts. A migration file with multiple
+commits in its history was probably edited by hand — fix the generator
+instead. This check has false positives (legitimate fixes also produce
+multiple commits), so present it as a flag, not a violation.
+
+```bash
+!for f in $(find "$ARGUMENTS" -path "*/migrations/*.ts" -type f 2>/dev/null); do
+  count=$(git log --oneline -- "$f" 2>/dev/null | wc -l | tr -d ' ')
+  [ "$count" -gt "1" ] && echo "$f: $count commits (hand-edit suspected)"
+done
+```
+
+## Report format
+
+Group findings by check number. For each finding:
+
+```
+[1 infra-fields] file:line — id/createdAt/updatedAt in defineModel
+  > offending excerpt
+```
+
+End with a count summary:
+
+```
+N findings: A infra-fields, B infra-imports, C string-ids, D missing-Locked, ...
+```
+
+If a check has zero hits, omit it entirely from the report — silence is
+the success state.
+
+## Don't auto-fix
+
+This is a triage tool. Print findings; let the user decide what to fix
+and how. Auto-fixing rule violations across a codebase causes more churn
+than it saves and obscures the real problem (often a misplaced
+abstraction, not the surface symptom).

package/templates/skills/justscale-concepts/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: justscale-concepts
+description: JustScale orientation skill — what the framework is for, the four core principles (durable processes, ID-free domain, type-states, distributed-first), the canonical project layout (domain/infra/app), and where things go. Load when starting work on a JustScale codebase, when the user asks "what is JustScale", "where does X go", "how is this structured", or before generating non-trivial framework code.
+---
+
+# Skill: justscale-concepts
+
+Orientation. Loads what the framework is for, the principles that
+constrain its API, and the canonical project layout — so subsequent code
+generation matches the framework's grain instead of fighting it.
+
+The full philosophy lives at `CORE_PHILOSOPHY.md` in the repo root. The
+canonical example project is `examples/simple-app/`. When in doubt, read
+those — this skill is a fast load for what's already there.
+
+## What JustScale is
+
+A TypeScript backend framework where **domain code describes what
+happens, not how**. Infrastructure (databases, persistence across
+restarts, coordination across nodes) is removed from the surface area
+you write. The code reads like a description of the workflow.
+
+## The four principles
+
+### 1. Domain code describes WHAT, never HOW
+
+A subscription that charges monthly until cancelled looks like a `while`
+loop with a monthly timer:
+
+```typescript
+const subscription = createProcess({
+  path: '/subscription/:user',
+  types: { user: User },
+  inject: { billing: BillingService, notifications: NotificationService },
+
+  async handler({ billing, notifications }, { user }) {
+    while (true) {
+      const r = race();
+      switch (true) {
+        case delay.days(r, 30):
+          await billing.charge(user);
+          await notifications.send(user, 'Payment processed');
+          continue;
+        case signal(r, billing.cancellation):
+          return { status: 'cancelled' as const };
+      }
+    }
+  },
+});
+```
+
+The compiler turns this into an opcode-based state machine that survives
+restarts and routes signals across nodes. You don't see that.
+
+### 2. IDs do not exist in domain code
+
+Domain methods take `Ref<T>`, `Persistent<T>`, or `Locked<T>`. A
+persistent entity IS its own reference.
+
+```typescript
+// Domain: pass entities directly
+await transfer(fromAccount, toAccount, amount);
+
+// Boundary: strings become typed refs
+const user = User.ref(userId);
+```
+
+`defineModel` blocks NEVER include `id`, `createdAt`, or `updatedAt` —
+those are adapter concerns, stored via non-enumerable symbols.
+
+Inter-entity links are typed refs, not foreign keys:
+
+```typescript
+export class Order extends defineModel({
+  fields: {
+    customer: field.ref(User),
+    total: field.decimal(10, 2),
+  },
+  permissions: ({ customer }) => ({
+    view:          permit(User).when(customer),
+    requestReturn: permit(User).when(customer),
+  }),
+}) {}
+```
+
+Permissions live with the model. `permit(User).when(customer)` reads as
+"a User can view this Order when they are its `customer`".
+
+### 3. Type-states as compile-time contracts
+
+A method that mutates says so in its signature:
+
+```typescript
+async addLine(
+  cart: Locked<Cart>,
+  product: Ref<Product>,
+  quantity: number,
+): Promise<Persistent<CartLine>> { /* ... */ }
+
+async removeLine(cart: Locked<Cart>, line: Locked<CartLine>): Promise<void> {
+  using stock = await inventory.lockFor(line.product);
+  await inventory.release(stock, line.quantity);
+}
+```
+
+`Locked<T>` is the only thing `repo.update`/`save`/`delete` accepts. The
+only way to obtain one is `using x = await repo.lock(ref)`, which is
+atomic with the read under `SELECT ... FOR UPDATE`. Stale-write bugs
+are structurally impossible.
+
+### 4. Distributed-first by default
+
+Channels, locks, signals, and durable processes are framework primitives —
+not transport helpers. The same domain code that runs against an
+in-memory lock locally runs correctly against Postgres advisory locks
+across 20 nodes, unchanged. Four mechanical rules close the loop:
+
+- Every mutating repository method requires `Locked<T>`.
+- `repo.lock()` is atomic with the read.
+- `Locked<T>` cannot cross process boundaries (the serializer refuses).
+- Signals carry routable identity. Every signal path param goes through
+  `.types({...})`.
+
+## The canonical project layout
+
+Look at `examples/simple-app/`. Each domain owns its own folder; infra
+is separate; app composes them.
+
+```
+src/
+├── app.ts                 ← composes everything via JustScale().add(...)
+├── controllers/           ← HTTP/protocol surface (status codes, auth, serialization)
+├── domains/
+│   ├── order/
+│   │   ├── order.model.ts        ← defineModel + permissions
+│   │   ├── order.service.ts      ← defineService — mutators take Locked<T>
+│   │   ├── order.feature.ts      ← createFeature — bundles the domain
+│   │   └── order.cli.ts          ← Cli('order ...') routes
+│   └── cart/
+│       ├── cart.model.ts
+│       ├── cart.service.ts
+│       ├── cart.signals.ts        ← defineSignals
+│       ├── cart-lifecycle.process.ts  ← createProcess
+│       ├── cart.feature.ts
+│       └── cart.cli.ts
+└── infra/
+    └── pg/                ← createPgModel + createPgRepository per model
+```
+
+Conventions:
+
+- **`<domain>.model.ts`** — `defineModel` with fields, refs, and a
+  `permissions` block.
+- **`<domain>.service.ts`** — `defineService`. Mutators take `Locked<T>`.
+- **`<domain>.signals.ts`** — `defineSignals`. Path params get `.types`.
+- **`<domain>-<verb>.process.ts`** — `createProcess`.
+- **`<domain>.feature.ts`** — `createFeature` bundling model, service,
+  signals, processes, CLI. `app.ts` imports the feature.
+- **`<domain>.cli.ts`** — `Cli('<verb>')` routes live in the domain
+  folder. CLI is domain logic; HTTP is presentation.
+- **`infra/pg/<model>.pg.ts`** — adapter bindings. Domain code does NOT
+  import from `infra/`. Only `app.ts` does.
+
+## Where things go
+
+| Question | Answer |
+|-|-|
+| New domain entity? | `src/domains/<domain>/<entity>.model.ts` |
+| Domain logic? | `src/domains/<domain>/<domain>.service.ts` |
+| CLI command? | `src/domains/<domain>/<domain>.cli.ts` (NOT `controllers/`) |
+| HTTP controller? | `src/controllers/<group>/...` |
+| Durable workflow? | `src/domains/<domain>/<verb>.process.ts` |
+| Storage details? | `src/infra/pg/...` |
+| Migration? | Generated by `just migrate make` — never hand-author |
+
+## Companion skills
+
+When generating framework code, prefer the dedicated skills:
+
+- `/new-process` — durable process with the rules baked in.
+- `/audit-domain-purity` — static check before commit.
+- `/multi-instance-test` — distributed e2e test scaffold (real
+  `child_process.spawn` workers, not two builders in one process).
+
+## When to load
+
+- Starting a session on a JustScale codebase.
+- The user asks "what is JustScale", "where does X go", "how should I
+  structure this", or "why does the framework do Y".
+- Before generating any non-trivial framework code (model, service,
+  process, controller). The principles prevent drift.