workflow-orchestrator

What this skill does

# Workflow Orchestrator — AEM 6.5 LTS

## Purpose

This is the **master entry point** for all AEM Workflow tasks on AEM 6.5 LTS — spanning both **development** (building workflows) and **production support** (debugging and triaging workflow issues). Read this skill first. It classifies the user's request and routes to the right sub-skill.

## How to Use This Skill

1. Read the user's request carefully
2. Classify it using the **Task Classifier** table below
3. Load the identified sub-skill's `SKILL.md` and its references
4. For development tasks, always load the `workflow-foundation` references alongside the sub-skill references
5. For production-support tasks, the debugging and triaging skills are self-contained

---

## Task Classifier

### Development Skills

| User Says / Asks | Sub-Skill to Load |
|---|---|
| "Create a workflow model", "Add steps to a workflow", "Design an OR split", "I need a parallel review" | `workflow-model-design` |
| "Implement a custom process step", "Write a WorkflowProcess", "Create a ParticipantStepChooser", "Dynamic participant" | `workflow-development` |
| "Start a workflow from code", "Trigger a workflow via API", "Use Manage Publication with a workflow", "HTTP REST API to start a workflow" | `workflow-triggering` |
| "Configure a launcher", "Auto-start on asset upload", "Launcher not firing", "cq:WorkflowLauncher", "Overlay an OOTB launcher" | `workflow-launchers` |
| "How do workflows work?", "What is the Granite Workflow Engine?", "Explain workflow architecture" | Load `workflow-foundation` references only |

### Production Support Skills

| User Says / Asks | Sub-Skill to Load |
|---|---|
| "Workflow is stuck", "Why isn't my workflow advancing?", "No work item", "Workflow failed", "Step shows error" | `workflow-debugging` |
| "Task not in Inbox", "User can't see work item", "Permissions error on workflow" | `workflow-debugging` |
| "Thread pool exhausted", "Auto-advancement not working", "Queue backlog", "Sling Jobs stuck" | `workflow-debugging` |
| "Repository bloat", "Too many workflow instances", "Purge not working", "Stale workflows" | `workflow-debugging` |
| "countStaleWorkflows", "restartStaleWorkflows", "retryFailedWorkItems", "JMX workflow" | `workflow-debugging` |
| "What workflow errors on host X?", "Workflow activity for the past N hours", "What should I collect?" | `workflow-triaging` |
| "Classify this workflow ticket", "What Splunk query should I use?", "What logs do I need?" | `workflow-triaging` |
| "Why did workflow X fail? Show me the error.", "Failure details for model Y" | `workflow-triaging` |
| "What does JMX returnSystemJobInfo show?", "Check queue depth via JMX" | `workflow-triaging` |

**Routing heuristic:**
- Building/implementing workflows → development skills (`workflow-model-design`, `workflow-development`, `workflow-triggering`, `workflow-launchers`)
- Deep troubleshooting (decision trees, config checks, thread analysis, JMX remediation) → `workflow-debugging`
- Incident classification (symptom → runbook, log patterns, Splunk, JMX metrics, data gathering) → `workflow-triaging`
- When both debugging and triaging apply, start with `workflow-triaging` to classify, then `workflow-debugging` for resolution

---

## Reference Loading Order

For every workflow task on AEM 6.5 LTS, load in this order:

### Step 1: Always load these foundation references

```
workflow-orchestrator/references/workflow-foundation/architecture-overview.md
workflow-orchestrator/references/workflow-foundation/api-reference.md
workflow-orchestrator/references/workflow-foundation/jcr-paths-reference.md
workflow-orchestrator/references/workflow-foundation/65-lts-guardrails.md
workflow-orchestrator/references/workflow-foundation/quick-start-guide.md
```

### Step 2: Load the sub-skill's SKILL.md

```
workflow-model-design/SKILL.md         ← for model design tasks
workflow-development/SKILL.md          ← for Java implementation tasks
workflow-triggering/SKILL.md           ← for start/trigger tasks
workflow-launchers/SKILL.md            ← for launcher config tasks
workflow-debugging/SKILL.md            ← for production debugging tasks
workflow-triaging/SKILL.md             ← for incident triage tasks
```

