# Skill-Based Orchestrator

> **Purpose:** Task analysis, skill composition, work coordination using focused skills
> **When to use:** Default orchestrator for all development tasks
> **Foundation:** wordpress-plugin-foundation-skill.md ALWAYS applied to every task

---

## Core Principle

**Compose focused skills to solve tasks. Foundational skill implicit in every task.**

### What This Orchestrator Does
- Analyze user requests to identify required skills
- Compose multiple skills for complex tasks
- Delegate to specialized skills
- Verify completion and compliance
- Report results to user

### What This Orchestrator Does NOT Do
- Write code without loading skills (always load relevant skills before writing code)
- Make architectural decisions without skill guidance
- Skip foundational skill (always applies)

---

## Skill Architecture

### Foundational Skill (Always Applies)

**`wordpress-plugin-foundation-skill.md`** - Applied to EVERY task

Contains:
- WordPress.org compliance (naming, prefixes, text domains)
- Security patterns (SQL injection, XSS, CSRF, authentication)
- Input validation and sanitization
- Permission checking and access control
- Nonce verification
- Output escaping
- Common mistakes across all domains

**Never need to explicitly reference this skill** — auto-applied.

### Specialized Skills (Load As Needed)

**Core Technology (6 skills):**
- `php-skill.md` - PHP patterns, WordPress PHP APIs
- `javascript-skill.md` - Vanilla JS, DOM manipulation, XSS prevention
- `css-scss-skill.md` - SCSS architecture, styling, dark mode
- `sql-skill.md` - Database queries, SQL injection prevention
- `rest-api-skill.md` - REST endpoint patterns
- `ajax-skill.md` - WordPress AJAX patterns

**Architecture (4 skills):**
- `caching-skill.md` - Caching strategies, invalidation
- `database-schema-skill.md` - Schema design, migrations
- `frontend-architecture-skill.md` - Component patterns, state management
- `accessibility-skill.md` - WCAG compliance, ARIA

**Domain (4 skills):**
- `user-engagement-skill.md` - Reactions, subscriptions, notifications
- `moderation-skill.md` - Bans, warnings, reports, content filtering
- `messaging-skill.md` - Private messaging, conversations
- `forum-structure-skill.md` - Nodes, threads, posts, nested replies

**Quality Assurance (1 skill):**
- `verification.md` - Playwright-based visual + functional verification (admin SPA, modals, frontend, dark mode, CSS scoping). Required before committing SCSS / JS / template changes. Always put test files, screenshots, verification docs in `./tests/e2e/` or `./tests/e2e/tmp/` — never in root folder.

  **MANDATORY usage triggers:**
  - Any change to `admin/src-vanilla/styles/**`, `admin/src-vanilla/**/*.js`
  - Any change to `assets/scss/**`, `assets/js/**`, `templates/**/*.php`
  - Any reported visual / layout / dark-mode bug
  - Any change to `Modal.js`, `Tabs.js`, `Toast.js`, or other shared admin components

  **Local env**: WP at `http://localhost:8080`, container `devzone-wordpress`, creds `admin` / `admin123` (reset via `podman exec devzone-db mariadb -u wordpress -pwordpress wordpress -e "UPDATE wp_users SET user_pass=MD5('admin123') WHERE user_login='admin';"`).

---

## Skill Selection Matrix

### By Task Type

| Task Type | Required Skills | Optional Skills |
|-----------|----------------|-----------------|
| **Add REST endpoint** | `php-skill`, `rest-api-skill` | `sql-skill`, `caching-skill` |
| **Add AJAX handler** | `php-skill`, `ajax-skill` | `sql-skill` |
| **Add frontend JS feature** | `javascript-skill` | `frontend-architecture-skill`, `accessibility-skill` |
| **Add CSS styling** | `css-scss-skill` | `accessibility-skill`, `verification` |
| **Database query** | `php-skill`, `sql-skill` | `caching-skill` |
| **Schema change** | `database-schema-skill`, `sql-skill` | `caching-skill` |
| **Component design** | `javascript-skill`, `frontend-architecture-skill` | `accessibility-skill` |
| **Moderation feature** | `php-skill`, `moderation-skill` | `rest-api-skill`, `sql-skill` |
| **Messaging feature** | `php-skill`, `messaging-skill` | `rest-api-skill`, `sql-skill` |
| **Forum structure** | `php-skill`, `forum-structure-skill`, `sql-skill` | `caching-skill` |
| **Visual regression testing** | `verification` | `css-scss-skill` |

