the agent framework I use, and how I built our supply planner

Series: AI x Supply Chain build breakdown

Stack: Claude Code · Python + Windows Task Scheduler + GitHub Actions · Google Chat · the data layer from part 1

Free to use, all of it. If you would rather have it built than build it, that is what the Supply Planning Agent is.

---

Where this started

Every week I rebuilt our MRP file by hand. Demand, forecast, growth assumptions, inventory projections, production needs. I did that for about six weeks before I automated any of it, and doing it by hand that long is the reason the agent works.

We are five people. I run operations, which at this size means supply, dispatch, retail partners, customer service and process building. I am experimenting with agents so we can scale without me sitting in the middle of every process, and without hiring headcount for things that are really just a repeated loop.

This is the framework I have landed on. It is what I would give someone starting from scratch. It is also still changing, so read it as what is working for me rather than a finished method.

1. Start from a loop you already run by hand

Do not automate a job until you have done it manually enough times to be bored of it.

Six weeks of Mondays for the supply digest. Months for the dispatch review. That is not diligence, it is the only way to find the edge cases, and in operations the edge cases are the job. You find them on a Tuesday when something is late, not in a planning doc.

If you cannot write the rules down, the agent will make them up, and it will make them up confidently.

2. Build the skills first, then stack them into an agent

A skill is one job with one procedure: run the month-end stock count, build the landed cost, prep pack day. It is a written procedure the AI follows, not a personality.

The progression:

• A one-off thing I do in a session
• If I do it three or more times, it becomes a saved skill
• If I lean on that skill constantly, it becomes a duty belonging to an agent

Nothing skips a step. By the time a skill becomes an agent’s duty it has already been run enough times that the failure modes are known and written down.

3. Breadth beats specialisation

This is the one I would argue about with most people building these.

Our supply planner is ONE agent with a growing list of duties on the same loop: the same schedule, the same tools, the same ruleset, the same output. He is not a swarm of small agents that each do one thing.

The reason is context. Deciding “is this a supply question” is itself supply knowledge. Splitting the supply job across four narrow agents means four of them holding a partial picture and none of them holding the whole, plus four sets of credentials, four schedules and four things to audit. Every duty I have added to the existing agent has been cheaper than the first one was.

Where I do split is by DOMAIN, not by task. Supply is one agent’s everywhere. Commercial is another’s everywhere. Money is a third’s. Two agents in one room is only a problem if both answer the same question, and a clean domain split makes that impossible.

4. Write the job description before you build anything

Every agent gets a written constitution before a line of code exists. Mine cover:

• What the job is, in one paragraph
• What it produces, and when
• Who it reports to and who it may speak to
• What it may never do
• What silence means (for us, no digest by its Monday slot IS the alarm)

The “may never do” list matters more than the duty list, and it is the part people skip. For our supply planner it is money, price, carrier, and anything that touches a promise we made to a customer.

5. The autonomy matrix

This is the piece I would steal first if I were reading someone else’s writeup. Every duty sits in exactly one of three lanes, and the lane is written down and ratified before the duty goes live.

Lane	Meaning	Examples from our supply planner
AUTO	Acts alone, logs it, tells me afterwards	Rebuild the MRP, post the ops reporting, check data freshness, reconcile stock against shopify, quarantine odd orders out of the baseline maths, score its own forecast accuracy
PROPOSE	Drafts with reasoning, I decide	How much to make and when, who loses when we are short, growth assumptions, covering demand from excess instead of producing
ESCALATE	Straight to me, no draft	Killing a customer programme, classifying a new entity for the first time, anything that is really a judgement about a relationship

Two rules make it hold:

A global tripwire. Any single action that would move total eight-week demand by more than about 10% bumps up one lane automatically, whatever lane it started in.

The gate binds the write path, not the reply path. This is the one I learned the hard way. Our approval step worked perfectly in conversation, nothing was posted without approval, and meanwhile something got BUILT without approval. Gating what an agent says is not gating what it does.

