---
name: apex
description: |
  SmartStack incremental development using APEX methodology (Analyze-Plan-Execute-eXamine).
  Use this skill when:
  - Adding a new section/resource to an existing module
  - Developing feature by feature without /business-analyse
  - Fixing or extending code generated by /ralph-loop
  - Any incremental SmartStack development task
argument-hint: "[-a] [-x] [-s] [-t] [-e] [-r] [-pr] <task description>"
---

<objective>
Execute incremental SmartStack development using the APEX methodology. This skill knows the SmartStack hierarchy (context/application/module/section/resource), delegates code creation to existing skills (/controller, /application, /ui-components, /efcore, /notification, /workflow) and MCP tools, and validates via MCP conventions.

**Key principle:** /apex ORCHESTRATES — it never generates SmartStack code directly. All generation goes through skills and MCP tools.
</objective>

<quick_start>

```bash
/apex add absence management to HR module           # Add section to module
/apex -a fix the leave request controller            # Auto fix
/apex -a -x -s -t -pr add PDF export to Orders      # Full workflow
/apex -e add status field to Project entity          # Economy (no agents)
/apex -r                                             # Resume previous
```

</quick_start>

<parameters>

| Flag | Description |
|------|-------------|
| `-a` | Auto mode: skip confirmations |
| `-x` | Examine mode: adversarial code review |
| `-s` | Save mode: output to `.claude/output/apex/` |
| `-t` | Test mode: scaffold + run tests via MCP |
| `-e` | Economy mode: no subagents |
| `-r` | Resume: continue from previous state |
| `-pr` | PR mode: create pull request at end |

</parameters>

<state_variables>

| Variable | Type | Description |
|----------|------|-------------|
| `{task_description}` | string | What to implement (flags removed) |
| `{task_id}` | string | Kebab-case identifier |
| `{auto_mode}` | boolean | Skip confirmations |
| `{examine_mode}` | boolean | Adversarial review |
| `{save_mode}` | boolean | Save outputs to `.claude/output/apex/{task-id}/` |
| `{test_mode}` | boolean | Include test steps (07-08) |
| `{economy_mode}` | boolean | No subagents |
| `{pr_mode}` | boolean | Create PR at end |
| `{context_code}` | string | "business", "platform", "personal" |
| `{app_name}` | string | Application name |
| `{module_code}` | string | Module code |
| `{sections}` | string[] | Sections being added/modified |
| `{prd_path}` | string? | `.ralph/prd-{module}.json` if exists |
| `{feature_path}` | string? | `docs/business/.../feature.json` if exists |
| `{needs_seed_data}` | boolean | Seed data creation required |
| `{needs_migration}` | boolean | EF Core migration required |
</state_variables>

<entry_point>

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

</entry_point>

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

| Step | File | Model | Purpose |
|------|------|-------|---------|
| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect SmartStack context, verify MCP |
| 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
| 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
| 03 | `steps/step-03-execute.md` | Opus | Orchestrate execution via skills and MCP |
| 04 | `steps/step-04-validate.md` | Opus | MCP validation, build, seed data check |
| 05 | `steps/step-05-examine.md` | Opus | Adversarial review (if -x) |
| 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
| 07 | `steps/step-07-tests.md` | Opus | Scaffold tests via MCP (if -t) |
| 08 | `steps/step-08-run-tests.md` | Opus | Run tests until 100% pass (if -t) |
</step_files>

<reference_files>
**Loaded conditionally by steps that need them:**

| File | Purpose | Loaded by |
|------|---------|-----------|
| `references/smartstack-layers.md` | Layer execution rules, skill/MCP mapping, seed data | step-02, step-03 |
| `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 |
</reference_files>

<execution_rules>

- **Load one step at a time** - Progressive loading to manage context
- **ORCHESTRATE, never generate** - All SmartStack code via skills (/controller, /application, etc.) or MCP tools
- **MCP-first** - Use MCP scaffold/validate tools before manual approaches
- **Verify MCP at startup** - step-00 checks MCP availability
- **Layer order** - domain -> infra -> migration(BLOCKING) -> app -> api -> frontend -> i18n -> tests
- **Agent Teams** - Parallel execution for scan (step-01) and Layer 1 (step-03), unless economy_mode
- **Save outputs** if `{save_mode}` = true
- **Commits per layer** - Atomic commits after each execution layer

</execution_rules>

<success_criteria>
- SmartStack context detected (context/app/module)
- Plan validated with skill/MCP mapped for each file
- Code created/corrected via existing skills and MCP (no direct generation)
- MCP validate_conventions: 0 errors
- Build: dotnet build PASS + npm run typecheck PASS (if frontend)
- Seed data complete (navigation, permissions, roles, provider) if required
- Tests: 100% pass, >= 80% coverage (if -t)
- Commits atomic per layer
</success_criteria>
