Sub-Agents

Sub-agents are specialized AI agents that run as child processes of the main Cursor agent. Each one is scoped to a narrow domain with specific instructions, standards to enforce, and output formats. They are defined as markdown files in .cursor/agents/.

Automated Sub-Agents

These two run automatically via the quality gate hooks after every conversation that edits code files.

Code Marshal

File: .cursor/agents/code-marshal.md

Enforces coding standards from .cursor/rules/coding-standards.mdc. Reviews only the files passed in the invocation message — never runs git diff or scans the codebase on its own.

Standards enforced:

Category	Key Checks
SOLID	Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
DDD	Domain organization, ubiquitous language, encapsulated business logic, no infrastructure in domain
Code Splitting	Functions ≤30 lines (hard limit 50), one concern per file, max 3 nesting levels
DRY	No copy/paste, extracted utilities, composition over inheritance
TypeScript	No any, explicit return types, discriminated unions, readonly/as const
Clean Code	Descriptive names, no magic numbers, pure functions, no dead code

Severity levels:

1. Critical — Architectural violations (SOLID, DDD)
2. Warning — Code quality issues (splitting, DRY)
3. Style — Naming and clean code issues

Output format per violation:

FILE: path/to/file.ts
LINE: 42
VIOLATION: [Standard Name]
ISSUE: What's wrong
FIX: How to fix it

Security Sentinel

File: .cursor/agents/security-sentinel.md

Enforces security standards from .cursor/rules/security-rules.mdc. Same scoping rules as Code Marshal — reviews only explicitly listed files.

Security checks:

Category	Key Checks
Auth/JWT	httpOnly cookies, short expiration, token validation, refresh rotation, server-side invalidation
Cookies	httpOnly: true, secure: true, sameSite: 'strict', proper path/maxAge
Injection	Prisma parameterized queries, no string interpolation in SQL, sanitized input, allowlisted identifiers
Validation	Server-side validation, strict schemas, type/length/format checks, allowlists over denylists
XSS	Escaped user content, no dangerouslySetInnerHTML with user data, CSP headers, HTML sanitization
Secrets	No hardcoded keys, env vars used, .env gitignored, no secrets in logs
API	Rate limiting, specific CORS origins, request size limits, auth on sensitive endpoints

Severity levels:

1. Critical — Secrets exposure, SQL injection, auth bypass
2. High — XSS, missing validation, insecure cookies
3. Medium — Missing rate limits, weak CORS, verbose errors
4. Low — Missing headers, suboptimal config

Output format per vulnerability:

FILE: path/to/file.ts
LINE: 42
SEVERITY: Critical | High | Medium | Low
VULNERABILITY: [Type]
ISSUE: What's wrong
EXPLOIT: How it could be exploited
FIX: Specific remediation code

On-Demand Sub-Agents

These are invoked manually by the main agent when a conversation touches their domain.

Progressive Bot Debugger

File: .cursor/agents/progressive-bot-debugger.md

Specialist for the Progressive insurance agent portal automation. The Progressive carrier has no API — our NestJS gateway drives their Angular portal via Playwright page objects. This agent handles:

• Debugging page object interactions against the ForAgentsOnly (FAO) portal
• Handling Angular reactive form re-renders (state dropdown clears city/zip, etc.)
• Creating new page objects for additional quote flow steps
• Inspecting form elements via browser_run_code
• Detecting validation errors after form submission

Uses the Playwright MCP server (user-playwright-mcp) for all browser operations.

Safeco Documentation Expert

File: .cursor/agents/safeco-documentation-expert.md

Deep-dive researcher for Safeco/Liberty Mutual ACORD XML integration. Exhaustively searches through docs/safeco-auto/ to answer questions about field mappings, coverage requirements, transaction types (RC1/RC2/RC3), driver reconciliation, PIP rules, Hydra payment flows, MVR/CLUE reports, occupation codes, and error messages.

Uses the parse-xlsx, parse-docx, and parse-xml skills to read the various document formats in the Safeco docs directory.

Database Explorer

File: .cursor/agents/db-explorer.md

Explores the local PostgreSQL database running in Docker (goosehead-postgres container, fastlane schema). Handles table discovery, schema inspection, data querying, and result formatting.

Loads the local-db skill for connection details. Always prefixes tables with fastlane. and uses LIMIT to prevent overwhelming output.

Playwright

File: .cursor/agents/playwright.md

E2E test specialist that writes and runs Playwright tests following project patterns:

• Page object classes with Locator properties
• Every action wrapped in test.step() for CI reporting
• Scenario-based test data (TestScenario, TestCustomer, TestDriver, TestVehicle)
• Flow helpers (completeDaAutoFlow, navigateToFastlaneStep)
• Screenshot attachments for DA-to-Fastlane style tests
• JSON reporter output to dist/.playwright/

Built-In Cursor Sub-Agents

In addition to the custom agents above, the main Cursor agent uses several built-in sub-agent types:

Type	Purpose
explore	Fast codebase exploration — finds files by pattern, searches code, answers structural questions
generalPurpose	Multi-step research and complex task execution
shell	Terminal command execution (git operations, build commands, etc.)
browser-use	Browser automation for testing and web interaction

These don't have custom definitions — they use Cursor's default behavior.

Invocation Rules

The agent-rules.mdc rule defines when sub-agents should be invoked:

Trigger	Sub-Agent
After any code changes	Code Marshal
After changes to auth, user input, cookies, APIs, or sensitive data	Security Sentinel
When changes touch security-sensitive code	Both concurrently

In practice, the hooks system handles this automatically. The rule exists as a fallback for conversations where hooks don't fire (e.g., the agent is asked to review code without editing it).