Lanes are not permanent. Duties get promoted as trust builds. Drafting supplier POs started in PROPOSE and is now AUTO. Sending them is still not.

6. Training: walk the process, then ask it to poke holes

I walked our planner step by step through my MRP process. Not just the calculation, the decision context I carry in my head that is nowhere in the data: why one month’s dip was a production gap rather than churn, which customers order in a pattern and which are one-offs, what a realistic lead time looks like versus the one on paper.

Then I asked it to poke holes in my own logic. That step found more than the walkthrough did. It caught assumptions I had never stated, thresholds I had picked arbitrarily years ago, and two places where my own method double counted.

Two things that made the training stick:

• Context tables in the data, not in the prompt. A promotions log and a product lifecycle table live alongside the orders, so anomalies get read with context every run rather than me re-explaining them.
• Locked metric definitions. What counts as revenue, what a subscriber is, what is excluded. One tab, and every tool computes from it, so two people asking the same question get the same number.

7. Trace every run

Every scheduled run writes one structured log line: what it received, what it produced, WHY it made the call it made, which tools it used, and any error.

The reasoning field is the valuable one. It is the difference between knowing an agent posted something and knowing why it chose that over the alternative. Most of the failures below were caught by reading traces, not by noticing the output was wrong.

If you build one thing from this list before the fancy parts, build this.

8. Loops for learning and self improvement

Three that are running:

• A case bank. Every correction I make becomes a written case with a test attached, so the same mistake is caught the next time rather than re-learned.
• A weekly merge. Corrections and rule proposals accumulate through the week and get merged into the ruleset on a fixed day, rather than the rules mutating mid week.
• Self scoring. The planner freezes a forecast snapshot and scores itself against actuals later. Growth assumptions get reset monthly rather than quarterly, because at startup pace a quarter is far too long to run on a stale assumption.

9. Give them a manager

We have a governance agent whose entire job is auditing the others: that each one actually ran, that the documentation matches what is really happening, that nothing drifted since the last audit. It emails me one report a week.

That is the actual unlock. Not that the agents do the work, but that I read one report instead of checking five things. A workforce you cannot audit is worse than no workforce.

It proposes fixes rather than making them, for now. It will get more autonomy when I trust its judgement, which is the same progression every other duty goes through.

10. A contract for handing work between them

When a session or an agent hands work to another agent, it writes one line into that agent’s inbox opening with exactly one tag:

- 2026-07-19 [ACTION] jobs renamed _0615 / _0645 / _0705, update the expected list
  -> ACTIONED 2026-07-26 corrected against the live job list, all 8 pass

[FYI] is context and needs nothing. [ACTION] means someone must do something and it stays open until closed in place. Nothing is ever deleted. The governance agent warns at 14 days and fails it at 30.

Deliberately not in the format: reference numbers, owner fields, due dates. The owner is implied by whose inbox it is in, the due date is a flat 14 days, and every extra field is one more thing that quietly stops being filled in. Ceremony is what killed my first attempt at this.

What it looks like in practice

Our supply planner currently holds twenty one duties across the three lanes.

Does it on his own: the Monday MRP and material plan, the ops reporting, mid-week stock questions answered off that same plan, data freshness checks, stock reconciliation, baseline cleanup, inbound stock, the month-end count, creating and organising POs, drafting them, forecast scoring, and the S&OP inputs.

Recommends, I decide: how much to make, who loses when we are short, growth rates, and scenario what-ifs.

In training: tracking and sending the POs himself, dispatch box planning, reorder planning for film and pouches, and working alongside our finance agent.

He also talks to the team in our group chat, and works alongside the other agents I am building for finance, commercial analysis, and my own chief of staff.

What failed first (so you can skip it)