### By File Pattern

| File Pattern | Skills Needed |
|--------------|---------------|
| `*.php` | `php-skill` + domain skill if applicable |
| `*.js` | `javascript-skill` + `frontend-architecture-skill` if complex |
| `*.scss` | `css-scss-skill` |
| `*.js` (visual tests) | `verification` |
| `includes/api/*.php` | `php-skill`, `rest-api-skill` |
| `includes/class-*-query.php` | `php-skill`, `sql-skill`, `caching-skill` |
| `admin/src-vanilla/**/*.js` | `javascript-skill`, `frontend-architecture-skill` |
| `templates/**/*.php` | `php-skill`, `accessibility-skill` |

---

## Task Analysis Workflow

### Phase 1: Analyze Request

```
INPUT: User prompt
OUTPUT: List of required skills

Steps:
1. Identify task type (REST endpoint, UI component, database, etc.)
2. Identify affected files
3. Map to required skills using Skill Selection Matrix
4. Identify optional skills that would improve quality
5. Note: Foundation skill is implicit, don't list it
```

### Phase 2: Compose Skills

```
INPUT: List of required skills
OUTPUT: Skill composition guidance

For simple tasks (1-2 skills):
- Reference skills directly in work

For complex tasks (3+ skills):
- Create skill composition list
- Note any potential conflicts
- Determine execution order if dependencies exist
```

### Phase 3: Execute with Skills

```
INPUT: Skill composition
OUTPUT: Completed work

Read skill files before writing any code:
1. Read `.claude/skills/wordpress-plugin-foundation-skill.md` (always, every task)
2. Read each selected core technology skill: `.claude/skills/[name].md`
3. Read each selected architecture skill: `.claude/skills/[name].md`
4. Read each selected domain skill: `.claude/skills/[name].md`

Then implement following the content of the read skill files.

Verify:
- All skill requirements met
- No conflicts between skills
- Foundation skill compliance (security, naming, etc.)
```

---

## Skill Composition Examples

### Example 1: Add REST Endpoint for Banning Users

**Skills needed:**
1. Foundation (implicit - security, validation, permissions)
2. `php-skill.md` - PHP patterns, error handling
3. `rest-api-skill.md` - Endpoint registration, permission callbacks
4. `moderation-skill.md` - Ban logic, administrator protection

**Composition:**
```markdown
Read in order before implementing:
1. `.claude/skills/wordpress-plugin-foundation-skill.md` (always)
2. `.claude/skills/php-skill.md` - PHP patterns and error handling
3. `.claude/skills/rest-api-skill.md` - REST endpoint structure and permission callbacks
4. `.claude/skills/moderation-skill.md` - Ban system patterns and administrator protection

Key requirements from foundation:
- Permission callback required (no __return_true)
- Input sanitization (absint for user_id, sanitize_text_field for reason)
- Administrator protection (cannot ban admins)
- Audit logging (fire do_action for ban events)
```

### Example 2: Add Dark Mode Toggle Component

**Skills needed:**
1. Foundation (implicit - XSS prevention, naming)
2. `javascript-skill.md` - DOM manipulation, event handling
3. `css-scss-skill.md` - Dark mode SCSS patterns
4. `frontend-architecture-skill.md` - State management
5. `accessibility-skill.md` - Keyboard navigation, ARIA

**Composition:**
```markdown
Read in order before implementing:
1. `.claude/skills/wordpress-plugin-foundation-skill.md` (always)
2. `.claude/skills/javascript-skill.md` - Event handling and DOM manipulation
3. `.claude/skills/css-scss-skill.md` - Dark mode implementation with SCSS variables
4. `.claude/skills/frontend-architecture-skill.md` - State management for toggle
5. `.claude/skills/accessibility-skill.md` - Keyboard support and ARIA attributes

Key requirements from foundation:
- Global naming: 4+ characters (PresszoneForumDarkMode, not FPZ)
- XSS prevention: Use textContent, not innerHTML
- Safe global access: window.presszoneForumData?.prop ?? default
```

### Example 3: Add Database Table with Caching

**Skills needed:**
1. Foundation (implicit - security, SQL injection prevention)
2. `php-skill.md` - PHP patterns
3. `database-schema-skill.md` - Table creation with dbDelta
4. `sql-skill.md` - Query patterns with prepare()
5. `caching-skill.md` - Cache strategy and invalidation

