Modular monolith harness

The mini app split into modules (catalog, members, and loans), each with its public API and its own AGENTS.md, plus a subagent that works inside one module. It reuses the pieces from days 3 to 5.

Before you start

  • Hexagonal harnessHarness

    The mini app as a hexagon: a core with the library rules, and adapters around it for HTTP and storage. It reuses the security, quality, and clean-code pieces as they are.

    Published

The key idea: the app is split by parts of the library, not by technical layers. Each module has its code, its data, a small public API, and its own AGENTS.md. The agent that works on loans only needs the loans instructions and the public API of the other modules. Before it finishes, a hook checks that no module reaches inside another.

What a modular monolith is

A monolith is an app that is deployed in one piece. Kamil Grzybek puts it this way: a system with exactly one deployment unit. A modular monolith is a monolith split inside into modules, and each module matches a part of the business. Kirsten Westeinde, from Shopify, defines it as an app with strictly enforced boundaries between its domains.

Think of a department store. It is one building, with one entrance and one opening schedule. But each department (books, clothing, café) has its own staff, its own stockroom, and its own counter. If the café needs something from the book department, it asks at the counter; it does not walk into their stockroom. And if the book department rearranges its stockroom, the café never notices.

The mini app has three departments:

  • Catalog (src/modules/catalog/): the books and whether each one is available.
  • Members (src/modules/members/): the members.
  • Loans (src/modules/loans/): the loans and the two library rules (a loaned book cannot be loaned again, and each member has at most three loans).

Each module brings its own Express routes, its in-memory storage, and its logic. The counter is each module’s index.ts file: its public API. For example, the catalog publishes CatalogApi, with two methods: getBook, which returns a book or throws BOOK_NOT_FOUND, and setBookAvailable, which marks it as loaned or returned. Loans uses those two methods and nothing else from the catalog.

The idea is not new. In 1972, David Parnas proposed splitting a system into modules so that each one hides a design decision that may change, behind an interface that reveals as little as possible about how it works inside. Simon Brown calls it packaging by component: each component brings together the logic and the data access of one thing, and another component that needs that data has to go through its public interface. Grzybek adds that everything a module shares with the outside becomes its public API, and recommends that each module has its own data, except in very simple systems.

Modular monolith and microservices

The modular monolith is often compared with microservices: it splits the code by parts of the business, but without spreading it across services that are deployed separately. Martin Fowler wrote in 2015 that even experienced architects have trouble getting the boundaries right at the beginning. That is why he suggests starting with a monolith, paying attention to modularity both at the API boundaries and in how the data is stored. He adds that he had not yet heard many stories where that worked out. Stefan Tilkov answered six days later that, in practice, he has very rarely seen a monolith keep its boundaries with discipline.

To keep them, Shopify first wrote Wedge, a tool that recorded during the tests which component called which, and then Packwerk, which reads the code without running it and rejects changes that break the boundaries. In 2024 they explained that, in version 3.0, they removed the privacy check from Packwerk, the one that guarded the public API. One of the reasons: static analysis cannot see the references that are created while the code runs. Spring Modulith, for Java, checks two rules similar to this harness’s: that a module only uses another module’s API, and that there are no cycles between modules.

The key rule

A module uses another module only through its public API, the index.ts in its folder. The other files of a module are internal: only that module imports them. src/app.ts also builds each module through its index.ts.

Folder What it holds Public API (index.ts) Uses
src/modules/catalog/ Books and whether each one is available Book, CatalogApi, createCatalogModule() nothing
src/modules/members/ Members Member, MembersApi, createMembersModule() nothing
src/modules/loans/ Loans and their two rules LoansDependencies, createLoansModule() catalog, members
src/shared/ The AppError error and the HTTP helpers that every module uses not a module no module
src/app.ts Composition root: builds the modules and hands the others to loans not a module every module

The rules live in .dependency-cruiser.cjs, the same tool as in the earlier harnesses, which reads the import lines of the code. There are five:

  • modules-import-only-public-api: a module imports only the index.ts of another module. This is the main rule.
  • composition-root-imports-only-public-api: app.ts and server.ts also build the modules through their index.ts.
  • shared-does-not-import-modules: src/shared/ serves every module, so it knows none of them.
  • modules-do-not-import-the-composition-root: no module imports app.ts or server.ts.
  • no-circular: there are no circular dependencies. Between modules, a cycle means two modules that cannot change without each other.

The main rule uses a regular expression group, $1, that holds the name of the importing module. That way, a loans file can import any loans file, but from another module only its index.ts, and the rule also works for a new module without changes. The direction between modules comes from no-circular: loans already uses the catalog, so if the catalog imported loans, even through its index.ts, it would close a cycle.

One AGENTS.md per module

The earlier harnesses had a single AGENTS.md. This one has four: one at the root and one in each module.

  • The root one explains the app, the module table, the key rule, where new code goes, and the verification commands. It also carries the security, quality, and clean-code sections of the pieces, unchanged. It asks the agent to read a module’s AGENTS.md before changing that module.
  • Each module’s one explains what the module holds, what its index.ts publishes, what each file does, which modules it depends on, and where its tests go. The loans one adds the order in which the rules are checked.

The idea comes from context engineering: give the agent what it needs for the task, not the whole project. For a change in loans, the agent needs the general instructions, the loans ones, and the index.ts of the catalog and members modules. It does not need to know how the catalog stores its books.

In this mini app the saving is small, and it is worth saying so. The root AGENTS.md takes 10.3 KB, and most of it is the pieces’ sections. The module ones take between 1.8 and 2.7 KB. An agent that works on loans loads about 13 KB of instructions instead of the 16.6 KB of all four files together. The difference grows with the size of each module.

How each agent loads a module’s AGENTS.md

Whether the agent reads the AGENTS.md of a subfolder depends on the agent, and they do not all do it the same way. According to their documentation, read on October 21, 2026:

  • Claude Code reads AGENTS.md since version 2.1.277, if there is no CLAUDE.md. At the start it loads the one in the folder where it starts and the ones in the folders above. It adds a subfolder’s one when it opens a file in that subfolder with its Read tool. It reads nothing inside .agents/.
  • Codex builds its instructions once at the start, from the project root down to the folder where the session starts, and stops there. It does not document loading the ones in deeper folders. Some of the system instructions in the Codex source code ask the model to look for applicable AGENTS.md files when it works in a subfolder, but I could not confirm which ones current models use. By default it stops adding files once together they reach 32 KiB (project_doc_max_bytes).
  • Cursor, in the editor, applies the AGENTS.md files of subfolders when you work with files in that folder. The documentation of its CLI only mentions the root one.

That is why the root AGENTS.md does not rely on automatic loading and asks the agent to read the module’s one. That way it works with any of the three. I checked it in Claude Code: in one session I asked it to open only src/modules/loans/loans-service.ts with Read, and the session log shows that Claude Code added the loans AGENTS.md right after it, without the catalog or members ones. In two other sessions the agent read the files from the terminal, with cat, and then the automatic loading does not happen; but it read the module’s AGENTS.md anyway, because the root asked it to.

A subagent to work inside one module

A subagent is an agent that the main agent launches for a specific task, with its own instructions and its own context. The Subagents and delegation topic explains it. This harness brings one, module-developer, in .agents/agents/module-developer.md.

Its instructions are short: read the root and module AGENTS.md, change only files of that module, use the other modules only through their index.ts, touch nothing outside (other modules, src/shared/, app.ts, test/, or .agents/), run npm run verify, and report what is needed outside the module. It is the architecture rule applied to the agent’s work: if the task needs a new method in the catalog API, the subagent does not add it; it asks for it.

The file uses the format that Claude Code and Cursor share: Markdown with a YAML header holding name and description, and the instructions below. No agent reads it from .agents/agents/; further down I explain where to copy it for each one.

This harness has no skill of its own for the architecture, like add-endpoint in the layered harness or add-use-case in the hexagonal one. Here every change starts by choosing the module, and those steps are already in each module’s AGENTS.md. It does bring the review skill from the clean-code piece.

What the harness includes

The harness has seven parts. The security, quality, and clean-code ones are exact copies of the security piece, the quality piece, and the clean-code piece.

Part Files What it does
General instructions AGENTS.md Explains the modules, the key rule, and which commands to run.
Module instructions src/modules/catalog/AGENTS.md, src/modules/members/AGENTS.md, src/modules/loans/AGENTS.md The public API, the files, the dependencies, and the tests of each module.
Subagent .agents/agents/module-developer.md Works inside a single module and reports what it needs from outside.
Architecture .dependency-cruiser.cjs, .agents/hooks/check-architecture-before-stop.mjs The five module rules and the stop hook that checks them when the agent finishes.
Security .agents/permissions.json, .agents/hooks/block-dangerous-commands.mjs, .agents/hooks/check-secrets-before-stop.mjs, .secretlintrc.json Permission rules, a hook that blocks dangerous commands before they run, and a secret scanner when the agent finishes.
Quality .agents/hooks/format-after-edit.mjs, .agents/hooks/check-quality-before-stop.mjs, eslint.config.js, prettier.config.mjs A hook that formats each file the agent edits, and a stop hook that runs formatting, lint, types, and tests.
Clean code .agents/hooks/report-duplicates-before-stop.mjs, .agents/skills/clean-code-review/SKILL.md, .jscpd.json A stop hook that warns once about each new duplicate jscpd finds, a review skill, and seven rules in AGENTS.md.

What was reused from the hexagonal harness and what changed

Part Hexagonal harness Modular monolith harness
Endpoints and test/library.test.ts Those of the mini app contract The same; the test file is identical
How the code is split By technical role: domain, ports, use cases, adapters By part of the library: catalog, members, loans
Express routes and storage In adapters around the core Inside each module
How a loan reaches the books Through the BookRepository port Through CatalogApi, the catalog’s public API
dependency-cruiser rules Seven, about the direction of the dependencies Five, about each module’s public API and cycles
Instructions One AGENTS.md One at the root and one per module
Help for the architecture Skill add-use-case Subagent module-developer
Architecture hook check-architecture-before-stop.mjs The same script; only the message changes
Tests without HTTP 3, in test/, with the in-memory adapters The same 3, next to the loans module and without the other modules: they use fakes of their API
Security, quality, and clean-code pieces Included Copied without changes: same files, same 56 tests, and same AGENTS.md sections

The loans tests now live inside the module, in src/modules/loans/loans-service.test.ts. They do not need the real catalog or members modules: since loans can only use their public API, a small fake of CatalogApi and MembersApi is enough. The 11 acceptance tests in test/library.test.ts check the real modules together, over HTTP. I checked with cmp that the hooks, the review skill, the configurations, and the tests of the three pieces are byte-for-byte identical to those of the original pieces.

The explorer

On load, the explorer opens AGENTS.md. Hidden folders such as .agents/ are shown, because the hooks, the subagent, the permissions, and the skill live there. Dependencies and package-lock.json are not shown.

---
name: module-developer
description: Works on one module of the library API (catalog, members or loans) and changes nothing outside it. Use it for a task that stays inside one module, such as a new route or a new rule. Give it the module name and the task.
---

You work on one module of the library API: `catalog`, `members` or `loans`. The task names the module. If it names none, or more than one, stop and say so.

1. Read `AGENTS.md` at the project root and `src/modules/<module>/AGENTS.md`. Follow both.
2. Change only files inside `src/modules/<module>/`. Do not change other modules, `src/shared/`, `src/app.ts`, `test/` or the harness files in `.agents/`.
3. Use another module only through its public API, `src/modules/<other>/index.ts`. Read that file to learn what it offers. You do not need the other files of that module.
4. If the task needs a change outside the module, such as a new method in another module's public API, a new error code in `src/shared/` or a change in `src/app.ts`, do not make it. Do what you can inside the module, and report what is still needed.
5. Run `npm run verify` before you report.
6. Report in a few lines: the files you changed, the result of `npm run verify`, and any change still needed outside the module.
// Pre-tool hook: connect it to your agent's event that runs before a shell command.
// It reads the hook's JSON input from stdin, finds the shell command and checks it against a short
// list of dangerous patterns. If one matches, it prints the reason to stderr and exits with code 2,
// so the command does not run. Any other command exits with code 0 and no output.
//
// The script is not tied to one agent: it reads no agent-specific environment variable. The command
// is read from `tool_input.command` or from `command`, the two places where agents put it.
//
// This is a safety net for honest mistakes, not a sandbox. A command written in an unusual way, or a
// script that does the same thing from inside a program, gets past it.

const RULES = [
  {
    id: 'recursive-delete',
    reason: 'Recursive deletes cannot be undone.',
    matches: isRecursiveDelete,
  },
  {
    id: 'force-push',
    reason: 'A force push rewrites the history of the remote branch.',
    matches: (words) => isGit(words, 'push') && words.some(isForcePushFlag),
  },
  {
    id: 'hard-reset',
    reason: 'git reset --hard discards uncommitted changes.',
    matches: (words) => isGit(words, 'reset') && words.includes('--hard'),
  },
  {
    id: 'clean-untracked',
    reason: 'git clean -f deletes untracked files, which git cannot restore.',
    matches: (words) => isGit(words, 'clean') && words.some(isForceFlag),
  },
];

