Starting point: the mini app without a harness

The app that every harness in the series shares, as it is: it works and has tests, but it has no harness and no defined architecture.

The key idea: before building harnesses, it helps to see the app without any. It is the reference that everything after it is compared with, just like the Base setup in the topic path.

What the mini app is

Think of the front desk of a neighborhood library: you register books and members, and you write down who takes which book and when they bring it back. The mini app does the same thing, as a small REST API.

It is written in TypeScript with Node 22 or later, Express, and Vitest. Data lives in memory: there is no database, so it starts empty every time it boots.

Request What it does
GET /books Lists the books
POST /books Registers a book
GET /members Lists the members
POST /members Registers a member
POST /loans Lends a book to a member
POST /loans/:id/return Records a return

The business rules

  1. A loaned book cannot be loaned again until it is returned.
  2. A member can have at most three active loans.

If a request breaks a rule, the app answers with an error and a clear code, such as BOOK_ALREADY_LOANED or LOAN_LIMIT_REACHED.

What is missing on purpose

All the code lives in one file, src/app.ts: routes, rules, and data together. The app works and the tests pass. What is missing is whatever helps an agent work on it without breaking anything:

  • No AGENTS.md. The agent does not know where each thing goes or which commands to run.
  • No hooks. Nothing forces it to pass the tests before it calls a task done.
  • No permissions. Nothing stops it from reading a sensitive file or installing dependencies without asking.
  • No architecture rules. The code can grow in any shape, and nobody checks it.

Each harness in the series adds these pieces, each one with its own architecture.

The code

This is the full code of the app. Choose a file to see its content. The files are in English, like the code.

import express, { type Express, type Request, type Response, type NextFunction } from 'express';

interface Book {
  id: string;
  title: string;
  author: string;
  available: boolean;
}

interface Member {
  id: string;
  name: string;
}

interface Loan {
  id: string;
  bookId: string;
  memberId: string;
  loanedAt: string;
  returnedAt: string | null;
}

const MAX_ACTIVE_LOANS = 3;

export function createApp(): Express {
  const app = express();
  const books: Book[] = [];
  const members: Member[] = [];
  const loans: Loan[] = [];
  let lastBookId = 0;
  let lastMemberId = 0;
  let lastLoanId = 0;

  app.use(express.json());

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

  app.post('/books', (req, res) => {
    const input = readInput(req);
    const title = readText(input.title);
    const author = readText(input.author);
    if (title === null || author === null) {
      return sendError(res, 400, 'INVALID_INPUT', 'Title and author are required.');
    }
    const book: Book = { id: String(++lastBookId), title, author, available: true };
    books.push(book);
    res.status(201).json(book);
  });

  app.get('/books/:id', (req, res) => {
    const book = findById(books, req.params.id);
    if (!book) {
      return sendError(res, 404, 'BOOK_NOT_FOUND', `Book ${req.params.id} does not exist.`);
    }
    res.json(book);
  });

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

  app.post('/members', (req, res) => {
    const name = readText(readInput(req).name);
    if (name === null) {
      return sendError(res, 400, 'INVALID_INPUT', 'Name is required.');
    }
    const member: Member = { id: String(++lastMemberId), name };
    members.push(member);
    res.status(201).json(member);
  });

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

  app.post('/loans', (req, res) => {
    const input = readInput(req);
    const bookId = readText(input.bookId);
    const memberId = readText(input.memberId);
    if (bookId === null || memberId === null) {
      return sendError(res, 400, 'INVALID_INPUT', 'bookId and memberId are required.');
    }

    // The order of these checks is part of the contract: the first failing check wins.
    const book = findById(books, bookId);
    if (!book) {
      return sendError(res, 404, 'BOOK_NOT_FOUND', `Book ${bookId} does not exist.`);
    }
    const member = findById(members, memberId);
    if (!member) {
      return sendError(res, 404, 'MEMBER_NOT_FOUND', `Member ${memberId} does not exist.`);
    }
    if (!book.available) {
      return sendError(res, 409, 'BOOK_ALREADY_LOANED', `Book ${bookId} is already loaned.`);
    }
    const activeLoans = loans.filter(
      (loan) => loan.memberId === member.id && loan.returnedAt === null,
    ).length;
    if (activeLoans >= MAX_ACTIVE_LOANS) {
      return sendError(
        res,
        409,
        'LOAN_LIMIT_REACHED',
        `Member ${memberId} has ${MAX_ACTIVE_LOANS} active loans.`,
      );
    }

    const loan: Loan = {
      id: String(++lastLoanId),
      bookId: book.id,
      memberId: member.id,
      loanedAt: new Date().toISOString(),
      returnedAt: null,
    };
    loans.push(loan);
    book.available = false;
    res.status(201).json(loan);
  });

  app.post('/loans/:id/return', (req, res) => {
    const loan = findById(loans, req.params.id);
    if (!loan) {
      return sendError(res, 404, 'LOAN_NOT_FOUND', `Loan ${req.params.id} does not exist.`);
    }
    if (loan.returnedAt !== null) {
      return sendError(res, 409, 'LOAN_ALREADY_RETURNED', `Loan ${loan.id} was already returned.`);
    }
    loan.returnedAt = new Date().toISOString();
    const book = findById(books, loan.bookId);
    if (book) {
      book.available = true;
    }
    res.json(loan);
  });

  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)) {
      return sendError(res, 400, 'INVALID_INPUT', 'Request body must be valid JSON.');
    }
    console.error(err);
    sendError(res, 500, 'INTERNAL_ERROR', 'Unexpected server error.');
  });

  return app;
}

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