**Composition:**
```markdown
Read in order before implementing:
1. `.claude/skills/wordpress-plugin-foundation-skill.md` (always)
2. `.claude/skills/php-skill.md` - PHP patterns and type hints
3. `.claude/skills/database-schema-skill.md` - Table creation with dbDelta
4. `.claude/skills/sql-skill.md` - Query patterns with $wpdb->prepare()
5. `.claude/skills/caching-skill.md` - Cache-aside pattern and invalidation

Key requirements from foundation:
- Always use $wpdb->prepare() for queries
- Use $charset_collate in CREATE TABLE
- Prefix table names with $wpdb->prefix
- Invalidate cache on data changes
```

---

## Delegation Pattern

### When to Delegate to Task Tool

For complex multi-file tasks, use Task tool with skill composition:

```markdown
## Task: [Task Title]

### Skills to Read Before Implementing
Read in order:
1. `.claude/skills/wordpress-plugin-foundation-skill.md` (always)
2. `.claude/skills/php-skill.md` - [specific patterns needed]
3. `.claude/skills/rest-api-skill.md` - [specific patterns needed]
4. `.claude/skills/moderation-skill.md` - [specific patterns needed]

### Context
[Why this task exists, user goal]

### Requirements
[Specific deliverables]

### Files to Modify
- `path/to/file.php` - [changes needed]

### Key Foundation Requirements
- [Specific security/compliance rules that apply]

### Verification
- [ ] [How to test]
```

### When to Work Directly

For simple tasks (1-2 files, single concern):
- Reference skills directly
- Apply foundation skill implicitly
- No need for explicit delegation

---

## Compliance Verification

### After Completing Any Task

**Foundation Skill Checklist (ALWAYS):**
- [ ] All prefixes 4+ characters
- [ ] Text domain is `'forum-press-zone'`
- [ ] No inline CSS
- [ ] No CDN resources
- [ ] All SQL uses `$wpdb->prepare()`
- [ ] All output escaped
- [ ] All input sanitized
- [ ] Nonces verified
- [ ] Permission checks in place
- [ ] No CSS custom properties (use SCSS variables)

**Specialized Skill Checklist (As Applicable):**
- [ ] Skill-specific patterns followed
- [ ] No common mistakes from skill docs
- [ ] Integration points with other skills handled

---

## Error Handling

### When Skills Conflict

Two skills suggest different approaches:
1. Foundation skill takes precedence (security/compliance)
2. More specific skill takes precedence over general
3. Document conflict and chosen approach
4. Verify chosen approach meets all requirements

### When Skill Guidance Unclear

1. Refer to foundation skill for security/compliance
2. Check related skills for similar patterns
3. Follow WordPress coding standards
4. Document decision and rationale

---

## Reporting Format

### Task Completion Report

```markdown
## ✅ Task Complete: [Task Summary]

### Skills Applied
Foundation: wordpress-plugin-foundation-skill.md (security, compliance)
Specialized: [list of skills used]

### Changes Made
- **[Domain]**: [Description]

### Files Modified
| File | Change |
|------|--------|
| `path/to/file` | [What changed] |

### Compliance Verified
- [x] Foundation skill requirements met
- [x] Specialized skill patterns followed
- [x] No common mistakes introduced

### Build Commands Executed
- `npm run build:css` (if SCSS changed)
- `cd admin && npm run build` (if admin JS changed)

### Testing Recommendations
- [How to verify the changes work]
```

---

## Quick Reference

### Most Common Skill Combinations

```
PHP endpoint: php-skill + rest-api-skill
AJAX handler: php-skill + ajax-skill
Frontend feature: javascript-skill + frontend-architecture-skill
Styling: css-scss-skill + accessibility-skill
Database work: php-skill + sql-skill + caching-skill
Schema change: database-schema-skill + sql-skill
Moderation: php-skill + moderation-skill + rest-api-skill
Messaging: php-skill + messaging-skill + rest-api-skill
```

### Foundation Skill Quick Checks

```
Security: SQL injection, XSS, CSRF, authentication
Compliance: 4+ char prefixes, text domain, no inline CSS
Validation: Sanitize input, escape output, verify nonces
Permissions: Check capabilities, protect admins
```

---

## Self-Improvement

After each task:
1. Note skill gaps or unclear guidance
2. Identify patterns to add to skills
3. Flag conventions for CLAUDE.md updates
4. Record edge cases for skill documentation

Use `/learn-from-mistakes` to update skill documentation with discoveries.