What the code can't tell an agent

Agents on the team is a series about putting AI agents to work at a real company. That company is Wonderby, a Metorial customer that builds booking and scheduling software for beauty businesses. We're working with their team to bring agents into the day-to-day work of development, design, marketing, and support.

We'll connect the agents to Wonderby's tools through Metorial integrations and share skills (packaged instructions any agent on the team can reuse) as we go. Each post comes with a prompt you can hand to your own agent, since you'd probably ask an AI to help with the setup anyway.

This first post covers company knowledge: a handful of files that explain what the company does and why. The full setup prompt walks through every step, or you can copy individual sections as you read.

Teach the agent what Wonderby does

Wonderby works a lot like Fresha. If you run a barbershop, or you've booked a haircut at one, you'll recognize the idea.

An agent that reads our code will figure out how a booking works. What it may never find out is why we changed a business rule, why we dropped a plan, or what fix we promised a customer. I don't want to explain that again in every chat.

Why we're keeping the knowledge in files

In her talk "Learning while you sleep: Beyond memory to dreaming", Lamis Mukta describes keeping agent memory in ordinary files, with the agent loading only the notes a given job needs. Her case for it is short: "file systems are great. You can just fill them up with markdown."

She also draws a line between an agent's own scratch notes and the knowledge the whole organization shares, and the shared part is where guardrails matter:

We're bringing both ideas to Wonderby. People maintain the company notes, and agents read them. The notes live in their own Git repo, wonderby-headquarters, so a tech lead, designer, or product owner can edit them without touching any app repo.

These files are where the guardrails go, the rules we expect every agent to follow. I suspect this kind of work is going to take up more of our time. An agent may well know how to do a job better than we do, but deciding what it must not change, assume, or promise is still on us.

There's one exception, and only to get started. With our approval, an agent writes an uncommitted first draft from sources we've already reviewed, and people correct and approve it. After that, only people edit the eleven knowledge files. Agents can read them and suggest changes, but an owner makes the edit.

The files and who will update them

Here's the structure. Each area has an owner and a specific event that triggers an update:

# wonderby-headquarters

- [Business and product](business-and-product/overview.md)
- [Development](development/overview.md)
- [Marketing](marketing/overview.md)
- [Design](design/overview.md)
- [Support](support/overview.md)

index.md is just links with short labels. Each overview describes where that part of the company stands today, and its changelog records what changed, when, and why, with links to the decision or the work behind it. So when we drop a plan, we update the overview and the reason stays in the changelog.

One person can own several areas, and your company may split them differently.

This looks a lot like a task tracker. Why not just let the agent read Linear directly?

Because task trackers get messy. Several directions are open at once, priorities move when a customer needs something, and plans change or quietly disappear. All of that is useful evidence, but someone still has to decide what it means for the company.

Say we test a coral upgrade button against the old violet one on the pricing page. An agent reading that issue could easily conclude we're rebranding and start turning every button coral. We're only changing upgrade buttons, and the design notes say exactly that.

The eleven files only change when something important does, and people decide what goes in them. That gives agents a stable account of the company to read alongside the noisier record of day-to-day work.

Gather the starting facts

We connect Linear and Google Drive through Metorial. Linear is where the work is tracked, and Drive has the documents, spreadsheets, and PDFs we picked as sources. The Metorial CLI, our command-line tool, sets up both connections and installs them in whichever agent we're using.

LinearThe work

Google DriveDocs, sheets, and PDFs

MetorialApproved sources, read-only

Your agentWith Metorial Magic MCP connected

The prompt starts by asking about your company and who owns each area. Then it connects Linear and Google Drive to one Metorial MCP server and adds that server to your agent. MCP, the Model Context Protocol, is the standard agents use to reach outside tools, so one server gives the agent both. Whenever you need to sign in or approve something in the browser, the prompt stops and waits for you.

The agent also reads our public pages, meaning the website, the pricing page, and the app store listings, because those show what we promise customers today. If it can't open a file, it says so rather than guessing.

Create the starting notes once

With the sources approved, the agent can prepare the first draft. Every overview lists its owner, its sources, and the date they were checked. Every changelog starts with a single snapshot dated the day we run the task. We don't reconstruct a history from old tickets.

