/wordpress-setup — WordPress 6.x Project Scaffold

USAGE

/wordpress-setup <project-name>
/wordpress-setup <project-name> --type=block-theme
/wordpress-setup <project-name> --type=plugin
/wordpress-setup <project-name> --type=full --with-woocommerce

DESCRIPTION

Scaffold un projet WordPress 6.x production-ready pour l'agence ATUM. Trois types de projets supportés :

• block-theme (défaut) — thème Full Site Editing avec theme.json, templates HTML, parts, patterns
• plugin — plugin custom avec structure PSR-4, activation/desactivation/uninstall, Gutenberg blocks
• full — thème + plugin compagnon, environnement dev wp-env configuré, CI GitHub Actions

Tous les scaffolds incluent la checklist sécurité (nonces, capabilities, kses, i18n) et respectent les WordPress Coding Standards.

OPTIONS

Flag	Défaut	Description
--type=block-theme|plugin|full	block-theme	Type de scaffold
--with-woocommerce	false	Déclare la compatibilité HPOS + hooks de base
--namespace=<Ns>	Atum\\<ProjectName>	Namespace PSR-4 pour les plugins
--text-domain=<td>	<project-name>	Textdomain i18n
--wp-version=<6.x>	6.6	Version WordPress minimale requise
--php-version=<8.x>	8.1	Version PHP minimale requise
--dry-run	—	Affiche la structure sans créer les fichiers

DÉMARCHE

1. Phase de vérification (PRE-CREATE)

Avant de créer quoi que ce soit, Claude Code vérifie :

1. Le répertoire cible n'existe pas déjà (sinon stop, ou --force pour overwrite)
2. L'utilisateur est bien dans un contexte de projet WordPress (présence d'un dossier wp-content/themes/ ou wp-content/plugins/ parent)
3. Les outils requis sont disponibles : node, npm, composer, wp (WP-CLI optionnel mais recommandé)

2. Type block-theme

Crée la structure FSE complète :

<project-name>/
├── style.css                  # Header avec "Theme Name", "Version", "Text Domain"
├── theme.json                 # Settings : color palette, typography, spacing
├── functions.php              # Enqueue, add_theme_support, load_theme_textdomain
├── templates/
│   ├── index.html             # Template par défaut
│   ├── single.html            # Post individuel
│   ├── page.html              # Page individuelle
│   ├── archive.html           # Archives
│   ├── 404.html               # Erreur 404
│   └── search.html            # Résultats de recherche
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   ├── hero.php               # Pattern hero section
│   └── cta.php                # Pattern call-to-action
├── assets/
│   ├── css/
│   │   └── editor.css         # Styles additionnels éditeur
│   ├── js/
│   └── fonts/
├── languages/
│   └── <text-domain>.pot      # Généré via wp i18n make-pot
├── screenshot.png             # 1200x900 placeholder
└── readme.txt                 # Release notes

Contenu de theme.json : palette de 3 couleurs, font family Inter, spacing scale, 4 font sizes, appearanceTools: true pour activer padding/margin/gap sur tous les blocs.

Contenu de functions.php : enqueue discipline, add_theme_support pour wp-block-styles, editor-styles, align-wide, responsive-embeds, custom-units, chargement du textdomain, cleanup de wp_head (remove emoji, shortlink, etc.).

3. Type plugin

Crée un plugin moderne avec namespace et Composer :

<project-name>/
├── <project-name>.php         # Fichier principal avec header plugin
├── composer.json              # PSR-4 autoload
├── uninstall.php              # Cleanup DB options/meta
├── readme.txt                 # README pour wordpress.org
├── src/                       # Classes PSR-4
│   ├── Plugin.php             # Classe principale (singleton)
│   ├── Activator.php          # Hook activation (dbDelta)
│   ├── Deactivator.php        # Hook désactivation (cleanup cron)
│   ├── Admin/
│   │   └── SettingsPage.php
│   ├── Rest/
│   │   └── Controller.php     # Routes REST
│   └── Blocks/
│       └── BlockRegistry.php  # Enregistrement des blocs
├── blocks/
│   └── example/               # Un bloc de départ
│       ├── block.json
│       ├── edit.js
│       ├── save.js
│       ├── style.scss
│       └── editor.scss
├── assets/
│   ├── css/
│   └── js/
├── tests/                     # PHPUnit + Brain Monkey
│   └── PluginTest.php
├── languages/
│   └── <text-domain>.pot
└── .github/
    └── workflows/
        └── ci.yml             # PHPCS + PHPUnit

