🛞Capstan
A WP-CLI command package that scaffolds, configures, and packages PressGang WordPress themes. Dry-run by default — preview every plan before it writes a byte.
Aboard ship, the capstan is the winch that hauls the anchor and gets the vessel underway. In your project, Capstan gets a new PressGang theme underway — WordPress core, parent theme, child theme, one command. ⚓
📦 Install
wp package install https://github.com/pressgang-wp/pressgang-capstan.gitRequirements: PHP 8.3+, WP-CLI, Composer
🧰 Commands
wp capstan new
Scaffold a full PressGang project — core, parent, child theme
wp capstan make child
Scaffold a child theme into an existing WordPress install
wp capstan make cpt
Scaffold a custom post type entry in config/custom-post-types.php
wp capstan make block
Scaffold an ACF block — block.json, Twig stub, config registration
wp capstan make controller
Scaffold a controller with a documented $context_getters manifest
wp capstan resolve <url>
Template hierarchy candidates → resolved controller for a URL
wp capstan context <Ctrl>
A controller's context manifest and getters; --add publishes keys
wp capstan config dump
The resolved PressGang configuration the theme boots with
wp capstan snippets
Registered snippets, their resolved classes and args
wp capstan doctor
Deterministic theme configuration health checks
wp capstan theme package
Build a WordPress-uploadable ZIP from a theme directory
wp capstan about
Capstan version, PHP version, WordPress root detection
🧭 Introspection
PressGang's conventions are invisible by design — introspection makes them verifiable:
These answer the questions agents (and new crew) ask most: which controller handles this URL, what data does the template get, and is the rigging sound? Bosun-composed guidelines teach agents these recipes.
doctor stays runtime-only: deterministic, fast, and heuristic-free. It should not absorb PHPStan-style static analysis, type checks, or convention inference. Use composer phpstan for static analysis and Shakedown for browser/runtime assertions.
wp capstan check is deliberately unbuilt. If it lands later, it must be a thin orchestrator that shells out to the target theme's composer check, runs wp capstan doctor, and reports both results. It must not re-implement, configure, or wrap PHPStan itself. Do not build it until at least one child theme has adopted a working composer check for Capstan to call.
🚀 New Project
One command takes you from empty directory to running PressGang project: downloads WordPress core, installs the parent theme via Composer, scaffolds a child theme, and optionally configures ACF Pro as an MU-plugin.
🧒 Child Theme
Scaffold a PressGang child theme into an existing WordPress installation — PSR-4 src/, config/ registration, Composer wiring, all from the maintained starter template.
After a scaffold's dependencies land, Capstan automatically runs Bosun (when installed) — so a freshly launched theme starts life with its AI crew already briefed. 🧭
📦 Theme Packaging
Build a ZIP ready for Appearance → Themes → Upload Theme. Build artifacts — .git/, node_modules/, editor directories, .env, dev config — are excluded automatically.
The ZIP lands alongside the theme directory by default (e.g. themes/my-theme.zip).
🧠 Philosophy
🗺️
Dry-run by default — always preview before writing
🎯
Explicit over implicit — no hidden global state
🔍
Minimal abstractions, maximum inspectability
🌍
Global by design — available before any project exists
🗺️ Roadmap
Capstan's README roadmap is the single source of truth for planned commands. Currently charted:
🖼️
theme screenshot
Generate a theme screenshot
🔗 Links
Heave away, and get her underway. 🛞⚓
Last updated