Workflow

The first call is discovery: why the init prompt sets the frame for everything after

The first time a build agent calls TheDesignAgent with no prior context, something different happens. Not just a score — an inference of domain, persona, jobs, and day-shape. Every evaluation that follows is calibrated to what was learned here.

The first time a build agent calls TheDesignAgent with no prior project context — no stored profile, no previous calls — the response type is call_type: "init". Something different happens on this call. Not just a score and a set of patches. A discovery: the system infers the domain, builds a persona profile, constructs a job registry, and produces a .thedesignagent file for the agent to commit to the repo. Every score that follows is calibrated to what was learned here.

This makes the init call the most consequential one. A generic init produces generic scores. A rich init produces scores that are specific to the actual people using the actual product.

What discovery infers

From the task description and artifact the agent provides, discovery builds out three things.

The domain profile: what kind of product is this, what operational context does it operate in, what cognitive costs matter most in this domain. Domain is used to set the load weightings — the relative severity of extraneous load penalties, the tolerance for deliberation, the expected expertise level of users. A warehouse ops tool gets a different baseline than a financial review tool.

The personas: who uses this product, what are their cognitive characteristics, and what does their workday look like. Each persona gets a cognitive profile (working memory capacity, time pressure, expertise level, multitasking demand, risk tolerance) and a day-shape — the map of jobs they move between across a typical day. This is the frame that makes "is this good for the user" a specific question rather than a general one.

The job registry: every job the personas do in the product, with priority, frequency, and cognitive requirements per job. Each call after init specifies which job the current artifact is serving. The jtbd_alignment score is evaluated against the requirements of that specific job — not against a generic "user job" abstraction.

Pattern: the init call is not a config step. It's the moment the system learns who your users are and what they're actually trying to do. The richer the context you provide here, the more specific every score will be.

What the agent gets back

On an init call, the response includes everything that a graded call includes — fit score, patches, flags — plus two additional outputs.

captured_context is the full discovery output: the domain profile, personas, job registry, and active job identification. It's surfaced for transparency so you can review what the system inferred and correct anything that's wrong. If the persona profile missed a key cognitive characteristic, or the job registry missed a job that matters, this is where you see it.

tda_file is the content to write to .thedesignagent in the repo root. This file is the project identity — it's how subsequent calls from any agent on this repo get associated with the same project context without re-running discovery. The build agent is expected to commit this file. Once it's in the repo, every agent that clones or pulls the repo inherits the project context automatically.

How to get more from the first call

Discovery infers from what it receives. A task description that says "build a tool for the warehouse team" produces a narrower inference than one that says "build an order fulfillment interface for warehouse operators doing pick-pack-ship workflows, approximately 200 orders per shift, time pressure is high." Both produce a usable discovery. The second one produces a more accurate persona with more specific load weightings.

Providing codebase_context on the init call — a summary of the existing product, the tech stack, the current user base, the domain — produces the richest inferences. If you're adding a new feature to an existing product, include a brief description of what the product does and who uses it. The discovery will fold that into the domain profile and produce a persona that reflects the actual user rather than an archetype of the domain.

What happens when it's wrong

Discovery is inference. It will occasionally get something wrong — a domain assumption that doesn't fit, a persona cognitive profile that's off, a job registry that missed a key job. The captured_context output is designed for exactly this: review it, find what's off, and update the .thedesignagent file directly. The file is plain JSON; the fields map directly to the captured context output.

Future calls will pick up the updated file. The next score after a correction will reflect the more accurate profile. The system doesn't require a reset — the correction propagates forward.