---
name: controller
description: Generate SmartStack API controllers with progressive step loading and context refresh.
argument-hint: "[-a] [-p] [-d] [-i] <area> <module> [entity]"
---

<objective>
Generate complete API controllers following SmartStack conventions. Uses progressive step loading to minimize context usage and ensure thorough validation at each phase.
</objective>

<quick_start>
**Basic usage:**

```bash
/controller Admin Users
```

**With Postman tests:**

```bash
/controller -p Support Tickets Ticket
```

**Full generation (auto + DTOs + Postman):**

```bash
/controller -a -d -p Business Orders Order
```

**Flags:**

- `-a` (auto): Skip confirmations
- `-p` (postman): Generate Postman tests
- `-d` (dtos): Generate request/response DTOs
- `-i` (interactive): Configure via menu

See `<parameters>` for complete flag list.
</quick_start>

<parameters>

<flags>
**Enable flags (turn ON):**
| Short | Long | Description |
|-------|------|-------------|
| `-a` | `--auto` | Autonomous mode: skip confirmations |
| `-p` | `--postman` | Postman mode: generate API tests |
| `-d` | `--dtos` | DTO mode: generate CreateDto, UpdateDto, ResponseDto |
| `-i` | `--interactive` | Interactive mode: configure flags via menu |

**Disable flags (turn OFF):**
| Short | Long | Description |
|-------|------|-------------|
| `-A` | `--no-auto` | Disable auto mode |
| `-P` | `--no-postman` | Disable postman mode |
| `-D` | `--no-dtos` | Disable DTO mode |
</flags>

<examples>
```bash
# Basic CRUD controller
/controller Admin Users

# With specific entity name
/controller Support Tickets Ticket

# Full autonomous generation
/controller -a -d -p Admin Roles Role

# Interactive mode
/controller -i Business Products
```
</examples>

<parsing_rules>
**Argument parsing:**

1. Parse flags first (remove from input)
2. `{area}` = First remaining word (Admin, Support, Business, User, Auth)
3. `{module}` = Second remaining word (PascalCase)
4. `{entity}` = Third word OR singularize({module})
</parsing_rules>

</parameters>

<workflow>
**Standard flow:**
1. Parse flags and arguments
2. Analyze existing codebase (Entity, DbContext, Permissions)
3. Plan controller structure (endpoints, DTOs, permissions)
4. Generate controller file
5. Synchronize permissions (Permissions.cs + PermissionConfiguration.cs)
6. Generate Postman tests (if -p)
7. Validate build and conventions
</workflow>

<state_variables>
**Persist throughout all steps:**

| Variable | Type | Description |
|----------|------|-------------|
| `{area}` | string | Controller area (Admin, Support, Business, User, Auth) |
| `{module}` | string | Module name PascalCase (e.g., Users, Tickets) |
| `{entity}` | string | Entity name PascalCase (e.g., User, Ticket) |
| `{controller_type}` | string | crud, readonly, auth, custom |
| `{permission_path}` | string | Full permission path (e.g., platform.support.tickets) |
| `{auto_mode}` | boolean | Skip confirmations |
| `{postman_mode}` | boolean | Generate Postman tests |
| `{dto_mode}` | boolean | Generate DTOs |
| `{interactive_mode}` | boolean | Configure interactively |

</state_variables>

<entry_point>

**FIRST ACTION:** Load `steps/step-00-init.md`

</entry_point>

<step_files>
**Progressive loading - only load current step:**

| Step | File | Purpose |
|------|------|---------|
| 00 | `steps/step-00-init.md` | Parse args, validate area/module, initialize state |
| 01 | `steps/step-01-analyze.md` | Find Entity, DbContext, existing patterns |
| 02 | `steps/step-02-plan.md` | Plan endpoints, DTOs, permissions |
| 03 | `steps/step-03-generate.md` | Generate controller + DTOs |
| 04 | `steps/step-04-perms.md` | Sync Permissions.cs + PermissionConfiguration.cs |
| 05 | `steps/step-05-validate.md` | Build check, convention validation |

</step_files>

<execution_rules>

- **Load one step at a time** - Only load the current step file
- **ULTRA THINK** before code generation
- **Persist state variables** across all steps
- **Follow next_step directive** at end of each step
- **NEVER skip permission sync** - security is mandatory
- **Use templates from** `templates.md` and `postman-templates.md`
</execution_rules>

<security_rules>

**MANDATORY - Never skip:**

1. `[RequirePermission(Permissions.*)]` - Never use string literals
2. `[ProducesResponseType]` - Document all response codes
3. Protect system accounts (UserType.System/LocalAdmin)
4. Log all operations (Info for CRUD, Warning for Delete)
5. No raw SQL - use EF Core only
</security_rules>

<success_criteria>

- Controller follows SmartStack conventions
- Permissions synced in both files
- Build passes without errors
- Postman tests generated (if -p)
- All endpoints documented with [ProducesResponseType]
</success_criteria>
