Norml WordPress Copilot Advanced

What it does

Norml WordPress Copilot Advanced develops and deploys WordPress themes from a CLI runtime. It connects the local theme repository, GitHub, production SSH, remote WP-CLI, and optional staging; then records what those verified systems allow.

It works in Sage and inherited-theme modes. Existing architecture wins: the Copilot does not quietly replace a site’s framework, builder, data model, or delivery path because another stack is more familiar.

When to reach for it

Use Advanced when the request includes code or infrastructure:

• Build or change theme templates, components, or styles.
• Create Advanced Custom Fields blocks.
• Model custom post types and taxonomies.
• Inspect WordPress through WP-CLI.
• Connect GitHub or a hosting server.
• Configure or run CI/CD.
• Deploy to staging or production.
• Diagnose architecture the REST API cannot see.

Use Norml WordPress Copilot for routine content and administration, especially in Claude Desktop / Cowork.

Prerequisites

• Claude Code, Codex, or Gemini CLI.
• A local WordPress theme folder containing style.css.
• A local WordPress environment.
• Git and an authenticated GitHub repository.
• SSH access to the production hosting account.
• Remote WP-CLI in the exact production WordPress root.
• A declared deployment and backup strategy.

Claude Desktop / Cowork is not supported because Advanced requires a terminal, local filesystem, Git, and SSH.

A typical first run

1. 01

   Open the theme

   Start the CLI runtime in the theme root. The project is either Sage or inherited mode; when uncertain, the Copilot preserves the inherited structure.

2. 02

   Connect GitHub

   The theme must have an authenticated github.com origin. A read-only git ls-remote origin check must pass before onboarding can finish.

3. 03

   Connect the server

   The Copilot records an SSH alias in machine-local configuration and verifies remote WP-CLI in the exact production WordPress root. Staging is optional.

4. 04

   Analyze

   Fixed read-only commands capture WordPress, PHP, WP-CLI, theme, plugin, content, taxonomy, and infrastructure evidence. A bounded local scan maps the theme source.

5. 05

   Explain

   The Copilot generates .claude/capabilities.md, .claude/architecture.md, and the detailed snapshot, then explains the project from those files.

6. 06

   Develop and ship

   Work happens locally within the recorded architecture. GitHub, staging QA, explicit confirmation, and backup acknowledgement gate deployment.

What it creates

{theme-root}/.claude/
├── CLAUDE.md
├── capabilities.md
├── architecture.md
├── ci-cd.md
├── changelog/
│   ├── README.md
│   ├── daily.md
│   ├── weekly.md
│   └── changelog.md
├── docs/
│   ├── README.md
│   ├── 01-infrastructure.md
│   ├── 02-application.md
│   ├── 03-theme-architecture.md
│   ├── 04-content-structure.md
│   └── 05-issues.md
└── skills/
    └── README.md

The theme-local .claude/ folder is committed with the code. Generated evidence can be replaced by a rescan. Durable decisions stay in CLAUDE.md; durable work history stays in changelog/. Connection metadata and secrets remain outside the repository.

Common requests

• “Set up this project for Norml WordPress Copilot Advanced.”
• “Explain this architecture and the limits in capabilities.md.”
• “Add an ACF block following this theme’s existing component system.”
• “Build a case-study post type with archive and single templates.”
• “Rescan the WordPress and theme architecture.”
• “Ship this branch to staging and run the documented QA gate.”
• “Promote the verified staging release to production.”

Credential safety

• GitHub authentication stays in GitHub CLI, SSH, or the operating-system credential store.
• SSH private keys stay under ~/.ssh/; passphrases stay in ssh-agent and the operating-system secret store.
• Machine-local project config contains connection metadata only.
• Tokens, passwords, private keys, and database credentials never belong in chat, command arguments, .claude/, commits, or workflow files.
• GitHub Actions secrets are configured in GitHub, not written into the theme.

Boundary

CLI development, not Desktop administration.

Missing GitHub access, production SSH, or remote WP-CLI is an onboarding blocker, not a partially successful setup. Read-only inspection can run directly. Local writes and Git state changes require confirmation. Staging deploys require confirmation and QA.

Every production write requires explicit confirmation and a verified backup acknowledgement. A direct production code edit is elevated, recorded as [DIRECT-PROD], and mirrored into GitHub immediately so live code never remains ahead of source control.

It is working if

• The GitHub origin passes a read-only connectivity check.
• Production SSH reaches the exact configured WordPress root.
• Remote wp --info succeeds.
• capabilities.md records the verified local, GitHub, SSH, WP-CLI, staging, and production boundary.
• architecture.md points to five generated evidence files.
• Development follows the detected Sage or inherited structure.
• Theme-local documentation is safe to commit because it contains no secrets.

What changed