Contenu de composer.json :

{
  "name": "atum/<project-name>",
  "description": "<project-name> plugin by ATUM",
  "type": "wordpress-plugin",
  "license": "GPL-2.0-or-later",
  "require": { "php": ">=8.1" },
  "require-dev": {
    "phpunit/phpunit": "^10",
    "brain/monkey": "^2.6",
    "wp-coding-standards/wpcs": "^3.0"
  },
  "autoload": { "psr-4": { "Atum\\<ProjectName>\\": "src/" } },
  "autoload-dev": { "psr-4": { "Atum\\<ProjectName>\\Tests\\": "tests/" } },
  "scripts": {
    "lint": "phpcs --standard=WordPress src/",
    "test": "phpunit"
  },
  "config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true } }
}

4. Type full

Combine block-theme + plugin dans un monorepo + ajoute :

• wp-env configuré via .wp-env.json (WordPress + le thème + le plugin montés)
• GitHub Actions : workflow de CI (PHPCS, PHPUnit, wp i18n make-pot)
• Makefile : raccourcis pour make install, make start, make test, make pot
• README.md du projet combiné avec instructions pour démarrer

5. Option --with-woocommerce

Si activée (sur plugin ou full) :

• Ajoute la déclaration de compatibilité HPOS dans Activator.php :

add_action('before_woocommerce_init', function () {
    if (class_exists('\Automattic\WooCommerce\Utilities\FeaturesUtil')) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
});

• Ajoute un template woocommerce/archive-product.php dans le thème si type full
• Ajoute woocommerce dans le tableau des dépendances plugin (Requires Plugins header)

POST-CREATE

Après création des fichiers, le command :

1. Affiche la structure créée avec un arbre ASCII
2. Affiche les prochaines étapes concrètes :
   • cd <project-name>
   • composer install (si plugin/full)
   • npm install && npm run build (si blocs)
   • wp-env start (si full)
3. Propose de lancer immédiatement les checks de qualité :
   • composer run lint (PHPCS)
   • composer run test (PHPUnit)
4. Rappelle la checklist agence (sécurité, i18n, accessibilité, SEO)

EXEMPLES

Thème FSE simple

/wordpress-setup mon-agence

Crée mon-agence/ avec block theme standard.

Plugin custom avec Gutenberg blocks

/wordpress-setup lead-capture --type=plugin --namespace=Atum\\LeadCapture

Crée un plugin avec structure PSR-4, namespace Atum\LeadCapture.

Projet complet monorepo avec WooCommerce

/wordpress-setup boutique-client --type=full --with-woocommerce

Crée un monorepo boutique-client/ avec thème + plugin compagnon + compat HPOS + wp-env configuré.

DÉPENDANCES

• Node.js 18+ (pour wp-scripts et le build des blocs)
• Composer 2+ (pour PSR-4 autoload et tooling PHP)
• WP-CLI recommandé (pour wp i18n make-pot, scaffolding secondaire)
• PHP 8.1+ (défaut, overridable via --php-version)

ANTI-PATTERNS ÉVITÉS PAR LE SCAFFOLD

Le scaffold ne crée jamais :

• Des thèmes classiques PHP sans theme.json (sauf si explicitement demandé)
• Des plugins sans uninstall.php
• Des hooks d'activation sans dbDelta
• Des endpoints REST sans permission_callback et args
• Des blocs custom sans block.json (API v3)
• Des enqueue inline (tout passe par wp_enqueue_*)

DÉLÉGATION

Une fois le scaffold en place, les prochaines étapes doivent être déléguées à :

• Agent wordpress-expert (ce plugin) pour écrire la logique métier
• Skill wordpress-patterns (ce plugin) pour les patterns sécurisés
• Skill woocommerce-patterns (ce plugin) pour les customisations e-commerce
• Agent security-reviewer (atum-reviewers) pour le security audit final
• Skill e2e-testing pour les tests Playwright post-scaffold