// File names that look like .env but are meant to be shared, so they hold no real secrets.
const SHARED_ENV_FILE = /\.(?:example|sample|template)$/u;
const ENV_FILE_REFERENCE = /(?:^|[\s'"=<>(:/\\])(\.env(?:\.[\w.-]+)?)(?=$|[\s'";|&)<>])/gu;

const DOWNLOADERS = new Set([
  'curl',
  'wget',
  'invoke-webrequest',
  'iwr',
  'invoke-restmethod',
  'irm',
]);
const SHELLS = new Set([
  'cmd',
  'sh',
  'bash',
  'zsh',
  'dash',
  'fish',
  'pwsh',
  'powershell',
  'iex',
  'invoke-expression',
]);

readStdin().then((text) => {
  const command = readCommand(text);
  if (command === undefined) {
    return;
  }
  const problem = findProblem(command);
  if (problem !== undefined) {
    process.stderr.write(
      [
        `Blocked by the security hook (${problem.id}): ${problem.reason}`,
        `Command: ${command}`,
        'Do not look for another way to run it. Tell the user what you wanted to do and why.',
        '',
      ].join('\n'),
    );
    process.exitCode = 2;
  }
});

// Reads stdin as a stream. readFileSync(0) would be shorter, but it does not read piped input in
// every Node runtime: in StackBlitz it did not get the input.
function readStdin() {
  return new Promise((resolve, reject) => {
    let text = '';
    process.stdin.setEncoding('utf8');
    process.stdin.on('data', (chunk) => {
      text += chunk;
    });
    process.stdin.on('end', () => resolve(text));
    process.stdin.on('error', reject);
  });
}

// Returns the shell command from the hook input, or undefined when the tool call has none.
// Input that is not JSON blocks the call: a security check that cannot read its input must not
// let the command through.
function readCommand(text) {
  let input;
  try {
    input = JSON.parse(text);
  } catch {
    process.stderr.write('Blocked by the security hook: its input was not valid JSON.\n');
    process.exitCode = 2;
    return undefined;
  }
  const candidate = input?.tool_input?.command ?? input?.command;
  if (Array.isArray(candidate)) {
    return candidate.join(' ');
  }
  return typeof candidate === 'string' && candidate.trim() !== '' ? candidate : undefined;
}

function findProblem(text) {
  const envFile = findEnvFile(text);
  if (envFile !== undefined) {
    return {
      id: 'env-file',
      reason: `${envFile} may hold secrets. The agent does not read or change .env files.`,
    };
  }
  if (pipesDownloadIntoShell(text)) {
    return {
      id: 'download-into-shell',
      reason: 'Piping a download into a shell runs code that nobody has reviewed.',
    };
  }
  for (const segment of splitCommands(text)) {
    const words = toWords(segment);
    const rule = RULES.find((candidate) => candidate.matches(words));
    if (rule !== undefined) {
      return rule;
    }
  }
  return undefined;
}

function findEnvFile(text) {
  for (const match of text.matchAll(ENV_FILE_REFERENCE)) {
    const name = match[1];
    if (!SHARED_ENV_FILE.test(name)) {
      return name;
    }
  }
  return undefined;
}

// Splits on ; && || & and new lines. Pipes stay inside a segment: each side is checked by
// pipesDownloadIntoShell, and the rules look at the words of the whole segment.
function splitCommands(text) {
  return text.split(/;|&&|\|\||&|\r?\n/u).filter((segment) => segment.trim() !== '');
}

// Lowercase words without quotes. A leading sudo, VAR=value assignments and shell wrappers such as
// `bash -lc` are dropped, so `bash -lc "rm -rf dist"` is checked as `rm -rf dist`.
function toWords(segment) {
  const words = segment
    .trim()
    .split(/\s+/u)
    .map((word) => word.replace(/^['"]|['"]$/gu, '').toLowerCase());
  for (;;) {
    if (words[0] === 'sudo' || /^[a-z_][a-z0-9_]*=/u.test(words[0] ?? '')) {
      words.shift();
    } else if (
      SHELLS.has(baseName(words[0])) &&
      /^(?:-[a-z]*c|-command|\/c)$/u.test(words[1] ?? '')
    ) {
      words.splice(0, 2);
    } else {
      return words;
    }
  }
}

function isRecursiveDelete(words) {
  const program = baseName(words[0]);
  const flags = words.slice(1);
  if (program === 'rm') {
    // Short options of rm can be grouped, as in -rf or -fr.
    return flags.some((flag) => flag === '--recursive' || /^-[dfirv]*r[dfirv]*$/u.test(flag));
  }
  if (program === 'remove-item' || program === 'ri') {
    return flags.some((flag) => /^-r(?:e(?:c(?:u(?:r(?:se?)?)?)?)?)?$/u.test(flag));
  }
  if (['rmdir', 'rd', 'del', 'erase'].includes(program)) {
    return flags.includes('/s');
  }
  return false;
}

// True when the words run `git <subcommand>`, also with options before it such as `git -C dir`.
function isGit(words, subcommand) {
  if (baseName(words[0]) !== 'git') {
    return false;
  }
  let index = 1;
  while (words[index]?.startsWith('-')) {
    // -C and -c take a value: skip it too.
    index += words[index] === '-c' ? 2 : 1;
  }
  return words[index] === subcommand;
}

function isForcePushFlag(word) {
  return word.startsWith('--force') || /^-[a-z]*f/u.test(word) || /^\+\S/u.test(word);
}

function isForceFlag(word) {
  return word === '--force' || /^-[a-z]*f/u.test(word);
}

function pipesDownloadIntoShell(text) {
  for (const segment of splitCommands(text)) {
    const programs = segment.split('|').map((part) => baseName(toWords(part)[0]));
    const download = programs.findIndex((program) => DOWNLOADERS.has(program));
    if (download !== -1 && programs.slice(download + 1).some((program) => SHELLS.has(program))) {
      return true;
    }
  }
  return false;
}

// `/usr/bin/rm` and `rm.exe` count as `rm`.
function baseName(word = '') {
  return word
    .split(/[/\\]/u)
    .pop()
    .replace(/\.exe$/u, '');
}
// Stop hook: connect it to your agent's stop event, the moment the agent is about to finish.
// It runs the architecture check (`npm run check:architecture`, dependency-cruiser). If a file
// breaks a module rule, it prints the report to stderr and exits with code 2. Agents that follow
// this convention read code 2 as "not done yet" and send the report back to the agent. Exit code 0
// with no output means every module uses the others only through their public API.
//
// The script is not tied to one agent: it reads no agent-specific input or environment variable.
// stdin (the hook's JSON input) is not read: the check does not depend on it. The check runs on
// every stop, so the only way to pass is to fix the code. Whether the agent caps how many times in
// a row it can be sent back depends on the agent that runs the hook.
//
// The tests run in the quality piece's stop hook, check-quality-before-stop.mjs, so each hook
// checks one thing. This script is the same as in the layered and hexagonal harnesses; only the
// message changes.
import { spawnSync } from 'node:child_process';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// The project root is two folders up from .agents/hooks/. Agents start hooks from different
// folders, so the script does not rely on the current directory.
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const projectDir = path.resolve(scriptDir, '..', '..');

const COMMAND = 'npm run check:architecture';
const TIMEOUT_MS = 120_000;
const MAX_OUTPUT_CHARS = 4_000;

// shell: true lets Windows run npm.cmd. The command is a fixed string, not user input.
const result = spawnSync(COMMAND, {
  cwd: projectDir,
  shell: true,
  encoding: 'utf8',
  timeout: TIMEOUT_MS,
});

if (result.status !== 0) {
  const output = [result.stdout, result.stderr, result.error?.message]
    .filter(Boolean)
    .join('\n')
    .trim();
  process.stderr.write(
    [
      'Architecture check failed. Use other modules only through their index.ts before you finish.',
      '',
      `$ ${COMMAND}`,
      tail(output),
      '',
    ].join('\n'),
  );
  process.exitCode = 2;
}

// Keeps only the end of long output, where the violations usually are.
function tail(text) {
  if (text.length <= MAX_OUTPUT_CHARS) {
    return text;
  }
  return `...(${text.length - MAX_OUTPUT_CHARS} characters cut)\n${text.slice(-MAX_OUTPUT_CHARS)}`;
}
// Stop hook: connect it to your agent's stop event, the moment the agent is about to finish.
// It runs the formatting check, the linter, the type checker and the tests. If any of them fails,
// it prints the output to stderr and exits with code 2. Agents that follow this convention read
// code 2 as "not done yet" and send the output back to the agent. Exit code 0 with no output means
// every check passed.
//
// The script is not tied to one agent: it reads no agent-specific input or environment variable.
// stdin (the hook's JSON input) is not read: the checks do not depend on it. The checks run on
// every stop, so the only way to pass is to fix the code. Whether the agent caps how many times in
// a row it can be sent back depends on the agent that runs the hook.
import { spawnSync } from 'node:child_process';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// The project root is two folders up from .agents/hooks/. Agents start hooks from different
// folders, so the script does not rely on the current directory.
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const projectDir = path.resolve(scriptDir, '..', '..');

// Every command runs even if an earlier one fails, so the agent gets every problem in one report.
// typecheck is here because Vitest runs TypeScript without checking its types: the tests can pass
// while the types are wrong.
const CHECKS = ['npm run format:check', 'npm run lint', 'npm run typecheck', 'npm test'];
const CHECK_TIMEOUT_MS = 120_000;
const MAX_OUTPUT_CHARS = 4_000;

const failures = [];
for (const command of CHECKS) {
  // shell: true lets Windows run npm.cmd. The commands are fixed strings, not user input.
  const result = spawnSync(command, {
    cwd: projectDir,
    shell: true,
    encoding: 'utf8',
    timeout: CHECK_TIMEOUT_MS,
  });
  if (result.status !== 0) {
    const output = [result.stdout, result.stderr, result.error?.message]
      .filter(Boolean)
      .join('\n')
      .trim();
    failures.push({ command, output: tail(output) });
  }
}

if (failures.length > 0) {
  const report = [
    'Quality check failed. Fix these before you finish.',
    'Run `npm run format` to fix formatting. Fix lint, type and test errors in the code, not in the checks.',
    '',
  ];
  for (const failure of failures) {
    report.push(`$ ${failure.command}`, failure.output, '');
  }
  process.stderr.write(report.join('\n'));
  process.exitCode = 2;
}

// Keeps only the end of long output, where the errors and failing assertions usually are.
function tail(text) {
  if (text.length <= MAX_OUTPUT_CHARS) {
    return text;
  }
  return `...(${text.length - MAX_OUTPUT_CHARS} characters cut)\n${text.slice(-MAX_OUTPUT_CHARS)}`;
}
// Stop hook: connect it to your agent's stop event, the moment the agent is about to finish.
// It runs the secret scanner (`npm run check:secrets`, secretlint). If it finds a secret, it prints
// the report to stderr and exits with code 2. Agents that follow this convention read code 2 as
// "not done yet" and send the report back to the agent. Exit code 0 with no output means no secret
// was found.
//
// The script is not tied to one agent: it reads no agent-specific input or environment variable.
// stdin (the hook's JSON input) is not read: the scan does not depend on it.
import { spawnSync } from 'node:child_process';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// The project root is two folders up from .agents/hooks/. Agents start hooks from different
// folders, so the script does not rely on the current directory.
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const projectDir = path.resolve(scriptDir, '..', '..');

const COMMAND = 'npm run check:secrets';
const TIMEOUT_MS = 60_000;
const MAX_OUTPUT_CHARS = 4_000;

// shell: true lets Windows run npm.cmd. The command is a fixed string, not user input.
const result = spawnSync(COMMAND, {
  cwd: projectDir,
  shell: true,
  encoding: 'utf8',
  timeout: TIMEOUT_MS,
});

if (result.status !== 0) {
  const output = [result.stdout, result.stderr, result.error?.message]
    .filter(Boolean)
    .join('\n')
    .trim();
  process.stderr.write(
    [
      'Secret check failed. Remove the secret before you finish.',
      'Read it from an environment variable instead, and keep the real value in .env, which is not committed.',
      '',
      `$ ${COMMAND}`,
      tail(output),
      '',
    ].join('\n'),
  );
  process.exitCode = 2;
}

// Keeps only the end of long output, where the findings usually are.
function tail(text) {
  if (text.length <= MAX_OUTPUT_CHARS) {
    return text;
  }
  return `...(${text.length - MAX_OUTPUT_CHARS} characters cut)\n${text.slice(-MAX_OUTPUT_CHARS)}`;
}
// Post-edit hook: connect it to your agent's event that runs after it writes or edits a file.
// It reads the hook's JSON input from stdin, finds the edited files and formats them with Prettier,
// using the project's Prettier config and .prettierignore. If Prettier cannot format a file, for
// example because of a syntax error, it prints the reason to stderr and exits with code 2, so the
// agent sees it. Everything else exits with code 0 and no output: a file outside the project, a
// file that Prettier does not know or ignores, or input without a file path.
//
// The script is not tied to one agent: it reads no agent-specific environment variable. The file
// is read from `tool_input.file_path` or from `file_path`, the two places where agents put it, or
// from the file headers of a patch in `tool_input.command`, for agents that edit with patches.
//
// Formatting here is a convenience, not a gate. Files that the agent changes from the terminal
// never reach this hook, so the stop hook checks the formatting of every file.
import { spawnSync } from 'node:child_process';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// The project root is two folders up from .agents/hooks/. Agents start hooks from different
// folders, so the script does not rely on the current directory.
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const projectDir = path.resolve(scriptDir, '..', '..');

// The hook runs Prettier's own script with node. `npx prettier` would start npm first, which adds
// time to every edit.
const PRETTIER = path.join(projectDir, 'node_modules', 'prettier', 'bin', 'prettier.cjs');
const TIMEOUT_MS = 30_000;

// A patch names each file it adds, changes or moves in a header line such as
// `*** Update File: src/app.ts`.
const PATCH_FILE_HEADER = /^\*\*\* (?:Add File|Update File|Move to): (.+)$/gmu;

readStdin().then((text) => {
  const files = readEditedFiles(text).filter((file) => isInsideProject(file) && existsSync(file));
  if (files.length > 0) {
    format(files);
  }
});

// Reads stdin as a stream. readFileSync(0) would be shorter, but it does not read piped input in
// every Node runtime: in StackBlitz it did not get the input.
function readStdin() {
  return new Promise((resolve, reject) => {
    let text = '';
    process.stdin.setEncoding('utf8');
    process.stdin.on('data', (chunk) => {
      text += chunk;
    });
    process.stdin.on('end', () => resolve(text));
    process.stdin.on('error', reject);
  });
}

// Returns the absolute paths of the edited files, or an empty list when the input has none. Input
// that is not JSON does nothing: a formatter must not get in the agent's way.
function readEditedFiles(text) {
  let input;
  try {
    input = JSON.parse(text);
  } catch {
    return [];
  }
  const base = typeof input?.cwd === 'string' ? input.cwd : projectDir;
  return namedFiles(input)
    .map((name) => name.trim())
    .filter((name) => name !== '')
    .map((name) => path.resolve(base, name));
}

function namedFiles(input) {
  const filePath = input?.tool_input?.file_path ?? input?.file_path;
  if (typeof filePath === 'string') {
    return [filePath];
  }
  const command = input?.tool_input?.command;
  if (typeof command === 'string') {
    return [...command.matchAll(PATCH_FILE_HEADER)].map((match) => match[1]);
  }
  return [];
}

// The hook only touches files inside its own project.
function isInsideProject(file) {
  const relative = path.relative(projectDir, file);
  return relative !== '' && !path.isAbsolute(relative) && relative.split(path.sep)[0] !== '..';
}

function format(files) {
  if (!existsSync(PRETTIER)) {
    report('Prettier is not installed. Run `npm install` in the project.');
    return;
  }
  // --ignore-unknown skips files that Prettier cannot format, such as images.
  const result = spawnSync(
    process.execPath,
    [PRETTIER, '--write', '--ignore-unknown', '--log-level', 'warn', '--no-color', ...files],
    { cwd: projectDir, encoding: 'utf8', timeout: TIMEOUT_MS },
  );
  if (result.status !== 0) {
    const output = [result.stdout, result.stderr, result.error?.message]
      .filter(Boolean)
      .join('\n')
      .trim();
    report(output);
  }
}

function report(output) {
  process.stderr.write(
    ['Formatting failed. The edit was saved, but Prettier could not format it.', output, ''].join(
      '\n',
    ),
  );
  process.exitCode = 2;
}
// Stop hook: connect it to your agent's stop event, the moment the agent is about to finish.
// It runs jscpd on the folders named in the `check:duplicates` script and reports the duplicated
// blocks it has not reported before. Duplicated code is sometimes the right choice, so this is a
// warning, not a gate: each duplicate is reported once. The first time, the hook prints the list to
// stderr and exits with code 2, which agents that follow this convention read as "not done yet". If
// the agent decides to keep a duplicate and tries to finish again, the hook lets it. Exit code 0
// with no output means there is nothing new to report.
//
// The script is not tied to one agent: it reads no agent-specific input or environment variable.
// stdin (the hook's JSON input) is not read: the check does not depend on it.
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

// The project root is two folders up from .agents/hooks/. Agents start hooks from different
// folders, so the script does not rely on the current directory.
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const projectDir = path.resolve(scriptDir, '..', '..');

// node_modules/.cache/ is where Node tools usually keep their caches, and git already ignores it.
// The JSON report and the list of reported duplicates live there, out of the agent's way.
const CACHE_DIR = 'node_modules/.cache/report-duplicates';
const REPORT_FILE = path.join(projectDir, CACHE_DIR, 'jscpd-report.json');
const REPORTED_FILE = path.join(projectDir, CACHE_DIR, 'reported.json');
const JSCPD = path.join(projectDir, 'node_modules', 'jscpd', 'bin', 'jscpd');
const CHECK_TIMEOUT_MS = 60_000;
const MAX_LISTED = 10;

const problem = runJscpd();
if (problem !== null) {
  // A check that cannot run must not pass in silence. The usual cause is a missing install or a
  // folder in check:duplicates that does not exist.
  process.stderr.write(
    `Could not run the duplicate check (\`npm run check:duplicates\`).\n${problem}\n` +
      'Fix the setup, or tell the user if you cannot.\n',
  );
  process.exitCode = 2;
} else {
  const duplicates = readDuplicates();
  const reported = readReported();
  const fresh = duplicates.filter((duplicate) => !reported.has(duplicate.id));
  // Only the duplicates that still exist are remembered. If one is removed and comes back later, it
  // is reported again.
  writeReported(duplicates.map((duplicate) => duplicate.id));
  if (fresh.length > 0) {
    process.stderr.write(warning(fresh));
    process.exitCode = 2;
  }
}

// The folders come from the check:duplicates script in package.json (for example `jscpd src`), so
// the hook and the command a person runs always scan the same code. The hook starts jscpd with node
// instead of npm, which added about 0.7 seconds to every run. Returns null when the report is ready,
// or the reason it is not.
function runJscpd() {
  const [command, ...args] = readCheckDuplicatesScript();
  if (command !== 'jscpd') {
    return 'The check:duplicates script in package.json must run jscpd, for example `jscpd src`.';
  }
  rmSync(REPORT_FILE, { force: true });
  const reportArgs = ['--silent', '--reporters', 'json', '--output', CACHE_DIR];
  const result = spawnSync(process.execPath, [JSCPD, ...args, ...reportArgs], {
    cwd: projectDir,
    encoding: 'utf8',
    timeout: CHECK_TIMEOUT_MS,
  });
  if (result.status === 0 && existsSync(REPORT_FILE)) {
    return null;
  }
  return [result.stdout, result.stderr, result.error?.message].filter(Boolean).join('\n').trim();
}

function readCheckDuplicatesScript() {
  try {
    const packageJson = JSON.parse(readFileSync(path.join(projectDir, 'package.json'), 'utf8'));
    return String(packageJson.scripts?.['check:duplicates'] ?? '')
      .trim()
      .split(/\s+/);
  } catch {
    return [];
  }
}

// Each duplicate gets an id from its two files and its code, not its line numbers, so an edit
// above it does not make it new.
function readDuplicates() {
  const report = JSON.parse(readFileSync(REPORT_FILE, 'utf8'));
  return report.duplicates.map((duplicate) => {
    const first = location(duplicate.firstFile);
    const second = location(duplicate.secondFile);
    const files = [first.file, second.file].sort().join('\n');
    const id = createHash('sha256').update(`${files}\n${duplicate.fragment}`).digest('hex');
    return { id, first, second, lines: duplicate.lines };
  });
}

// jscpd writes paths with the separator of the operating system. The agent gets forward slashes.
function location(file) {
  return { file: file.name.replaceAll('\\', '/'), start: file.start, end: file.end };
}

function readReported() {
  try {
    return new Set(JSON.parse(readFileSync(REPORTED_FILE, 'utf8')));
  } catch {
    return new Set();
  }
}

function writeReported(ids) {
  mkdirSync(path.dirname(REPORTED_FILE), { recursive: true });
  writeFileSync(REPORTED_FILE, `${JSON.stringify(ids, null, 2)}\n`);
}

function warning(fresh) {
  const lines = [
    'Duplicated code: a warning, not a failure. jscpd found the same code in more than one place:',
    '',
  ];
  for (const { first, second, lines: count } of fresh.slice(0, MAX_LISTED)) {
    lines.push(
      `- ${first.file}:${first.start}-${first.end} and ${second.file}:${second.start}-${second.end} (${count} lines)`,
    );
  }
  if (fresh.length > MAX_LISTED) {
    lines.push(`- and ${fresh.length - MAX_LISTED} more. Run \`npm run check:duplicates\`.`);
  }
  lines.push(
    '',
    'Look at each one before you finish:',
    '- If both copies hold the same rule and would change together, move it into one function and call it from both places.',
    '- If they only look alike, or a shared function would need a flag or extra parameters to tell its callers apart, keep the copies.',
    'Tell the user which duplicates you kept and why. Each duplicate is reported once: when you try to finish again, this hook lets you.',
    '',
  );
  return lines.join('\n');
}
---
name: clean-code-review
description: Review your own changes for duplicated code, names and responsibilities before you say a task is done. Use at the end of any task that added or changed code, or when the user asks for a clean-code review.
---

# Clean-code review

Review only the code this task changed. List it with `git status` and `git diff`. Change only what is clearly better: a review that adds layers, helpers or defensive code that nobody asked for makes the code worse.

1. **Duplicates.** Run `npm run check:duplicates`. jscpd only finds copies with the same tokens, so it misses the same logic written with other names. For each function you added, search the code for its main domain word (for example, `grep -rn "loan" src`) and read what is already there. For each duplicate, extract a shared function only if both copies hold the same rule and would change together. If they only look alike, or a shared function would need a flag or extra parameters to tell its callers apart, keep the copies.
2. **Names.** Each new file, function and variable says what it is or does, with the words of the domain (book, member, loan). Rename vague names such as `data`, `info`, `item`, `handle`, `process`, `utils` or `temp`. A boolean reads as a question: `isAvailable`, `hasActiveLoans`.
3. **Responsibilities.** Each new function does one thing. If you need "and" to describe it, split it. Keep each part in the folder where the project's `AGENTS.md` says it goes.
4. **Scope.** Remove what the task did not ask for: unused parameters and options, abstractions written for a future need, commented-out code, and changes to files the task did not need.
5. **Verify.** If you changed anything, run `npm run verify` again.
6. **Report.** Tell the user in a few lines what this review changed, and which duplicates you kept and why.
{
  "description": "Permission rules for the agent. No agent reads this file on its own: copy the rules into the permission settings of the agent you use. deny: the agent never reads these files. ask: the agent asks you before running these commands.",
  "deny": {
    "read": [".env", ".env.*"]
  },
  "ask": {
    "commands": ["git push", "npm install", "npm i", "npm add"]
  }
}
# Catalog module

Owns the books of the library: adding, listing and finding them, and whether each one is available. The root `AGENTS.md` applies here too.

## Public API

`index.ts` is the only file that other modules and `src/app.ts` import. It exports:

- `Book`: the book type.
- `CatalogApi`: what other modules may ask the catalog. `getBook(id)` returns the book or throws `BOOK_NOT_FOUND`. `setBookAvailable(id, available)` marks a book as loaned or returned. The loans module uses both.
- `createCatalogModule()`: builds the module with empty data. Only `src/app.ts` calls it.

Other modules rely on `CatalogApi`. Do not change or remove a method that a module uses, and add a method only when another module needs it.

## Files

| File                 | What it does                                                                   |
| -------------------- | ------------------------------------------------------------------------------ |
| `book.ts`            | The `Book` type                                                                |
| `book-repository.ts` | In-memory storage of books                                                     |
| `catalog-service.ts` | Every catalog operation. The routes use all of them; `CatalogApi` only a part. |
| `catalog-routes.ts`  | `GET /books`, `POST /books` and `GET /books/:id`                               |
| `index.ts`           | The public API                                                                 |

## Dependencies

- May import its own files, `src/shared/` and npm packages.
- Uses no other module. Keep it that way: the loans module already uses the catalog, so importing loans here would create a cycle.

## Tests

The acceptance tests in `test/library.test.ts` cover the catalog routes. Put new tests for this module next to its code, as `<file>.test.ts`.
import type { Book } from './book';

// Keeps books in memory. Only the catalog module uses it: other modules reach the books through
// the public API in index.ts. Reads return copies, so a caller cannot change stored data by
// accident.
export class BookRepository {
  private readonly books: Book[] = [];
  private lastId = 0;

  create(fields: { title: string; author: string }): Book {
    const book: Book = { id: String(++this.lastId), ...fields, available: true };
    this.books.push(book);
    return { ...book };
  }

  findById(id: string): Book | undefined {
    const book = this.books.find((item) => item.id === id);
    return book && { ...book };
  }

  findAll(): Book[] {
    return this.books.map((book) => ({ ...book }));
  }

  // Does nothing for an unknown id. Callers check that the book exists before calling this.
  setAvailable(id: string, available: boolean): void {
    const book = this.books.find((item) => item.id === id);
    if (book) {
      book.available = available;
    }
  }
}
export interface Book {
  id: string;
  title: string;
  author: string;
  available: boolean; // false while the book has an active loan
}
import { Router } from 'express';
import { AppError } from '../../shared/app-error';
import { handleError, readInput, readText } from '../../shared/http';
import type { CatalogService } from './catalog-service';

// The HTTP routes of the catalog module. src/app.ts mounts them through index.ts.
export function createCatalogRouter(catalog: CatalogService): Router {
  const router = Router();

  router.get('/books', (_req, res) => {
    res.json(catalog.listBooks());
  });

  router.post('/books', (req, res, next) => {
    try {
      const input = readInput(req);
      const title = readText(input.title);
      const author = readText(input.author);
      if (title === null || author === null) {
        throw new AppError('INVALID_INPUT', 'Title and author are required.');
      }
      res.status(201).json(catalog.addBook(title, author));
    } catch (error) {
      handleError(error, res, next);
    }
  });

  router.get('/books/:id', (req, res, next) => {
    try {
      res.json(catalog.getBook(req.params.id));
    } catch (error) {
      handleError(error, res, next);
    }
  });

  return router;
}
import { AppError } from '../../shared/app-error';
import type { Book } from './book';
import type { BookRepository } from './book-repository';

// Every catalog operation. The routes use all of them; index.ts publishes only the ones that
// other modules need.
export class CatalogService {
  constructor(private readonly books: BookRepository) {}

  addBook(title: string, author: string): Book {
    return this.books.create({ title, author });
  }

  listBooks(): Book[] {
    return this.books.findAll();
  }

  getBook(id: string): Book {
    const book = this.books.findById(id);
    if (!book) {
      throw new AppError('BOOK_NOT_FOUND', `Book ${id} does not exist.`);
    }
    return book;
  }

  setBookAvailable(id: string, available: boolean): void {
    this.books.setAvailable(id, available);
  }
}
import type { Router } from 'express';
import type { Book } from './book';
import { BookRepository } from './book-repository';
import { createCatalogRouter } from './catalog-routes';
import { CatalogService } from './catalog-service';

// Public API of the catalog module: the only file that other modules and src/app.ts may import.
// The other files in this folder are internal, so they can change without breaking other modules.
export type { Book };

// What other modules may ask the catalog. Every method here is a promise to the modules that use
// it, so add one only when another module needs it.
export interface CatalogApi {
  getBook(id: string): Book; // throws BOOK_NOT_FOUND
  setBookAvailable(id: string, available: boolean): void;
}

export interface CatalogModule {
  api: CatalogApi;
  router: Router;
}

// Builds the module with empty data.
export function createCatalogModule(): CatalogModule {
  const catalog = new CatalogService(new BookRepository());
  return { api: catalog, router: createCatalogRouter(catalog) };
}
# Loans module

Owns the loans: lending a book, returning it and listing loans. It holds the two business rules of the library. The root `AGENTS.md` applies here too.

## Business rules

`loans-service.ts` checks a new loan in this order. The first failing check wins, and the order is part of the contract that every template shares.

1. The book exists, through `CatalogApi.getBook`, which throws `BOOK_NOT_FOUND`.
2. The member exists, through `MembersApi.getMember`, which throws `MEMBER_NOT_FOUND`.
3. The book is available, or `BOOK_ALREADY_LOANED`.
4. The member has fewer than 3 active loans, or `LOAN_LIMIT_REACHED`.

Lending a book marks it as unavailable with `CatalogApi.setBookAvailable`, and returning the loan marks it as available again. Books and members belong to their modules: a loan keeps only their IDs.

## Public API

`index.ts` is the only file that `src/app.ts` imports. No other module uses loans. It exports `LoansDependencies`, the public API of the modules that loans uses, and `createLoansModule()`, which builds the module with empty data.

## Files

| File                    | What it does                                                                           |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `loan.ts`               | The `Loan` type                                                                        |
| `loan-repository.ts`    | In-memory storage of loans                                                             |
| `loans-service.ts`      | The loan rules                                                                         |
| `loans-service.test.ts` | Tests of the loan rules without HTTP, with fakes of the catalog and members public API |
| `loans-routes.ts`       | `GET /loans`, `POST /loans` and `POST /loans/:id/return`                               |
| `index.ts`              | The public API                                                                         |

## Dependencies

- May import its own files, `src/shared/`, npm packages, and the `index.ts` of `catalog` and `members`.
- To learn what the catalog and members modules offer, read their `index.ts`. You do not need their other files.
- If loans needs something that their `index.ts` does not offer, the change belongs in that module: add a method to its API interface and implement it there, following that module's `AGENTS.md`.

## Tests

`loans-service.test.ts` runs the loan rules on their own, with small fakes of `CatalogApi` and `MembersApi`. Add the tests for a new rule there. When `CatalogApi` or `MembersApi` gains a method, TypeScript fails until you add it to the fake too.
import type { Router } from 'express';
import type { CatalogApi } from '../catalog';
import type { MembersApi } from '../members';
import { LoanRepository } from './loan-repository';
import { createLoansRouter } from './loans-routes';
import { LoansService } from './loans-service';

// Public API of the loans module: the only file that other modules and src/app.ts may import.
// No other module uses loans, so it publishes only what src/app.ts needs to build it.

// The public API of the modules that loans uses. src/app.ts passes them in.
export interface LoansDependencies {
  catalog: CatalogApi;
  members: MembersApi;
}

export interface LoansModule {
  router: Router;
}

// Builds the module with empty data.
export function createLoansModule(dependencies: LoansDependencies): LoansModule {
  const loans = new LoansService(new LoanRepository(), dependencies.catalog, dependencies.members);
  return { router: createLoansRouter(loans) };
}
import type { Loan } from './loan';

// Keeps loans in memory. Only the loans module uses it. Reads return copies, like the book
// repository in the catalog module.
export class LoanRepository {
  private readonly loans: Loan[] = [];
  private lastId = 0;

  create(fields: { bookId: string; memberId: string; loanedAt: string }): Loan {
    const loan: Loan = { id: String(++this.lastId), ...fields, returnedAt: null };
    this.loans.push(loan);
    return { ...loan };
  }

  findById(id: string): Loan | undefined {
    const loan = this.loans.find((item) => item.id === id);
    return loan && { ...loan };
  }

  findAll(): Loan[] {
    return this.loans.map((loan) => ({ ...loan }));
  }

  findActiveByMember(memberId: string): Loan[] {
    return this.loans
      .filter((loan) => loan.memberId === memberId && loan.returnedAt === null)
      .map((loan) => ({ ...loan }));
  }

  // Does nothing for an unknown id. The service checks that the loan exists before calling this.
  setReturnedAt(id: string, returnedAt: string): void {
    const loan = this.loans.find((item) => item.id === id);
    if (loan) {
      loan.returnedAt = returnedAt;
    }
  }
}
export interface Loan {
  id: string;
  bookId: string;
  memberId: string;
  loanedAt: string; // ISO 8601
  returnedAt: string | null; // null while the loan is active
}
import { Router } from 'express';
import { AppError } from '../../shared/app-error';
import { handleError, readInput, readText } from '../../shared/http';
import type { LoansService } from './loans-service';

// The HTTP routes of the loans module. src/app.ts mounts them through index.ts.
export function createLoansRouter(loans: LoansService): Router {
  const router = Router();

  router.get('/loans', (_req, res) => {
    res.json(loans.listLoans());
  });

  router.post('/loans', (req, res, next) => {
    try {
      const input = readInput(req);
      const bookId = readText(input.bookId);
      const memberId = readText(input.memberId);
      if (bookId === null || memberId === null) {
        throw new AppError('INVALID_INPUT', 'bookId and memberId are required.');
      }
      res.status(201).json(loans.lendBook(bookId, memberId));
    } catch (error) {
      handleError(error, res, next);
    }
  });

  router.post('/loans/:id/return', (req, res, next) => {
    try {
      res.json(loans.returnLoan(req.params.id));
    } catch (error) {
      handleError(error, res, next);
    }
  });

  return router;
}
import { describe, expect, it } from 'vitest';
import { AppError } from '../../shared/app-error';
import type { Book, CatalogApi } from '../catalog';
import type { MembersApi } from '../members';
import { LoanRepository } from './loan-repository';
import { LoansService } from './loans-service';

// These tests run the loans module on its own: no HTTP and no other module. Loans may only use the
// public API of the catalog and members modules, so a small fake of that API is all they need.
// test/library.test.ts checks the real modules together, over HTTP.

function createFakeCatalog(titles: string[]): CatalogApi {
  const books: Book[] = titles.map((title, index) => ({
    id: `book-${index + 1}`,
    title,
    author: 'Author',
    available: true,
  }));
  return {
    getBook(id) {
      const book = books.find((item) => item.id === id);
      if (!book) {
        throw new AppError('BOOK_NOT_FOUND', `Book ${id} does not exist.`);
      }
      return { ...book };
    },
    setBookAvailable(id, available) {
      const book = books.find((item) => item.id === id);
      if (book) {
        book.available = available;
      }
    },
  };
}

// Every member exists. The acceptance tests check MEMBER_NOT_FOUND.
const members: MembersApi = {
  getMember: (id) => ({ id, name: `Member ${id}` }),
};

// Returns the error code thrown by fn, or undefined when fn does not throw an AppError.
function errorCodeOf(fn: () => unknown): string | undefined {
  try {
    fn();
  } catch (error) {
    return error instanceof AppError ? error.code : undefined;
  }
  return undefined;
}

describe('LoansService', () => {
  it('marks a lent book as unavailable in the catalog', () => {
    const catalog = createFakeCatalog(['Dune']);
    const loans = new LoansService(new LoanRepository(), catalog, members);

    const loan = loans.lendBook('book-1', 'ana');

    expect(loan).toMatchObject({ bookId: 'book-1', memberId: 'ana', returnedAt: null });
    expect(catalog.getBook('book-1').available).toBe(false);
  });

  it('throws BOOK_ALREADY_LOANED when the book has an active loan', () => {
    const loans = new LoansService(new LoanRepository(), createFakeCatalog(['Dune']), members);
    loans.lendBook('book-1', 'ana');

    expect(errorCodeOf(() => loans.lendBook('book-1', 'luis'))).toBe('BOOK_ALREADY_LOANED');
  });

  it('refuses a fourth active loan and leaves the book available', () => {
    const catalog = createFakeCatalog(['Dune', 'Emma', 'Ulysses', 'Beloved']);
    const loans = new LoansService(new LoanRepository(), catalog, members);
    for (const bookId of ['book-1', 'book-2', 'book-3']) {
      loans.lendBook(bookId, 'ana');
    }

    expect(errorCodeOf(() => loans.lendBook('book-4', 'ana'))).toBe('LOAN_LIMIT_REACHED');
    expect(catalog.getBook('book-4').available).toBe(true);
  });
});
import { AppError } from '../../shared/app-error';
import type { CatalogApi } from '../catalog';
import type { MembersApi } from '../members';
import type { Loan } from './loan';
import type { LoanRepository } from './loan-repository';

const MAX_ACTIVE_LOANS = 3;

// The loan rules. Books belong to the catalog module and members to the members module, so this
// service reaches them only through their public API. The order of the checks is part of the
// contract: the first failing check wins.
export class LoansService {
  constructor(
    private readonly loans: LoanRepository,
    private readonly catalog: CatalogApi,
    private readonly members: MembersApi,
  ) {}

  lendBook(bookId: string, memberId: string): Loan {
    const book = this.catalog.getBook(bookId);
    const member = this.members.getMember(memberId);
    if (!book.available) {
      throw new AppError('BOOK_ALREADY_LOANED', `Book ${bookId} is already loaned.`);
    }
    if (this.loans.findActiveByMember(member.id).length >= MAX_ACTIVE_LOANS) {
      throw new AppError(
        'LOAN_LIMIT_REACHED',
        `Member ${memberId} has ${MAX_ACTIVE_LOANS} active loans.`,
      );
    }

    const loan = this.loans.create({
      bookId: book.id,
      memberId: member.id,
      loanedAt: new Date().toISOString(),
    });
    this.catalog.setBookAvailable(book.id, false);
    return loan;
  }

  returnLoan(loanId: string): Loan {
    const loan = this.loans.findById(loanId);
    if (!loan) {
      throw new AppError('LOAN_NOT_FOUND', `Loan ${loanId} does not exist.`);
    }
    if (loan.returnedAt !== null) {
      throw new AppError('LOAN_ALREADY_RETURNED', `Loan ${loan.id} was already returned.`);
    }

    const returnedAt = new Date().toISOString();
    this.loans.setReturnedAt(loan.id, returnedAt);
    this.catalog.setBookAvailable(loan.bookId, true);
    return { ...loan, returnedAt };
  }

  listLoans(): Loan[] {
    return this.loans.findAll();
  }
}
# Members module

Owns the members of the library: adding, listing and finding them. The root `AGENTS.md` applies here too.

## Public API

`index.ts` is the only file that other modules and `src/app.ts` import. It exports:

- `Member`: the member type.
- `MembersApi`: what other modules may ask this module. `getMember(id)` returns the member or throws `MEMBER_NOT_FOUND`. The loans module uses it.
- `createMembersModule()`: builds the module with empty data. Only `src/app.ts` calls it.

Other modules rely on `MembersApi`. Do not change or remove a method that a module uses, and add a method only when another module needs it.

## Files

| File                   | What it does                                                                   |
| ---------------------- | ------------------------------------------------------------------------------ |
| `member.ts`            | The `Member` type                                                              |
| `member-repository.ts` | In-memory storage of members                                                   |
| `members-service.ts`   | Every members operation. The routes use all of them; `MembersApi` only a part. |
| `members-routes.ts`    | `GET /members` and `POST /members`                                             |
| `index.ts`             | The public API                                                                 |

## Dependencies

- May import its own files, `src/shared/` and npm packages.
- Uses no other module. Keep it that way: the loans module already uses this module, so importing loans here would create a cycle.

## Tests

The acceptance tests in `test/library.test.ts` cover the members routes. Put new tests for this module next to its code, as `<file>.test.ts`.
import type { Router } from 'express';
import type { Member } from './member';
import { MemberRepository } from './member-repository';
import { createMembersRouter } from './members-routes';
import { MembersService } from './members-service';

// Public API of the members module: the only file that other modules and src/app.ts may import.
// The other files in this folder are internal, so they can change without breaking other modules.
export type { Member };

// What other modules may ask the members module. Every method here is a promise to the modules
// that use it, so add one only when another module needs it.
export interface MembersApi {
  getMember(id: string): Member; // throws MEMBER_NOT_FOUND
}

export interface MembersModule {
  api: MembersApi;
  router: Router;
}

// Builds the module with empty data.
export function createMembersModule(): MembersModule {
  const members = new MembersService(new MemberRepository());
  return { api: members, router: createMembersRouter(members) };
}
import type { Member } from './member';

// Keeps members in memory. Only the members module uses it. Reads return copies, like the book
// repository in the catalog module.
export class MemberRepository {
  private readonly members: Member[] = [];
  private lastId = 0;

  create(fields: { name: string }): Member {
    const member: Member = { id: String(++this.lastId), ...fields };
    this.members.push(member);
    return { ...member };
  }

  findById(id: string): Member | undefined {
    const member = this.members.find((item) => item.id === id);
    return member && { ...member };
  }

  findAll(): Member[] {
    return this.members.map((member) => ({ ...member }));
  }
}
export interface Member {
  id: string;
  name: string;
}
import { Router } from 'express';
import { AppError } from '../../shared/app-error';
import { handleError, readInput, readText } from '../../shared/http';
import type { MembersService } from './members-service';

// The HTTP routes of the members module. src/app.ts mounts them through index.ts.
export function createMembersRouter(members: MembersService): Router {
  const router = Router();

  router.get('/members', (_req, res) => {
    res.json(members.listMembers());
  });

  router.post('/members', (req, res, next) => {
    try {
      const name = readText(readInput(req).name);
      if (name === null) {
        throw new AppError('INVALID_INPUT', 'Name is required.');
      }
      res.status(201).json(members.addMember(name));
    } catch (error) {
      handleError(error, res, next);
    }
  });

  return router;
}
import { AppError } from '../../shared/app-error';
import type { Member } from './member';
import type { MemberRepository } from './member-repository';

// Every members operation. The routes use all of them; index.ts publishes only the ones that
// other modules need.
export class MembersService {
  constructor(private readonly members: MemberRepository) {}

  addMember(name: string): Member {
    return this.members.create({ name });
  }

  listMembers(): Member[] {
    return this.members.findAll();
  }

  getMember(id: string): Member {
    const member = this.members.findById(id);
    if (!member) {
      throw new AppError('MEMBER_NOT_FOUND', `Member ${id} does not exist.`);
    }
    return member;
  }
}
// Errors raised by the modules. They carry a code, never an HTTP status: src/shared/http.ts maps
// each code to a status. Every module uses this file, so it imports nothing.

export type ErrorCode =
  | 'INVALID_INPUT'
  | 'BOOK_NOT_FOUND'
  | 'MEMBER_NOT_FOUND'
  | 'LOAN_NOT_FOUND'
  | 'BOOK_ALREADY_LOANED'
  | 'LOAN_LIMIT_REACHED'
  | 'LOAN_ALREADY_RETURNED';

export class AppError extends Error {
  readonly code: ErrorCode;

  constructor(code: ErrorCode, message: string) {
    super(message);
    this.name = 'AppError';
    this.code = code;
  }
}
import type { NextFunction, Request, Response } from 'express';
import { AppError, type ErrorCode } from './app-error';

// HTTP helpers that the routes of every module use. The only place where error codes become HTTP
// statuses.
const STATUS_BY_CODE: Record<ErrorCode, number> = {
  INVALID_INPUT: 400,
  BOOK_NOT_FOUND: 404,
  MEMBER_NOT_FOUND: 404,
  LOAN_NOT_FOUND: 404,
  BOOK_ALREADY_LOANED: 409,
  LOAN_LIMIT_REACHED: 409,
  LOAN_ALREADY_RETURNED: 409,
};

export function sendError(res: Response, status: number, code: string, message: string): void {
  res.status(status).json({ error: { code, message } });
}

// Answers an AppError with its mapped status. Any other error goes to the error middleware.
export function handleError(error: unknown, res: Response, next: NextFunction): void {
  if (error instanceof AppError) {
    sendError(res, STATUS_BY_CODE[error.code], error.code, error.message);
    return;
  }
  next(error);
}

export function readInput(req: Request): Record<string, unknown> {
  const body: unknown = req.body;
  return isRecord(body) ? body : {};
}

// Returns the trimmed text, or null when the value is not a string or is blank.
export function readText(value: unknown): string | null {
  if (typeof value !== 'string') {
    return null;
  }
  const text = value.trim();
  return text === '' ? null : text;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}
import express, { type Express, type NextFunction, type Request, type Response } from 'express';
import { createCatalogModule } from './modules/catalog';
import { createLoansModule } from './modules/loans';
import { createMembersModule } from './modules/members';
import { sendError } from './shared/http';

// Composition root: builds each module through its public API (its index.ts) and hands loans the
// public API of the modules it uses. It builds new modules on each call, so each app starts with
// empty data and tests do not share state.
export function createApp(): Express {
  const catalog = createCatalogModule();
  const members = createMembersModule();
  const loans = createLoansModule({ catalog: catalog.api, members: members.api });

  const app = express();
  app.use(express.json());
  app.use(catalog.router);
  app.use(members.router);
  app.use(loans.router);

  app.use((_req, res) => {
    sendError(res, 404, 'NOT_FOUND', 'Route not found.');
  });

  app.use((err: unknown, _req: Request, res: Response, next: NextFunction) => {
    if (res.headersSent) {
      next(err);
      return;
    }
    if (isMalformedJson(err)) {
      sendError(res, 400, 'INVALID_INPUT', 'Request body must be valid JSON.');
      return;
    }
    console.error(err);
    sendError(res, 500, 'INTERNAL_ERROR', 'Unexpected server error.');
  });

  return app;
}

function isMalformedJson(err: unknown): boolean {
  return err instanceof Error && 'type' in err && err.type === 'entity.parse.failed';
}
import { createApp } from './app';

const port = Number(process.env.PORT ?? 3000);

createApp().listen(port, () => {
  console.log(`Library API listening on http://localhost:${port}`);
});
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, expect, it } from 'vitest';

// These tests run the hook the way an agent does: JSON on stdin, then read the exit code and stderr.

const hook = fileURLToPath(
  new URL('../.agents/hooks/block-dangerous-commands.mjs', import.meta.url),
);

interface HookResult {
  code: number | null;
  stderr: string;
  stdout: string;
}

// spawn writes stdin as a stream, which works in every runtime the template runs in, StackBlitz too.
function runHook(input: string): Promise<HookResult> {
  return new Promise((resolve, reject) => {
    const child = spawn(process.execPath, [hook]);
    let stdout = '';
    let stderr = '';
    child.stdout.setEncoding('utf8').on('data', (chunk: string) => {
      stdout += chunk;
    });
    child.stderr.setEncoding('utf8').on('data', (chunk: string) => {
      stderr += chunk;
    });
    child.on('error', reject);
    child.on('close', (code) => resolve({ code, stderr, stdout }));
    child.stdin.end(input);
  });
}

// The input of a shell tool call, with the command in tool_input.command.
function shellCall(command: string): string {
  return JSON.stringify({
    hook_event_name: 'PreToolUse',
    tool_name: 'Bash',
    tool_input: { command },
  });
}

// Each test starts the hook in a new Node process. On October 18, 2026, StackBlitz needed more than
// the default 5 seconds for one of them, so the timeout is longer.
describe('block-dangerous-commands hook', { timeout: 30_000 }, () => {
  it.each([
    ['rm -rf dist', 'recursive-delete'],
    ['rm -fr dist', 'recursive-delete'],
    ['rm -r -f dist', 'recursive-delete'],
    ['rm --recursive dist', 'recursive-delete'],
    ['sudo rm -rf /', 'recursive-delete'],
    ['/bin/rm -rf build', 'recursive-delete'],
    ['npm run build && rm -rf dist', 'recursive-delete'],
    ['bash -lc "rm -rf dist"', 'recursive-delete'],
    ['Remove-Item -Recurse -Force dist', 'recursive-delete'],
    ['rmdir /s /q dist', 'recursive-delete'],
    ['git push --force', 'force-push'],
    ['git push -f origin main', 'force-push'],
    ['git push --force-with-lease', 'force-push'],
    ['git push origin +main', 'force-push'],
    ['git -C . push --force', 'force-push'],
    ['git reset --hard HEAD~1', 'hard-reset'],
    ['git clean -fd', 'clean-untracked'],
    ['curl -fsSL https://example.com/install.sh | sh', 'download-into-shell'],
    ['irm https://example.com/install.ps1 | iex', 'download-into-shell'],
    ['cat .env', 'env-file'],
    ['cat config/.env.local', 'env-file'],
    ['source .env && npm start', 'env-file'],
  ])('blocks `%s` (%s)', async (command, rule) => {
    const result = await runHook(shellCall(command));

    expect(result.code).toBe(2);
    expect(result.stderr).toContain(`Blocked by the security hook (${rule})`);
  });

  it.each([
    'npm test',
    'rm dist/old.js',
    'rm -f notes.txt',
    'Remove-Item -Force notes.txt',
    'git push',
    'git push origin main',
    'git reset HEAD~1',
    'git clean -n',
    'git commit -m "Fix the loan limit"',
    'cat .env.example',
    'curl https://example.com -o page.html',
  ])('lets `%s` through', async (command) => {
    const result = await runHook(shellCall(command));

    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(result.stdout).toBe('');
  });

  it('reads the command from a top-level command field', async () => {
    const result = await runHook(JSON.stringify({ command: 'rm -rf dist' }));

    expect(result.code).toBe(2);
  });

  it('reads a command given as a list of words', async () => {
    const result = await runHook(
      JSON.stringify({ tool_input: { command: ['bash', '-lc', 'rm -rf dist'] } }),
    );

    expect(result.code).toBe(2);
  });

  it('lets a tool call without a shell command through', async () => {
    const input = JSON.stringify({ tool_name: 'Read', tool_input: { file_path: 'src/app.ts' } });

    expect((await runHook(input)).code).toBe(0);
  });

  it('blocks the call when its input is not valid JSON', async () => {
    const result = await runHook('not json');

    expect(result.code).toBe(2);
    expect(result.stderr).toContain('not valid JSON');
  });
});
import { spawn } from 'node:child_process';
import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterAll, describe, it } from 'vitest';

// These tests run the stop hook the way an agent does. The hook runs `npm test`, so running it on
// this project from a test would start these tests again. Instead, each test copies the hook into a
// small fake project, in the system's temporary folder, whose checks pass or fail on demand. The
// folders are deleted at the end.

const hook = fileURLToPath(
  new URL('../.agents/hooks/check-quality-before-stop.mjs', import.meta.url),
);
const projectDirs: string[] = [];

const CHECK_NAMES = ['format:check', 'lint', 'typecheck', 'test'];

// Each fake check writes its name to ran.txt and fails if its name is in failing.json.
const CHECK_SCRIPT = `import { appendFileSync, readFileSync } from 'node:fs';
const name = process.argv[2];
appendFileSync('ran.txt', name + '\\n');
if (JSON.parse(readFileSync('failing.json', 'utf8')).includes(name)) {
  console.log(name + ' found 1 problem');
  process.exitCode = 1;
}
`;

function createProject(failing: string[]): string {
  const projectDir = mkdtempSync(path.join(tmpdir(), 'quality-hook-'));
  projectDirs.push(projectDir);
  mkdirSync(path.join(projectDir, '.agents', 'hooks'), { recursive: true });
  copyFileSync(hook, path.join(projectDir, '.agents', 'hooks', 'check-quality-before-stop.mjs'));
  const scripts = Object.fromEntries(
    CHECK_NAMES.map((check) => [check, `node check.mjs ${check}`]),
  );
  writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify({ private: true, scripts }));
  writeFileSync(path.join(projectDir, 'check.mjs'), CHECK_SCRIPT);
  writeFileSync(path.join(projectDir, 'failing.json'), JSON.stringify(failing));
  return projectDir;
}

// The hook runs from this project's folder, not the fake project's, as when an agent starts it
// from another folder. spawn is asynchronous, so both tests can run at the same time.
function runHook(projectDir: string): Promise<{ code: number | null; stderr: string }> {
  return new Promise((resolve, reject) => {
    const child = spawn(process.execPath, [
      path.join(projectDir, '.agents', 'hooks', 'check-quality-before-stop.mjs'),
    ]);
    let stderr = '';
    child.stderr.setEncoding('utf8').on('data', (chunk: string) => {
      stderr += chunk;
    });
    child.on('error', reject);
    child.on('close', (code) => resolve({ code, stderr }));
    child.stdin.end('{}');
  });
}

function checksThatRan(projectDir: string): string[] {
  return readFileSync(path.join(projectDir, 'ran.txt'), 'utf8').trim().split('\n');
}

afterAll(() => {
  for (const projectDir of projectDirs) {
    rmSync(projectDir, { recursive: true, force: true });
  }
});

// Each test runs npm four times, which takes a few seconds, so the timeout is longer than usual.
describe.concurrent('check-quality-before-stop hook', { timeout: 60_000 }, () => {
  it('passes when every check passes', async ({ expect }) => {
    const projectDir = createProject([]);

    const result = await runHook(projectDir);

    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(checksThatRan(projectDir)).toEqual(CHECK_NAMES);
  });

  it('fails with code 2 and reports every failing check', async ({ expect }) => {
    const projectDir = createProject(['lint', 'test']);

    const result = await runHook(projectDir);

    expect(result.code).toBe(2);
    expect(result.stderr).toContain('Quality check failed');
    expect(result.stderr).toContain('$ npm run lint');
    expect(result.stderr).toContain('lint found 1 problem');
    expect(result.stderr).toContain('$ npm test');
    expect(result.stderr).toContain('test found 1 problem');
    expect(result.stderr).not.toContain('$ npm run typecheck');
    // A failing check does not stop the ones after it.
    expect(checksThatRan(projectDir)).toEqual(CHECK_NAMES);
  });
});
import { spawnSync } from 'node:child_process';
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { afterEach, describe, expect, it } from 'vitest';

// These tests run the stop hook the way an agent does, against the files of this project.

const hook = fileURLToPath(
  new URL('../.agents/hooks/check-secrets-before-stop.mjs', import.meta.url),
);
// A folder for the fake secret. The test deletes it when it ends.
const leakDir = fileURLToPath(new URL('../tmp-secret-test/', import.meta.url));

function runHook() {
  const result = spawnSync(process.execPath, [hook], { input: '{}', encoding: 'utf8' });
  return { code: result.status, stderr: result.stderr };
}

afterEach(() => {
  rmSync(leakDir, { recursive: true, force: true });
});

// Each test runs npm, which takes a few seconds, so the timeout is longer than the default.
describe('check-secrets-before-stop hook', { timeout: 60_000 }, () => {
  it('passes when no file holds a secret', () => {
    const result = runHook();

    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
  });

  it('fails with code 2 when a file holds a token', () => {
    // A fake GitHub token, built here so this test file does not contain one.
    const fakeToken = `ghp_${'FAKE'.repeat(9)}`;
    mkdirSync(leakDir, { recursive: true });
    writeFileSync(`${leakDir}config.ts`, `export const token = '${fakeToken}';\n`);

    const result = runHook();

    expect(result.code).toBe(2);
    expect(result.stderr).toContain('Secret check failed');
    expect(result.stderr).toContain('GITHUB_TOKEN');
    // secretlint masks the secret in its report.
    expect(result.stderr).not.toContain(fakeToken);
  });
});
import { spawn } from 'node:child_process';
import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';

// These tests run the hook the way an agent does: JSON on stdin, then read the exit code, stderr
// and the edited file.
//
// Each test copies the hook into a fake project in the system's temporary folder. Creating and
// deleting files inside this project would race with other checks that read every file at the same
// time, such as a secret scan in a harness.

const hook = fileURLToPath(new URL('../.agents/hooks/format-after-edit.mjs', import.meta.url));
const prettierScript = fileURLToPath(
  new URL('../node_modules/prettier/bin/prettier.cjs', import.meta.url),
);

const UNFORMATTED = 'export const  book = {title:"Dune",\n  year:1965}\n';
const FORMATTED = "export const book = { title: 'Dune', year: 1965 };\n";

let projectDir = '';
let outsideDir = '';

interface HookResult {
  code: number | null;
  stderr: string;
  stdout: string;
}

function createProject(): string {
  const dir = mkdtempSync(path.join(tmpdir(), 'format-hook-'));
  mkdirSync(path.join(dir, '.agents', 'hooks'), { recursive: true });
  copyFileSync(hook, path.join(dir, '.agents', 'hooks', 'format-after-edit.mjs'));
  for (const name of ['prettier.config.mjs', '.prettierignore']) {
    copyFileSync(fileURLToPath(new URL(`../${name}`, import.meta.url)), path.join(dir, name));
  }
  // The hook runs node_modules/prettier/bin/prettier.cjs of its own project. In the fake project,
  // that file loads the Prettier installed in this one.
  const binDir = path.join(dir, 'node_modules', 'prettier', 'bin');
  mkdirSync(binDir, { recursive: true });
  writeFileSync(path.join(binDir, 'prettier.cjs'), `require(${JSON.stringify(prettierScript)});\n`);
  return dir;
}

// spawn writes stdin as a stream, which works in every runtime the template runs in, StackBlitz too.
function runHook(input: string): Promise<HookResult> {
  return new Promise((resolve, reject) => {
    const child = spawn(process.execPath, [
      path.join(projectDir, '.agents', 'hooks', 'format-after-edit.mjs'),
    ]);
    let stdout = '';
    let stderr = '';
    child.stdout.setEncoding('utf8').on('data', (chunk: string) => {
      stdout += chunk;
    });
    child.stderr.setEncoding('utf8').on('data', (chunk: string) => {
      stderr += chunk;
    });
    child.on('error', reject);
    child.on('close', (code) => resolve({ code, stderr, stdout }));
    child.stdin.end(input);
  });
}

function writeFile(dir: string, name: string, content: string): string {
  const file = path.join(dir, name);
  mkdirSync(path.dirname(file), { recursive: true });
  writeFileSync(file, content);
  return file;
}

// The input after an edit tool call, with the file in tool_input.file_path.
function editCall(file: string): string {
  return JSON.stringify({
    hook_event_name: 'PostToolUse',
    tool_name: 'Edit',
    tool_input: { file_path: file },
  });
}

beforeEach(() => {
  projectDir = createProject();
  outsideDir = mkdtempSync(path.join(tmpdir(), 'format-hook-outside-'));
});

afterEach(() => {
  rmSync(projectDir, { recursive: true, force: true });
  rmSync(outsideDir, { recursive: true, force: true });
});

// Each test starts Prettier in a new Node process. On October 18, 2026, StackBlitz needed more than
// the default 5 seconds for some of them, so the timeout is longer.
describe('format-after-edit hook', { timeout: 30_000 }, () => {
  it('formats the file in tool_input.file_path', async () => {
    const file = writeFile(projectDir, 'src/book.ts', UNFORMATTED);

    const result = await runHook(editCall(file));

    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(result.stdout).toBe('');
    expect(readFileSync(file, 'utf8')).toBe(FORMATTED);
  });

  it('formats the file in a top-level file_path', async () => {
    const file = writeFile(projectDir, 'src/book.ts', UNFORMATTED);

    const result = await runHook(JSON.stringify({ file_path: file }));

    expect(result.code).toBe(0);
    expect(readFileSync(file, 'utf8')).toBe(FORMATTED);
  });

  it('reads a relative path from the folder in cwd', async () => {
    const file = writeFile(projectDir, 'src/book.ts', UNFORMATTED);
    const input = { cwd: path.join(projectDir, 'src'), tool_input: { file_path: 'book.ts' } };

    const result = await runHook(JSON.stringify(input));

    expect(result.code).toBe(0);
    expect(readFileSync(file, 'utf8')).toBe(FORMATTED);
  });

  it('formats every file named in the headers of a patch in tool_input.command', async () => {
    const changed = writeFile(projectDir, 'src/book.ts', UNFORMATTED);
    const added = writeFile(projectDir, 'src/member.ts', UNFORMATTED);
    const patch = [
      '*** Begin Patch',
      '*** Update File: src/book.ts',
      '@@',
      '-old line',
      '+new line',
      '*** Add File: src/member.ts',
      '+new file',
      '*** End Patch',
    ].join('\n');
    const input = { cwd: projectDir, tool_name: 'apply_patch', tool_input: { command: patch } };

    const result = await runHook(JSON.stringify(input));

    expect(result.code).toBe(0);
    expect(readFileSync(changed, 'utf8')).toBe(FORMATTED);
    expect(readFileSync(added, 'utf8')).toBe(FORMATTED);
  });

  it('fails with code 2 when Prettier cannot parse the file, and leaves it as it was', async () => {
    const broken = 'export const = ;\n';
    const file = writeFile(projectDir, 'src/broken.ts', broken);

    const result = await runHook(editCall(file));

    expect(result.code).toBe(2);
    expect(result.stderr).toContain('Formatting failed');
    expect(result.stderr).toContain('broken.ts');
    expect(result.stderr).toContain('SyntaxError');
    expect(readFileSync(file, 'utf8')).toBe(broken);
  });

  it('leaves a file outside the project alone', async () => {
    const file = writeFile(outsideDir, 'book.ts', UNFORMATTED);

    const result = await runHook(editCall(file));

    expect(result.code).toBe(0);
    expect(readFileSync(file, 'utf8')).toBe(UNFORMATTED);
  });

  it('leaves a file that Prettier does not know alone', async () => {
    const content = 'some   notes\n';
    const file = writeFile(projectDir, 'notes.unknown', content);

    const result = await runHook(editCall(file));

    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
    expect(readFileSync(file, 'utf8')).toBe(content);
  });

  it.each([
    ['a tool call without a file', JSON.stringify({ tool_input: { command: 'npm test' } })],
    ['a file that does not exist', editCall('src/missing.ts')],
    ['input that is not JSON', 'not json'],
  ])('does nothing for %s', async (_case, input) => {
    const result = await runHook(input);

    expect(result.code).toBe(0);
    expect(result.stderr).toBe('');
  });
});
import type { Express } from 'express';
import request from 'supertest';
import { describe, expect, it } from 'vitest';
import { createApp } from '../src/app';

async function createBook(app: Express, title = 'Dune'): Promise<string> {
  const res = await request(app).post('/books').send({ title, author: 'Frank Herbert' });
  return (res.body as { id: string }).id;
}

async function createMember(app: Express, name = 'Ana'): Promise<string> {
  const res = await request(app).post('/members').send({ name });
  return (res.body as { id: string }).id;
}

describe('library API', () => {
  it('creates a book and lists it as available', async () => {
    const app = createApp();

    const created = await request(app)
      .post('/books')
      .send({ title: 'Dune', author: 'Frank Herbert' });
    expect(created.status).toBe(201);
    expect(created.body).toMatchObject({ title: 'Dune', author: 'Frank Herbert', available: true });

    const list = await request(app).get('/books');
    expect(list.status).toBe(200);
    expect(list.body).toContainEqual(
      expect.objectContaining({ id: created.body.id, available: true }),
    );
  });

  it('returns 404 BOOK_NOT_FOUND for an unknown book', async () => {
    const app = createApp();

    const res = await request(app).get('/books/does-not-exist');
    expect(res.status).toBe(404);
    expect(res.body.error.code).toBe('BOOK_NOT_FOUND');
  });

  it('rejects a book without a title with 400 INVALID_INPUT', async () => {
    const app = createApp();

    const res = await request(app).post('/books').send({ author: 'Frank Herbert' });
    expect(res.status).toBe(400);
    expect(res.body.error.code).toBe('INVALID_INPUT');
  });

  it('creates a member and lists it', async () => {
    const app = createApp();

    const created = await request(app).post('/members').send({ name: 'Ana' });
    expect(created.status).toBe(201);
    expect(created.body).toMatchObject({ name: 'Ana' });

    const list = await request(app).get('/members');
    expect(list.status).toBe(200);
    expect(list.body).toContainEqual(expect.objectContaining({ id: created.body.id, name: 'Ana' }));
  });

  it('lends an available book, and the book stops being available', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const memberId = await createMember(app);

    const loan = await request(app).post('/loans').send({ bookId, memberId });
    expect(loan.status).toBe(201);
    expect(loan.body).toMatchObject({ bookId, memberId, returnedAt: null });

    const book = await request(app).get(`/books/${bookId}`);
    expect(book.status).toBe(200);
    expect(book.body.available).toBe(false);
  });

  it('rejects lending a book that is already loaned with 409 BOOK_ALREADY_LOANED', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const firstMemberId = await createMember(app, 'Ana');
    const secondMemberId = await createMember(app, 'Luis');

    const first = await request(app).post('/loans').send({ bookId, memberId: firstMemberId });
    expect(first.status).toBe(201);

    const second = await request(app).post('/loans').send({ bookId, memberId: secondMemberId });
    expect(second.status).toBe(409);
    expect(second.body.error.code).toBe('BOOK_ALREADY_LOANED');
  });

  it('rejects a fourth active loan for the same member with 409 LOAN_LIMIT_REACHED', async () => {
    const app = createApp();
    const memberId = await createMember(app);

    for (const title of ['Dune', 'Emma', 'Ulysses']) {
      const bookId = await createBook(app, title);
      const loanRes = await request(app).post('/loans').send({ bookId, memberId });
      expect(loanRes.status).toBe(201);
    }

    const bookId = await createBook(app, 'Beloved');
    const res = await request(app).post('/loans').send({ bookId, memberId });
    expect(res.status).toBe(409);
    expect(res.body.error.code).toBe('LOAN_LIMIT_REACHED');

    const book = await request(app).get(`/books/${bookId}`);
    expect(book.body.available).toBe(true);
  });

  it('returning a loan makes the book available again', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const memberId = await createMember(app);
    const loanRes = await request(app).post('/loans').send({ bookId, memberId });

    const res = await request(app).post(`/loans/${loanRes.body.id}/return`);
    expect(res.status).toBe(200);
    expect(res.body).toMatchObject({ id: loanRes.body.id, bookId, memberId });
    expect(res.body.returnedAt).toEqual(expect.any(String));

    const book = await request(app).get(`/books/${bookId}`);
    expect(book.body.available).toBe(true);
  });

  it('rejects returning the same loan twice with 409 LOAN_ALREADY_RETURNED', async () => {
    const app = createApp();
    const bookId = await createBook(app);
    const memberId = await createMember(app);
    const loanRes = await request(app).post('/loans').send({ bookId, memberId });
    const loanPath = `/loans/${loanRes.body.id}/return`;

    const first = await request(app).post(loanPath);
    expect(first.status).toBe(200);

    const second = await request(app).post(loanPath);
    expect(second.status).toBe(409);
    expect(second.body.error.code).toBe('LOAN_ALREADY_RETURNED');
  });

  it('rejects a loan for an unknown member with 404 MEMBER_NOT_FOUND', async () => {
    const app = createApp();
    const bookId = await createBook(app);

    const res = await request(app).post('/loans').send({ bookId, memberId: 'does-not-exist' });
    expect(res.status).toBe(404);
    expect(res.body.error.code).toBe('MEMBER_NOT_FOUND');
  });

  it('rejects malformed JSON with 400 INVALID_INPUT', async () => {
    const app = createApp();

    const res = await request(app)
      .post('/books')
      .set('Content-Type', 'application/json')
      .send('{"title": "Dune"');
    expect(res.status).toBe(400);
    expect(res.body.error.code).toBe('INVALID_INPUT');
  });
});
import { spawn } from 'node:child_process';
import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterAll, describe, it } from 'vitest';

