# New Plugin Guide

How to add a new Bowden Works WordPress plugin to this repo.

## Step 1: Scaffold

```bash
cd /srv/apps/bw-plugins
tools/new-plugin.sh bw-<slug> "BW <Display Name>" "Short description of what it does."
```

This creates `wp-content/plugins/bw-<slug>/` with the full standard structure:

- Main plugin file with proper header, VERSION constant, update-checker wiring
- README.md, CLAUDE.md, CHANGELOG.md, LICENSE, uninstall.php
- `docs/` with ARCHITECTURE, SPEC, ROADMAP, TESTING, KNOWN-ISSUES, HANDOFF-NOTES, SESSION-LOG
- `includes/`, `admin/`, `assets/{css,js,images}/`, `languages/`, `vendor/`
- Vendored `plugin-update-checker` library
- Activates the plugin on the dev site

Initial version is `0.1.0`.

## Step 2: Build it

Edit `wp-content/plugins/bw-<slug>/bw-<slug>.php` and add includes/classes under `includes/` as needed. Follow the standards in [CLAUDE-STANDARDS.md](CLAUDE-STANDARDS.md):

- Prefix everything with `bw_<slug>_`
- `defined( 'ABSPATH' ) || exit;` at the top of every PHP file
- Escape output (`esc_html`, `esc_attr`, `esc_url`)
- Prepare SQL (`$wpdb->prepare`)
- Verify nonces on state-changing actions
- Class files named `class-bw-<slug>-<thing>.php`

Update `docs/SPEC.md` with real requirements. Update `docs/ARCHITECTURE.md` as you go.

## Step 3: Test

Test on the dev site: https://bw-plugins.demoing.info (behind demoing-auth gate).

Run the scans any time:

```bash
tools/test-plugin.sh bw-<slug>
tools/cleanup-scan.sh bw-<slug>
tools/security-scan.sh bw-<slug>
```

Work through the manual test checklist in `docs/TESTING.md`.

## Step 4: Release

When ready to publish the first version:

```bash
tools/bump-version.sh bw-<slug> 0.1.0  # (optional for initial — already set)
# Edit CHANGELOG.md to add real entries under [0.1.0]
tools/release.sh bw-<slug> 0.1.0
```

See [RELEASE-PROCESS.md](RELEASE-PROCESS.md) for the full pipeline.

## Step 5: Add a product page on the dist site

Log into https://plugins.bowden.works/wp-admin/ and create a page at `/bw-<slug>/` with:

- Plugin name and description
- Screenshot(s)
- Link to download (auto-updated from latest release)
- Changelog section

## Conventions

- **Slug:** `bw-<kebab-case>`. Examples: `bw-source-capture`, `bw-ai-schema-pro`
- **Display name:** "BW \<Title Case\>". Examples: "BW Source Capture", "BW AI Schema Pro"
- **Prefix:** All globals/hooks/options/functions: `bw_<slug_underscored>_`
- **Constants:** `BW_<SLUG_UNDERSCORED>_<NAME>`
- **Class files:** `class-bw-<slug>-<thing>.php`
- **Version:** SemVer, `0.x.y` until stable, then `1.0.0`

## When in doubt

Read `docs/CLAUDE-STANDARDS.md` for cross-plugin coding rules, or look at an existing BW plugin in this repo for a reference implementation.