Member standards

What every app, package and service must contain, and which check enforces each rule.

A member is anything pnpm-workspace.yaml lists: apps/*, packages/<category>/<name>, services/*. The rules on this page apply to all of them. Kind-specific shape lives on Packages, Services and Apps.

Required files

Every member has the files below; LICENSE is for packages and tooling only.

File	Holds
package.json	The manifest fields below; scripts from the task vocabulary
turbo.jsonc	{ "extends": ["//"], "tags": ["tier:<x>"] } with exactly one tier tag
tsconfig.json	Extends one @stackra/typescript-config/<preset> and nothing else
README.md	What it is, a tasks table of its scripts, the structure of src/, how to run it
AGENTS.md	Where code goes, rules that fail the build, tasks, and a mandatory ## PII table
CHANGELOG.md	# <package name> and a note that Changesets writes it; never hand-edited
LICENSE	Packages and tooling only: a byte-for-byte copy of the root LICENSE. Apps and services carry none (0195)

A member with a build or tests also carries vitest.config.ts (extends a @stackra/vitest-config preset) and tsdown.config.ts (when build is tsdown), each starting with the file contract. All source lives in src/.

The PII table

AGENTS.md always has a ## PII section with the columns Data, Where, Handling. A member that handles no personal data says so and names the change that would make it revisit the answer:

## PII

| Data | Where | Handling                                                                    |
| ---- | ----- | --------------------------------------------------------------------------- |
| None | —     | Handles no personal data yet. Revisit when it stores or receives user data. |

Presence of the heading is checked; whether the table is still true is a review obligation (security reviewer, see Security).

package.json

Field	Rule
name	@stackra/<name>; apps @figentra/<dir>; services @figentra/service-<name>
description	Non-empty, one sentence
license	"MIT" for @stackra/* (0024); "UNLICENSED" for apps and services (0195)
private	true until a package is published
type	"module"
sideEffects	false on every tier:lib package
exports	tier:lib only: each module entry is { "@stackra/source": "./src/….ts", types: "./dist/….d.mts", default: "./dist/….mjs" }, source condition first; a plain string entry is a static asset (0025)
dependencies	catalog:, catalog:<name> or workspace:* only: see Dependencies

Key order: name, version, private, description, license, files, type, main (Expo only), sideEffects, imports, exports, scripts, dependencies, devDependencies. Order is convention, not checked.

turbo.jsonc and tiers

The tag matches the directory:

Directory	Tag	May depend on
packages/tooling/*	tier:config	nothing workspace-local
packages/<category>/<name>	tier:lib	tier:lib, tier:config
apps/*	tier:app	tier:lib, tier:config
services/*	tier:service	anything below it

The direction rule is a law: see Boundaries and ADR 0003.

Kinds

Tier	Kinds
tier:app	app:console, app:mobile, app:desktop, app:docs
tier:lib	package, entries-first (see Packages, ADR 0126)
tier:config	tooling
tier:service	service: services/<name>, entry src/main.ts, root module in stackra.module (see Services)

Scaffolding

pnpm new <kind> <name> [--category <c>] [--entries <list>|none] [--description "<text>"] [--title "<Title>"] [--port <n>] [--repo <path>] [--dry-run] copies a template from tools/scaffold/templates, replaces the tokens, copies the target repo’s LICENSE (packages and tooling only), and formats the result. Then run pnpm install and pnpm verify.

Kind	Template	Lands in
service	templates/services/service	services/<name> (@figentra/service-<name>)
package	templates/packages/package	packages/<category>/<name> (--category required)
tooling	templates/packages/tooling	packages/tooling/<name>
app:console	templates/apps/console	apps/<name> (port from 3710)
app:mobile	templates/apps/mobile	apps/<name> (no hyphens in the name)
app:desktop	templates/apps/desktop	apps/<name>
app:docs	templates/apps/docs	apps/<name> (port from 3334)

pnpm new service billing --description "Billing."
pnpm new package retry --category foundation --entries contracts,testing
pnpm new app:console admin --title "Admin"
pnpm new service billing --repo ../figentra-os --dry-run

Shapes: ADR 0126. Flags and tokens: Scaffolding.

What enforces this

Rule	Check	Status
README.md, AGENTS.md, CHANGELOG.md exist; LICENSE too for packages, tooling	validate-repository.mjs (checkFiles)	Yes
AGENTS.md has a ## PII heading	validate-repository.mjs	Yes
Package LICENSE equals the root LICENSE; apps and services have none	validate-repository.mjs	Yes
description non-empty, license is MIT (UNLICENSED for apps, services)	validate-repository.mjs	Yes
name is @stackra/<name>, @figentra/<dir> or @figentra/service-<dir>	validate-repository.mjs	Yes
Exactly one tier:* tag matching the directory; extends //	validate-repository.mjs (check)	Yes
tsconfig.json extends @stackra/typescript-config/<preset>	validate-repository.mjs	Yes
sideEffects: false and the dist + @stackra/source exports shape on tier:lib	validate-repository.mjs	Yes
Catalog or workspace versions only; no forbidden dependency	validate-repository.mjs + catalogMode	Yes
Tier direction	turbo boundaries (pnpm boundaries)	Yes
Every member exposes the task-vocabulary scripts	planned: validator check	No
CHANGELOG.md heading, package.json key order, tsconfig.json has no extra keys	planned: validator	No
vitest.config.ts / tsdown.config.ts start with the file contract	planned: doc-standard check (see Code style)	No

Run it directly with node tools/scripts/validate-repository.mjs; it prints nothing when clean.