How Agents Work

Agents are the core of the Dev MCP workflow. They define how you work on a specific platform — component patterns, file structure, build rules, validation checklists, and anti-patterns. Commands are generic workflow orchestration that adapts to whichever agent is active.

The Two-Layer Architecture

Layer	Role	Example
Agents	Platform knowledge + persona. “WHO you are and HOW you work.”	theme-developer, hydrogen-developer
Commands	Workflow orchestration. “WHAT to do.”	setup, build, refine, audit

When you activate an agent, its full platform knowledge loads into context. When you then run a command like build, the command references “the active agent” for platform-specific details — component types, creation rules, validation steps. Same command name, different behavior based on which agent is active.

Agent Types

Platform Agents

Define how to build for a specific stack. Activate one at the start of every session.

Agent	Platform	Activate
Theme Developer	Shopify Liquid themes (Online Store 2.0)	activate_agent("theme-developer")
Hydrogen Developer	Shopify Hydrogen storefronts (React + Remix)	activate_agent("hydrogen-developer")

Platform agents carry ~300-500 lines of conventions: component taxonomy, build order, creation rules with code examples, token system, CSS/JS patterns, validation checklists, performance patterns, and anti-patterns.

Cross-Cutting Agents

Provide methodology that works across any platform. Can be activated alongside a platform agent.

Agent	Purpose	Activate
QA Engineer	Audit methodology, WCAG, Core Web Vitals, code review	activate_agent("qa-engineer")
Comms	Client-facing writing — scopes, testing notes, release summaries	activate_agent("comms")

Note

The QA Engineer agent reads the active platform agent’s validation rules and anti-patterns for platform-specific checks. Activate a platform agent first for full coverage.

Agent Persistence

When you run /setup on a new project, the command detects the project type, activates the matching agent, and saves it to project memory:

save_project_note("agent", "hydrogen-developer")

Future sessions retrieve this via get_project_context and auto-suggest the right agent. You can always switch agents manually.

What Agents Contain

Every platform agent follows the same structure:

• Session Init — what to load before writing code
• Core Mindset — 5-6 guiding principles
• Command Table — which commands to use for which tasks
• Project Detection — how to identify this project type
• Directory Structure — standard file layout
• Component Taxonomy — types, locations, hierarchy
• Build Order — bottom-up dependency chain
• Component Creation Rules — per-type rules with code examples
• Composition Plan Fields — what to include in build plans
• Token System — design token format and naming
• CSS/JS/Translation Rules — platform-specific code patterns
• Figma MCP Configuration — clientLanguages and clientFrameworks values
• File Mapping — issue type to file location (for refine/audit)
• Fix Cascade Order — apply fixes upstream-first
• Validation — platform validation command + per-type checklists
• Performance Patterns — platform-specific optimisations
• Anti-Patterns — what to avoid

How Commands Reference Agents

Commands use phrases like:

• “Follow the active agent’s component creation rules”
• “Use the active agent’s component taxonomy to determine build type”
• “Run the active agent’s validation checklist”
• “Apply fixes in the active agent’s fix cascade order”

The agent content is already in the LLM’s context from activation — commands just reference it.