// These tests run the stop hook the way an agent does, then read its exit code and stderr. Each
// test copies the hook and .jscpd.json into a small fake project in the system's temporary folder
// and writes some source files. The hook runs the real jscpd installed in this project. The folders
// are deleted at the end.

const hook = fileURLToPath(
  new URL('../.agents/hooks/report-duplicates-before-stop.mjs', import.meta.url),
);
const jscpdConfig = fileURLToPath(new URL('../.jscpd.json', import.meta.url));
const jscpdBin = fileURLToPath(new URL('../node_modules/jscpd/bin/jscpd', import.meta.url));
const projectDirs: string[] = [];

// A function that validates a text field, and the same function copied under another name. jscpd
// sees the copy: only the function name changed.
const READ_TITLE = `export function readTitle(input: unknown): string {
  if (typeof input !== 'string') {
    throw new Error('The value must be text');
  }
  const text = input.trim();
  if (text.length === 0 || text.length > 200) {
    throw new Error('The value must have between 1 and 200 characters');
  }
  return text;
}
`;
const READ_NAME_COPY = READ_TITLE.replace('readTitle', 'readName');
// The same logic with every name and message changed. jscpd compares tokens, so it does not see it.
const READ_NAME_RENAMED = `export function readName(value: unknown): string {
  if (typeof value !== 'string') {
    throw new Error('A name is text');
  }
  const name = value.trim();
  if (name.length === 0 || name.length > 200) {
    throw new Error('A name has between 1 and 200 characters');
  }
  return name;
}
`;
const COUNT_LOANS = `export function countActiveLoans(loans: { returnedAt: string | null }[]): number {
  return loans.filter((loan) => loan.returnedAt === null).length;
}
`;