### Step 3: Load the sub-skill's topic references

**workflow-model-design:**
```
workflow-model-design/references/workflow-model-design/step-types-catalog.md
workflow-model-design/references/workflow-model-design/model-xml-reference.md
workflow-model-design/references/workflow-model-design/model-design-patterns.md
```

**workflow-development:**
```
workflow-development/references/workflow-development/process-step-patterns.md
workflow-development/references/workflow-development/participant-step-patterns.md
workflow-development/references/workflow-development/variables-and-metadata.md
```

**workflow-triggering:**
```
workflow-triggering/references/workflow-triggering/triggering-mechanisms.md
workflow-triggering/references/workflow-triggering/programmatic-api.md
```

**workflow-launchers:**
```
workflow-launchers/references/workflow-launchers/launcher-config-reference.md
workflow-launchers/references/workflow-launchers/condition-patterns.md
```

**workflow-debugging:**
```
workflow-debugging/SKILL.md
workflow-debugging/reference.md
```

**workflow-triaging:**
```
workflow-triaging/SKILL.md
```

---

## 6.5 LTS / AMS Production Support Capabilities

| Capability | Detail |
|---|---|
| JMX | Full access via Felix Console (`/system/console/jmx`) or JMX client |
| Retry failed items | JMX `retryFailedWorkItems` or Inbox Retry |
| Stale detection | JMX `countStaleWorkflows` |
| Stale restart | JMX `restartStaleWorkflows(dryRun=true)` then execute |
| Purge | JMX `purgeCompleted(dryRun=true)` or Purge Scheduler |
| Queue info | JMX `returnSystemJobInfo`, `returnWorkflowQueueInfo` |
| Log access | Direct filesystem (`crx-quickstart/logs/`) or AMS log access |
| Thread dumps | jstack or AMS support request |
| Config status ZIP | Felix Console → Status → Configuration Status |
| Config changes | Felix Console, OSGi config in repo, or CRX/DE |

---

## AEM 6.5 LTS Guardrails Summary

Before doing anything, apply these constraints:

| Rule | Detail |
|---|---|
| Avoid editing `/libs` | Use overlays under `/apps` or store at `/conf/global` |
| Model design-time path | `/conf/global/settings/workflow/models/<id>` (preferred) or `/etc/workflow/models/<id>` (legacy) |
| Model runtime path (for API calls) | `/var/workflow/models/<id>` |
| Launcher config paths | `/conf/global/settings/workflow/launcher/config/` (preferred), `/apps/settings/workflow/launcher/config/` (overlay), or `/etc/workflow/launcher/config/` (legacy) |
| Service users | Use `ResourceResolverFactory.getServiceResourceResolver()` with a sub-service; avoid `loginAdministrative` |
| OSGi annotations | DS R6 preferred; Felix SCR still supported on 6.5 LTS |
| Deploy via | Package Manager (CRX Package), Maven + Content Package Plugin, or ACS AEM Commons JCR |
| No `javax.jcr.Session.loginAdministrative` | Deprecated — use `loginService()` or `ResourceResolverFactory` |

Full detail: `references/workflow-foundation/65-lts-guardrails.md`

---

## Quick Architecture Recap

```
Author tier
  │
  ├── Content Author
  │     └── triggers via: Timeline UI / Manage Publication
  │
  ├── Custom code (OSGi service / event handler / scheduler)
  │     └── triggers via: WorkflowSession.startWorkflow()
  │
  ├── Workflow Launcher (cq:WorkflowLauncher)
  │     └── triggers via: JCR observation events
  │
  └── Replication Agent (6.5 LTS only)
        └── triggers via: replication event / "Trigger on Receive"
              ↓
        Granite Workflow Engine
              ↓
        Workflow Instance (/var/workflow/instances/)
              ↓
        Steps executed as Sling Jobs:
          - PROCESS step  → WorkflowProcess.execute()
          - PARTICIPANT step → inbox task for user/group
          - DYNAMIC_PARTICIPANT → ParticipantStepChooser.getParticipant()
          - OR_SPLIT →