Piece: quality
Two hooks and a few ESLint rules that keep formatting, lint, types, and tests passing without asking the agent. It comes from the layered harness and works in any harness of the series.
Before you start
- Layered harnessHarness
The mini app organized in layers (controllers, services, and repositories), with instructions for the agent and a hook that stops it from finishing if it breaks the layer rule.
Published
The key idea: the agent does not have to remember to format, run the linter, or run the tests. One hook formats each file right after the agent edits it. Another hook, at the end, runs the formatting check, the linter, the type checker, and the tests, and does not let the agent finish until everything passes.
What problem it prevents
You can write in AGENTS.md: “run the tests and the linter before you finish”. The agent almost always does. But “almost always” is not enough, and some mistakes get through even when it does:
- Messy formatting. The agent writes code that works, but in another style: double quotes, very long lines. The diff fills up with changes that do not matter, and reviewing it takes longer.
- Functions that keep growing. To handle a new case, an agent tends to add one more
ifto the function it is already editing. It works, but each time it reads worse. - Green tests with broken types. Vitest runs TypeScript without checking the types. If the agent only runs
npm test, a type error gets through and nobody sees it. - Silencing the linter. If a rule gets in the way, the agent can add an
eslint-disablecomment and move on.
Think of the spell checker in a word processor and the editor of a magazine. The spell checker fixes typos while you write, without asking. The editor does not let the article go out until it is right. The piece has both: one hook that formats right away and another that checks everything at the end.
The layered harness already had ESLint and Prettier, but only as commands: the agent had to remember to run them. This piece runs them on its own and adds a few rules meant for agents. The layered harness now uses this version.
What files it adds
| Part | Files | What it does |
|---|---|---|
| Format on edit | .agents/hooks/format-after-edit.mjs |
After the agent writes or edits a file, formats it with Prettier. If Prettier cannot read it, for example because of a syntax error, the agent sees the error. |
| Checks at the stop | .agents/hooks/check-quality-before-stop.mjs |
When the agent tries to finish, runs npm run format:check, npm run lint, npm run typecheck, and npm test. If one fails, the agent cannot finish yet. |
| ESLint rules | eslint.config.js |
The recommended rule sets, four limits on the size of a function, and eslint-disable comments turned off. |
| Formatting rules | prettier.config.mjs, .prettierignore |
The Prettier style and the files it skips. |
| Instructions | The Quality section of AGENTS.md |
Tells the agent what the hooks do and what it must not change to pass a check. |
| Tests | test/ |
Run both hooks the way an agent does and check what they change, what they report, and the exit code. |
A hook is a command that the agent’s tool runs on its own at a specific moment; the topic on hooks explains it. Why the agent should check its work with tests, types, and a linter is explained in Verification and evaluation.
The ESLint rules
The setup starts from the recommended rule sets of ESLint and typescript-eslint, which already flag, for example, the any type and the @ts-ignore comment. On top of them it adds a few rules, and each one has the reason it is there written in the file:
| Rule and limit | Why |
|---|---|
complexity: 10 |
Counts the paths a function can take: each if, loop, or && adds one. ESLint uses 20 by default; with 10, the function gets split sooner. |
max-depth: 3 |
Limits how many blocks sit inside one another. Deep nesting usually calls for an early return. |
max-params: 4 |
A function with many parameters is easy to call the wrong way. |
max-lines-per-function: 50 |
Not counting blank lines or comments. It does not apply to tests, because a describe block groups many short tests. |
noInlineConfig |
ESLint ignores eslint-disable comments. An exception has to go in eslint.config.js, where a reviewer sees it. |
eqeqeq and consistent-type-imports |
They come from the layered harness: === instead of ==, and imports that only bring types marked as import type. |
The four limits work against the habit of adding one more branch to the function that already exists. The values are a starting point, not a scientific measure. The code of the layered harness meets them without changes.
noInlineConfig is the most interesting rule for an agent. In the security piece, nothing technical stops the agent from hiding a key with a secretlint-disable comment: only AGENTS.md forbids it. Here there is a barrier. If the agent writes // eslint-disable-next-line, ESLint warns that the comment has no effect and still reports the error. The agent could still change eslint.config.js, but that change shows up in the diff.
How the format hook works
- It reads the path of the edited file from the JSON input. It looks in
tool_input.file_path(the way Claude Code sends it), infile_path(Cursor), or in the headers of a patch insidetool_input.command, such as*** Update File: src/app.ts, because Codex edits with patches. - It only touches files in its own project and follows
.prettierignore. It skips files that Prettier does not know. - It starts the Prettier script in
node_modulesdirectly withnode, instead of usingnpx prettier.npxstarts npm first, which would add time to every edit. - It is a help, not a barrier: if the input is not JSON or names no file, it does nothing. The guarantee is the stop hook, which checks the formatting of every file, including the ones the agent writes from the terminal, which this hook never sees.
How the stop hook works
It follows the same contract as the rest of the series. It finds the project root from its own location and runs the four commands even if one fails, so the agent gets every problem at once. If any of them fails, it writes the output to stderr (the error output) and exits with code 2. If everything passes, it exits with code 0 and writes nothing.
It runs npm run typecheck besides the linter and the tests because, as the Vitest documentation says, tests do not check types unless you ask for it. I checked it in the layered harness: with a type error, the 65 tests still passed.
The explorer
When it loads, the explorer opens AGENTS.md. The piece has no mini app: only its settings, its hooks, and the tests of those hooks. The dependencies and package-lock.json are not shown.
.agents/hooks/check-quality-before-stop.mjs
// 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)}`;
}.agents/hooks/format-after-edit.mjs
// 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;
}test/check-quality-before-stop.test.ts
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);
});
});test/format-after-edit.test.ts
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('');
});
});.gitignore
node_modules/.prettierignore
node_modules/
package-lock.jsonAGENTS.md
# AGENTS.md
## Project
This folder is the **quality piece** of the Agent Atlas harness series. It is not an app: it holds the formatting and lint settings, two hooks and the tests of those hooks, ready to add to a harness. The layered harness (`../layered/`) already includes it.
Use npm in this folder, not pnpm. Run `npm run verify` before you say a task is done.
The `Quality` section below is the one to paste into the `AGENTS.md` of a harness.
## 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.
## Files
| File | What it does |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `.agents/hooks/format-after-edit.mjs` | Runs after the agent writes or edits a file and formats that file with Prettier |
| `.agents/hooks/check-quality-before-stop.mjs` | Runs when the agent tries to finish and fails if formatting, lint, types or tests fail (exit code 2) |
| `eslint.config.js` | The ESLint rules: the recommended sets, a few limits on the size of a function, and no `eslint-disable` |
| `prettier.config.mjs`, `.prettierignore` | The Prettier settings and the files it skips |
| `test/` | Runs both hooks the way an agent does and checks what they change, what they report and their exit codes |
## Verification
Run these from this folder:
- `npm run format:check`: Prettier. Use `npm run format` to fix formatting.
- `npm run lint`: ESLint.
- `npm run typecheck`: TypeScript, for the tests.
- `npm test`: the tests of both hooks.
- `npm run verify`: all of the above, in that order.eslint.config.js
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' },
},
);package.json
{
"name": "harness-piece-quality",
"private": true,
"type": "module",
"engines": {
"node": ">=22"
},
"scripts": {
"test": "vitest run",
"typecheck": "tsc --noEmit",
"lint": "eslint .",
"format": "prettier --write .",
"format:check": "prettier --check .",
"verify": "npm run format:check && npm run lint && npm run typecheck && npm test"
},
"devDependencies": {
"@eslint/js": "10.0.1",
"@types/node": "22.20.5",
"eslint": "10.12.0",
"globals": "17.13.0",
"prettier": "3.9.10",
"typescript": "5.9.3",
"typescript-eslint": "8.71.2",
"vitest": "5.0.4"
}
}prettier.config.mjs
/** @type {import('prettier').Config} */
export default {
printWidth: 100,
semi: true,
singleQuote: true,
trailingComma: 'all',
};README.md
# Quality piece
A reusable part of the Agent Atlas harness series. It keeps the formatting, the lint, the types and the tests passing without you having to ask the agent. It started as the ESLint and Prettier setup of the [layered harness](../layered/), and the layered harness now uses this version.
It is not an app. It holds the settings, two hooks and their tests, so you can check the hooks before you copy them into a harness.
## Run it
```bash
npm install
npm run verify
```
## What it adds to a harness
| Part | Files | What it does |
| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Format after an edit | `.agents/hooks/format-after-edit.mjs` | After the agent writes or edits a file, formats that file with Prettier. If Prettier cannot parse it, the agent sees the error. |
| Checks at the stop | `.agents/hooks/check-quality-before-stop.mjs` | When the agent tries to finish, runs the formatting check, ESLint, TypeScript and the tests. If one fails, the agent cannot finish yet. |
| Lint rules | `eslint.config.js` | The recommended sets, limits on the size of a function (complexity, nesting, parameters and lines), and `eslint-disable` comments turned off. |
| Formatting rules | `prettier.config.mjs`, `.prettierignore` | The Prettier settings and the files it skips. |
| Instructions | The `Quality` section of `AGENTS.md` | Tells the agent what the hooks do and what it must not change to pass a check. |
Both hooks follow the same contract as the rest of the series: they find the project root from their own location, read no agent-specific environment variable, and report a problem with exit code 2 and the reason on stderr. Exit code 0 with no output means "go on".
The format hook reads the edited file from `tool_input.file_path` or `file_path`, or from the file headers of a patch (`*** Update File: <path>`) in `tool_input.command`. It runs `node node_modules/prettier/bin/prettier.cjs` instead of `npx prettier`, which would start npm first.
## Add it to a harness
1. Copy `.agents/hooks/format-after-edit.mjs`, `.agents/hooks/check-quality-before-stop.mjs`, `eslint.config.js`, `prettier.config.mjs`, `.prettierignore` and the two files in `test/` into the harness.
2. Install the tools with `npm install --save-dev --save-exact eslint @eslint/js typescript-eslint globals prettier`. The harness also needs TypeScript and Vitest.
3. Add the scripts `"lint": "eslint ."`, `"format": "prettier --write ."`, `"format:check": "prettier --check ."` and `"typecheck": "tsc --noEmit"` to `package.json`, and add them to the harness's `verify` script.
4. If the harness has another stop hook that runs `npm test`, remove `npm test` from it. This piece runs the tests now.
5. Paste the `Quality` section of `AGENTS.md` into the harness's `AGENTS.md`.
6. Connect the hooks to your agent (next section).
7. Run `npm run format` once, then `npm run verify`.
## Connect it to your agent
Agents do not share a settings format, so the files in `.agents/` do nothing on their own. Each agent's own settings point to them:
- **After an edit:** register `node .agents/hooks/format-after-edit.mjs` on the event that runs after the agent writes or edits a file.
- **Stop:** register `node .agents/hooks/check-quality-before-stop.mjs` on the event that runs when the agent is about to finish.
The Agent Atlas page for this piece shows the settings for some agents and says what was tested: <https://agentatlas-dev.vercel.app/en/harnesses/quality/>.
## Checks
| Command | What it checks |
| ---------------------- | ------------------------------------------ |
| `npm run format:check` | Prettier formatting |
| `npm run lint` | ESLint |
| `npm run typecheck` | TypeScript types of the tests |
| `npm test` | Both hooks, run the way an agent runs them |
| `npm run verify` | All of the above, in order |
## Limits
- The format hook only sees edits made with the agent's file tools. A file written from the terminal is not formatted until someone runs `npm run format`; the stop hook catches it.
- The stop hook runs every check on every stop, so a slow test suite makes every stop slow.
- ESLint finds long or tangled functions, not bad names or a wrong design. That still needs a review.
- Tests only prove what they check. The stop hook cannot tell a good test from a weak one, and nothing technical stops the agent from weakening a test or changing the settings. `AGENTS.md` forbids it, but that is an instruction, not a barrier.
- How many times in a row a stop hook can send the agent back depends on the agent. The scripts do not limit it.tsconfig.json
{
"compilerOptions": {
"strict": true,
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"noEmit": true,
"types": ["node"],
"skipLibCheck": true,
"noUncheckedIndexedAccess": true,
"verbatimModuleSyntax": true
},
"include": ["test"]
}How to use it
You can run the piece’s tests in the browser or on your computer.
In the browser, the Run in the browser button opens the piece in StackBlitz, an external service, in a new tab. StackBlitz installs the dependencies and runs npm test: 12 tests that start both hooks the way an agent would. On October 16, 2026, I tested it in Chromium 152 with the “Open StackBlitz in this tab” button: all 12 tests passed, and its terminal measured 33 s to install the dependencies and run them. I did not test it in Firefox or Safari, or with the new-tab button.
StackBlitz is an external service and opens in a new tab. It works best in Chrome and Edge; in Firefox and Safari it is in beta. The first run takes a while because it installs the dependencies.
On your computer you need Node 22 or later. Copy the piece’s files into a folder and run, with npm:
npm install
npm run verify
npm run verify checks the formatting, runs ESLint, checks the types of the tests, and runs the 12 tests.
Add it to a harness
- Copy
.agents/hooks/format-after-edit.mjs,.agents/hooks/check-quality-before-stop.mjs,eslint.config.js,prettier.config.mjs,.prettierignore, and the two files intest/into the harness. - Install the tools with
npm install --save-dev --save-exact eslint @eslint/js typescript-eslint globals prettier. The harness also needs TypeScript and Vitest. - Add the
lint,format,format:check, andtypecheckscripts topackage.json(they are in the piece’spackage.json), and add them to theverifyscript. - If the harness has another stop hook that runs
npm test, remove it from there: this piece runs the tests now. - Paste the
Qualitysection of the piece’sAGENTS.mdinto the harness’sAGENTS.md. - Connect the hooks to your agent, as the next section explains.
- Run
npm run formatonce, thennpm run verify.
That is how I added it to the layered harness. The new ESLint rules did not require any change to its code. Its stop hook, which ran the layer rules and the tests, was renamed check-architecture-before-stop.mjs and now only checks the layers. The tests went from 53 to 65, and the harness has three stop hooks: architecture, secrets, and quality.
On day 6 I copied the piece without changes into the hexagonal harness: the same files and the same 12 tests. Its code met the ESLint rules on the first try.
On day 7 I also copied it without changes into the modular monolith harness. The tests of its loans module live inside src/, next to the code, and the linter checks them too; they met the rules on the first try.
On day 8 I copied it without changes into the event-driven harness. There the linter also checks scripts/check-events.ts, the command that draws the event map, and the new code met the rules on the first try. This piece’s stop hook is the one that catches an event with another shape, because npm run typecheck or the tests fail.
Connect it to your agent
Each agent reads hooks from its own settings. Those files are not part of the piece: create them yourself in the harness folder. If you already connected other pieces, add these hooks to the same settings.
Claude Code. In .claude/settings.json:
{
"hooks": {
"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-quality-before-stop.mjs"],
"timeout": 600
}
]
}
]
}
}
PostToolUseis the moment after a tool is used, andEdit|Writecovers the two tools Claude Code writes files with. Its hooks guide has a similar example with Prettier. According to its documentation, a file changed from the terminal does not trigger this hook.- If the format hook exits with code 2, Claude Code shows the reason to the agent, but the edit is already made: it is not undone.
- Claude Code runs the stop hooks every time it finishes a response, not only at the end of a task, and it runs them all in parallel. In the layered harness, the wait is that of the slowest hook, which is this one.
timeoutis in seconds. 600 is Claude Code’s default for a command hook; I write it out to make it clear that the stop hook can take a while.
Codex. In .codex/hooks.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "^apply_patch$",
"hooks": [
{
"type": "command",
"command": "node .agents/hooks/format-after-edit.mjs",
"timeout": 30
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "node .agents/hooks/check-quality-before-stop.mjs",
"timeout": 600
}
]
}
]
}
}
- Codex edits files with the
apply_patchtool. According to its documentation, the hook receives it with the patch intool_input.command. I took the shape of the patch headers, such as*** Update File: <path>, from the tests in Codex’s source code, not from its documentation. - If the format hook exits with code 2, Codex replaces the tool result with the hook’s message.
- Its documentation says that, at the stop, it expects JSON on standard output when the hook exits with code 0. The stop hooks of the series write nothing in that case, and I could not check whether Codex accepts that.
- As with the other pieces, open it in the harness folder and mark the hooks as trusted with
/hooks.
Cursor. In .cursor/hooks.json:
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"type": "command",
"command": "node .agents/hooks/format-after-edit.mjs",
"timeout": 30
}
]
}
}
According to its documentation, afterFileEdit runs after the agent edits a file, is useful for formatters, and sends the absolute path in file_path, which is where the script looks for it. It does not say what it does with this hook’s output. Its stop hook expects JSON with followup_message on standard output, so the stop hook would need a small adapter, which I did not write.
I did not test any of these settings in a real session. They come from each agent’s documentation, consulted on October 16, 2026.
What can be automated and what cannot
| What | What handles it | What gets through |
|---|---|---|
| Formatting | The format hook on edit and format:check at the stop |
Nothing, if both are connected: what the first one misses, the second one stops. |
| Lint errors | ESLint in the stop hook | Whatever the rules do not look at. |
| Long or tangled functions | The four ESLint limits | A short function that is badly thought out. |
| Silencing the linter | noInlineConfig |
A change to eslint.config.js, which shows up in the diff. |
| Type errors | npm run typecheck in the stop hook |
What TypeScript cannot know, such as bad data that arrives over HTTP. |
| Failing tests | npm test in the stop hook |
A test that was weakened or deleted. |
| Whether the tests check what matters | You | Not automated. |
| Clear names and a good design | You | Not automated. The clean-code piece gives the agent rules and a review. |
What was checked
What I tested on October 16, 2026, on Windows 11 with Node 24.19:
- In the piece,
npm run verifypassed: formatting, lint, types, and 12 of 12 tests. - In the layered harness, with the piece added,
npm run verifypassed: types, lint with the new rules, formatting,no dependency violations found (15 modules, 39 dependencies cruised), secretlint, and 65 of 65 tests. - I broke a test on purpose: I changed the loan limit from 3 to 4. The quality hook exited with code 2 in about 13 seconds, showing
$ npm testand the 2 tests that failed. Then I undid it. - I changed the return type of
addinbook-service.tsfromBooktonumber.npm testpassed all 65 tests, but the hook exited with code 2 because ofnpm run typecheck, witherror TS2322. Then I undid it. - I added
// eslint-disable-next-lineabove a variable of typeany. ESLint warned that the comment had no effect and still reported theanyas an error. - I wrote an unformatted file from the terminal, without going through the format hook. The stop hook exited with code 2 because of
npm run format:check. - I gave the format hook an input like Claude Code’s, with a Windows path. It formatted the file in 0.45 to 0.53 seconds.
- The layers hook still works: with an import of
BookRepositoryin a controller, it exited with code 2 in about 2.4 seconds.
Times with correct code: the quality hook took about 11 seconds in the piece and about 14.5 in the layered harness. The slowest parts are the tests (4 to 8 seconds in the harness), the linter (about 4), and the type check (about 2.5). Each command starts through npm, which adds almost a second. In the layered harness, the three stop hooks started at the same time, as Claude Code does, took about 15 seconds. The layers hook takes about 2.4 and the secrets hook about 1.5.
In StackBlitz, with Chromium 152 and the same-tab button, the piece’s 12 tests passed (33 s in its terminal), and so did the layered harness’s 65 (38 s). On October 18, StackBlitz was slower and 5 format hook tests failed in the layered harness because they went over Vitest’s 5-second limit. I raised their limit to 30 seconds; after that, the piece’s 12 tests passed (37 s in its terminal), and so did all of the harness’s. The hook tests create their fake projects in the system’s temporary folder, not inside the project. That way they do not clash with the layered harness’s secret scanner, which reads every file while the other tests run and could fail if a file disappeared halfway through.
What I could not test: a real agent session. The machine’s Claude Code CLI (2.1.220) was still logged out. On October 15, Codex said the account had reached its usage limit until November 2, so I did not try it. Cursor is not installed. I tested the hooks with simulated inputs, like the ones the documentation describes.
Limits
- The format hook only sees the edits the agent makes with its file tools. A file written from the terminal is not formatted on its own:
format:checkcatches it at the stop, and the agent has to runnpm run format. - The stop hook runs everything on every stop, also when the agent only answers a question. On that machine it took between 11 and 15 seconds, and a slow test suite would make every stop slow.
- ESLint measures how long and tangled a function is, not whether its names or design are good.
- The hook cannot tell a good test from a weak one. Nothing technical stops the agent from weakening a test, changing
eslint.config.js, or touching the hooks.AGENTS.mdforbids it, but that is an instruction, not a barrier. - How many times in a row the stop hook can send the agent back depends on the agent. The script does not limit it.
- I only tested it on Windows 11 with Node 24.19.
Next step
The clean-code piece, from day 5, separates the part of clean code that can be automated from the part that still needs judgment. You can see the full schedule in Harnesses by architecture.
Sources
Consulted on October 16, 2026:
- Hooks reference, Claude Code documentation.
- Get started with hooks, Claude Code hooks guide. It includes an example that formats with Prettier after edits.
- Tools reference, Claude Code documentation.
- Hooks, Codex documentation.
- Codex hook tests, Codex source code.
- Hooks, Cursor documentation.
- complexity, max-depth, max-params, and max-lines-per-function, ESLint rules.
- Configure rules, ESLint documentation. It explains
noInlineConfig. - CLI, Prettier documentation.
- Testing types, Vitest documentation.
Related content
- Hooks: checks that run on their ownTechnique
Commands that run automatically at specific moments of the agent’s work, such as before editing a file or when it finishes, so the important steps do not depend on the agent remembering 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