The Merch-Expert Consultant Agent

Tier 3 · What we built 6 min read

Before this, read:

Inter-agent messaging (ask_agent) — how agents call each other by name
The autonomous CEO-operator — the operator this agent advises

Most business advice agents hallucinate. They generate confident-sounding answers from training data that may be a year stale, with no connection to the specific store they’re supposedly advising. The merch-expert was built to solve that problem with a specific architectural choice: every answer injects the live config.yaml from the store, so the pricing, margins, and provider details in the response are the actual current numbers.

What it is

agents/merch_expert/ is a KB-backed advisory agent for the print-on-demand business. It has deep knowledge of POD economics across eight research streams (niche selection, design strategy, POD provider economics, organic traffic, paid ads, retention, conversion, and IP/operations law), delivered as an 11-file knowledge base built from deep-research runs.

The public API is simple:

from agents.merch_expert.agent import ask

result = ask("Should we start paid ads now?")
# result["answer"] includes break-even math on current $30/shirt pricing
# result["sources"] lists the KB files that informed the answer

Or from the shell:

python3.12 -m agents.merch_expert "What margin should we target at 100 orders/month?"

The agent is also reachable via ask_agent as merch-expert:

python3.12 -m agents.shared.ask_agent merch-expert "Is $30 the right price for launch?"

The live-config injection

The key architectural decision is in agent.py:

# From merch_expert/agent.py:
# MERCH_CONFIG_FILE is ~/clawd/domains/merch/config.yaml
# Injected when present so the expert's pricing/provider/lane numbers
# track the real store rather than drifting.
MERCH_CONFIG_FILE = Path.home() / "clawd" / "domains" / "merch" / "config.yaml"

On every call, the agent reads the live config file and injects it alongside the retrieved KB files. If the store’s default price changes from $26 to $30 (which happened on 2026-06-09), the next advice call automatically uses $30 in its break-even math. No KB update, no retraining — the live file is the source of truth.

This matters because pricing advice that uses stale numbers is worse than useless. An agent recommending against paid ads based on a $26 margin is giving different advice than one using the $30 margin at which the math actually changes.

The KB structure

The knowledge base ships inside the package at agents/merch_expert/expert-kb/ — it’s version-controlled with the code, not stored as domain state. The files:

00-AGENT-SYSTEM-PROMPT.md — verbatim persona prompt (always injected into system)
00-MASTER-SYNTHESIS.md — integrated picture across all research streams (always injected)
00-OPEN-QUESTIONS.md — live open questions for the business
1-niche-selection-validation.md through 8-operations-risk-ip.md — topic artifacts injected on relevance

Retrieval is keyword/section scoring over the topic artifacts. There’s no vector database — the KB is around 80KB, small enough that keyword scoring over topic headings is sufficient and simpler to maintain.

Token strategy

Rather than dumping the entire KB into every call, the agent follows a tiered injection pattern:

System prompt (always): persona.
Always injected: 00-MASTER-SYNTHESIS.md + the live config.yaml.
On relevance: the top-K topic files, keyword-scored against the question.

For a question about pricing, 3-pod-economics-pricing.md scores high and gets injected. For a question about niche selection, 1-niche-selection-validation.md leads. A question about IP risk pulls in 8-operations-risk-ip.md.

This keeps the context window at 3–5 files per query rather than the full 11, which matters for latency and cost on Opus-tier calls.

16 tests

The test suite covers: KB files all present, live config injected when available, top-K selection matches expected topic files for sample queries, the ask() function returns a dict with required keys, and the CLI exits 0. 16 tests, all green at ship time.

Role in the operator

The operator’s daily standup (standup.py) brings the merch-expert into the decision loop: the operator contributes performance data and pending decisions; the expert contributes strategic framing — when to push paid ads, which margin thresholds matter, whether the current catalog mix makes sense for the niche.

The expert doesn’t have write access to anything. It advises; the operator decides; JD approves items that cross the hard walls. The three-layer separation means no single component can accidentally do something consequential without the others agreeing.

What the architecture teaches

This agent demonstrates a pattern that applies beyond POD businesses: ground advisory agents in live state, not just trained knowledge. A business expert that reads current numbers from a config file will always give better advice than one that reasons from stale training data, even if the underlying research is identical.

The cost of injecting a small config file on every call is negligible. The cost of advice based on outdated numbers is not.

Next: Group F starts with the deep-research agent that powered the merch store’s initial market research — and everything else that needed 300+ sources to answer properly. The deep-research agent.