function createProject(checkDuplicates = 'jscpd src'): string {
  const projectDir = mkdtempSync(path.join(tmpdir(), 'duplicates-hook-'));
  projectDirs.push(projectDir);
  mkdirSync(path.join(projectDir, '.agents', 'hooks'), { recursive: true });
  copyFileSync(
    hook,
    path.join(projectDir, '.agents', 'hooks', 'report-duplicates-before-stop.mjs'),
  );
  copyFileSync(jscpdConfig, path.join(projectDir, '.jscpd.json'));
  const scripts = { 'check:duplicates': checkDuplicates };
  writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify({ private: true, scripts }));
  // The hook runs node_modules/jscpd/bin/jscpd of its own project. In the fake project, that file
  // loads the jscpd installed in this one.
  const binDir = path.join(projectDir, 'node_modules', 'jscpd', 'bin');
  mkdirSync(binDir, { recursive: true });
  writeFileSync(path.join(binDir, 'jscpd'), `require(${JSON.stringify(jscpdBin)});\n`);
  mkdirSync(path.join(projectDir, 'src'));
  return projectDir;
}

function writeSource(projectDir: string, name: string, content: string): void {
  writeFileSync(path.join(projectDir, 'src', name), content);
}

// The hook runs from this project's folder, not the fake project's, as when an agent starts it
// from another folder. spawn is asynchronous, so the tests can run at the same time.
function runHook(projectDir: string): Promise<{ code: number | null; stderr: string }> {
  return new Promise((resolve, reject) => {
    const child = spawn(process.execPath, [
      path.join(projectDir, '.agents', 'hooks', 'report-duplicates-before-stop.mjs'),
    ]);
    let stderr = '';
    child.stderr.setEncoding('utf8').on('data', (chunk: string) => {
      stderr += chunk;
    });
    child.on('error', reject);
    child.on('close', (code) => resolve({ code, stderr }));
    child.stdin.end('{}');
  });
}

