CAITSGet started

Get started

Your app, green, in one command.

One command creates a full-stack TypeScript app on Marko and Vite, with its harness, installs everything, and leaves it passing every check.

npx @ingenioz-it/caits init my-app --example

Needs Linux, macOS, or WSL 2 on Windows (native Windows does not work); Node.js 22 (22.18 or later), 24, or 26 and later; and git. The command installs the rest, the browser of the end-to-end tests included. npx asks once to install CAITS: answer y.

Create your app

In the folder where your projects live, run the command above. It makes the project in the folder my-app, in four steps:

  1. It writes the files of the project: the configuration of the tools, the example app and its tests, and an AGENTS.md for your AI agent.
  2. It writes package.json, with the scripts and the packages.
  3. It installs the packages, with npm install.
  4. It installs the browser for the end-to-end tests, with npx playwright install chromium.

Then check that everything passes:

cd my-app && npm run check

~/my-app

npm run check
6 checks at once: typecheck, lint:code, lint:architecture, test:coverage, test:mutation, test:e2e
✓ lint:architecture  0s
✓ lint:code          4s
✓ typecheck          5s
✓ test:coverage      5s
✓ test:e2e           9s
✓ test:mutation      53s
All 6 checks passed in 53s.

All green: the app passes its types, its lint, its 52 architecture rules, its unit tests with 100% coverage, its mutation tests with 100% of the mutants killed, and its end-to-end tests. This run took 53 seconds on a machine with 32 threads. npm run dev then starts the app on http://localhost:3000.

Prefer a blank page? Drop --example: you get one page and its end-to-end test, with the same harness. The example is worth a look first, though: it shows each layer, and each kind of test.

What you get

The files of the project are yours, except quality/caits/: CAITS keeps its defaults there, and npx caits update rewrites them.

my-app

package.json
tsconfig.json        # extends quality/caits/tsconfig.json
AGENTS.md            # the commands, where the code goes, the rules
quality/             # the configuration of the tools: yours
  architecture.mjs
  eslint.config.js
  playwright.config.ts
  stryker.config.mjs
  vite.config.ts
  caits/             # CAITS's defaults: its own
src/
  backend/           # the backend contexts
  frontend/          # the frontend contexts
  routes/            # the pages and the HTTP handlers
test/e2e/            # the end-to-end tests

Each file of quality/ imports CAITS's defaults, then changes them: your file has the last word. Change a rule or a setting 

The commands

These commands cover your day. The scripts are yours: change them, add your own.

The scripts of package.json

npm run dev
the app on localhost:3000, which follows your changes
npm run tdd
the tests of the files that you change, at each save
npm test
all the unit tests, in seconds
npm run check
before each commit: all the checks, at once
npm run test:mutation
the mutation tests alone
npm run build && npm start
the production app, on localhost:3000

While you work, keep npm run tdd running: it runs the tests of what you change, at each save. Before a commit, run npm run check.

Every check at once

npm run check starts the six checks at the same time, each with a build folder of its own. It prints one line for each check, then the output of the checks that fail, and only theirs. Here is a real run of caits check with four of the checks, after a use case imported an adapter instead of its port:

npx caits check lint:architecture typecheck lint:code test:coverage

4 checks at once: lint:architecture, typecheck, lint:code, test:coverage
✗ lint:architecture  0s
✓ lint:code          3s
✓ typecheck          3s
✓ test:coverage      4s

── lint:architecture ──
src/backend/messages/application/command/add-message/add-message.handler.ts → src/backend/messages/infra/message-repository/file-message-repository.js: application must not depend on infra (layer-direction)

1 architecture violation.

1 of 4 checks failed: lint:architecture.

The file, the import, and the name of the rule: enough to fix it, for you or for an agent. npm run check runs caits check with the scripts of the checks: remove one, or add one of yours.

Hand it to your agent

Your project has an AGENTS.md: the commands, where the code goes, and the rules. Many coding agents read it on their own. Claude Code reads CLAUDE.md: one line points it to AGENTS.md.

echo '@AGENTS.md' >> CLAUDE.md

Commit first, so that you review what the agent changes: git init && git add -A && git commit -m "Start with CAITS". Then give it a task, and the definition of done: npm run check passes. Prompts that work 

An existing project, and the updates

The same command, without the folder name and without --example, adds CAITS to a project: it writes only the files and the values that the project does not have. It fits a Marko app or a nearly empty folder best. CAITS is the npm package @ingenioz-it/caits: npm install --save-dev @ingenioz-it/caits@latest gets a new version, and npx caits update brings its defaults. Add CAITS to a project, or update it 

Next steps