Workspace Structure

Consumer workspaces use this shape:

{repo}/
  .config/
    dotnet-tools.json
  .litespec/
    project.json
    glossary.yaml
    intent/
      product.yaml
      goals/ problems/ constraints/ decisions/ research/ actors/ roles/ journeys/
      modules/
        {module}/
          module.yaml
          goals/ problems/ constraints/ decisions/ research/
          features/
            {feature}.yaml              requirements as entries
    behavior/
      rules/                            cross-module invariants only
      external-systems/                 create with the first product-level external system
      entry-points/
        {entry-point}/
          entry-point.yaml
          screens/
            {screen}.yaml
      modules/
        {module}/
          permissions.yaml
          use-cases/ rules/ reactions/ jobs/ notifications/ settings/ integration-events/ external-systems/
          {aggregate}/
            aggregate.yaml
            {use-case}.yaml             results and scenarios as entries
            events/ rules/
    implementation/
      decisions/ api/ guides/ operations/ patterns/ writing/ runbooks/
      operations/
        limits.yaml                     create with the first limit record
        secrets.json                    create with the first secret
        log/                            create with the first operations entry
      entry-points/
        {entry-point}/                  UI catalog, captures and patterns
      modules/
        {module}/
          decisions/ runbooks/
    governance/
      exceptions/                       create with the first exception record
      modules/
        {module}/
          exceptions/
    proof/                              generated registers, gate files and run outputs; no authored records
    model/                              generated; ignored
  apps/
    api/
      <backend project manifest>
      src/
      tests/
    {frontend}/
    apphost/                            when one host runs more than one application
  packages/
  AGENTS.md
  <toolchain pin file>
  package.json                          when a frontend or TypeScript package exists
  pnpm-lock.yaml                        when a frontend or TypeScript package exists
  pnpm-workspace.yaml                   when a frontend or TypeScript package exists

A backend stack binding names the files that realize the entries in angle brackets.

The example places neither the backend application nor a frontend application at the workspace root. Under behavior/modules/, each module folder holds one folder per aggregate in plural kebab-case form. A module with one aggregate of the module's own name may stay flat.

A record file lives at the home the model page names for its type. An entry lives in its home file: requirements in their feature file, permissions in their module's permissions file, results and scenarios in their use case file, and rules and events in their aggregate file or type folder. Each entry point is one record in its own folder, with its screens beside it.

Reviewed forThe workspace tree matches the canonical tree in this section, with each record at its type's home under .litespec/.

Marked guidance: a reviewer answers this question.

Size decides which record types and test projects apply: small or large selects the project's required-record set. Each stack decides which technology pages and checks apply to its application. Declaring both in .litespec/project.json lets tools and reviewers read the selection from one file. The scope page states the full selection.

Reviewed for.litespec/project.json at the workspace root declares size and one stack for the backend and for each frontend.

Marked guidance: a reviewer answers this question.

The model builder writes generated working files there, such as frontend facts, while it builds the model from records, code, routes, tests, and test runs. Tracking them would commit derived files beside their sources, and every commit would carry stale working files until somebody rebuilds. The folder is rebuilt rather than reviewed.

Reviewed forNo path under .litespec/model/ is tracked in git; git ls-files .model prints nothing.

Marked guidance: a reviewer answers this question.

Production code under apps/api/src/ and test code under apps/api/tests/ keep the two graphs apart by path. The split makes a test dependency reaching production code visible in the path itself, and keeps test helpers from shipping with the product.

The backend tree is:

apps/api/
  <backend project manifest>
  src/
  tests/

Reviewed forProduction files sit under apps/api/src/ and test files under apps/api/tests/, with no test helper shipped beside production code.

Marked guidance: a reviewer answers this question.

Each root makes one promise: apps/ runs, packages/ is reused. A reusable package under apps/ or deployable code under packages/ inverts that promise, so neither location tells the reader what it holds. One home per kind keeps the promise readable.

Reviewed forEach directory under apps/ runs on its own, and each directory under packages/ is imported by an application.

Marked guidance: a reviewer answers this question.

A shared package with one consumer pays versioning, publishing, and cross-package edits for an audience of one. Requiring two consumers or generated output shared by design keeps sharing deliberate. The baseline permits shared configuration, generated API types, a thin client, and CSS theme tokens.

Reviewed forEach package under packages/ is imported by at least two consumers, or carries generated output shared by design; read the imports in apps/.

Marked guidance: a reviewer answers this question.

Project records describe the product, not the standard and not the code. Placing them inside the application tree makes them disappear when it is rewritten. The root .litespec/ directory keeps records in a place that survives replacing the standard or rewriting the application.

Reviewed forEvery record path sits under the root .litespec/ directory.

Marked guidance: a reviewer answers this question.

A README orients; a record decides. A README that restates a decision becomes a second authored source that drifts from the record it summarizes, until the two disagree and neither is trusted. Linking to the record keeps one source with many pointers.

Reviewed forEach README.md under .litespec/ links to its record and restates no record content.

Marked guidance: a reviewer answers this question.