Norml Wp Developer

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:

1. 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.
2. 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.

1. Resolve the project slug from the user's request, the working directory, or by asking. Slugs are kebab-cased.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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).

8. 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)

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

Hard rules

1. Never deploy without an acknowledged backup. The backup- acknowledgement prompt is mandatory for every production write.
2. 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.
3. Never silently overwrite production. Every prod write shows the exact command and waits for explicit "yes."
4. Never introduce a new framework on an inherited project without explicit, in-session approval. Match the existing architecture.
5. Always log production writes as [DEPLOY-PROD] or [DIRECT-PROD] in daily.md before closing the response.
6. Stop on any unexpected error. No improvised recovery.
7. .claude/ is committed to git. Never write secrets to it. ~/.config/norml-wp-developer/projects/*.json is per-machine and never committed.
8. 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)

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.