afterAll(() => {
  for (const projectDir of projectDirs) {
    rmSync(projectDir, { recursive: true, force: true });
  }
});

// Each run starts jscpd, which takes about a second on a computer and much longer in StackBlitz,
// so the timeout is longer than usual. The hook starts jscpd without npm, which keeps each run light
// enough to run the tests at the same time there too.
describe.concurrent('report-duplicates-before-stop hook', { timeout: 120_000 }, () => {
  it('passes in silence when there is no duplicated code', async ({ expect }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'loans.ts', COUNT_LOANS);

    const result = await runHook(projectDir);

    expect(result.stderr).toBe('');
    expect(result.code).toBe(0);
  });

  it('reports a copied function once, with code 2 and both locations', async ({ expect }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'members.ts', READ_NAME_COPY);

    const first = await runHook(projectDir);
    // The agent keeps the copy and tries to finish again: the hook lets it.
    const second = await runHook(projectDir);

    expect(first.code).toBe(2);
    expect(first.stderr).toContain('Duplicated code: a warning, not a failure.');
    expect(first.stderr).toMatch(/src\/books\.ts:\d+-\d+/);
    expect(first.stderr).toMatch(/src\/members\.ts:\d+-\d+/);
    expect(first.stderr).toContain('Each duplicate is reported once');
    expect(second.stderr).toBe('');
    expect(second.code).toBe(0);
  });

  it('reports a new duplicate, and a duplicate that was removed and comes back', async ({
    expect,
  }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'members.ts', READ_NAME_COPY);
    await runHook(projectDir);

    // The copy in members.ts goes away and a new one appears in authors.ts.
    writeSource(projectDir, 'members.ts', COUNT_LOANS);
    writeSource(projectDir, 'authors.ts', READ_TITLE.replace('readTitle', 'readAuthor'));
    const fresh = await runHook(projectDir);
    // The copy in members.ts comes back.
    writeSource(projectDir, 'members.ts', READ_NAME_COPY);
    const back = await runHook(projectDir);

    expect(fresh.code).toBe(2);
    expect(fresh.stderr).toMatch(/src\/authors\.ts:\d+-\d+/);
    expect(fresh.stderr).not.toContain('src/members.ts');
    expect(back.code).toBe(2);
    expect(back.stderr).toMatch(/src\/members\.ts:\d+-\d+/);
  });

  // A limit of jscpd, not of the hook: the clean-code-review skill asks the agent to look for this.
  it('does not see the same logic written with other names', async ({ expect }) => {
    const projectDir = createProject();
    writeSource(projectDir, 'books.ts', READ_TITLE);
    writeSource(projectDir, 'members.ts', READ_NAME_RENAMED);

    const result = await runHook(projectDir);

    expect(result.stderr).toBe('');
    expect(result.code).toBe(0);
  });

  it('fails with code 2 when the duplicate check cannot run', async ({ expect }) => {
    const projectDir = createProject('jscpd missing-folder');
    writeSource(projectDir, 'books.ts', READ_TITLE);

    const result = await runHook(projectDir);

    expect(result.code).toBe(2);
    expect(result.stderr).toContain('Could not run the duplicate check');
    expect(result.stderr).toContain('missing-folder');
  });
});
// Architecture rules for the modular monolith. Each rule is one sentence in plain words, and each
// rule fails the check when it is broken. Run with: npm run check:architecture
//
// Each module (src/modules/<name>/) owns one part of the library: catalog, members or loans. Its
// index.ts is its public API. Everything else in the module is internal. src/shared/ holds the
// code that every module uses, and app.ts plugs the modules together.
/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
  forbidden: [
    {
      // The key rule. A module imports another module only through its public API, index.ts.
      // $1 is the name of the importing module, so a module can import its own files freely.
      name: 'modules-import-only-public-api',
      severity: 'error',
      from: { path: '^src/modules/([^/]+)/' },
      to: {
        path: '^src/modules/',
        pathNot: ['^src/modules/$1/', '^src/modules/[^/]+/index\\.ts$'],
      },
    },
    {
      // app.ts and server.ts build the modules through their public API too.
      name: 'composition-root-imports-only-public-api',
      severity: 'error',
      from: { path: '^src/(app|server)\\.ts$' },
      to: { path: '^src/modules/', pathNot: '^src/modules/[^/]+/index\\.ts$' },
    },
    {
      // Shared code serves every module, so it knows none of them.
      name: 'shared-does-not-import-modules',
      severity: 'error',
      from: { path: '^src/shared/' },
      to: { path: '^src/(modules/|app\\.ts$|server\\.ts$)' },
    },
    {
      // Only app.ts and server.ts know every module. A module never imports them.
      name: 'modules-do-not-import-the-composition-root',
      severity: 'error',
      from: { path: '^src/modules/' },
      to: { path: '^src/(app|server)\\.ts$' },
    },
    {
      // A cycle means no module can be understood or tested on its own. Between modules, a cycle
      // also means two modules that cannot change without each other.
      name: 'no-circular',
      severity: 'error',
      from: { pathNot: '^node_modules' },
      to: { circular: true },
    },
  ],
  options: {
    doNotFollow: { path: 'node_modules' },
    tsConfig: { fileName: 'tsconfig.json' },
    // Count "import type" lines too. Without this, a type-only import would hide a broken rule.
    tsPreCompilationDeps: true,
  },
};
node_modules/
.env
.env.*
!.env.example
{
  "format": ["typescript", "javascript"],
  "minTokens": 50,
  "minLines": 5,
  "noTips": true
}
node_modules/
package-lock.json
{
  "rules": [{ "id": "@secretlint/secretlint-rule-preset-recommend" }]
}
# AGENTS.md

