Specify the Work Surface

Failure pattern

The raw coding agent starts from a vague request:

Fix onboarding.

The model opens the repo, edits auth redirect logic, changes onboarding copy, touches dashboard state, and adds a partial test. The output looks productive, but the work is not bounded. A reviewer cannot tell which behavior was supposed to change.

Reproduce the failure

const response = await model.complete({
  messages: [{ role: "user", content: "Fix onboarding." }],
});

This is not a work surface. There is no user-visible behavior, in-scope file area, out-of-scope boundary, required evidence, or stop condition.

Successful Anvia pattern

Use Anvia to make the first step a structured work-surface brief. The agent must define the bounded coding task before it can implement.

import { z } from "zod";
import { AgentBuilder } from "@anvia/core";

const WorkSurface = z.object({
  behavior: z.string(),
  entryPoints: z.array(z.string()),
  inScope: z.array(z.string()),
  outOfScope: z.array(z.string()),
  requiredEvidence: z.array(z.string()),
  stopCondition: z.string(),
  readyToImplement: z.boolean(),
});

const codingAgent = new AgentBuilder("repo-coding-agent", model)
  .instructions(`
You are a coding agent working inside a SaaS repository.
Before editing, turn vague requests into a bounded work surface.
Keep one user-visible behavior active at a time.
If the behavior, evidence, or scope is unclear, return readyToImplement=false.
`)
  .outputSchema(WorkSurface)
  .defaultMaxTurns(2)
  .build();

Why it succeeds

The successful pattern changes the first output from “start changing code” into “name the job.” The agent may still propose a fix, but the harness first asks whether the request is narrow enough to implement.

Success check

The run is successful when the agent returns something like:

Field	Example
behavior	invited user lands in workspace setup after accepting a valid invite
entryPoints	/invite/:token, invite acceptance e2e test
inScope	token validation, membership creation, redirect target
outOfScope	email copy, billing trial state, dashboard redesign
requiredEvidence	failing test before patch, passing test after patch
stopCondition	upstream auth callback bug discovered

Next move

Only after readyToImplement=true should the agent receive tools that can read files, run tests, or prepare a patch.