function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
  return items.find((item) => item.id === id);
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

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.
function readText(value: unknown): string | null {
  if (typeof value !== 'string') {
    return null;
  }
  const text = value.trim();
  return text === '' ? null : text;
}

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 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');
  });
});
node_modules/
{
  "name": "library-starting-point",
  "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"
  },
  "dependencies": {
    "express": "5.3.0"
  },
  "devDependencies": {
    "@types/express": "5.0.6",
    "@types/node": "22.20.5",
    "@types/supertest": "7.2.1",
    "supertest": "7.3.1",
    "tsx": "4.23.15",
    "typescript": "5.9.3",
    "vitest": "5.0.4"
  }
}
# Library starting point

A small library REST API: books, members and loans. This is the starting point of the Agent Atlas harness series: the app works, but it has no harness and no defined architecture.

## Run it

```bash
npm install
npm test
npm run dev
```

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

## Endpoints

| Method | Path                | What it does                                          |
| ------ | ------------------- | ----------------------------------------------------- |
| GET    | `/books`            | List all books                                        |
| POST   | `/books`            | Add a book. Body: `{ title, author }`                 |
| GET    | `/books/:id`        | Get one book                                          |
| GET    | `/members`          | List all members                                      |
| POST   | `/members`          | Add a member. Body: `{ name }`                        |
| GET    | `/loans`            | List all loans                                        |
| POST   | `/loans`            | Lend a book to a member. Body: `{ bookId, memberId }` |
| POST   | `/loans/:id/return` | Return a loan                                         |

## Business rules

1. A book with an active loan cannot be loaned again until it is returned.
2. A member can have at most 3 active loans.

## What is missing on purpose

- No `AGENTS.md` or other agent instructions.
- No hooks.
- No permission rules.
- No architecture rules or linters.
- The only checks are the TypeScript compiler (`npm run typecheck`) and the test suite (`npm test`).

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 computer.

In the browser, the Run in the browser button opens the app in StackBlitz in a new tab, installs the dependencies, and runs the tests without copying any file. It needs JavaScript.

On your computer, copy the files into a folder and run:

npm install
npm test
npm run dev

npm test runs the tests, and npm run dev starts the API at http://localhost:3000.

The tests, the contract between harnesses

The test/library.test.ts file has eleven acceptance tests. They talk to the app only through HTTP: they create books and members, lend, return, and check the errors. They do not look at how the code is organized inside.

That is why the same file works for any architecture. Every harness in the series has to pass these tests without changing them. If a harness passes them, the app does the same thing as here; what changes is how it is organized and what help the agent gets.

What gets checked today

There are no hooks here, so nothing runs on its own. The only checks are the ones someone runs by hand: the tests (npm test) and the type check (npm run typecheck).

On October 12, 2026, I installed the dependencies and ran both checks with Node 24: all eleven tests passed and the type check reported no errors.

On October 13, 2026, I also tried the Run in the browser button in Chromium: StackBlitz installed 137 packages and all eleven tests passed about 30 seconds after the click. I did not test it in Firefox or Safari.

Limitations

  • The app is small on purpose. It is useful for comparing harnesses, not for measuring how an agent works on a large project.
  • In-memory data keeps the example simple, but it leaves out real problems such as migrations or concurrency.
  • This page does not compare agents or models: it only presents the base the harnesses are built on.

Next step

The first harness, the Layered harness, organizes this same app in layers and adds instructions, hooks, and permissions. To choose between the four harnesses of the series, the guide How to choose a harness compares them. You can see the full calendar in Harnesses by architecture.

Sources

Accessed on October 12, 2026:

  • AGENTS.md: persistent project instructionsTechnique

    A Markdown file at the root of the repository that tells the agent how your project works: commands, conventions, and how to check changes. It is a guide, not a control mechanism.

    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
  • 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