# Comments Press Zone - Development Guide

## Skills Architecture

This plugin uses a 2-layer skills-based architecture for AI-assisted development.

### Layer 1: Skills (16 focused skills)

Skills are located in `.claude/skills/` and are automatically composed by expert.md.

**Foundation (implicit in every task):**
- `wordpress-plugin-foundation-skill.md` - Security, compliance, WordPress.org standards

**Technology (6 skills):**
- `php-skill.md` - PHP patterns, WordPress APIs
- `javascript-skill.md` - Vanilla JS, XSS prevention
- `css-scss-skill.md` - Pure SCSS (NO CSS custom properties)
- `sql-skill.md` - Database queries, SQL injection prevention
- `rest-api-skill.md` - REST endpoints
- `ajax-skill.md` - WordPress AJAX

**Architecture (4 skills):**
- `caching-skill.md` - Transients, object cache
- `database-schema-skill.md` - dbDelta, migrations
- `frontend-architecture-skill.md` - Components, state
- `accessibility-skill.md` - WCAG, ARIA, keyboard

**Domain (4 skills):**
- `moderation-skill.md` - Bans, mutes, warnings
- `user-engagement-skill.md` - Voting, reporting
- `comment-threading-skill.md` - Nested comments
- `rich-text-editor-skill.md` - TinyMCE, content filtering

**Release & Deployment (1 skill):**
- `plugin-release-skill.md` - WordPress.org submission, release preparation (ONLY use for releases)

### Layer 2: Primary Orchestrator

**`.claude/agents/expert.md`** - Skill composition orchestrator for ALL tasks
- Analyzes task requirements
- Composes relevant skills automatically
- Applies foundation skill implicitly
- Verifies compliance

### Legacy Agents (Deprecated)

9 legacy agents in `.claude/agents/` are DEPRECATED. Use `expert.md` instead.

### Usage

When working on this plugin, Claude will automatically use `expert.md` to:
1. Analyze your request
2. Identify required skills
3. Compose skills appropriately
4. Apply foundation skill implicitly
5. Complete task with skill guidance

## Prefixing Standards
- **PHP/Database/Options**: `presszone_comments_` (e.g., `presszone_comments_init`, `presszone_comments_settings`)
- **CSS Classes/Handles**: `presszone-comments-` (e.g., `.presszone-comments-btn`)
- **SCSS Variables**: `$presszone-comments-` (e.g., `$presszone-comments-primary`, `$presszone-comments-spacing-md`)
- **PHP Constants**: `PRESSZONE_COMMENTS_` (e.g., `PRESSZONE_COMMENTS_VERSION`)
- **JS Objects/Data**: `presszoneComments` (e.g., `presszoneCommentsData`, `presszoneCommentsApp`)

## ⛔ ABSOLUTE PROHIBITION: CSS Custom Properties

**ZERO TOLERANCE POLICY:** CSS custom properties (`var(--*)` and `--*` declarations) are **STRICTLY FORBIDDEN** in this codebase. **NO EXCEPTIONS.**

```scss
// ❌ FORBIDDEN - NO CSS custom properties
:root {
    --presszone-comments-primary: #1f71dd;
}
.btn { color: var(--presszone-comments-primary); }

// ✅ REQUIRED - Pure SCSS variables ONLY
$presszone-comments-primary: #1f71dd;
.btn { 
    color: $presszone-comments-primary;
    
    .dark-mode & {
        color: $presszone-comments-primary-dark;
    }
}
```

## Code Style & Conventions
- **PHP**: 
  - WordPress Coding Standards (PSR-12 compatible)
  - Strict typing (`declare(strict_types=1);`)
  - All files must start with `if ( ! defined( 'ABSPATH' ) ) exit;`
  - Late escaping for all outputs (`esc_html`, `esc_attr`, `wp_kses_post`)
  - Text Domain: `comments-press-zone`
- **JS**: 
  - Standard ES6+ (no jQuery in admin SPA)
  - Admin: Vanilla JS SPA in `admin/src-vanilla/`
  - Frontend: Vanilla JS in `assets/js/`
- **CSS/SCSS**:
  - BEM naming: `.presszone-comments-block__element--modifier`
  - SCSS Variables ONLY for all colors, spacing, and animations
  - ZERO CSS custom properties - NO var(--*) or --* declarations

## Build Commands
- **Admin App**: `cd admin && npm install && npm run build`
- **Frontend Assets**: (Managed by WP core handles)

## Security
- Always use nonces for AJAX/REST: `presszone_comments_nonce` or `wp_rest`
- Sanitize all inputs: `sanitize_text_field`, `absint`, `map_deep`
-Late escaping is mandatory.

## Common Handles
- Admin Script: `presszone-comments-admin-app`
- Frontend Script: `presszone-comments-frontend`
- Admin Localized Data: `presszoneCommentsAdmin`
- Frontend Localized Data: `presszoneCommentsData`