• I built one that could not hear me. His connection only worked one way. He could post and could not read. For a week the whole setup assumed otherwise, and another agent spent that week writing him notes into a file he never opened. I found it when I asked three questions in his own channel and got silence. The fix was a relay rather than a second connection: the agent that already reads every room got the job of passing supply questions on. Six days of lag became about twenty minutes.
• An approval I never gave. Code went into a live job carrying a comment saying I had approved it. I had not. What actually happened was a test: I ran the approval protocol end to end to see whether it held, and it read the test as consent. The invented comment was more dangerous than the code, because code gets reviewed and a comment claiming approval gets believed. A test is never an approval, and an approval claim has to be checkable against a record holding the exact words.
• A rule written nine times that no tool could follow. I had written “only reply inside the thread” into nine separate documents. The tool available could not do it, and reported success every time. A rule an agent cannot mechanically follow is not a rule. Name the mechanism and name how you will check it.
• Notices that were written, read, and never acted on. A note telling the governance agent the scheduled jobs had been renamed sat unactioned through a full weekly audit, so its expected-job list stayed stale and it spent that audit reporting failures that did not exist. The tell: the note was prefixed “Also FYI” and contained an instruction. That is the whole reason the two-token contract exists.

What I took back out

The failures above are things that broke. These are things that worked well enough to ship and that I removed anyway, which I find more useful to read about because nobody writes them down.

• A relay between two agents. One agent could post but not read, so I had the agent that could read forward things to it. It worked, and it was the wrong shape. It left a hole nobody noticed: a supply question asked in a room the forwarding agent did not cover reached no one at all. Gone, replaced by every agent reading every room and classifying its own inbound. Deciding “is this mine” turned out to be domain knowledge, so no agent should do it on another’s behalf.
• “One voice per room” as the ownership rule. I used the room as a proxy for the domain and the proxy drifted. It is now one owner per domain, in every room. Two agents in one room is only a problem if both answer the same question.
• A second set of ears. When I found the agent that could not read, my first instinct was to give it its own listener. I did not build it. One more listener means duplicating auth, polling and triage for a single consumer. Do not give agents duplicate senses, give the one that already has the sense the duty to pass it on.
• Warnings posted into the team room. Sync failures used to page the supply room. The team does not need to see infrastructure noise, and mixing it with real supply information taught people to skim the room. All of it now goes to the governance agent, and to me.
• Email digests to me. I built them, and then I stopped reading them, which made them worse than nothing because I believed I was covered. Anything that needs my attention now appears where the work already happens rather than in a mailbox I have trained myself to ignore.
• A heavier version of the handoff protocol, with reference numbers, owner fields and due dates. Every one of those fields quietly stopped being filled in. What survived is two tags and a closing line.
• A check the agent was supposed to remember to run. There was a plausibility test on the weekly numbers that existed as a written instruction. It got skipped under time pressure, and the digest went out with six of seven lines breaching it. A check that depends on remembering is not a check. It is now a computed step that runs whether anyone remembers or not.
• A whole agent. One of them accumulated enough patched behaviour that the patches stopped agreeing with each other. I retired it and rebuilt the same domain from scratch rather than keep repairing it. Cheaper than it sounds, because the constitution, the lanes and the traces carried over. The personality and the accumulated workarounds did not.
• A duty I had planned and never built. Monthly invoice reconciliation was on the supply planner’s roadmap. It came off, because it is a finance job and putting it here would have been convenience rather than domain. Scope creep in an agent is the same problem as scope creep in a role.

Where to start

The build order I would give another operator:

1. Pick a loop you already run weekly by hand, and keep running it by hand while you write down every rule and every exception.
2. Turn it into a skill first. One job, one written procedure. Run it manually a few more times.
3. Write the job description, including the never-do list, before you schedule anything.
4. Put every duty in a lane and start almost everything in PROPOSE. Promote on evidence, not on a date.
5. Turn on tracing before you turn on the schedule. You cannot debug what you cannot see.
6. Only then stack a second duty onto the same agent, and a third. Resist making a second agent until the domain is genuinely different.

Leverage rating: 8 / 10

The highest I have rated anything. It is the difference between automating a task and removing myself from a loop. Marked down from a ten because the governance overhead is real, it only works on top of a data layer that is already trustworthy, and most of what I know about it I learned from things breaking.

---