Agent task recipes

Minimal operating templates for dependencies, HTTP, subprocesses, files, and migration probes

Add a dependency

Precondition: verify that Bun is the repository's package manager and locate the correct workspace.

bun add zod
bun run typecheck
bun test

Acceptance: package.json and bun.lock agree, lifecycle behavior did not change unexpectedly, and relevant tests pass.

Implement an HTTP route

const server = Bun.serve({
  routes: {
    '/api/items/:id': async (request) => {
      const id = request.params.id;
      if (!/^\d+$/.test(id)) {
        return Response.json({ error: 'invalid id' }, { status: 400 });
      }
      return Response.json({ id: Number(id) });
    },
  },
  fetch: () => Response.json({ error: 'not found' }, { status: 404 }),
});

First check whether the project already has a router, error schema, authentication, and logging. Existing architecture outranks this minimal sample.

Spawn a process

const proc = Bun.spawn(['git', 'status', '--short'], {
  stdout: 'pipe',
  stderr: 'pipe',
});

const [stdout, stderr, exitCode] = await Promise.all([
  new Response(proc.stdout).text(),
  new Response(proc.stderr).text(),
  proc.exited,
]);

if (exitCode !== 0) throw new Error(stderr);
console.log(stdout);

Do not concatenate user input into a sh -c string.

Read and write files

const configFile = Bun.file('./config.json');
if (!(await configFile.exists())) throw new Error('config.json is missing');

const config = await configFile.json();
await Bun.write('./dist/config.json', JSON.stringify(config, null, 2));

Resolve the target and overwrite authority first. Use atomic writes or existing project helpers for important data.

Minimal migration probe

bun install
bun run typecheck
bun test
bun run build

Record the exit code and failure class at every step. Four passing commands still do not prove production compatibility.