Norml WordPress Copilot Advanced
Installed skill: norml-wp-developer.
CLI only. Run this skill in Claude Code, Codex, or Gemini CLI with
filesystem and terminal access. It is not a Claude Desktop / Cowork upload
skill. Desktop users should use Norml WordPress Copilot (norml-wp-manager),
which operates through the WordPress REST API.
Local-only migration exception: For Squarespace-to-WordPress or HTML-to-WordPress builds before hosting exists, start with the migration recipe. It creates a verified local-only contract and disables every remote operation until normal hosting-connected onboarding passes.
Requires hosting-connected onboarding for remote work. Before this skill can perform hosting-connected work, the user must
run onboarding.md once per project on their machine. If
~/.config/norml-wp-developer/projects/{slug}.json is missing for the
project they're asking about, hard-stop and point at onboarding.md.
Never improvise the SSH connection by asking for host/port/passphrase in
chat.
⛔ HARD WARNING — backups are not optional and not provided
This skill does not make backups for you. The flows here — rsync
over SSH, wp db import, theme deploys, wp search-replace — can lose
data if a step fails or a wrong path is passed. You are expected to:
- Keep host-side automatic backups on (most managed hosts have this on
by default; verify in your hosting panel).
- Or take a manual backup before any destructive operation. A safe
manual backup is two things: a database dump and a
wp-content/
archive. Both must live OFF the server you're deploying to.
Every deploy command in this skill prints a backup-acknowledgement
prompt — you confirm a backup exists before the command runs. The
default answer is "no, abort." There is no autopilot here. If you
lose data, you lose data. No skill can recover it.
🟡 Working directly on the production server is elevated risk
The skill supports two modes:
- Local-first (recommended). Develop locally against WP Local /
DDEV / similar. Commit to Git. Push. CI/CD ships to staging, you
smoke test, then promote to production. Mistakes stay local until
you explicitly promote them. This is the pattern setup defaults
to.
- Direct-on-server. Edit theme files on the production server via
SSH. Faster for one-line hotfixes; risky because there's no
local copy to fall back to and the next CI/CD deploy can
overwrite your live edit if it isn't mirrored to Git. Permitted
but every direct-on-server write is logged as
[DIRECT-PROD] in
the project changelog and triggers a warning that the change is
not in Git.
Default to local-first. Reach for direct-on-server only when the
developer has explicitly chosen it for a specific operation.
When to use
For "migrate my Squarespace website", "turn this mirror into WordPress", or
"build this HTML mockup in WordPress", read Squarespace to WordPress first.
Any request to build, modify, or deploy theme code for a WordPress
site. Typical asks:
- "Set up a new WordPress project from scratch."
- "Initialize this WordPress theme repo — scaffold
.claude/, set up
Git, wire it to GitHub."
- "Build a hero block with ACF fields."
- "Add a new ACF block to the existing theme."
- "Ship this to staging."
- "Promote staging to production."
- "Hot-fix a typo on production — direct on the server."
- "Pull production database down to my local."
- "What's the CI/CD pattern for this project?"
Skip if
- The work is content management on a deployed site (posts, ACF
values, media, users, settings). → use
norml-wp-manager. That skill
is REST-API-only, doesn't require SSH, and is safer to hand to
non-developers.
- The work is fixing the WordPress install itself (broken database,
corrupted core files, hosting migration). → escalate to the hosting
provider's support or use a dedicated migration skill.
- The work is security testing / penetration testing. → use a
dedicated security skill.
Three-phase mental model
Every interaction with this skill falls into one of three phases. Each
phase has its own rules + safety posture.
1. Setup (one-time per project)
Done once per project. Outputs:
~/.config/norml-wp-developer/projects/{slug}.json — per-project
connection config (no secrets).
- SSH key (existing or generated) registered with
ssh-agent.
- SSH passphrase (if any) in macOS Keychain / Windows Credential Manager.
- Local WordPress environment detected (WP Local default; DDEV / Lando /
Valet / Local Lightning recognized as alternates).
- Git repo initialized in the theme folder, first commit made.
- GitHub remote configured and read-only connectivity verified.
.claude/ scaffolded inside the theme repo with CLAUDE.md,
capabilities.md, architecture.md, ci-cd.md, rolling changelog,
and generated architecture docs.
- CI/CD pattern chosen +
.github/workflows/ scaffolded.
- Required first-time read-only architecture scrape via WP-CLI over SSH.
See development-guides/wp-local-setup.md for the local environment details and
onboarding.md for the step-by-step.
2. Develop (the everyday workflow)
After setup, building is the bulk of the work. Rules vary by project mode:
- New / Sage-based project (Norml-authored): Roots Sage + Acorn +
Blade + Tailwind v4 + Vite + Alpine.js + ACF Pro. Read
development-guides/dev-conventions.md → Mode A, which routes to
conventions/sage-stack.md, component-system.md,
css-architecture.md, and acf-blocks.md.
- Inherited project (non-Sage, handed to us): respect the existing
architecture. Apply the framework-agnostic core principles
(section/component/partial separation, ACF block registration,
block previews, 3-layer CSS model) inside the existing theme.
Read
development-guides/dev-conventions.md → Mode B, which routes to
conventions/inherited-projects.md (+ css-architecture.md and
acf-blocks.md for the cross-cutting specifics).
Git workflow + commit conventions are the same for both:
GitHub Flow + Conventional Commits. See development-guides/git-workflow.md.
3. Deploy (the gated, backup-required workflow)
The deploy phase runs:
npm run build (or yarn / pnpm equivalent) → produces production
assets.
git push → triggers CI/CD if configured.
- Or
rsync -avz --delete over SSH for direct deploys (no CI/CD).
wp cache flush + wp acorn view:cache (Sage projects) on the
server after deploy.
- Smoke test (HEAD on the homepage, follow-up GET on a CPT archive).
- For staging→prod promotions: re-run the staging deploy steps against
the production server.
Every deploy gates on the backup acknowledgement prompt described in
the HARD WARNING block above. Without acknowledgement, the deploy
aborts. See development-guides/ci-cd/patterns.md for the three supported
patterns and their command sequences, development-guides/qa-gates.md for the
pre-deploy and post-deploy QA checkpoints (staging-based for
full-pipeline, local-based for the prod-direct patterns), and
development-guides/ci-cd/backup-strategies.md for the per-provider backup +
restore detail behind the acknowledgement.
Pre-flight (every session, before the first dev/deploy operation)
If this is an explicitly selected local-only build, use the local pre-flight in
the migration recipe instead.
The following full pre-flight remains mandatory for any hosting-connected operation.
Resolve the project slug from the user's request, the working
directory, or by asking. Slugs are kebab-cased.
Read ~/.config/norml-wp-developer/projects/{slug}.json.
- If missing → hard-stop. Tell the user the project isn't
configured and point them at
onboarding.md. Do NOT improvise SSH
details in chat.
Read the project's .claude/CLAUDE.md and .claude/ci-cd.md
from the theme repo path in the project JSON.
- If
.claude/ is missing → tell the user the project isn't
initialized and offer to run init (scripts/init-claude.sh /
init-claude.ps1) to scaffold it. Don't proceed with dev work
against an un-initialized repo.
Read .claude/capabilities.md and .claude/architecture.md.
capabilities.md is the live operating contract for GitHub, SSH,
WP-CLI, local development, staging, and production.
architecture.md is the index into the latest generated site and theme
snapshot under .claude/docs/.
- If either is missing or still says the first scan is pending, run
scripts/scrape-architecture.sh {slug} (or the PowerShell mirror) before
development.
Read the project changelog at
{theme_root}/.claude/changelog/daily.md (or changelog.md if the
project skipped the rolling-three-tier setup). Surface the most
recent entries — they tell you what was just done.
Identify the project mode from .claude/CLAUDE.md:
mode: sage → New / Norml-authored. Apply Sage conventions.
mode: inherited → Respect the existing theme. Apply
framework-agnostic principles.
Resolve the SSH alias to the production server from the project
JSON. Confirm the alias exists in ~/.ssh/config (the setup script
writes it; if it's missing, re-run setup).
Identify the deploy pattern from .claude/ci-cd.md:
full-pipeline — Git push → CI/CD → staging → manual promote → prod
prod-direct-with-git — Git push → server pulls from Git → prod
prod-direct-no-ci — rsync from local → prod (no automated deployment pipeline; source still committed and pushed to GitHub)
You now have everything needed to operate. Never ask for SSH
passphrases, GitHub tokens, or server passwords in chat. If anything's
missing, point back at onboarding.
Project knowledge layer — inside the theme repo
Every project carries its own .claude/ directory inside the theme
repository (not in the user's project folder, not on Drive — inside
the repo, so it travels with the code).
{theme_root}/.claude/
├── CLAUDE.md # Project overview, mode (sage/inherited), pointers
├── capabilities.md # Generated operating contract for this project
├── architecture.md # Generated architecture summary + docs index
├── ci-cd.md # Per-project deploy contract (pattern, envs, hooks)
├── changelog/
│ ├── README.md # The rolling-three-tier protocol
│ ├── daily.md # Today's raw entries
│ ├── weekly.md # Compressed week
│ └── changelog.md # Long-term history
├── docs/ # 5-file read-only architecture scrape
│ ├── 01-infrastructure.md
│ ├── 02-application.md
│ ├── 03-theme-architecture.md
│ ├── 04-content-structure.md
│ └── 05-issues.md
└── skills/ # Project-specific skills (empty by default)
This is the canonical knowledge layer for this project. Both the
human developer and Claude read from it at every session. It is in
git, committed with the theme code, travels everywhere the repo
travels.
Why .claude/ lives in the theme repo (not in ~/.config/ or on
Drive)
| Concern |
Where it lives |
Why |
| Connection details (host, port, SSH key path, Git remote URL) |
~/.config/norml-wp-developer/projects/{slug}.json |
Per-machine, private. Doesn't travel with the code. |
| Project knowledge (architecture, conventions, decisions, changelog) |
{theme_root}/.claude/ |
Lives with the code, travels in git, available to anyone who clones the repo. |
| Secrets (SSH passphrase, GitHub PAT) |
macOS Keychain / Windows Credential Manager / ssh-agent |
OS-managed. Claude never sees the value. |
This split is non-negotiable. Never write a secret into
{theme_root}/.claude/ — those files are committed to git. Never write
deploy state or build artifacts into ~/.config/ either — they're
per-machine config, not knowledge.
Write-back rules — how the skill compounds knowledge per-project
The point of .claude/ is that every session leaves it richer. Three
write-back triggers:
daily.md — close-of-session changelog (always)
Append an entry to {theme_root}/.claude/changelog/daily.md before
ending any session that:
- Wrote theme code (component, block, template, function)
- Ran a deploy to staging or production
- Performed a direct-on-server edit
- Pulled production DB / uploads to local
- Made a non-trivial decision the next session would benefit from
knowing
Tags:
[CODE] — theme code change
[BUILD] — Vite / Composer / NPM build ran
[DEPLOY-STAGING] — push or deploy to staging
[DEPLOY-PROD] — promote to prod (gated by backup acknowledgement)
[DIRECT-PROD] — edit made directly on the production server (high
risk, flag the un-mirrored-to-git status)
[PULL-DB] — production DB pulled to local
[PULL-UPLOADS] — production uploads pulled to local
[DECISION] — architectural choice worth recording
[LEARNED] — non-obvious fact about this project
The daily file compresses to weekly.md weekly and to changelog.md
when the calendar quarter rolls over — see
{theme_root}/.claude/changelog/README.md for the protocol the init
flow scaffolds.
.claude/CLAUDE.md — project-level decisions
When the user makes a project-level decision ("from now on this site
uses BEM for component class names," "we always set show_in_rest: true on ACF field groups"), update the relevant section of
CLAUDE.md. This file is the durable answer to "how do we work on
this project."
.claude/capabilities.md + architecture docs — rescan only
The visible capability contract, architecture index, and 5-file snapshot are
generated by scripts/scrape-architecture.sh (or .ps1) from local theme files,
Git/GitHub state, and read-only WP-CLI commands over SSH. They are overwritten on
rescan. Anything that should survive a rescan goes in CLAUDE.md or daily.md,
never hand-edited into generated files.
Safety classification — every operation buckets
Three buckets:
Safe — read-only or low-risk single-item operations. Run
immediately. Examples: git status, git log, wp post list on
local, reading any file under the theme repo, listing the active
plugin set.
Confirm — anything that writes to the local repo, to staging, or
changes git state. Show the exact command, show the diff if relevant,
ask for "yes" before running. Examples: git commit, git push,
git rebase, rsync to staging, wp plugin install on local,
database imports.
Confirm + backup — anything that writes to the production server.
Show the exact command, show the backup-acknowledgement prompt,
refuse without an explicit "I have a backup from {date}" reply.
Examples: rsync to production, wp db import on production,
wp search-replace on production, deleting plugin/theme files on
production, direct file edits over SSH on production.
The backup-acknowledgement prompt is mandatory for every production
write. There is no "skip the prompt" flag. If the project's
.claude/ci-cd.md declares the host has automatic backups (and we
trust the host), the prompt may be answered with "yes, host backups
verified" — but only if ci-cd.md says so, and only after the user
explicitly types that phrase.
Output style
- Default to terse. The user wants the result.
- When you ran a command, show the command first (one line, monospaced).
- For
Confirm + backup operations, the backup prompt is mandatory and
shown verbatim. Don't paraphrase it.
- For diffs, prefer
git diff --stat for summary + the full diff on
request rather than dumping 500 lines unprompted.
Error handling
- SSH refused / timeout → don't retry. Suggest the user run
scripts/test-ssh.sh and check their ~/.ssh/config alias.
wp: command not found on the remote → WP-CLI not installed on
the server. Stop, tell the user, suggest contacting their host.
Composer detected ... platform_check.php → server PHP < theme's
Composer floor. Stop, point at the composer.json require.php
line, tell the user to either bump the server PHP or lower the
theme's floor.
- Git conflicts → don't auto-resolve. Show the conflicting files,
let the user pick the side. Conventional Commit rules in
development-guides/git-workflow.md.
- Build failures → show the full Vite / Composer / NPM error, stop,
do not deploy with a failing build.
- Deploy failures mid-flight → stop immediately. Tell the user the
exact step that failed. Do not auto-retry — partial deploys are the
most common cause of broken production.
In all cases, fail loudly and stop. No improvised destructive
recovery.
Knowledge baseline — what the skill reads
| File |
When to read |
development-guides/dev-conventions.md |
At the start of any session that touches theme code. The router — routes to the right conventions/ files by project mode, plus the global rules (Conventional Commits, don't-commit artifacts/secrets, ACF JSON sync caveat). |
development-guides/conventions/sage-stack.md |
Sage / new projects, before building. The Sage + Acorn + Blade + Tailwind v4 + Vite + Alpine + ACF Pro foundation. |
development-guides/conventions/component-system.md |
Before building a section / component / block in a Sage project. Anatomy + core component catalog + the Alpine pattern + layout. |
development-guides/conventions/css-architecture.md |
Before writing ANY CSS, either mode. The 3-layer model + the forbidden per-page-stylesheet rule. |
development-guides/conventions/acf-blocks.md |
Before registering an ACF block or its preview, either mode. Registration + previews + ACF JSON sync. |
development-guides/conventions/inherited-projects.md |
FIRST, whenever you open a non-Sage / inherited theme. Respect-existing decision flow + framework-agnostic principles. |
development-guides/git-workflow.md |
Before any git commit, git push, branch creation, or PR. GitHub Flow + Conventional Commits. |
development-guides/ci-cd/patterns.md |
Before any deploy or any CI/CD configuration task. The three supported patterns and the per-project ci-cd.md contract. |
development-guides/ci-cd/database-strategies.md |
When content / the database moves (or must not move) between environments. |
development-guides/ci-cd/backup-strategies.md |
Before any production write — backup provider, verification, restore runbook, acknowledgement tier. |
development-guides/qa-gates.md |
Before merging, before deploying, and right after deploying. The pre-merge / pre-deploy / post-deploy checkpoints. |
development-guides/safety-rules.md |
At session start. The full Safe / Confirm / Confirm+backup classification with examples. |
development-guides/wp-local-setup.md |
During onboarding, or if the local environment is unclear. WP Local default, DDEV / Lando / Valet / Local Lightning as alternates. |
{theme_root}/.claude/CLAUDE.md |
At session start. Project mode (sage / inherited), live URLs, deploy hints. |
{theme_root}/.claude/capabilities.md |
At session start and before any operation. Verified GitHub, SSH, WP-CLI, local, staging, and production boundary. |
{theme_root}/.claude/architecture.md |
At session start. Latest architecture snapshot summary and read order. |
{theme_root}/.claude/ci-cd.md |
Before any deploy. Per-project pattern, deploy commands, pre/post hooks. |
{theme_root}/.claude/changelog/daily.md |
At session start. The last ~20 entries — what the last sessions touched. |
Hard rules
- Never deploy without an acknowledged backup. The backup-
acknowledgement prompt is mandatory for every production write.
- Never write secrets into committed files. SSH keys, GitHub
PATs, database passwords belong in the OS secret store or
ssh-agent — never in .claude/, never in .env checked into
git, never in commit messages.
- Never silently overwrite production. Every prod write shows the
exact command and waits for explicit "yes."
- Never introduce a new framework on an inherited project without
explicit, in-session approval. Match the existing architecture.
- Always log production writes as
[DEPLOY-PROD] or
[DIRECT-PROD] in daily.md before closing the response.
- Stop on any unexpected error. No improvised recovery.
.claude/ is committed to git. Never write secrets to it.
~/.config/norml-wp-developer/projects/*.json is per-machine and
never committed.
- Local-first is the default. Direct-on-server is permitted but
explicit per-operation. Never default to it.
Related skills
Companion (install both for a full WordPress workflow):
norml-wp-manager — REST-API-only content management on a deployed
site. Use it for posts, pages, ACF values, media. This skill
(norml-wp-developer) is for theme code; norml-wp-manager is for
content. They share no state.
What lives where (recap)
| What |
Where |
Why |
| The skill itself |
Runtime-specific skills directory |
Claude Code, Codex, or Gemini CLI discovers the stable norml-wp-developer slug. |
| Per-project connection config |
~/.config/norml-wp-developer/projects/{slug}.json |
Per-machine. Host, SSH alias, theme repo path, remote URL, deploy pattern. No secrets. |
| Per-project knowledge |
{theme_root}/.claude/ |
Lives in the GitHub repo. Travels with the code. CLAUDE.md, capabilities.md, architecture.md, ci-cd.md, changelog, architecture docs. |
| SSH key |
~/.ssh/{key} |
Owned by the user; ssh-agent holds the passphrase. |
| SSH passphrase |
macOS Keychain (via ssh-add --apple-use-keychain) / Windows ssh-agent (DPAPI-backed) |
OS-managed. Claude never reads it. |
The split is intentional: ~/.config/ is per-machine connection state;
{theme_root}/.claude/ is portable per-project knowledge; the OS
secret store is for secrets.
1---2name: norml-wp-developer3version: 1.3.04requires_onboarding: true5description: >6 Norml WordPress Copilot Advanced: rebuild Squarespace captures and HTML mockups7 as editable WordPress in Local, with local-only onboarding before hosting. The CLI-only WordPress development8 skill for Claude Code, Codex, and Gemini CLI. Develop themes locally9 and deploy through SSH + Git + GitHub Actions. WP Local is the default10 local environment (DDEV / Lando / Valet recognized too). Per-project11 onboarding connects GitHub and SSH, verifies remote WP-CLI, chooses the12 CI/CD pattern, scaffolds .claude/ inside the theme repo, generates13 capabilities.md, and records a five-file architecture snapshot. The14 everyday workflow is edit locally, commit, push, stage, smoke15 test, promote to prod. **Does NOT make backups.** Every production16 write gates on a backup acknowledgement. Direct-on-server work is17 permitted but flagged and logged. Local-first is the default. Use18 when the user says "build a WordPress theme," "develop a WP site,"19 "set up a new WP project," "init this WP project," "ship to20 staging," "deploy to production," "promote to prod," "set up CI/CD21 for WordPress," "what's the deploy flow," "pull production DB,"22 "rescan architecture," "norml-wp-developer," or23 "/norml-wp-developer." Companion: `norml-wp-manager` (REST-only24 content mgmt). The two share no state.25metadata:26 source: https://skillmd.com/skills/normlstudio/norml-wp-developer27 author: "Norml Studio"28---2930# Norml WordPress Copilot Advanced3132Installed skill: `norml-wp-developer`.3334> **CLI only.** Run this skill in Claude Code, Codex, or Gemini CLI with35> filesystem and terminal access. It is not a Claude Desktop / Cowork upload36> skill. Desktop users should use Norml WordPress Copilot (`norml-wp-manager`),37> which operates through the WordPress REST API.3839> **Local-only migration exception:** For Squarespace-to-WordPress or HTML-to-WordPress builds before hosting exists, start with [the migration recipe](development-guides/squarespace-to-wordpress.md). It creates a verified local-only contract and disables every remote operation until normal hosting-connected onboarding passes.4041> **Requires hosting-connected onboarding for remote work.** Before this skill can perform hosting-connected work, the user must42> run `onboarding.md` once per project on their machine. If43> `~/.config/norml-wp-developer/projects/{slug}.json` is missing for the44> project they're asking about, hard-stop and point at `onboarding.md`.45> Never improvise the SSH connection by asking for host/port/passphrase in46> chat.4748> ## ⛔ HARD WARNING — backups are not optional and not provided49>50> This skill does **not** make backups for you. The flows here — `rsync`51> over SSH, `wp db import`, theme deploys, `wp search-replace` — can lose52> data if a step fails or a wrong path is passed. You are expected to:53>54> - Keep host-side automatic backups on (most managed hosts have this on55> by default; verify in your hosting panel).56> - Or take a manual backup before any destructive operation. A safe57> manual backup is two things: a database dump and a `wp-content/`58> archive. Both must live OFF the server you're deploying to.59>60> Every deploy command in this skill prints a backup-acknowledgement61> prompt — you confirm a backup exists before the command runs. The62> default answer is "no, abort." There is no autopilot here. **If you63> lose data, you lose data.** No skill can recover it.6465> ## 🟡 Working directly on the production server is elevated risk66>67> The skill supports two modes:68>69> 1. **Local-first (recommended).** Develop locally against WP Local /70> DDEV / similar. Commit to Git. Push. CI/CD ships to staging, you71> smoke test, then promote to production. Mistakes stay local until72> you explicitly promote them. **This is the pattern setup defaults73> to.**74> 2. **Direct-on-server.** Edit theme files on the production server via75> SSH. Faster for one-line hotfixes; risky because there's no76> local copy to fall back to and the next CI/CD deploy can77> overwrite your live edit if it isn't mirrored to Git. Permitted78> but every direct-on-server write is logged as `[DIRECT-PROD]` in79> the project changelog and triggers a warning that the change is80> not in Git.81>82> Default to local-first. Reach for direct-on-server only when the83> developer has explicitly chosen it for a specific operation.8485## When to use8687For "migrate my Squarespace website", "turn this mirror into WordPress", or88"build this HTML mockup in WordPress", read [Squarespace to WordPress](development-guides/squarespace-to-wordpress.md) first.8990Any request to **build, modify, or deploy theme code** for a WordPress91site. Typical asks:9293- *"Set up a new WordPress project from scratch."*94- *"Initialize this WordPress theme repo — scaffold `.claude/`, set up95 Git, wire it to GitHub."*96- *"Build a hero block with ACF fields."*97- *"Add a new ACF block to the existing theme."*98- *"Ship this to staging."*99- *"Promote staging to production."*100- *"Hot-fix a typo on production — direct on the server."*101- *"Pull production database down to my local."*102- *"What's the CI/CD pattern for this project?"*103104## Skip if105106- The work is **content management on a deployed site** (posts, ACF107 values, media, users, settings). → use `norml-wp-manager`. That skill108 is REST-API-only, doesn't require SSH, and is safer to hand to109 non-developers.110- The work is **fixing the WordPress install itself** (broken database,111 corrupted core files, hosting migration). → escalate to the hosting112 provider's support or use a dedicated migration skill.113- The work is **security testing / penetration testing**. → use a114 dedicated security skill.115116## Three-phase mental model117118Every interaction with this skill falls into one of three phases. Each119phase has its own rules + safety posture.120121### 1. Setup (one-time per project)122123Done once per project. Outputs:124125- `~/.config/norml-wp-developer/projects/{slug}.json` — per-project126 connection config (no secrets).127- SSH key (existing or generated) registered with `ssh-agent`.128- SSH passphrase (if any) in macOS Keychain / Windows Credential Manager.129- Local WordPress environment detected (WP Local default; DDEV / Lando /130 Valet / Local Lightning recognized as alternates).131- Git repo initialized in the theme folder, first commit made.132- GitHub remote configured and read-only connectivity verified.133- `.claude/` scaffolded inside the theme repo with `CLAUDE.md`,134 `capabilities.md`, `architecture.md`, `ci-cd.md`, rolling changelog,135 and generated architecture docs.136- CI/CD pattern chosen + `.github/workflows/` scaffolded.137- Required first-time read-only architecture scrape via WP-CLI over SSH.138139See `development-guides/wp-local-setup.md` for the local environment details and140`onboarding.md` for the step-by-step.141142### 2. Develop (the everyday workflow)143144After setup, building is the bulk of the work. Rules vary by project mode:145146- **New / Sage-based project (Norml-authored):** Roots Sage + Acorn +147 Blade + Tailwind v4 + Vite + Alpine.js + ACF Pro. Read148 `development-guides/dev-conventions.md` → Mode A, which routes to149 `conventions/sage-stack.md`, `component-system.md`,150 `css-architecture.md`, and `acf-blocks.md`.151- **Inherited project (non-Sage, handed to us):** respect the existing152 architecture. Apply the framework-agnostic core principles153 (section/component/partial separation, ACF block registration,154 block previews, 3-layer CSS model) inside the existing theme.155 Read `development-guides/dev-conventions.md` → Mode B, which routes to156 `conventions/inherited-projects.md` (+ `css-architecture.md` and157 `acf-blocks.md` for the cross-cutting specifics).158159Git workflow + commit conventions are the same for both:160GitHub Flow + Conventional Commits. See `development-guides/git-workflow.md`.161162### 3. Deploy (the gated, backup-required workflow)163164The deploy phase runs:165166- `npm run build` (or yarn / pnpm equivalent) → produces production167 assets.168- `git push` → triggers CI/CD if configured.169- Or `rsync -avz --delete` over SSH for direct deploys (no CI/CD).170- `wp cache flush` + `wp acorn view:cache` (Sage projects) on the171 server after deploy.172- Smoke test (HEAD on the homepage, follow-up GET on a CPT archive).173- For staging→prod promotions: re-run the staging deploy steps against174 the production server.175176Every deploy gates on the **backup acknowledgement prompt** described in177the HARD WARNING block above. Without acknowledgement, the deploy178aborts. See `development-guides/ci-cd/patterns.md` for the three supported179patterns and their command sequences, `development-guides/qa-gates.md` for the180pre-deploy and post-deploy QA checkpoints (staging-based for181`full-pipeline`, local-based for the prod-direct patterns), and182`development-guides/ci-cd/backup-strategies.md` for the per-provider backup +183restore detail behind the acknowledgement.184185## Pre-flight (every session, before the first dev/deploy operation)186187If this is an explicitly selected local-only build, use the local pre-flight in188[the migration recipe](development-guides/squarespace-to-wordpress.md) instead.189The following full pre-flight remains mandatory for any hosting-connected operation.1901911. **Resolve the project slug** from the user's request, the working192 directory, or by asking. Slugs are kebab-cased.1931942. **Read `~/.config/norml-wp-developer/projects/{slug}.json`.**195 - If missing → hard-stop. Tell the user the project isn't196 configured and point them at `onboarding.md`. Do NOT improvise SSH197 details in chat.1981993. **Read the project's `.claude/CLAUDE.md` and `.claude/ci-cd.md`**200 from the theme repo path in the project JSON.201 - If `.claude/` is missing → tell the user the project isn't202 initialized and offer to run init (scripts/init-claude.sh /203 init-claude.ps1) to scaffold it. Don't proceed with dev work204 against an un-initialized repo.2052064. **Read `.claude/capabilities.md` and `.claude/architecture.md`.**207 - `capabilities.md` is the live operating contract for GitHub, SSH,208 WP-CLI, local development, staging, and production.209 - `architecture.md` is the index into the latest generated site and theme210 snapshot under `.claude/docs/`.211 - If either is missing or still says the first scan is pending, run212 `scripts/scrape-architecture.sh {slug}` (or the PowerShell mirror) before213 development.2142155. **Read the project changelog** at216 `{theme_root}/.claude/changelog/daily.md` (or `changelog.md` if the217 project skipped the rolling-three-tier setup). Surface the most218 recent entries — they tell you what was just done.2192206. **Identify the project mode** from `.claude/CLAUDE.md`:221 - `mode: sage` → New / Norml-authored. Apply Sage conventions.222 - `mode: inherited` → Respect the existing theme. Apply223 framework-agnostic principles.2242257. **Resolve the SSH alias** to the production server from the project226 JSON. Confirm the alias exists in `~/.ssh/config` (the setup script227 writes it; if it's missing, re-run setup).2282298. **Identify the deploy pattern** from `.claude/ci-cd.md`:230 - `full-pipeline` — Git push → CI/CD → staging → manual promote → prod231 - `prod-direct-with-git` — Git push → server pulls from Git → prod232 - `prod-direct-no-ci` — rsync from local → prod (no automated deployment pipeline; source still committed and pushed to GitHub)233234You now have everything needed to operate. **Never** ask for SSH235passphrases, GitHub tokens, or server passwords in chat. If anything's236missing, point back at onboarding.237238## Project knowledge layer — inside the theme repo239240Every project carries its own `.claude/` directory **inside the theme241repository** (not in the user's project folder, not on Drive — inside242the repo, so it travels with the code).243244```245{theme_root}/.claude/246├── CLAUDE.md # Project overview, mode (sage/inherited), pointers247├── capabilities.md # Generated operating contract for this project248├── architecture.md # Generated architecture summary + docs index249├── ci-cd.md # Per-project deploy contract (pattern, envs, hooks)250├── changelog/251│ ├── README.md # The rolling-three-tier protocol252│ ├── daily.md # Today's raw entries253│ ├── weekly.md # Compressed week254│ └── changelog.md # Long-term history255├── docs/ # 5-file read-only architecture scrape256│ ├── 01-infrastructure.md257│ ├── 02-application.md258│ ├── 03-theme-architecture.md259│ ├── 04-content-structure.md260│ └── 05-issues.md261└── skills/ # Project-specific skills (empty by default)262```263264This is the **canonical knowledge layer for this project**. Both the265human developer and Claude read from it at every session. It is **in266git, committed with the theme code, travels everywhere the repo267travels.**268269### Why `.claude/` lives in the theme repo (not in `~/.config/` or on270Drive)271272| Concern | Where it lives | Why |273|---|---|---|274| Connection details (host, port, SSH key path, Git remote URL) | `~/.config/norml-wp-developer/projects/{slug}.json` | Per-machine, private. Doesn't travel with the code. |275| Project knowledge (architecture, conventions, decisions, changelog) | `{theme_root}/.claude/` | Lives with the code, travels in git, available to anyone who clones the repo. |276| Secrets (SSH passphrase, GitHub PAT) | macOS Keychain / Windows Credential Manager / ssh-agent | OS-managed. Claude never sees the value. |277278This split is non-negotiable. **Never write a secret into279`{theme_root}/.claude/` — those files are committed to git.** Never write280deploy state or build artifacts into `~/.config/` either — they're281per-machine config, not knowledge.282283## Write-back rules — how the skill compounds knowledge per-project284285The point of `.claude/` is that **every session leaves it richer**. Three286write-back triggers:287288### `daily.md` — close-of-session changelog (always)289290Append an entry to `{theme_root}/.claude/changelog/daily.md` before291ending any session that:292293- Wrote theme code (component, block, template, function)294- Ran a deploy to staging or production295- Performed a direct-on-server edit296- Pulled production DB / uploads to local297- Made a non-trivial decision the next session would benefit from298 knowing299300Tags:301302- `[CODE]` — theme code change303- `[BUILD]` — Vite / Composer / NPM build ran304- `[DEPLOY-STAGING]` — push or deploy to staging305- `[DEPLOY-PROD]` — promote to prod (gated by backup acknowledgement)306- `[DIRECT-PROD]` — edit made directly on the production server (high307 risk, flag the un-mirrored-to-git status)308- `[PULL-DB]` — production DB pulled to local309- `[PULL-UPLOADS]` — production uploads pulled to local310- `[DECISION]` — architectural choice worth recording311- `[LEARNED]` — non-obvious fact about this project312313The daily file compresses to `weekly.md` weekly and to `changelog.md`314when the calendar quarter rolls over — see315`{theme_root}/.claude/changelog/README.md` for the protocol the init316flow scaffolds.317318### `.claude/CLAUDE.md` — project-level decisions319320When the user makes a project-level decision ("from now on this site321uses BEM for component class names," "we always set `show_in_rest:322true` on ACF field groups"), update the relevant section of323`CLAUDE.md`. This file is the durable answer to "how do we work on324this project."325326### `.claude/capabilities.md` + architecture docs — rescan only327328The visible capability contract, architecture index, and 5-file snapshot are329generated by `scripts/scrape-architecture.sh` (or `.ps1`) from local theme files,330Git/GitHub state, and read-only WP-CLI commands over SSH. They are overwritten on331rescan. Anything that should survive a rescan goes in `CLAUDE.md` or `daily.md`,332never hand-edited into generated files.333334## Safety classification — every operation buckets335336Three buckets:337338- **Safe** — read-only or low-risk single-item operations. Run339 immediately. Examples: `git status`, `git log`, `wp post list` on340 local, reading any file under the theme repo, listing the active341 plugin set.342343- **Confirm** — anything that writes to the local repo, to staging, or344 changes git state. Show the exact command, show the diff if relevant,345 ask for "yes" before running. Examples: `git commit`, `git push`,346 `git rebase`, `rsync` to staging, `wp plugin install` on local,347 database imports.348349- **Confirm + backup** — anything that writes to the production server.350 Show the exact command, **show the backup-acknowledgement prompt**,351 refuse without an explicit "I have a backup from {date}" reply.352 Examples: `rsync` to production, `wp db import` on production,353 `wp search-replace` on production, deleting plugin/theme files on354 production, direct file edits over SSH on production.355356The backup-acknowledgement prompt is mandatory for every production357write. There is no "skip the prompt" flag. If the project's358`.claude/ci-cd.md` declares the host has automatic backups (and we359trust the host), the prompt may be answered with "yes, host backups360verified" — but only if `ci-cd.md` says so, and only after the user361explicitly types that phrase.362363## Output style364365- Default to terse. The user wants the result.366- When you ran a command, show the command first (one line, monospaced).367- For `Confirm + backup` operations, the backup prompt is mandatory and368 shown verbatim. Don't paraphrase it.369- For diffs, prefer `git diff --stat` for summary + the full diff on370 request rather than dumping 500 lines unprompted.371372## Error handling373374- **SSH refused / timeout** → don't retry. Suggest the user run375 `scripts/test-ssh.sh` and check their `~/.ssh/config` alias.376- **`wp: command not found` on the remote** → WP-CLI not installed on377 the server. Stop, tell the user, suggest contacting their host.378- **`Composer detected ... platform_check.php`** → server PHP < theme's379 Composer floor. Stop, point at the `composer.json` `require.php`380 line, tell the user to either bump the server PHP or lower the381 theme's floor.382- **Git conflicts** → don't auto-resolve. Show the conflicting files,383 let the user pick the side. Conventional Commit rules in384 `development-guides/git-workflow.md`.385- **Build failures** → show the full Vite / Composer / NPM error, stop,386 do not deploy with a failing build.387- **Deploy failures mid-flight** → stop immediately. Tell the user the388 exact step that failed. Do not auto-retry — partial deploys are the389 most common cause of broken production.390391In all cases, **fail loudly and stop**. No improvised destructive392recovery.393394## Knowledge baseline — what the skill reads395396| File | When to read |397|---|---|398| `development-guides/dev-conventions.md` | At the start of any session that touches theme code. The **router** — routes to the right `conventions/` files by project mode, plus the global rules (Conventional Commits, don't-commit artifacts/secrets, ACF JSON sync caveat). |399| `development-guides/conventions/sage-stack.md` | Sage / new projects, before building. The Sage + Acorn + Blade + Tailwind v4 + Vite + Alpine + ACF Pro foundation. |400| `development-guides/conventions/component-system.md` | Before building a section / component / block in a Sage project. Anatomy + core component catalog + the Alpine pattern + layout. |401| `development-guides/conventions/css-architecture.md` | Before writing ANY CSS, **either mode**. The 3-layer model + the forbidden per-page-stylesheet rule. |402| `development-guides/conventions/acf-blocks.md` | Before registering an ACF block or its preview, **either mode**. Registration + previews + ACF JSON sync. |403| `development-guides/conventions/inherited-projects.md` | FIRST, whenever you open a non-Sage / inherited theme. Respect-existing decision flow + framework-agnostic principles. |404| `development-guides/git-workflow.md` | Before any `git commit`, `git push`, branch creation, or PR. GitHub Flow + Conventional Commits. |405| `development-guides/ci-cd/patterns.md` | Before any deploy or any CI/CD configuration task. The three supported patterns and the per-project `ci-cd.md` contract. |406| `development-guides/ci-cd/database-strategies.md` | When content / the database moves (or must not move) between environments. |407| `development-guides/ci-cd/backup-strategies.md` | Before any production write — backup provider, verification, restore runbook, acknowledgement tier. |408| `development-guides/qa-gates.md` | Before merging, before deploying, and right after deploying. The pre-merge / pre-deploy / post-deploy checkpoints. |409| `development-guides/safety-rules.md` | At session start. The full Safe / Confirm / Confirm+backup classification with examples. |410| `development-guides/wp-local-setup.md` | During onboarding, or if the local environment is unclear. WP Local default, DDEV / Lando / Valet / Local Lightning as alternates. |411| `{theme_root}/.claude/CLAUDE.md` | At session start. Project mode (sage / inherited), live URLs, deploy hints. |412| `{theme_root}/.claude/capabilities.md` | At session start and before any operation. Verified GitHub, SSH, WP-CLI, local, staging, and production boundary. |413| `{theme_root}/.claude/architecture.md` | At session start. Latest architecture snapshot summary and read order. |414| `{theme_root}/.claude/ci-cd.md` | Before any deploy. Per-project pattern, deploy commands, pre/post hooks. |415| `{theme_root}/.claude/changelog/daily.md` | At session start. The last ~20 entries — what the last sessions touched. |416417## Hard rules4184191. **Never deploy without an acknowledged backup.** The backup-420 acknowledgement prompt is mandatory for every production write.4212. **Never write secrets into committed files.** SSH keys, GitHub422 PATs, database passwords belong in the OS secret store or423 `ssh-agent` — never in `.claude/`, never in `.env` checked into424 git, never in commit messages.4253. **Never silently overwrite production.** Every prod write shows the426 exact command and waits for explicit "yes."4274. **Never introduce a new framework on an inherited project** without428 explicit, in-session approval. Match the existing architecture.4295. **Always log production writes** as `[DEPLOY-PROD]` or430 `[DIRECT-PROD]` in `daily.md` before closing the response.4316. **Stop on any unexpected error.** No improvised recovery.4327. **`.claude/` is committed to git.** Never write secrets to it.433 `~/.config/norml-wp-developer/projects/*.json` is per-machine and434 never committed.4358. **Local-first is the default.** Direct-on-server is permitted but436 explicit per-operation. Never default to it.437438## Related skills439440**Companion (install both for a full WordPress workflow):**441442- `norml-wp-manager` — REST-API-only content management on a deployed443 site. Use it for posts, pages, ACF values, media. This skill444 (`norml-wp-developer`) is for theme code; `norml-wp-manager` is for445 content. They share no state.446447## What lives where (recap)448449| What | Where | Why |450|---|---|---|451| The skill itself | Runtime-specific skills directory | Claude Code, Codex, or Gemini CLI discovers the stable `norml-wp-developer` slug. |452| **Per-project connection config** | **`~/.config/norml-wp-developer/projects/{slug}.json`** | Per-machine. Host, SSH alias, theme repo path, remote URL, deploy pattern. **No secrets.** |453| **Per-project knowledge** | **`{theme_root}/.claude/`** | Lives in the GitHub repo. Travels with the code. CLAUDE.md, capabilities.md, architecture.md, ci-cd.md, changelog, architecture docs. |454| SSH key | `~/.ssh/{key}` | Owned by the user; ssh-agent holds the passphrase. |455| SSH passphrase | macOS Keychain (via `ssh-add --apple-use-keychain`) / Windows ssh-agent (DPAPI-backed) | OS-managed. Claude never reads it. |456457The split is intentional: `~/.config/` is per-machine connection state;458`{theme_root}/.claude/` is portable per-project knowledge; the OS459secret store is for secrets.