## Project

A small library REST API with books, members and loans. TypeScript, Node 22 or later, Express 5. Data lives in memory. The full contract (entities, endpoints, error codes, business rules) is in `../MINI_APP_SPEC.md`.

This folder is the **modular monolith harness**: the same app as `starting-point`, split into modules by part of the library. Each module owns its code and its data, and offers the rest of the app a small public API. It is still one app, started and tested as a whole.

Use npm in this folder, not pnpm.

## The modules

| Folder                 | What it owns                                           | Public API (`index.ts`)                         | Uses             |
| ---------------------- | ------------------------------------------------------ | ----------------------------------------------- | ---------------- |
| `src/modules/catalog/` | Books and whether each one is available                | `Book`, `CatalogApi`, `createCatalogModule()`   | nothing          |
| `src/modules/members/` | Members                                                | `Member`, `MembersApi`, `createMembersModule()` | nothing          |
| `src/modules/loans/`   | Loans and the two loan rules                           | `LoansDependencies`, `createLoansModule()`      | catalog, members |
| `src/shared/`          | `AppError` and the HTTP helpers that every module uses | not a module: it imports no module              |                  |
| `src/app.ts`           | Composition root: builds the modules and connects them | not a module                                    | every module     |
| `src/server.ts`        | Starts `createApp()` on `PORT` (default 3000)          | not a module                                    | `app.ts`         |