Then the owners review and correct the draft, and the prompt waits until they approve it. This is the step where we decide which facts and rules make it into the company notes. If knowledge files already exist, the setup stops, so it can't overwrite our edits or replace the changelogs with a fresh summary every week.

From then on, agents only read these files or propose changes in conversation. Keeping them current is part of each owner's job.

Every codebase will point to the same notes

On our machines, the headquarters repo sits next to the app repos:

In every codebase, AGENTS.md and CLAUDE.md point to the same index and tell the agent to read whichever notes matter for its task. They also say that people maintain the knowledge files and agents may only propose edits. That's a rule the agent is asked to follow. Nothing in the filesystem enforces it.

Keeping headquarters as its own checkout means a change to the company plan doesn't need a commit in every app to update a pinned copy. The codebase setup section covers the local paths, access, and how to make sure the notes are current before work starts.

Let's put it to the test

Once the owners had checked the notes, we ran a comparison in two fresh sessions that shared a model, a code checkout, and a set of tools. One had the existing AGENTS.md. The other also had the headquarters link. We gave both the same small task, one that touches three repos at once:

Which button component and color should the “Upgrade to Professional” CTA use in wonderby-web, the iOS app, and the Android app, and why? Tell me what you checked.
Search(pattern: "Upgrade|Professional", path: "repos")
Found 14 files
Read(repos/wonderby-web/src/components/ui/button/Button.tsx)
Read 115 lines
Read(repos/wonderby-web/src/components/ui/button/Button.module.scss)
background: $main-gradient;
Search(pattern: "components/ui/button", path: "repos/wonderby-web/src")
Found 17 files
Search(pattern: "ButtonV2", path: "repos/wonderby-web/src")
Found 3 files
Read(repos/anybook-swift/Wonderby/Components/Buttons/GradientButton.swift)
var gradientType = GradientType.purple
Read(repos/anybook-kotlin/app/src/main/java/com/wonderby/wonderby/ui/components/Button.kt)
backgroundGradient: List<Color> = WonderbyTheme.colors.gradientViolet
Web: Button from ui/button, with $main-gradient
iOS: GradientButton, gradientType .purple
Android: ButtonWithLoader, gradientViolet (#9C36B5 → #6741D9)
Why: the violet gradient is the primary CTA style in all three apps. ButtonV2 appears in only 3 files and looks experimental, so I kept the established components for consistency.

Which button component and color should the “Upgrade to Professional” CTA use in wonderby-web, the iOS app, and the Android app, and why? Tell me what you checked.
Read(index.md)
Read 18 lines
Read(business-and-product/changelog.md)
2026-07-21: Upgrade buttons switch to coral after the A/B test
Read(design/overview.md)
Read 58 lines
Read(development/overview.md)
Never use the legacy gradient buttons on any platform.
Search(pattern: "ButtonV2|WBButton|WbButton", path: "repos")
Found 9 files
Web: <ButtonV2 variant="upgrade">
iOS: WBButton(style: .upgrade)
Android: WbButton(variant = WbButtonVariant.Upgrade)
Color: coral #F2542D, white text, #D9431F when pressed
Why: in the June A/B test, coral upgrade buttons beat the violet gradient by 8.4% in paid upgrades, and the product owner made it the rule (business-and-product/changelog.md). The designer specified the colors in Figma, WonderBy DS 2026 › Buttons, node 2140:318 (design/overview.md). development/overview.md retires GradientButton, ButtonWithLoader's gradientViolet, and the old web Button, even where they're used more.

The default session did what a careful engineer would. It found two button components in each app, saw that the violet gradient is used almost everywhere, and picked it. From the code alone, the new components really do seem like an unfinished experiment.

The headquarters session knew the rest of the story, which no single repo holds. The product owner switched upgrade buttons to coral after an A/B test raised paid upgrades, the designer recorded the exact colors and the Figma node, and the development notes retire the gradient buttons on every platform. It took three notes to give one answer that holds in all three apps.

Next up: Make the tests faster before adding more agents

In the next post, we'll set up Wonderby's development environment for agents. An agent can fix a booking screen in a minute and then wait twenty for the tests and the build, so that's where we'll start: running only the checks a change needs, timing our parallel test workers, and trimming our GitLab CI (the pipeline that builds and tests every change).