# Cursor Subagent Quick Reference

## 🚀 How to Invoke Subagents

Use the `/agent-name` syntax in your Cursor chat:

```
/test-writer create tests for UserPermissionCache
/pr-reviewer review my current branch
/bug-coordinator debug the Gantt persistence issue
```

---

## 📋 Available Subagents

### Planning & Architecture
- **`/task-architect`** - Design DDD architecture and full implementation plan before writing any code
- **`/feature-implementer`** - Implement the plan produced by `/task-architect` using strict TDD (Red → Green → Refactor). Covers Database, Backend, and Frontend phases

### Testing
- **`/test-writer`** - Create new test files (Pest + SQLite patterns)
- **`/test-runner`** - Run tests, diagnose failures, apply fixes

### Code Quality
- **`/pr-reviewer`** - Pre-flight code review against standards
- **`/optimization-architect`** - Scan for N+1, caching issues, performance debt

### Debugging
- **`/bug-coordinator`** - Orchestrate multi-specialist debugging workflow
- **`/bug-fixer`** - Apply specific bug fixes with verification
- **`/gantt-debugger`** - DHTMLX Gantt chart specialist (persistence, Alpine.js)

### Specialist Reviews
- **`/backend-review-specialist`** - PHP/Laravel: N+1, tenancy, authorization
- **`/frontend-specialist`** - Livewire/Alpine: reactivity leaks, performance
- **`/security-warden`** - Security audit: IDOR, tenancy leaks, input sanitization
- **`/qa-engineer`** - Generate reproduction steps and test plans
- **`/impact-analyst`** - Assess business risk and severity (P1-P4)

### Planning
- **`/jira-architect`** - Create Jira tickets with LOE estimation

> **⚠️ `bug-inspector` is internal** — invoked automatically by `/bug-coordinator` as the first triage step. Do NOT invoke it directly; bypassing it skips the false-positive check that gates all fixes.
>
> The specialist agents (`/backend-review-specialist`, `/frontend-specialist`, `/security-warden`, `/qa-engineer`, `/impact-analyst`) can be invoked both directly and via `/bug-coordinator`.

### 🔧 Pipeline-Internal Agents (do not invoke directly)

These agents exist in `.agent/workflows/` but are **orchestrated exclusively by `/task-architect`** via the Task tool. Invoking them in isolation requires an active task slug already stored in the Blackboard via `php artisan agent:mem:init`.

| Agent file | Role | Invoked by |
|:-----------|:-----|:-----------|
| `explorer.md` | Forensic researcher — scans code and schema, saves `observation:exploration` | `/task-architect` |
| `architect.md` | Technical designer — reads Blackboard, produces `design:technical` | `/task-architect` |
| `planner.md` | Spec writer — reads Blackboard, produces `spec:implementation` | `/task-architect` |
| `auditor.md` | Compliance verifier — reads Blackboard, validates implementation against spec | `/task-architect` |

---

## 🎯 When to Use Each Subagent

| Scenario | Subagent | Example Prompt |
|:---------|:---------|:---------------|
| Starting a new feature/task | `/task-architect` | `/task-architect design the Events canonical schema validation feature` |
| Creating new tests | `/test-writer` | `/test-writer create integration tests for PermissionCacheService` |
| Test failures | `/test-runner` | `/test-runner diagnose why UserPermissionCacheTest is failing` |
| Before PR | `/pr-reviewer` | `/pr-reviewer review changes in current branch` |
| Performance issues | `/optimization-architect` | `/optimization-architect scan Dashboard controller for N+1 queries` |
| Bug reported | `/bug-coordinator` | `/bug-coordinator investigate why user permissions aren't updating` |
| Gantt not working | `/gantt-debugger` | `/gantt-debugger task status changes aren't persisting` |
| Security review | `/security-warden` | `/security-warden audit the new API endpoints` |
| Creating ticket | `/jira-architect` | `/jira-architect create ticket for permission caching optimization` |

---

## 📁 Project Standards (Auto-Applied Rules)

These are **not** subagents - they're always-on standards hosted in `docs/ai-rules/` and auto-loaded via pointers in `.cursor/rules/`:

- **000-core-standards.md** - Architecture, DDD, prohibitions
- **050-infrastructure.md** - Tech stack, Redis/Predis contract, queue architecture
- **100-backend-laravel.md** - Laravel patterns
- **101-routing-and-controllers.md** - Routing and Controller conventions
- **102-domain-driven-design.md** - DDD implementation guidelines
- **103-console-commands.md** - Artisan command standards
- **104-dto-standards.md** - DTO patterns and data transfer conventions
- **200-frontend-livewire.md** - Livewire fundamentals
- **201-alpine-patterns.md** - Alpine JS integration patterns
- **202-secure-delete.md** - Frontend deletion workflows
- **300-security.md** - General Security policies
- **301-security-validation.md** - Input validation & IDOR
- **400-testing.md** - Pest, SQLite, test patterns
- **401-testing-philosophy.md** - Test vs Production Philosophy
- **500-performance.md** - N+1, caching, debouncing
- **600-eloquent-safe-patterns.md** - Models, Observers, Traits
- **700-import-jobs-and-domain.md** - Background jobs and imports
- **800-documentation-tracking.md** - Doc updates and PR reviews
- **900-workflow.md** - Git, linting, code generation

Rules are **automatically loaded** based on file context by the IDE pointer system. You don't invoke them.

---

## 🔄 Subagent vs Rule

| Type | Purpose | How to Use | Example |
|:-----|:--------|:-----------|:--------|
| **Rule** | Standards, conventions | Auto-applied | Security rule prevents `tenant_id` in queries |
| **Subagent** | Multi-step tasks | Explicitly invoke | `/test-writer` generates test file |

---

## 💡 Tips

1. **Explicit invocation:** Use `/agent-name` when you know exactly which specialist you need
2. **Proactive delegation:** Agent will automatically invoke relevant subagents based on context
3. **Parallel execution:** Agent can launch multiple subagents simultaneously for efficiency
4. **View progress:** Subagents run in isolated context windows and return summaries

## 🧠 Recommended Model Tier per Agent

The `model:` field in `.cursor/agents/*.md` controls which model each agent uses.
Set these manually in each agent pointer file using the model identifier from your Cursor plan.

| Tier | Agents | Reason |
|:-----|:-------|:-------|
| **Max capability** | `task-architect`, `pr-reviewer`, `bug-coordinator` | Deep multi-step reasoning, architectural decisions |
| **Balanced** | `test-writer`, `bug-fixer`, `bug-inspector`, `optimization-architect` | Code generation + analysis, moderate complexity |
| **Fast / cheap** | `impact-analyst`, `qa-engineer`, `jira-architect`, `gantt-debugger` | Structured output, classification, templated responses |

> To configure: open `.cursor/agents/<name>.md` and set `model: <your-model-id>`.
> Example: `model: claude-3-5-sonnet-20241022`

---

## 📚 Full Documentation

- **Official Docs:** https://cursor.com/docs/context/subagents
- **Main Config:** `.cursorrules`
- **Architecture KI:** `docs/architecture/agnostic-agent-architecture-ki.md`