Each module has its own `AGENTS.md` with its public API, its files, its rules and its tests. **Before you change a module, read its `AGENTS.md`.** You do not need the `AGENTS.md` of the modules you do not change.

## The key rule

A module uses another module only through its public API: the `index.ts` file in the module folder. Every other file in a module is internal, and only that module imports it. `src/app.ts` also builds each module through its `index.ts`. `src/shared/` imports no module, and no module imports `app.ts`. There are no cycles, so two modules never depend on each other. `npm run check:architecture` checks this with dependency-cruiser, using `.dependency-cruiser.cjs`.

## Where new code goes

- A change inside one module, such as a new route or rule: in that module's folder. Follow its `AGENTS.md`.
- Something a module needs from another module: use what the other module's `index.ts` offers. If nothing fits, add a method to the API interface in that `index.ts` (`CatalogApi`, `MembersApi`) and implement it inside that module. Add only what the caller needs: every method in a public API is a promise to the modules that use it.
- A new error code: `src/shared/app-error.ts`, with its status in `STATUS_BY_CODE` in `src/shared/http.ts`.
- A new module: a new folder in `src/modules/` with an `index.ts` and an `AGENTS.md`, built in `src/app.ts`. Add it to the table above.
- Tests of one module: next to its code, as `<file>.test.ts`. They may fake the public API of the modules it uses. Tests that cross modules, over HTTP, go in `test/`.

For a task that stays inside one module, you can hand it to the subagent `module-developer` (`.agents/agents/module-developer.md`) if your agent supports subagents. It works only inside that module and reports anything that needs a change outside it.

## Verification

Run these from this folder:

- `npm test`: the acceptance tests in `test/library.test.ts`, the tests of each module and the tests of the harness hooks.
- `npm run check:architecture`: the module rules.
- `npm run check:secrets`: secretlint looks for secrets, such as API keys or tokens, in every file that `.gitignore` does not exclude.
- `npm run typecheck`: TypeScript.
- `npm run lint`: ESLint.
- `npm run format:check`: Prettier. Use `npm run format` to fix formatting.
- `npm run verify`: all of the above, in that order.
- `npm run check:duplicates`: jscpd lists duplicated code in `src/`. It is a report and never fails, so it is not part of `verify`.

Run `npm run verify` before you say a task is done.

When you try to finish, four stop hooks run. `.agents/hooks/check-architecture-before-stop.mjs` runs `npm run check:architecture`, `.agents/hooks/check-secrets-before-stop.mjs` runs `npm run check:secrets`, and `.agents/hooks/check-quality-before-stop.mjs` runs `npm run format:check`, `npm run lint`, `npm run typecheck` and `npm test`. If one of them fails, you cannot finish until it passes. Together they run every check in `npm run verify`. The fourth, `.agents/hooks/report-duplicates-before-stop.mjs`, is a warning described in the `Clean code` section.

## Harness files

The harness keeps its agent files in `.agents/`, not in the folder of one specific agent:

- `.agents/hooks/check-architecture-before-stop.mjs`: the stop hook for the module rules.
- `.agents/hooks/check-secrets-before-stop.mjs` and `.agents/hooks/block-dangerous-commands.mjs`: the security hooks described in the `Security` section.
- `.agents/hooks/format-after-edit.mjs` and `.agents/hooks/check-quality-before-stop.mjs`: the quality hooks described in the `Quality` section.
- `.agents/hooks/report-duplicates-before-stop.mjs`: the duplicate warning described in the `Clean code` section.
- `.agents/agents/module-developer.md`: the subagent for a task inside one module.
- `.agents/skills/clean-code-review/SKILL.md`: the review before you say a task is done.
- `.agents/permissions.json`: the files you must not read and the commands you must ask about.

Each agent reads hooks, subagents and permissions from its own settings, which point to these files or hold a copy. The README explains how.

## Never

- Edit `test/library.test.ts`. It is the contract that every template shares. Do not weaken, skip or delete its tests.
- Change `.dependency-cruiser.cjs` to make a failing check pass. Use the other module's `index.ts` instead, or add what you need to its public API.
- Edit the files in `.agents/`, or your agent's hook and permission settings, to get past a failing check. Fix the code instead.

## Security

- Never read, print or change `.env` or `.env.*` files. They hold real secrets. If a task needs a secret, ask the user.
- Never write a real secret (an API key, a token, a password or a private key) in code, tests or docs. Read it from an environment variable and add the variable name, without its value, to `.env.example`.
- Ask the user before you run `git push` or install a dependency (`npm install`, `npm i`, `npm add`).
- Before each shell command, the hook `.agents/hooks/block-dangerous-commands.mjs` blocks recursive deletes, force pushes, `git reset --hard`, `git clean -f`, downloads piped into a shell, and commands that mention a `.env` file. If it blocks a command, do not look for another way to run it. Tell the user what you wanted to do and why.
- When you try to finish, the hook `.agents/hooks/check-secrets-before-stop.mjs` runs `npm run check:secrets`. If it finds a secret, remove it from the file. Do not add the file to `.secretlintignore` or a `secretlint-disable` comment to the code to pass the check.
- Never edit the security hooks, `.secretlintrc.json` or your agent's hook and permission settings to get past a check.

## Quality

- After you write or edit a file, the hook `.agents/hooks/format-after-edit.mjs` formats it with Prettier. You do not need to format by hand. If the hook says it could not format a file, the file usually has a syntax error: fix it.
- When you try to finish, the hook `.agents/hooks/check-quality-before-stop.mjs` runs `npm run format:check`, `npm run lint`, `npm run typecheck` and `npm test`. If one fails, you cannot finish until it passes. Run `npm run format` for formatting problems. Fix lint, type and test errors in the code.
- ESLint limits the size of a function: complexity 10, nesting depth 3, 4 parameters and 50 lines. If you reach a limit, split the function. Do not move the code somewhere else only to pass the check.
- `eslint-disable` comments have no effect here. Do not add them. If a rule is wrong for a case, tell the user. Exceptions go in `eslint.config.js`, where a reviewer sees them, and only the user adds them.
- Never weaken, skip or delete a test to make the checks pass. Never edit the quality hooks, `eslint.config.js`, `prettier.config.mjs`, `.prettierignore` or your agent's hook settings to get past a check.

## Clean code

- Before you write a new function, search the code for one that already does the job, and reuse it.
- Name files, functions and variables with the words of the domain (book, member, loan). Do not use vague names such as `data`, `info`, `handle` or `utils`.
- A function does one thing. If you need "and" to describe what it does, split it.
- Do not merge code only because it looks alike. Extract a shared function when the copies hold the same rule and would change together. If the shared function would need a flag or extra parameters to tell its callers apart, keep the copies.
- Write only what the task needs: no options, parameters or abstractions for later, and no changes to code the task does not touch.
- When you try to finish, the hook `.agents/hooks/report-duplicates-before-stop.mjs` runs jscpd on the folders of the `check:duplicates` script and lists the duplicated blocks it has not reported before. It is a warning: decide on each one with the rule above and tell the user which ones you kept. Never edit `.jscpd.json`, the `check:duplicates` script or the hook to hide a duplicate.
- Before you say a task is done, follow the skill `clean-code-review` (`.agents/skills/clean-code-review/SKILL.md`).

## Conventions

- TypeScript in strict mode. No `any`. Treat request bodies as `unknown` and validate them in the routes of the module.
- IDs are strings created by the repository of each module. Clients and other modules must not assume their format.
- Text fields are trimmed and must not be empty after trimming.
- Keep the error messages short and human-readable. Tests check the `code`, not the message.
import eslint from '@eslint/js';
import globals from 'globals';
import tseslint from 'typescript-eslint';

// A few rules on top of the recommended sets, each with the reason it is here.
export default tseslint.config(
  eslint.configs.recommended,
  tseslint.configs.recommended,
  {
    // Scripts such as the hooks run in Node, so they get Node globals like `process`.
    files: ['**/*.{js,mjs,cjs}'],
    languageOptions: { globals: globals.node },
  },
  {
    linterOptions: {
      // An agent that cannot pass a rule may silence it with an `eslint-disable` comment. With this
      // option ESLint ignores those comments, so an exception has to go in this file, where a
      // reviewer sees it.
      noInlineConfig: true,
    },
    rules: {
      // Type-only imports are erased when the code runs. Marking them makes the dependencies
      // easier to read, and it matches verbatimModuleSyntax in tsconfig.json.
      '@typescript-eslint/consistent-type-imports': 'error',
      // Strict equality avoids silent coercions such as '' == 0.
      eqeqeq: 'error',
      // Agents tend to handle a new case by adding one more branch to the function they are
      // editing. These four limits ask for a new function instead, before it becomes hard to read.
      complexity: ['error', 10],
      'max-depth': ['error', 3],
      'max-params': ['error', 4],
      'max-lines-per-function': ['error', { max: 50, skipBlankLines: true, skipComments: true }],
    },
  },
  {
    // A describe block groups many tests, so its length says nothing about how complex it is.
    files: ['test/**'],
    rules: { 'max-lines-per-function': 'off' },
  },
);
{
  "name": "library-modular-monolith",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "start": "tsx src/server.ts",
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "check:architecture": "depcruise --config .dependency-cruiser.cjs --output-type err src",
    "check:secrets": "secretlint \"**/*\"",
    "check:duplicates": "jscpd src",
    "lint": "eslint .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "verify": "npm run typecheck && npm run lint && npm run format:check && npm run check:architecture && npm run check:secrets && npm test"
  },
  "dependencies": {
    "express": "5.3.0"
  },
  "devDependencies": {
    "@eslint/js": "10.0.1",
    "@secretlint/secretlint-rule-preset-recommend": "13.0.7",
    "@types/express": "5.0.6",
    "@types/node": "22.20.5",
    "@types/supertest": "7.2.1",
    "dependency-cruiser": "18.6.0",
    "eslint": "10.12.0",
    "globals": "17.13.0",
    "jscpd": "4.3.0",
    "prettier": "3.9.10",
    "secretlint": "13.0.7",
    "supertest": "7.3.1",
    "tsx": "4.23.15",
    "typescript": "5.9.3",
    "typescript-eslint": "8.71.2",
    "vitest": "5.0.4"
  }
}
/** @type {import('prettier').Config} */
export default {
  printWidth: 100,
  semi: true,
  singleQuote: true,
  trailingComma: 'all',
};
# Library modular monolith harness

The library API from [`starting-point`](../starting-point/), split into modules and protected by a harness. The endpoints, behavior and acceptance tests are the same: `test/library.test.ts` is byte-for-byte identical to the starting point.

This is the third base harness of the Agent Atlas series, after the [layered harness](../layered/) and the [hexagonal harness](../hexagonal/). The architecture is the context; the harness is the subject. It reuses the security, quality and clean-code pieces without changes. What is new is the architecture part (the folders, the rules and the architecture hook message), an `AGENTS.md` per module and a subagent that works inside one module.

## Run it

```bash
npm install
npm run verify
npm run dev
```

The server listens on port 3000. Set `PORT` to use another port.

## The modules

| Folder                 | What it owns                                  | Public API (`index.ts`)                         | Uses             |
| ---------------------- | --------------------------------------------- | ----------------------------------------------- | ---------------- |
| `src/modules/catalog/` | Books and whether each one is available       | `Book`, `CatalogApi`, `createCatalogModule()`   | nothing          |
| `src/modules/members/` | Members                                       | `Member`, `MembersApi`, `createMembersModule()` | nothing          |
| `src/modules/loans/`   | Loans and the two loan rules                  | `LoansDependencies`, `createLoansModule()`      | catalog, members |
| `src/shared/`          | `AppError` and the HTTP helpers               | not a module                                    | no module        |
| `src/app.ts`           | Composition root: builds and connects modules | not a module                                    | every module     |

The rule: a module uses another module only through its public API, the `index.ts` in its folder. Every other file in a module is internal. The full description is in [`AGENTS.md`](AGENTS.md).

## What the harness adds to starting-point

- `AGENTS.md`, with the module table, the key rule and the verification commands. It is an open format that several coding agents read from the project root.
- One `AGENTS.md` per module, in `src/modules/<name>/AGENTS.md`, with the public API, the files, the rules and the tests of that module. The root `AGENTS.md` asks the agent to read it before it changes the module.
- The subagent `.agents/agents/module-developer.md`, for a task that stays inside one module. It reads the root and module `AGENTS.md`, changes only that module and reports what it needs from outside.
- Architecture rules in `.dependency-cruiser.cjs`, run by `npm run check:architecture`.
- A stop hook, `.agents/hooks/check-architecture-before-stop.mjs`. When the agent tries to finish, it runs the architecture check. If it fails, it prints the output to stderr and exits with code 2, so the agent cannot finish yet. It is the same script as in the layered and hexagonal harnesses; only its message changes.
- A module test file, `src/modules/loans/loans-service.test.ts`, that checks the loan rules without HTTP and without the other modules, with fakes of their public API.
- The [security piece](../security/), the [quality piece](../quality/) and the [clean-code piece](../clean-code/), copied without changes. Each piece's README explains its files, and the `Security`, `Quality` and `Clean code` sections of `AGENTS.md` are the same as in the pieces.

## What changed from the hexagonal harness

