Rules, Workflow and Sub-Agents: Splitting an AI Agent Plugin for dbt
Why one big instructions file failed, and how AGENTS.md, a spec-driven skill, isolated sub-agents, hooks and Jira MCP each took one job in a dbt workflow.
This article is published in English.
Sources: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
A single instructions file can't carry a rulebook, a process and the day-to-day work without dropping the thread on all three. That's how the first version of one dbt agent workflow behaved, and the reasons for splitting it say a lot about how to organize AI agent instructions.
Some context. An AI agent asked to write dbt models can hand back code that compiles and passes every test and still produces wrong numbers. Rather than trust the agent's memory, the process was converted into seven hard gates stored inside the repository itself, and those gates have since caught real defects that testing alone would have let through. Here the focus is the machinery that keeps the gates standing: rules, workflow, sub-agents, hooks and Jira integration. The plugin has three layers, namely always-on rules, a workflow a user kicks off and isolated sub-agents for the heavy steps, plus hooks that keep a session consistent and MCP to reach outside the repo. No piece duplicates another's job.
Vocabulary first
- Agent. An AI system that can open files, run commands and carry out several steps independently, so it does more than answer questions.
- Rules file (
AGENTS.md). Standing rules the agent loads automatically when a session starts. It's an open standard that works across tools, not tied to one vendor. Think of an employee handbook that everyone is expected to know already. - Skill (workflow). Instructions loaded only when that particular kind of task shows up, much like a recipe pulled out when a specific dish is ordered.
- Sub-agent. A separate copy of the agent started for one job in its own private context, which returns a summary when done.
- Hook. A script tied to a fixed moment in a session that runs automatically, regardless of what the agent decides. A fire sprinkler is the picture to hold: it triggers at the first sign of smoke without asking anyone.
- MCP (Model Context Protocol). A published standard from Anthropic that defines how an agent reaches external tools, so nobody writes bespoke glue per tool. People call it a USB-C port for AI applications, since anything built to the standard can plug in.
What went wrong at first
The earliest spec-driven workflow lacked most of these pieces. It was one markdown file at the repo root that held the rules and the process and tried to walk the agent through each step in order. There were no sub-agents, hooks or hard gates, only a suggested sequence.
For a while that held up. Once a session grew long, though, the rules near the top of the file fell out of the active context by roughly the third implementation step, and the agent began improvising without saying so. Discovery, specification and implementation shared one window, and the oldest instructions were the first casualty.
Teams on other warehouses run into the same thing. One pattern seen in the wild, from a team further along, separated rules, workflow and execution, and used session hooks so context compaction couldn't silently drop instructions mid-task. The takeaway was to stop treating "the agent's instructions" as a single thing. There are three, each with a different lifetime and a different job.
Three layers, one owner each
- Layer one, the standing rules:
AGENTS.md, present at all times - Layer two, the process: the
spec-drivenskill, started by the user - Layer three, heavy steps: sub-agents, created when needed
Rules
The rules file carries the blocking engineering rules that are mandatory, together with a Project Profile that captures each team's settings: naming conventions, materializations, the base branch, the CI system and so on. A hook loads the file at the start of every session, which removes any dependence on the agent remembering to look. It's in context before the first message. Since the profile is separate, other teams can adopt the plugin without a fork.
Workflow
The process is encoded as a skill that the agent invokes at the user's request. It triggers on phrases like "fix bug X" or "build feature Y", or explicitly through a /dbt-spec-driven:spec-driven command in Cortex Code. It routes by intent (feature, bug, refactor, standalone review or standalone docs) and orchestrates the gated phases.
One design decision matters most: the skill never restates the rules. It points back to AGENTS.md. That choice fixed most of the original context problem, because no duplicate copies of a rule drift out of sync in two places.
Sub-agents
Five tasks consume so much context that running them in the main thread would squeeze out the real work: discovery, test-author, output-validator, peer-reviewer and ci-interpreter. Each one starts in a context of its own, performs a single job and returns a structured report with only what matters.
The underlying insight is that context is a limited budget and not a bottomless scratchpad. Take discovery: it may involve reading a dozen model files and tracing lineage. Kept in the main thread, it means half the budget is spent before implementation begins, on files nobody needs by then. Discovery is also a good fit for a small, cheap model, since reading and summarizing takes less reasoning power.
Hooks
The file hooks/hooks.json fires three hooks with no agent cooperation required. One loads AGENTS.md at session start. One warns before context compaction, so nothing important vanishes silently, which was the exact failure of the first version. One appends a session note on exit.
Every hook ships as paired bash and PowerShell variants. Cortex runs whichever matches the operating system, and the other fails silently. A team mixing operating systems needs no per-user configuration.
MCP wiring to Jira
All of that falls flat if "post the spec back to the ticket" means somebody copying text between a terminal and Jira by hand. Two MCP servers connect the workflow.
The Atlassian MCP is the indispensable one. The discovery sub-agent uses it to read the ticket when a session opens, and the Specify phase uses it to post numbered requirements back onto that ticket. The spec therefore sits next to the work, not in a chat history that disappears.
The Notion MCP plays a smaller role at the moment. It's used when something deserves documentation in a more lasting place than a PR description or the repo, such as an end-to-end flow. In general, MCP is what lets rules, workflow and sub-agents touch anything outside the repository. Today that's a ticket, and tomorrow it might be a BI platform or a Teams channel.
The whole picture
The user asks, the skill routes and workers run off to the side. Each worker returns a report and doesn't dump its files into the main thread. Hooks and MCP wrap the picture without sitting inside it: they load rules, warn before compaction and reach Jira.
What improved
- The main thread stays focused on decisions and isn't weighed down by a dozen files' worth of discovery output.
- Rules stop drifting, since exactly one copy exists.
- Mid-session compaction can't lose anything without a warning first.
The general lesson reaches well beyond dbt. Anyone running an AI agent against a real repository will likely have a version of "one file doing everything", and it tends to break the same way: the longer the session, the more the earliest instructions get squeezed out.