| Part                                    | Hexagonal harness                                     | Modular monolith harness                                          |
| --------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
| How the code is split                   | By technical role: domain, ports, use cases, adapters | By part of the library: catalog, members, loans                   |
| Where the HTTP routes and storage live  | In adapters around the core                           | Inside each module                                                |
| How a loan reaches the books            | Through the `BookRepository` port                     | Through `CatalogApi`, the public API of the catalog module        |
| Architecture rules                      | Seven, about the direction of the dependencies        | Five, about the public API of each module and cycles              |
| Instructions                            | One `AGENTS.md`                                       | One `AGENTS.md` at the root and one per module                    |
| Architecture skill or subagent          | Skill `add-use-case`                                  | Subagent `module-developer`                                       |
| Tests without HTTP                      | 3, in `test/`, with the in-memory adapters            | The same 3, next to the loans module, with fakes of the other two |
| Security, quality and clean-code pieces | Included                                              | The same files, copied without changes                            |

## Connect it to your agent

The harness is not tied to one agent. Agents do not share a settings format, so the logic lives in `.agents/` and each agent's own settings point to it. Until you connect them, the files in `.agents/` do nothing on their own.

- **Stop hooks:** register `node .agents/hooks/check-architecture-before-stop.mjs`, `node .agents/hooks/check-secrets-before-stop.mjs`, `node .agents/hooks/check-quality-before-stop.mjs` and `node .agents/hooks/report-duplicates-before-stop.mjs` as your agent's stop hooks, the event that runs when the agent is about to finish. The scripts find the project root from their own location, so they work from any current directory. Your agent must read exit code 2, with the reason on stderr, as "not done yet". If it expects another output format, it needs a small adapter.
- **Before a shell command:** register `node .agents/hooks/block-dangerous-commands.mjs` on the event that runs before a tool or shell command. Exit code 2 means "do not run it".
- **After an edit:** register `node .agents/hooks/format-after-edit.mjs` on the event that runs after the agent writes or edits a file.
- **Module instructions:** the root `AGENTS.md` tells the agent to read the `AGENTS.md` of the module it changes. Some agents also load it on their own when they work in that folder.
- **Subagent:** copy `.agents/agents/module-developer.md` to the folder where your agent looks for subagents, in the format it expects.
- **Skills:** some agents read `.agents/skills/` directly. For the others, copy `.agents/skills/clean-code-review/` to the folder where your agent looks for skills.
- **Permissions:** copy the rules in `.agents/permissions.json` into your agent's permission settings.

The Agent Atlas page for this harness shows the settings for some agents and says what was tested: <https://agentatlas-dev.vercel.app/en/harnesses/modular-monolith/>.

## Checks

| Command                      | What it checks                                                                                                                | Run by a stop hook     |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `npm test`                   | Acceptance tests (11), loans module tests (3), security hook tests (39), quality hook tests (12) and duplicate hook tests (5) | yes (quality)          |
| `npm run check:architecture` | Module rules                                                                                                                  | yes (architecture)     |
| `npm run check:secrets`      | Secrets in the files that `.gitignore` keeps                                                                                  | yes (secrets)          |
| `npm run typecheck`          | TypeScript types                                                                                                              | yes (quality)          |
| `npm run lint`               | ESLint                                                                                                                        | yes (quality)          |
| `npm run format:check`       | Prettier formatting                                                                                                           | yes (quality)          |
| `npm run verify`             | All of the above, in order                                                                                                    | no                     |
| `npm run check:duplicates`   | Duplicated code in `src/` (a report, it never fails)                                                                          | yes (duplicates, once) |

## Limits

- dependency-cruiser checks imports, not data. A module that keeps its own copy of another module's data, such as the title of a book inside a loan, is not detected.
- The rules rely on the folder names: a module is any folder in `src/modules/`, and its public API is the file named `index.ts`. Whatever `index.ts` exports is public, so a module can still publish too much.
- dependency-cruiser looks for cycles between files, not between modules. A file that nothing imports, such as a test, can import a module that depends on its own module without a report.
- The module `AGENTS.md` files only help if the agent reads them. The root `AGENTS.md` asks for it, but it is an instruction, not a check.
- `.agents/permissions.json` only lists the rules. How far they reach depends on the agent's permission settings. The dangerous command hook reads the text of a command, so a script that deletes files or reads `.env` from inside a program gets past it. Only a sandbox stops that. The limits of each piece are in its README.
- The stop hooks run on every stop. The quality hook is the slowest, because it runs the linter, the type checker and every test.
- How many times in a row a stop hook can send the agent back depends on the agent. The scripts do not limit it.

The full contract (entities, status codes, error codes and acceptance tests) is in [`../MINI_APP_SPEC.md`](../MINI_APP_SPEC.md).
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "noEmit": true,
    "types": ["node"],
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src", "test"]
}

How to use it

You can run it in the browser or on your machine.

In the browser, the Run in the browser button opens the harness in StackBlitz, an external service, in a new tab. StackBlitz installs the dependencies and runs npm test, which here means 70 tests. On October 21, 2026, I tested it from a local copy of the site with headless Chromium 151, through Playwright, using the main button: the StackBlitz tab opened in 1.7 s and the 70 tests passed. Vitest measured 42.5 s to run them, and the summary appeared about 75 s after the click, including the install. I did not test it in Firefox or Safari.

On your machine you need Node 22 or later. Copy the harness files into a folder and run these commands inside it, with npm, not pnpm:

npm install
npm test
npm run verify
npm run dev

npm test runs the 70 tests: the 11 acceptance tests, 3 loans module tests without HTTP, 39 for the security hooks, 12 for the quality hooks, and 5 for the duplicate hook. npm run verify runs everything AGENTS.md asks for: types, lint, formatting, the module rules, the secret scanner, and the tests. npm run check:duplicates shows the duplicated code in src/ and never fails. npm run dev starts the API at http://localhost:3000.

Connect it to your agent

Each agent reads hooks, subagents, skills, and permissions from its own settings, and there is no common format. That is why the harness keeps the logic in .agents/, and each agent only needs a few files that point there or copy what is there. Those files are not part of the harness: create them yourself in the harness folder, or in the root of the project where you copied it. The hooks have the same names as in the earlier harnesses, so their settings are the same.

The hook scripts do not depend on the agent. They find the project root from their own location and, if something fails, they exit with code 2 and write the reason to stderr (the error output).

Claude Code. Create .claude/settings.json with the hooks and the permission rules. This is the configuration I tested in a real session; the result is in “What the hook checks”.

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"],
    "ask": ["Bash(git push *)", "Bash(npm install *)", "Bash(npm i *)", "Bash(npm add *)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/block-dangerous-commands.mjs"],
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/format-after-edit.mjs"],
            "timeout": 30
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/check-architecture-before-stop.mjs"],
            "timeout": 120
          },
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/check-secrets-before-stop.mjs"],
            "timeout": 120
          },
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/check-quality-before-stop.mjs"],
            "timeout": 600
          },
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.agents/hooks/report-duplicates-before-stop.mjs"],
            "timeout": 120
          }
        ]
      }
    ]
  }
}

The command form with args requires Claude Code 2.1.139 or later. Also:

  • Instructions. Without a CLAUDE.md, Claude Code reads AGENTS.md since version 2.1.277, and each module’s one when it opens one of its files with Read, if that folder has no CLAUDE.md of its own. With an earlier version, create a CLAUDE.md with a single line, @AGENTS.md; then each module’s AGENTS.md depends on the agent reading it, as the root asks.
  • Subagent. Copy .agents/agents/module-developer.md to .claude/agents/module-developer.md, unchanged: Claude Code uses the same format and only requires name and description.
  • Skill. Copy the .agents/skills/clean-code-review/ folder into .claude/skills/.

Codex. It reads AGENTS.md and the skills in .agents/skills/ on its own. According to its release notes, since 0.150.0 it does not use the AGENTS.md of a project you have not marked as trusted. The hooks go in .codex/hooks.json, with the same configuration as in the hexagonal harness. For the subagent, Codex uses TOML files in .codex/agents/, with three required fields: name, description, and developer_instructions. Create .codex/agents/module-developer.toml and paste into developer_instructions the text below the header of module-developer.md:

name = "module-developer"
description = "Works on one module of the library API (catalog, members or loans) and changes nothing outside it. Use it for a task that stays inside one module, such as a new route or a new rule. Give it the module name and the task."
developer_instructions = """
You work on one module of the library API: `catalog`, `members` or `loans`.
(paste here the rest of the text of .agents/agents/module-developer.md)
"""

According to its documentation, Codex launches a subagent when you ask for it or when a project or skill instruction calls for it. Remember also that it only loads the AGENTS.md files between the root and the folder where you start the session: if you start it at the harness root, the module’s one depends on the agent reading it, as the root asks.

Cursor. It reads AGENTS.md, the ones in subfolders (in the editor), and the skills in .agents/skills/. Its subagents are Markdown files with a YAML header in .cursor/agents/, and it also reads the ones in .claude/agents/, so you can copy module-developer.md as it is. Its stop hook expects JSON with followup_message on standard output, so the stop hooks would need a small adapter, which I did not write.

I did not test Codex or Cursor: what I say about them comes from their documentation, read on October 21, 2026 for the instructions and the subagents, and between October 14 and 18 for the hooks.

What the hook checks

This section is about the module hook. The others are explained in the security piece, the quality piece, and the clean-code piece.

The hook is the script .agents/hooks/check-architecture-before-stop.mjs, the same as in the earlier harnesses with another message. Once connected, the agent runs it every time it tries to finish. The script runs npm run check:architecture. If it fails, it writes the output to stderr and exits with code 2, which in Claude Code means the agent cannot finish yet: the message goes back to the agent.

What I tested on October 21, 2026, on Fedora Linux 44 with Node 24.22:

  • npm run verify passed: types, lint, formatting, no dependency violations found (22 modules, 56 dependencies cruised), secretlint, and 70 of 70 tests. jscpd found no duplicates in src/.
  • I broke the main rule on purpose: in src/modules/loans/loans-service.ts I imported BookRepository from ../catalog/book-repository, an internal file of the catalog. npm run check:architecture failed with error modules-import-only-public-api: src/modules/loans/loans-service.ts → src/modules/catalog/book-repository.ts. I ran the hook from another folder with a simulated Stop event: it exited with code 2 in 0.8 seconds and showed Architecture check failed. Use other modules only through their index.ts before you finish.. With the correct code it exited with 0 in 0.9 seconds.
  • I broke each of the other rules once, and undid each change. Loans importing members/member.ts failed the main rule; app.ts importing catalog-service.ts failed composition-root-imports-only-public-api; src/shared/http.ts importing the catalog failed shared-does-not-import-modules; and members-service.ts importing app.ts failed modules-do-not-import-the-composition-root. The last two also failed no-circular. The catalog importing the loans index.ts passes the main rule, because it is a public API, but it failed no-circular. A loans file importing another loans file passed, as it should.
  • The pieces still work: with the loan limit set to 4, the quality hook exited with code 2 because 2 tests failed, one acceptance test and one loans module test.

In a real Claude Code session

I used Claude Code 2.1.307 in headless mode (claude -p), with the Sonnet 5.5 model, in a copy of the harness with the .claude/settings.json above, the skill in .claude/skills/, and the subagent in .claude/agents/. Claude Code recognized the module-developer subagent at the start. I ran four tests:

  1. A question. I asked what the loans module checks when it lends a book, and in what order, without changing anything. It read the loans AGENTS.md and loans-service.ts from the terminal, and listed the four checks correctly and in order. It took 22 seconds.
  2. Automatic loading. I asked it to open only src/modules/loans/loans-service.ts with Read and to say which AGENTS.md files were in its context. The session log shows that, at the start, it had only the root one, and that Claude Code added the loans one right after it opened the file. The agent named those two. It took 20 seconds.
  3. A task with the subagent. I asked it to use module-developer to add GET /loans/:id, which returns the loan or 404 LOAN_NOT_FOUND. The main agent passed it the module and the task, and asked it not to touch src/shared/ if the error code was missing. The subagent started with the root AGENTS.md in its context, read the loans one, and changed four files, all inside src/modules/loans/: the service (with a getLoan that returnLoan now uses too), the route, two new tests, and the route list in the module AGENTS.md. It ran npm run verify (72 tests), and the four stop hooks exited with code 0. It did not use the review skill. It took 58 seconds.
  4. A task that crosses modules. Without saying where, I asked for GET /members/:id/loans, which returns a member’s active loans or 404 MEMBER_NOT_FOUND. Even though the route starts with /members, it put it in the loans module, which owns that data, and checked the member with MembersApi.getMember. It did not touch the members module or delegate to the subagent. It wrote part of the changes with a Python script from the terminal, which the format hook does not see; the quality hook would have caught it. npm run verify passed with 72 tests, and the hooks exited with code 0. It took 54 seconds.

In these four sessions no one broke the rule, so the module hook had nothing to block; in the hexagonal harness I did test it blocking an agent. The instructions did the work: in three of the four sessions the agent read the module’s AGENTS.md itself, because the root asks it to, and in the other one Claude Code loaded it. These are four runs with one model, not a measurement.

Limitations

  • dependency-cruiser checks imports, not data. If a loan kept a copy of the book’s title, nothing would detect it, and the catalog would no longer be the only owner of that data.
  • The rules depend on names: a module is any folder inside src/modules/, and its public API is the index.ts file. Everything index.ts exports is public, so if it re-exports BookRepository, the rule accepts it.
  • dependency-cruiser looks for cycles between files, not between modules. A file that nothing imports, such as a test, can import a module that depends on its own module without a warning.
  • Each module’s AGENTS.md only helps if the agent reads it. The root asks for it, but that is an instruction, not a check. Claude Code loads it on its own only when it opens a file of the module with Read, not when it reads it with cat; Codex, according to its documentation, only loads the ones between the root and the folder where it starts.
  • In such a small app, splitting the instructions by module saves little: about 13 KB instead of 16.6 KB to work on loans.
  • No agent reads subagents from .agents/agents/. You have to copy the file to each agent’s folder, and convert it to TOML for Codex.
  • The stop hooks run on every stop, even when the agent only answers a question. On this machine, the module hook took 0.9 seconds, the secrets hook 0.5, the quality hook 10.1, and the duplicates hook 0.5. All four at once, as Claude Code runs them, took 9.9.
  • I only tested the connection with Claude Code, in headless mode. Codex and Cursor remain untested. The rule that blocks .env is not a sandbox; the security piece explains why.
  • Nothing technical stops the agent from changing the hooks, the permissions, or .dependency-cruiser.cjs. AGENTS.md forbids it, but that is an instruction, not a barrier.
  • I only tested it on Fedora Linux 44 with Node 24.22. I did not test it on Windows, on macOS, or with Node 22.

Next step

The event-driven harness, from day 8, also removes the calls between modules: each module publishes events and the others subscribe, with the same pieces. It compares its architecture with this one. You can see the full calendar in Harnesses by architecture.

Sources

Read on October 21, 2026, about the architecture:

Read on October 21, 2026, about per-folder instructions and subagents:

Read between October 14 and 18, 2026, to connect the hooks and the permissions:

  • Context engineering for agentsTechnique

    What information the agent receives at each moment, why more is not always better, and how to give it just enough: the essentials up front and the rest when it needs them.

    Published
  • Verification and evaluationTechnique

    How to check that the agent did the job right without taking its word for it: give it ways to verify itself, review both the result and the process, and compare setups honestly.

    Published